{"id":28379197,"url":"https://github.com/qingstor/qingstor-sdk-js","last_synced_at":"2025-10-10T22:48:28.329Z","repository":{"id":38119660,"uuid":"75298736","full_name":"qingstor/qingstor-sdk-js","owner":"qingstor","description":"The official QingStor SDK for the JavaScript programming language.","archived":false,"fork":false,"pushed_at":"2024-01-10T14:26:49.000Z","size":2212,"stargazers_count":12,"open_issues_count":8,"forks_count":9,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-10-02T04:37:58.929Z","etag":null,"topics":["qingcloud","qingstor","qingstor-sdk"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qingstor.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":"docs/code_of_conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-12-01T14:10:45.000Z","updated_at":"2022-08-03T02:43:17.000Z","dependencies_parsed_at":"2024-01-10T16:09:56.831Z","dependency_job_id":"6321368c-0cf0-46c7-a21b-73497c4ad464","html_url":"https://github.com/qingstor/qingstor-sdk-js","commit_stats":null,"previous_names":["yunify/qingstor-sdk-js"],"tags_count":39,"template":false,"template_full_name":null,"purl":"pkg:github/qingstor/qingstor-sdk-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qingstor%2Fqingstor-sdk-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qingstor%2Fqingstor-sdk-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qingstor%2Fqingstor-sdk-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qingstor%2Fqingstor-sdk-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qingstor","download_url":"https://codeload.github.com/qingstor/qingstor-sdk-js/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qingstor%2Fqingstor-sdk-js/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279005460,"owners_count":26083902,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["qingcloud","qingstor","qingstor-sdk"],"created_at":"2025-05-30T02:30:30.474Z","updated_at":"2025-10-10T22:48:28.309Z","avatar_url":"https://github.com/qingstor.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# QingStor SDK for JavaScript\n[![github-actions](https://github.com/qingstor/qingstor-sdk-js/workflows/Unit%20Test/badge.svg)](https://github.com/qingstor/qingstor-sdk-js/actions?query=branch%3Amaster+workflow%3A%22Unit+Test%22)\n[![api-reference](https://img.shields.io/badge/api-reference-green.svg)](https://docsv4.qingcloud.com/user_guide/storage/object_storage/)\n[![license](https://img.shields.io/badge/license-apache%20v2-blue.svg)](https://github.com/yunify/qingstor-sdk-js/blob/master/LICENSE)\n\n[![NPM](https://nodei.co/npm/qingstor-sdk.png)](https://nodei.co/npm/qingstor-sdk/)\n\nThe official QingStor SDK for the JavaScript programming language.\n\n[中文文档](https://github.com/yunify/qingstor-sdk-js/blob/master/docs/README_zh-cn.md)\n\n- [Install](#install)\n- [Quick Start](#quick-start)\n- [Response format](#response-format)\n- [SDK API Specification](./docs/api_specification.md)\n- [SDK Usage Examples](./docs/examples/index.md)\n- [Config Custom Settings](./docs/advanced_configuration-zh-cn.md)\n\n### Break Changes in 3.0.0\n\n- Config should be initialized like this: `const config = new Config({ access_key_id, secret_access_key })`\n\n## Install\n\nUse npm or [yarn](https://yarnpkg.com) to install SDK\n\n```bash\nnpm install qingstor-sdk\n\n# or\nyarn add qingstor-sdk\n```\n\nAlternatively, you can also use SDK by script tag. Go to the [release](https://github.com/yunify/qingstor-sdk-js/releases) page, download and save the SDK into you project, then in your HTML:\n\n```html\n\u003cscript src=\"https://example.com/path/to/qingstor-sdk.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  // reference sdk by a global variable: qingstor_sdk\n  console.log(qingstor_sdk.version);\n  console.log(qingstor_sdk.QingStor);\n  console.log(qingstor_sdk.Config);\n\u003c/script\u003e\n```\n\nWe recommend using the uncompressed version during development for debugging purposes. Use the `qingstor-sdk.min.js` in production environment.\n\n## Quick Start\n\nQingStor JS SDK is written in ES6 syntax, so make sure you have the right build environment before using it.\n\n### Browser Environment\n\nIf you are using the SDK in browser, it is recommended to compile the code using [Babel](https://babeljs.io) and package the code using [Webpack](https://webpack.js.org).\n\n1. install Babel firstly:\n\n```bash\nnpm install --save-dev @babel/core @babel/cli @babel/preset-env\n```\n\n2. then create file `babel.config.js` in the root folder of your project with the following content:\n\n```javascript\nconst presets = [\n  [\n    \"@babel/env\",\n    {\n      targets: {\n        edge: \"17\",\n        firefox: \"60\",\n        chrome: \"67\",\n        safari: \"11.1\",\n      },\n      useBuiltIns: \"usage\",\n    },\n  ],\n];\n\nmodule.exports = { presets };\n```\n\n3. install webpack:\n\n```bash\nnpm install --save-dev webpack webpack-cli\n```\n\n4. create the file `webpack.config.js` in the root folder of project, copy and paste code below:\n\n```javascript\nmodule.exports = {\n  mode: 'development',\n\n  // you can import { QingStor } from 'qingstor-sdk' in this file\n  entry: './index.js',\n\n  output: {\n    filename: 'dist.js',\n    libraryTarget: 'umd',\n  },\n\n  module: {\n    rules: [\n      {\n        test: /\\.js$/,\n        exclude: /node_modules/,\n        use: {\n          loader: 'babel-loader'\n        }\n      }\n    ]\n  }\n}\n```\n\nopen your terminal and input `./node_modules/.bin/webpack -w` for developing. For more details on the configuration and use of Babel and Webpack, please refer to its official documentation.\n\n### Node Environment\n\nIf you are using the SDK in a Node environment, it is recommended to use [esm](https://github.com/standard-things/esm) as the module loader.\n\n1. install esm:\n\n```bash\nnpm install esm\n```\n\n2. use esm:\n\n```bash\nnode -r esm index.js\n```\n\n### Request Signature\n\nRequests sent to the QingStor must be signed by Access Key and Secret Key. Please go to the [QingCloud Console] (https://console.qingcloud.com/access_keys/) to create and download them. The downloaded key file format is as follows, please save your key properly.\n\n```\naccess_key_id: 'ACCESS_KEY_ID_EXAMPLE'\nsecret_access_key: 'SECRET_ACCESS_KEY_EXAMPLE'\n```\n\nIf you use the SDK in the Node environment, you can initialize the Config object as follow:\n\n```\nimport { Config } from 'qingstor-sdk';\n\nconst config = new Config({\n  access_key_id: 'ACCESS_KEY_ID_EXAMPLE',\n  secret_access_key: 'SECRET_ACCESS_KEY_EXAMPLE',\n});\n```\n\nIf you use the SDK in browser environment, we strongly recommend deploying a signature server that is specifically used to sign requests, so the access_key_id and secret_access_key will not exposing to the client.\n\nThe code for the signature server is very simple, please refer to the [Express Example] (./docs/examples/signaure_server.js). After the signature server is deployed, initialize the Config object as follows:\n\n```javascript\nimport { Config } from 'qingstor-sdk';\n\nconst config = new Config({\n  signature_server: 'https://your.signserver.com/some_path',\n});\n```\n\nNote: If the signature server uses a different domain from user's, you need to configure the corresponding [CORS] (https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) rule.\n\n### Get Bucket list\n\ncreate a file call `index.js` with following content:\n\n```javascript\n// index.js\n\nimport { QingStor, Config } from 'qingstor-sdk';\n\nconst config = new Config({\n  access_key_id: 'ACCESS_KEY_ID_EXAMPLE',\n  secret_access_key: 'SECRET_ACCESS_KEY_EXAMPLE',\n});\n// or\nconst config = new Config({\n  signature_server: 'https://your.signserver.com/some_path',\n});\n\nconst qingstor = new QingStor(config);\n\nfunction listBuckets() {\n  qingstor.listBuckets().then((response) =\u003e {\n    console.log(response.data);\n    // output as follow\n    // {\n    //   \"count\": 2,\n    //   \"buckets\": [\n    //     {\n    //       \"name\": \"mybucket\",\n    //       \"location\": \"pek3a\",\n    //       \"url\": \"https://mybucket.pek3a.qingstor.com\",\n    //       \"created\": \"2015-07-11T04:45:57Z\"\n    //     },\n    //     {\n    //       \"name\": \"myphotos\",\n    //       \"location\": \"pek3a\",\n    //       \"url\": \"https://myphotos.pek3a.qingstor.com\",\n    //       \"created\": \"2015-07-12T09:40:32Z\"\n    //     }\n    //   ]\n    // }\n  });\n}\n\nlistBuckets();\n\n```\n\n### Create Bucket\n\n```javascript\n\nimport { QingStor, Config } from 'qingstor-sdk';\n\nconst config = new Config({\n  access_key_id: 'ACCESS_KEY_ID_EXAMPLE',\n  secret_access_key: 'SECRET_ACCESS_KEY_EXAMPLE',\n});\n// or\nconst config = new Config({\n  signature_server: 'https://your.signserver.com/some_path',\n});\n\nconst qingstor = new QingStor(config);\n\nfunction createBucket() {\n  qingstor.Bucket('example-bucket', 'sh1a').put().then(({ status }) =\u003e {\n    // bucket create succeed, status should be 201\n    console.log(status);\n  }).catch((error) =\u003e {\n    // bucket create failed\n    console.log(error.response.data);\n  });\n}\n\ncreateBucket();\n\n```\n\n### Get object list in a Bucket\n\n```javascript\n\nimport { QingStor, Config } from 'qingstor-sdk';\n\nconst config = new Config({\n  access_key_id: 'ACCESS_KEY_ID_EXAMPLE',\n  secret_access_key: 'SECRET_ACCESS_KEY_EXAMPLE',\n});\n// or\nconst config = new Config({\n  signature_server: 'https://your.signserver.com/some_path',\n});\n\nconst bucket = new QingStor(config).Bucket('example-bucket', 'sh1a');\n\nfunction listObjects() {\n  // list objects under perfix '/images'\n  bucket.listObjects({\n    limit: 10,\n    prefix: '/images',\n  }).then((response) =\u003e {\n    console.log(response.data);\n  }).catch((error) =\u003e {\n    console.log(error.response.data);\n  });\n}\n\nlistObjects();\n\n```\n\n## Response format\n\nQingStor SDK uses [axios] (https://github.com/axios/axios) as http client, and all requests are returned as a Promise. The response structure of axios is as follows:\n\n```javascript\n// copied from https://github.com/axios/axios/blob/master/README.md\n{\n  // `data` is the response that was provided by the server\n  data: {},\n\n  // `status` is the HTTP status code from the server response\n  status: 200,\n\n  // `statusText` is the HTTP status message from the server response\n  statusText: 'OK',\n\n  // `headers` the headers that the server responded with\n  // All header names are lower cased\n  headers: {},\n\n  // `config` is the config that was provided to `axios` for the request\n  config: {},\n\n  // `request` is the request that generated this response\n  // It is the last ClientRequest instance in node.js (in redirects)\n  // and an XMLHttpRequest instance in the browser\n  request: {}\n}\n```\n\n## Reference Documentations\n\n- [QingStor Documentation](https://docsv4.qingcloud.com/user_guide/storage/object_storage/intro/product/)\n- [QingStor Guide](https://docsv4.qingcloud.com/user_guide/storage/object_storage/)\n- [QingStor APIs](https://docsv4.qingcloud.com/user_guide/storage/object_storage/api/)\n\n## Contributing\n\nPlease see [Contributing Guidelines](docs/contributing.md) of this project before submitting patches.\n\n## LICENSE\n\nThe Apache License (Version 2.0, January 2004).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqingstor%2Fqingstor-sdk-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqingstor%2Fqingstor-sdk-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqingstor%2Fqingstor-sdk-js/lists"}