Download and Installation

Relevant resources

• Download the COS XML SDK resources for Node.js here.
• Fast SDK download: XML Node.js SDK.
• Download the demo here.

Environment dependencies

1. Your operating environment needs to have Node.js and npm to use the SDK.
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 parameters such as SecretId, SecretKey, and Bucket, please see the COS Glossary.

Installing the SDK

Install the SDK via npm which can be downloaded [here].(https://www.npmjs.com/package/cos-nodejs-sdk-v5).

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

Getting Started

Initialization

Initializing with a permanent key

First, log into the CAM Console, and get your SecretId and SecretKey from the Access Key page.
Replace SecretId, SecretKey, bucket, and region with the actual values in your development environment. To test file upload, please see the following sample code.

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

Initializing with a temporary key

For more information on how to generate and use a temporary key, please see Generating and Using Temporary Keys. The SDK for Node.js supports initialization by passing in a temporary key as shown in the sample code 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: 'https://example.com/sts',
            data: {
                // You can obtain the required parameters from options
            }
        }, function (err, response, body) {
            try {
                var data = JSON.parse(body);
                var credentials = data.credentials;
            } catch(e) {}
            if (!data || !credentials) return console.error('credentials invalid');
            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, // Expiration timestamp of the temporary key, which is calculated by adding durationSeconds to the timestamp when applying for the temporary key 
            });
        });
    }
});

Below are some examples of common APIs. For more detailed initialization methods, please see the [Demo] (https://github.com/tencentyun/cos-nodejs-sdk-v5/blob/master/demo/demo.js).

Configuration

Constructor Parameters

getAuthorization Callback function description (Format 1)

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

getAuthorization function parameters:

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

getAuthorization Callback function description (Format 2)

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

getAuthorization function parameters:

Once the getAuthorization callback function is finished, it returns one of the following:
An Authorization string.
An object whose attributes are listed as follows:

Acquiring authentication credentials

There are three ways to get the authentication credentials for your instance by passing in different parameters during instantiation:

1. During instantiation, pass in your SecretId and SecretKey, and each time a signature is required, it will be internally calculated by the instance.
2. During instantiation, pass in the getAuthorization callback function, and each time a signature is required, it will be calculated and returned to the instance through 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 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 a bucket list

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

Uploading an object

This API is used to upload small files. For large files, please use the multipart upload API. For more information, see Actions on Objects.

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 an 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);
});