Download and Installation
Relevant resources
Download the COS XML SDK resources for Node.js here. Note:
If you encounter errors such as non-existent functions or methods when using the SDK, you can update the SDK to the latest version and try again.
Environmental dependencies
1. The SDK requires your runtime environment to include Node.js (v6 or later) and npm.
3. Log in to the CAM console and get your project's SecretId and SecretKey. Note:
For the definition of terms such as SecretId, SecretKey, and Bucket, see COS Glossary. Installing SDK
Install the SDK through npm which can be downloaded here. npm i cos-nodejs-sdk-v5 --save
Getting Started
Initialization
Using a temporary key for initialization (recommended)
For more information on how to generate and use a temporary key, 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) {
request({
url: 'https://example.com/sts',
data: {
}
}, 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,
TmpSecretKey: credentials.tmpSecretKey,
SecurityToken: credentials.sessionToken,
ExpiredTime: data.expiredTime,
});
});
}
});
Using a permanent key for initialization (not recommended)
When using a permanent key for initialization, store the key properly to prevent leakage.
First, log in to 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, see the following sample code.
var COS = require('cos-nodejs-sdk-v5');
var cos = new COS({
SecretId: process.env.SecretId,
SecretKey: process.env.SecretKey,
});
Below are some common APIs. For more detailed initialization methods, see the demo. Configuration item
Constructor parameters
|
| | | |
| | | |
| Number of concurrent file uploads in the same instance. Default value: 3 | | |
| Number of concurrent part uploads for the same uploaded file. Default value: 3 | | |
| Number of retries for multipart upload failure. Default value: 2 (a request will be made 3 time in total, including the initial one) | | |
| Part size in the multipart upload in bytes. Default value: 1048576 (1 MB) | | |
| 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: 1048576 (1 MB) | | |
| Number of concurrent part uploads for the same multipart copy operation. Default value: 20 | | |
| Number of bytes in each part during a multipart copy operation with sliceCopyFile. Default value: 10485760 (10 MB) | | |
| 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: 10485760 (10 MB) | | |
| Callback frequency of the upload progress callback method onProgress in milliseconds. Default value: 1000 | | |
| The 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 | | |
| The request domain name when getService is called, such as service.cos.myqcloud.com | | |
| 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. | | |
| The maximum size of the upload queue. If the maximum is exceeded, failed, completed, and canceled tasks will be cleared. Default value: 1000 | | |
| Forces the use of a suffix when sending 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 | | |
| 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 | | |
| Timeout period in milliseconds. Default value: 0, indicating no timeout period. | | |
| 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. | | |
| Strict verification of the HTTPS certificate. Default value: true | | |
| Uses an HTTP proxy when making requests, such as: http://127.0.0.1:8080 | | |
| Callback method for getting the signature. If there is no SecretId or SecretKey, this parameter is required | | |
| Whether to enable a global acceleration endpoint. Default value: false. If you set the value to true, you need to enable global acceleration for the bucket. For more information, see Enabling Global Acceleration. | | |
getAuthorization: function(options, callback) { ... }
getAuthorization function parameters:
|
| Required for getting the signature | |
| Bucket name in the format of BucketName-APPID. The bucket name entered here must be in this format | |
| | |
| Callback method after the temporary key is obtained | |
After the temporary key is obtained, the callback returns an object. The attributes of the returned object are as listed below:
|
| tmpSecretId of the obtained temporary key
| | |
| tmpSecretKey of the obtained temporary key
| | |
| sessionToken of the obtained temporary key, which corresponds to the x-cos-security-token field in the header | | |
| 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. | | |
| expiredTime of the obtained temporary key measured in seconds, i.e., the timeout timestamp, such as 1580000900
| | |
getAuthorization: function(options, callback) { ... }
getAuthorization function parameters:
|
| Parameter object for getting the signature | |
| Method of the current request | |
| Request path used for signature calculation | |
| ObjectKey (object name) is the unique ID of an object in a bucket. For more information, see Object Overview. | |
| Query parameter in the current request. Format: {key: 'val'} | |
| Headers in the current request. Format: {key: 'val'} | |
| Callback after the temporary key is obtained | |
Once the getAuthorization callback function is finished, it returns one of the following:
An Authorization string.
An object whose attributes are listed as follows:
|
| Calculated signature string | | |
| sessionToken of the obtained temporary key, which corresponds to the x-cos-security-token field in the header
| | |
Getting an 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. Each time a signature is required, it will be internally calculated by the instance.
2. During instantiation, pass in the getAuthorization callback function. 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. Each time a temporary key is required, it will be returned to the instance for signature calculation within the instance during each request.
How to use
Callback method
The callback method is used by default in the documentation. Below is the sample code:
var cos = new COS({ ... });
cos.uploadFile({ ... }, function(err, data) {
if (err) {
console.log('Upload failed', err);
} else {
console.log('Uploaded successfully', data);
}
});
Promise
The SDK also supports calling through the promise method. For example, the code of the callback method above is equivalent to the following code:
var cos = new COS({ ... });
cos.uploadFile({ ... }).then(data => {
console.log('Uploaded successfully', data);
}).catch(err => {
console.log('Upload failed', err);
});
Sync method
The sync method is based on JavaScript's async and await. The code of the callback method above is equivalent to the following code:
async function upload() {
var cos = new COS({ ... });
try {
var data = await cos.uploadFile({ ... });
return { err: null, data: data }
} catch (err) {
return { err: err, data: null };
}
}
var uploadResult = await upload();
if (uploadResult.err) {
console.log('Upload failed', uploadResult.err);
} else {
console.log('Uploaded successfully', uploadResult.data);
}
Note:
cos.getObjectUrl currently only supports the callback method.
Tips
In most cases, you only need to create a COS SDK instance, and use it directly where SDK methods need to be called.
var cos = new COS({
....
});
function myUpload() {
cos.putObject({
....
});
}
function myDelete() {
cos.deleteObject({
....
});
}
Below are some common APIs. For more detailed initialization methods, see the demo. Creating a bucket
cos.putBucket({
Bucket: 'examplebucket-1250000000',
Region: 'COS_REGION'
}, function(err, data) {
console.log(err || data);
});
Querying the 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, use the multipart upload API. For more information, see Object Operations. cos.putObject({
Bucket: 'examplebucket-1250000000',
Region: 'COS_REGION',
Key: 'exampleobject',
StorageClass: 'STANDARD',
Body: fs.createReadStream('./exampleobject'),
onProgress: function(progressData) {
console.log(JSON.stringify(progressData));
}
}, function(err, data) {
console.log(err || data);
});
Querying objects
cos.getBucket({
Bucket: 'examplebucket-1250000000',
Region: 'COS_REGION',
Prefix: 'a/',
}, function(err, data) {
console.log(err || data.Contents);
});
Downloading an object
cos.getObject({
Bucket: 'examplebucket-1250000000',
Region: 'COS_REGION',
Key: 'exampleobject',
Output: fs.createWriteStream('./exampleobject'),
}, function(err, data) {
console.log(err || data);
});
Deleting an object
cos.deleteObject({
Bucket: 'examplebucket-1250000000',
Region: 'COS_REGION',
Key: 'exampleobject'
}, function(err, data) {
console.log(err || data);
});
