Getting Started

Last updated: 2020-09-10 17:13:26

    Download and Installation

    Relevant resources

    • Download the COS XML SDK resources for Node.js [here] (https://github.com/tencentyun/cos-nodejs-sdk-v5).
    • Fast SDK download: XML Node.js SDK.
    • Download the demo here.
    • For the complete sample, go to GitHub.

    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

    Parameter Name Description Type Required
    SecretId User SecretId String Yes
    SecretKey User SecretKey. We recommend you only use the SecretKey for frontend debugging to avoid key exposure String Yes
    FileParallelLimit Number of concurrent file uploads in the same instance. Default value: 3 Number No
    ChunkParallelLimit Number of concurrent part uploads for the same uploaded file. Default value: 3 Number No
    ChunkRetryTimes Number of retries for multipart upload failure. Default value: 3 (a request will be made 4 time in total, including the initial one) Number No
    ChunkSize Part size for the multipart upload in bytes. Default value: 1,048,576 (1 MB) Number No
    SliceSize When files are uploaded in batches using uploadFiles, if the file size is greater than the value of this parameter (measured in bytes), multipart upload is used; otherwise, simple upload is used. Default value: 1,048,576 (1 MB) Number No
    CopyChunkParallelLimit Number of concurrent part uploads for the same multipart copy operation. Default value: 20 Number No
    CopyChunkSize Number of bytes in each part during a multipart copy operation with sliceCopyFile. Default value: 10,485,760 (10 MB) (10MB) Number No
    CopySliceSize When a file is copied using sliceCopyFile, if the file size is greater than the value of this parameter, multipart copy is used; otherwise, simple copy is used. Default value: 10,485,760 (10 MB) Number No
    ProgressInterval Callback frequency of the upload progress callback method onProgress measured in milliseconds. Default value: 1,000 Number No
    Protocol Protocol used when the request is made. Valid values: https:, http:. By default, http: is used when the current page is determined to be in http: format; otherwise, https: is used String No
    ServiceDomain The request domain name when getService is called, such as service.cos.myqcloud.com String No
    Domain Custom request domain name used to call a bucket or object API. You can use a template
    such as "{Bucket}.cos.{Region}.myqcloud.com" which will use the bucket and region information passed in the replacement parameters when an API is called.
    String No
    UploadQueueSize The maximum size of the upload queue. If the maximum is exceeded, failed, completed, and canceled tasks will be cleared. Default value: 1,000 Number No
    ForcePathStyle Forces the use of a suffix to send requests. The suffixed bucket will be placed in the pathname after the domain name, and the bucket will be added to the signature pathname for calculation. Default value: false Boolean No
    UploadCheckContentMd5 Forces the verification of Content-MD5 for file uploads, which calculates the MD5 checksum of the file request body and places it in the Content-MD5 field of the header. Default value: false Boolean No
    Timeout Timeout period in milliseconds. Default value: 0, indicating no timeout period. Number No
    KeepAlive Indicates that more than one request is sent over one TCP connection. Default value: true. This parameter is recommended for a large number of concurrent requests. Boolean No
    StrictSsl Strict verification of the HTTPS certificate. Default value: true Boolean No
    Proxy Uses an HTTP proxy when making requests, such as: http://127.0.0.1:8080 String No
    GetAuthorization The callback method for getting the signature. If there is no SecretId or SecretKey, this parameter is mandatory. Function No

    getAuthorization Callback function description (Format 1)

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

    getAuthorization function parameters:

    Parameter Name Description Type
    options Required for getting the signature Object
    - Bucket Bucket name in the format: BucketName-APPID String
    - Region Bucket region. For the enumerated values, see Regions and Access Domain Names. String
    callback Callback method after the temporary key is obtained Function

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

    Attribute Description Type Required
    TmpSecretId tmpSecretId of the obtained temporary key String Yes
    TmpSecretKey tmpSecretKey of the obtained temporary key String No
    XCosSecurityToken sessionToken of the obtained temporary key, which corresponds to the x-cos-security-token field in the header String No
    StartTime The timestamp in seconds of when you obtained the key, such as 1580000000. Passing in this parameter as the signature start time can avoid signature expiration issues due to time deviation on the frontend. String No
    ExpiredTime expiredTime of the obtained temporary key measured in seconds, i.e., the timeout timestamp, such as 1580000900 String No

    getAuthorization Callback function description (Format 2)

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

    getAuthorization function parameters:

    Parameter Name Description Type
    options Parameter object necessary for getting the signature Object
    - Method Current request method String
    - Pathname Request path used for signature calculation String
    - Key ObjectKey (object name) is the unique ID of an object in a bucket. For more information, see Object Overview. String
    - Query Query parameter in the current request. Format: {key: 'val'} Object
    - Headers Headers in the current request. Format: {key: 'val'} Object
    callback Callback after the temporary key is obtained Function

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

    Attribute Description Type Required
    Authorization Calculated signature string String Yes
    XCosSecurityToken sessionToken of the obtained temporary key, which corresponds to the x-cos-security-token field in the header String No

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

    Was this page helpful?

    Was this page helpful?

    • Not at all
    • Not very helpful
    • Somewhat helpful
    • Very helpful
    • Extremely helpful
    Send Feedback
    Help