Download and Installation

Relevant resources

• Source code of COS XML JS SDK download: XML JavaScript SDK.
• Download the XML SDK for JavaScript here.
• Download the demo here.
• Find the complete sample code here.
• For the SDK changelog, please see Changelog.

Preparing environment

1. The SDK for JavaScript requires the browser to support basic HTML5 features (IE 10 and higher) for AJAX file uploading and file MD5 checksum calculation.
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 the SecretId and SecretKey of your project.
4. Configure CORS rule. Put in * for AllowHeader. For ExposeHeaders, put in ETag, Content-Length, and other header fields JS needs to read as shown below. For more information, please see Setting Cross-Origin Resource Sharing.
   

Note：

For the definitions of parameters such as SecretId, SecretKey, and Bucket, please see COS Glossary.

Installing SDK

You can install the SDK in the following ways:

Importing through script

<script src="./cos-js-sdk-v5.min.js"></script>

When the script tag references the SDK, the SDK occupies the global variable name COS, and its constructor can create an SDK instance.

Importing through webpack

Install the SDK dependencies by running npm i cos-js-sdk-v5 --save, which supports webpack packaging scenarios. You can use npm import as a module with the following code:

var COS = require('cos-js-sdk-v5');

Getting Started

Getting temporary key

As placing a permanent key on the frontend may cause security risks, we recommend you use temporary keys during formal deployment. The implementation process is as follows: the frontend first requests the server, and then the server uses the permanent key to call the STS service to apply for a temporary key (for more information, please see Generating and Using Temporary Keys) and returns it to the frontend.

Note：

If the site has a login state, login state verification should be added to the temporary key getting API.

Initialization

1. Create a web.html file, enter the following code, and modify the bucket name and region in web.html.
2. Deploy the temporary key service on the backend and modify the key service address in getAuthorization.
3. Place the web.html file on the web server, visit the page in a browser, and test file uploading. The sample code for web.html is as follows:

<input id="file-selector" type="file">
<script src="dist/cos-js-sdk-v5.min.js"></script>
<script>
var Bucket = 'examplebucket-1250000000';
var Region = 'COS_REGION';      /* Bucket region. Required */

// Initialize an instance.
var cos = new COS({
    getAuthorization: function (options, callback) {
        // Get a temporary key asynchronously.
        $.get('http://example.com/server/sts.php', {
            bucket: options.Bucket,
            region: options.Region,
        }, function (data) {
            var credentials = data && data.credentials;
            if (!data || !credentials) return console.error('credentials invalid');
            callback({
                TmpSecretId: credentials.tmpSecretId,
                TmpSecretKey: credentials.tmpSecretKey,
                XCosSecurityToken: credentials.sessionToken,
                // We recommend you use the time the server receives the credentials as the StartTime, so as to avoid signature error due to time deviations.
                StartTime: data.startTime, // Timestamp in seconds, such as 1580000000
                ExpiredTime: data.expiredTime, // Timestamp in seconds, such as 1580000900
            });
        });
    }
});

// The COS instance can then be used to call a COS request.
// TODO

</script>

Configuration items

Samples

Create a COS SDK instance in one of the following ways:

• Method 1 (recommended): the backend gets a temporary key and sends it to the frontend for signature calculation.

var COS = require('cos-js-sdk-v5');
var cos = new COS({
    // Required parameters
    getAuthorization: function (options, callback) {
        // Server-side JS and PHP sample: https://github.com/tencentyun/cos-js-sdk-v5/blob/master/server/
        // For server-side examples for other programming languages, please see the COS SDK for STS: https://github.com/tencentyun/qcloud-cos-sts-sdk
        // For the STS documentation, visit https://intl.cloud.tencent.com/document/product/436/14048?from_cn_redirect=1.
        $.get('http://example.com/server/sts.php', {
            // The required parameters can be obtained from options.
        }, function (data) {
            var credentials = data && data.credentials;
            if (!data || !credentials) return console.error('credentials invalid');
            callback({
                TmpSecretId: credentials.tmpSecretId,
                TmpSecretKey: credentials.tmpSecretKey,
                XCosSecurityToken: credentials.sessionToken,
                // We recommend you use the time the server receives the credentials as the StartTime, so as to avoid signature error due to time deviations.
                StartTime: data.startTime, // Timestamp in seconds, such as 1580000000
                ExpiredTime: data.expiredTime, // Timestamp in seconds, such as 1580000900
            });
        });
    }
});

• Method 2 (recommended): permissions are controlled in a more refined manner. The backend gets a temporary key and sends it to the frontend. The frontend reuses the key only for the same request, and the backend can granularly manage permissions through Scope.

var COS = require('cos-js-sdk-v5');
var cos = new COS({
    // Required parameters
    getAuthorization: function (options, callback) {
        // Server example: https://github.com/tencentyun/qcloud-cos-sts-sdk/blob/master/scope.md
        $.ajax({
            method: 'POST',
            url: ' http://example.com/server/sts-scope.php',
            data: JSON.stringify(options.Scope),
            beforeSend: function (xhr) {
                xhr.setRequestHeader('Content-Type', 'application/json');
            },
            dataType: 'json',
            success: function (data) {
                var credentials = data && data.credentials;
                if (!data || !credentials) return console.error('credentials invalid');
                callback({
                    TmpSecretId: credentials.tmpSecretId,
                    TmpSecretKey: credentials.tmpSecretKey,
                    XCosSecurityToken: credentials.sessionToken,
                    // We recommend you use the time the server receives the credentials as the StartTime, so as to avoid signature error due to time deviations.
                    StartTime: data.startTime, // Timestamp in seconds, such as 1580000000
                    ExpiredTime: data.expiredTime, // Timestamp in seconds, such as 1580000900
                    ScopeLimit: true, // Refined permission control needs to be set to true, limiting that the key can be reused only for the same request
                });
            }
        });
    }
});

• Method 3 (not recommended): the frontend needs to get a signature through getAuthorization before each request, and the backend uses a permanent or temporary key to calculate the signature and returns it to the frontend. This method makes it difficult to control permissions for multipart upload and thus is not recommended.

var cos = new COS({
    // Required parameters
    getAuthorization: function (options, callback) {
        // The server obtains a signature. For more information, please see the COS SDK for the corresponding programming language: https://intl.cloud.tencent.com/document/product/436/6474?from_cn_redirect=1
        // Note: there may be a security risk associated with this method. The backend needs to strictly control the permission through method and pathname, such as prohibiting put /
        $.get('http://example.com/server/auth.php', {
            method: options.Method,
            pathname: '/' + options.Key,
        }, function (data) {
            if (!data || !data.authorization) return console.error('authorization invalid');
            callback({
                Authorization: data.authorization,
                // XCosSecurityToken: data.sessionToken, // If a temporary key is used, sessionToken needs to be passed to XCosSecurityToken
            });
        });
    },
    // Optional parameters
    FileParallelLimit: 3,    // Controls the number of concurrent file uploads
    ChunkParallelLimit: 3,   // Controls the number of concurrent part uploads for a single file
    ProgressInterval: 1000,  // Controls the interval of upload `onProgress` callbacks
});

• Method 4 (not recommended): the frontend uses a permanent key to calculate the signature. This method can be used for frontend debugging. If you use this method, be sure to avoid key disclosure.

var cos = new COS({
    SecretId: 'COS_SECRETID',
    SecretKey: 'COS_SECRETKEY',
});

Constructor parameter description

getAuthorization callback function descriptions (using method 1)

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

getAuthorization callback parameter descriptions:

After the temporary key is obtained, the callback returns an object. The attributes of the returned object are as listed below:

getAuthorization callback function description (using method 2)

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

getAuthorization callback parameters:

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

Getting authentication credential

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. Every time a signature is required, it will be calculated and returned to the instance through this callback.
3. During instantiation, pass in the getAuthorization callback. When this callback is called, a temporary key will be returned, and after the key expires, the callback will be called again.

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

Uploading object

The simple upload API can be used to upload small files. For large files, use the multipart upload API. For more information, please see Object Operations.

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

Querying object list

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

Downloading object

Note：

This API is used to read the object content. If you need to launch a browser to download the file, you can get the URL through cos.getObjectUrl and then start a download in the browser. For more information, please see Pre-signed URL.

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

Deleting object

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