https://github.com/qingstor/qingstor-sdk-js
The official QingStor SDK for the JavaScript programming language.
https://github.com/qingstor/qingstor-sdk-js
qingcloud qingstor qingstor-sdk
Last synced: 8 months ago
JSON representation
The official QingStor SDK for the JavaScript programming language.
- Host: GitHub
- URL: https://github.com/qingstor/qingstor-sdk-js
- Owner: qingstor
- License: apache-2.0
- Created: 2016-12-01T14:10:45.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2024-01-10T14:26:49.000Z (over 2 years ago)
- Last Synced: 2025-10-02T04:37:58.929Z (8 months ago)
- Topics: qingcloud, qingstor, qingstor-sdk
- Language: JavaScript
- Homepage:
- Size: 2.11 MB
- Stars: 12
- Watchers: 4
- Forks: 9
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: docs/contributing.md
- License: LICENSE
- Code of conduct: docs/code_of_conduct.md
- Authors: AUTHORS
Awesome Lists containing this project
README
# QingStor SDK for JavaScript
[](https://github.com/qingstor/qingstor-sdk-js/actions?query=branch%3Amaster+workflow%3A%22Unit+Test%22)
[](https://docsv4.qingcloud.com/user_guide/storage/object_storage/)
[](https://github.com/yunify/qingstor-sdk-js/blob/master/LICENSE)
[](https://nodei.co/npm/qingstor-sdk/)
The official QingStor SDK for the JavaScript programming language.
[中文文档](https://github.com/yunify/qingstor-sdk-js/blob/master/docs/README_zh-cn.md)
- [Install](#install)
- [Quick Start](#quick-start)
- [Response format](#response-format)
- [SDK API Specification](./docs/api_specification.md)
- [SDK Usage Examples](./docs/examples/index.md)
- [Config Custom Settings](./docs/advanced_configuration-zh-cn.md)
### Break Changes in 3.0.0
- Config should be initialized like this: `const config = new Config({ access_key_id, secret_access_key })`
## Install
Use npm or [yarn](https://yarnpkg.com) to install SDK
```bash
npm install qingstor-sdk
# or
yarn add qingstor-sdk
```
Alternatively, 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:
```html
// reference sdk by a global variable: qingstor_sdk
console.log(qingstor_sdk.version);
console.log(qingstor_sdk.QingStor);
console.log(qingstor_sdk.Config);
```
We recommend using the uncompressed version during development for debugging purposes. Use the `qingstor-sdk.min.js` in production environment.
## Quick Start
QingStor JS SDK is written in ES6 syntax, so make sure you have the right build environment before using it.
### Browser Environment
If 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).
1. install Babel firstly:
```bash
npm install --save-dev @babel/core @babel/cli @babel/preset-env
```
2. then create file `babel.config.js` in the root folder of your project with the following content:
```javascript
const presets = [
[
"@babel/env",
{
targets: {
edge: "17",
firefox: "60",
chrome: "67",
safari: "11.1",
},
useBuiltIns: "usage",
},
],
];
module.exports = { presets };
```
3. install webpack:
```bash
npm install --save-dev webpack webpack-cli
```
4. create the file `webpack.config.js` in the root folder of project, copy and paste code below:
```javascript
module.exports = {
mode: 'development',
// you can import { QingStor } from 'qingstor-sdk' in this file
entry: './index.js',
output: {
filename: 'dist.js',
libraryTarget: 'umd',
},
module: {
rules: [
{
test: /\.js$/,
exclude: /node_modules/,
use: {
loader: 'babel-loader'
}
}
]
}
}
```
open 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.
### Node Environment
If 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.
1. install esm:
```bash
npm install esm
```
2. use esm:
```bash
node -r esm index.js
```
### Request Signature
Requests 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.
```
access_key_id: 'ACCESS_KEY_ID_EXAMPLE'
secret_access_key: 'SECRET_ACCESS_KEY_EXAMPLE'
```
If you use the SDK in the Node environment, you can initialize the Config object as follow:
```
import { Config } from 'qingstor-sdk';
const config = new Config({
access_key_id: 'ACCESS_KEY_ID_EXAMPLE',
secret_access_key: 'SECRET_ACCESS_KEY_EXAMPLE',
});
```
If 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.
The 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:
```javascript
import { Config } from 'qingstor-sdk';
const config = new Config({
signature_server: 'https://your.signserver.com/some_path',
});
```
Note: 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.
### Get Bucket list
create a file call `index.js` with following content:
```javascript
// index.js
import { QingStor, Config } from 'qingstor-sdk';
const config = new Config({
access_key_id: 'ACCESS_KEY_ID_EXAMPLE',
secret_access_key: 'SECRET_ACCESS_KEY_EXAMPLE',
});
// or
const config = new Config({
signature_server: 'https://your.signserver.com/some_path',
});
const qingstor = new QingStor(config);
function listBuckets() {
qingstor.listBuckets().then((response) => {
console.log(response.data);
// output as follow
// {
// "count": 2,
// "buckets": [
// {
// "name": "mybucket",
// "location": "pek3a",
// "url": "https://mybucket.pek3a.qingstor.com",
// "created": "2015-07-11T04:45:57Z"
// },
// {
// "name": "myphotos",
// "location": "pek3a",
// "url": "https://myphotos.pek3a.qingstor.com",
// "created": "2015-07-12T09:40:32Z"
// }
// ]
// }
});
}
listBuckets();
```
### Create Bucket
```javascript
import { QingStor, Config } from 'qingstor-sdk';
const config = new Config({
access_key_id: 'ACCESS_KEY_ID_EXAMPLE',
secret_access_key: 'SECRET_ACCESS_KEY_EXAMPLE',
});
// or
const config = new Config({
signature_server: 'https://your.signserver.com/some_path',
});
const qingstor = new QingStor(config);
function createBucket() {
qingstor.Bucket('example-bucket', 'sh1a').put().then(({ status }) => {
// bucket create succeed, status should be 201
console.log(status);
}).catch((error) => {
// bucket create failed
console.log(error.response.data);
});
}
createBucket();
```
### Get object list in a Bucket
```javascript
import { QingStor, Config } from 'qingstor-sdk';
const config = new Config({
access_key_id: 'ACCESS_KEY_ID_EXAMPLE',
secret_access_key: 'SECRET_ACCESS_KEY_EXAMPLE',
});
// or
const config = new Config({
signature_server: 'https://your.signserver.com/some_path',
});
const bucket = new QingStor(config).Bucket('example-bucket', 'sh1a');
function listObjects() {
// list objects under perfix '/images'
bucket.listObjects({
limit: 10,
prefix: '/images',
}).then((response) => {
console.log(response.data);
}).catch((error) => {
console.log(error.response.data);
});
}
listObjects();
```
## Response format
QingStor 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:
```javascript
// copied from https://github.com/axios/axios/blob/master/README.md
{
// `data` is the response that was provided by the server
data: {},
// `status` is the HTTP status code from the server response
status: 200,
// `statusText` is the HTTP status message from the server response
statusText: 'OK',
// `headers` the headers that the server responded with
// All header names are lower cased
headers: {},
// `config` is the config that was provided to `axios` for the request
config: {},
// `request` is the request that generated this response
// It is the last ClientRequest instance in node.js (in redirects)
// and an XMLHttpRequest instance in the browser
request: {}
}
```
## Reference Documentations
- [QingStor Documentation](https://docsv4.qingcloud.com/user_guide/storage/object_storage/intro/product/)
- [QingStor Guide](https://docsv4.qingcloud.com/user_guide/storage/object_storage/)
- [QingStor APIs](https://docsv4.qingcloud.com/user_guide/storage/object_storage/api/)
## Contributing
Please see [Contributing Guidelines](docs/contributing.md) of this project before submitting patches.
## LICENSE
The Apache License (Version 2.0, January 2004).