Getting Started

Download and Installation

Relevant Resources

• Download the COS XML SDK for JS resources here.
• Download the demo here.

Environmental Requirements

1. To use the SDK, your operating environment need to have Node.js and npm.
2. Log in to the COS Console, create a bucket, and get the bucket name and region name.
3. Log in to the CAM Console and get your project's SecretId and SecretKey.

• For the definitions of SecretId, SecretKey, Bucket and other terms, see COS Glossary.

Installing the SDK

Install the SDK via npm; download npm.

npm i cos-nodejs-sdk-v5 --save

Getting Started

Initialization

Initializing with a permanent key

Please refer to the following sample code. Replace the SecretId, SecretKey, Bucket, and Region with actual values in your development environment to test file upload.

var COS = require('cos-nodejs-sdk-v5');
var cos = new COS({
    SecretId: 'COS_SECRETID',
    SecretKey: 'COS_SECRETKEY'
});

Initializing with a temporary Key

The SDK for Node.js supports initialization with a temporary key. For more information on how to generate and use a temporary key, see Generating and Using Temporary Keys. The sample code is as shown below:

var request = require('request');
var COS = require('cos-nodejs-sdk-v5');
var cos = new COS({
    getAuthorization: function (options, callback) {
        // Get a temporary key asynchronously
        request({
            url: '../server/sts.php',
            data: {
                // The required parameters can be obtained from options
            }
        }, function (err, response, body) {
            try {
                var data = JSON.parse(body);
                var credentials = data.credentials;
            } catch(e) {}
            callback({
                    TmpSecretId: credentials.tmpSecretId, // tmpSecretId of the temporary key
                    TmpSecretKey: credentials.tmpSecretKey, // tmpSecretKey of the temporary key
                    XCosSecurityToken: credentials.sessionToken, // sessionToken needs to be passed to XCosSecurityToken
                    ExpiredTime: data.expiredTime, // Temporary key expiration timestamp, which is the timestamp when applying for a temporary key plus durationSeconds
            });
        });
    }
});

Below are some examples of common APIs. For more detailed initialization methods, please see the Demo.

Configuration Items

Parameters of the constructor

getAuthorization Callback Function Descriptions (Using Method 1)

getAuthorization: function(options, callback) { ... }

getAuthorization callback parameter descriptions:

Callback posts back an object after the temporary key is acquired. Here is a list of the attributes of this object:

getAuthorization Callback Function (Using Method 2)

getAuthorization: function(options, callback) { ... }

getAuthorization callback parameter descriptions:

After the calculation of getAuthorization is completed, callback parameter supports two formats:
Format 1: Returns the authentication string Authorization.
Format 2: Returns an object. The object attribute list is as follows:

Acquiring authentication credentials

You can obtain the authentication credentials for your instance in three ways by passing in different parameters during instantiation:

1. During instantiation, pass in the SecretId and SecretKey, and each time a signature is required, it will be internally calculated by the instance.
2. Pass in the getAuthorization callback. This allows the signature, every time it is required, to be calculated and returned to the instance by this callback.
3. During instantiation, pass in the getSTS callback, and each time a temporary key is required, it will be returned to the instance through this callback for signature calculation within the instance during each request.

Creating a bucket

cos.putBucket({
    Bucket: 'examplebucket-1250000000',
    Region: 'COS_REGION'
}, function(err, data) {
    console.log(err || data);
});

Querying bucket list

cos.getService(function (err, data) {
    console.log(data && data.Buckets);
});

Uploading an object

This API is suitable for uploading small files. For large files, please use the multipart upload API. For more information, see Object Operations.

cos.putObject({
    Bucket: 'examplebucket-1250000000', /*Required*/
    Region: 'COS_REGION', /*Required*/
    Key: 'exampleobject', /*Required*/
    StorageClass: 'STANDARD',
    Body: fs.createReadStream('./exampleobject'), // Uploading file object
    onProgress: function(progressData) {
        console.log(JSON.stringify(progressData));
    }
}, function(err, data) {
    console.log(err || data);
});

Querying the object list

cos.getBucket({
    Bucket: 'examplebucket-1250000000', /*Required*/
    Region: 'COS_REGION', /*Required*/
    Prefix: 'a/', /*Optional*/
}, function(err, data) {
    console.log(err || data.Contents);
});

Downloading an object

cos.getObject({
    Bucket: 'examplebucket-1250000000', /*Required*/
    Region: 'COS_REGION', /*Required*/
    Key: 'exampleobject', /*Required*/
    Output: fs.createWriteStream('./exampleobject'),
}, function(err, data) {
    console.log(err || data);
});

Deleting an object

cos.deleteObject({
    Bucket: 'examplebucket-1250000000', /*Required*/
    Region: 'COS_REGION', /*Required*/
    Key: 'exampleobject' /*Required*/
}, function(err, data) {
    console.log(err || data);
});