Overview

This document provides an overview of APIs and SDK code samples related to simple operations, multipart operations, and advanced APIs.

Simple operations

Multipart upload operations

Simple operations

Querying object list

API description

This API is used to query some or all objects in a bucket.

Use case

Sample 1. List all files in directory a.

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

Response:

{
    "Name": "examplebucket-1250000000",
    "Prefix": "",
    "Marker": "a/",
    "MaxKeys": "1000",
    "Delimiter": "",
    "IsTruncated": "false",
    "Contents": [{
        "Key": "a/3mb.zip",
        "LastModified": "2018-10-18T07:08:03.000Z",
        "ETag": "\"05a9a30179f3db7b63136f30aa6aacae-3\"",
        "Size": "3145728",
        "Owner": {
            "ID": "1250000000",
            "DisplayName": "1250000000"
        },
        "StorageClass": "STANDARD"
    }],
    "statusCode": 200,
    "headers": {}
}

Sample 2. List the files in directory a without deep traversal.

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

Response:

{
    "Name": "examplebucket-1250000000",
    "Prefix": "a/",
    "Marker": "",
    "MaxKeys": "1000",
    "Delimiter": "/",
    "IsTruncated": "false",
    "CommonPrefixes": [{
        "Prefix": "a/1/"
    }],
    "Contents": [{
        "Key": "a/3mb.zip",
        "LastModified": "2018-10-18T07:08:03.000Z",
        "ETag": "\"05a9a30179f3db7b63136f30aa6aacae-3\"",
        "Size": "3145728",
        "Owner": {
            "ID": "1250000000",
            "DisplayName": "1250000000"
        },
        "StorageClass": "STANDARD"
    }],
    "statusCode": 200,
    "headers": {}
}

Parameter description

Callback function description

function(err, data) { ... }

Uploading an object using simple upload

API description

This API (PUT Object) is used to upload an object smaller than 5 GB to a specified bucket. To call this API, you need to have permission to write the bucket. If the object size is larger than 5 GB, please use Multipart Upload or Advanced APIs for the upload.

Note：

1. The Key (filename) cannot end with /; otherwise, it will be identified as a folder.
2. Each root account (AAPID) can have up to 1,000 bucket ACLs and an unlimited number of object ACLs. If you do not need an ACL for an object, you can choose not to configure an ACL for the object during upload. In this way, the object will inherit the permissions of its bucket by default.
3. After an object is uploaded, you can use the same key to generate a pre-signed URL, which can be shared with other clients for downloading (to download, please use the GET method. The detailed API description is shown below). If your file is set to private-read, note that the pre-signed URL will only be valid for a certain period of time.

Use case

Simple upload is suitable for uploading small files.

const filePath = "temp-file-to-upload" // Local file path
cos.putObject({
    Bucket: 'examplebucket-1250000000', /*Required*/
    Region: 'COS_REGION',    /* Required */
    Key: 'exampleobject', /*Required*/
    StorageClass: 'STANDARD',
    Body: fs.createReadStream(filePath), // Upload file object
    onProgress: function(progressData) {
        console.log(JSON.stringify(progressData));
    }
}, function(err, data) {
    console.log(err || data);
});

Upload the buffer as the file content:

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

Upload a string as the file content:

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

Create a directory:

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

Parameter description

Callback function description

function(err, data) { ... }

Uploading an object using a form

The SDK for Node.js does not provide a method for the POST Object API. If you need to use this API, please see "Solution B: Upload with a Form" in Practice of Direct Transfer for Web End.

Querying object metadata

API description

This API is used to query the metadata of an object.

Use case

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

Parameter description

Callback function description

function(err, data) { ... }

Downloading an object

This API (GET Object) is used to download an object in a COS bucket to a local file system. To call this API, you need to have permission to read the object, or the object is set to public-read.

Use case

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

Get the file content with Range specified:

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

Download the file to a specified path:

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

Download the file to a specified write file stream:

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

Parameter description

Callback function description

function(err, data) { ... }

Pre-requesting cross-origin configuration

API description

This API (OPTIONS Object) is used to send a pre-flight request for the CORS configuration of an object. Before making a real CORS request, you can send an OPTIONS request that includes the source origin, HTTP method, and headers to COS for it to determine whether a real CORS request can be sent. If there is no CORS configuration, "403 Forbidden" will be returned. You can enable CORS for a bucket using the PUT Bucket cors API.

Use case

cos.optionsObject({
    Bucket: 'examplebucket-1250000000', /*Required*/
    Region: 'COS_REGION',    /* Required */
    Key: 'exampleobject', /*Required*/
    Origin: 'https://www.qq.com', /*Required*/
    AccessControlRequestMethod: 'PUT', /*Required*/
    AccessControlRequestHeaders: 'origin,accept,content-type' /*Optional*/
}, function(err, data) {
    console.log(err || data);
});

Parameter description

Callback function description

function(err, data) { ... }

Copying an object

API description

This API (PUT Object - Copy) is used to create a copy of an existing COS object, that is, an object is copied from the source path (object key) to the destination path (object key). During the copy, object metadata and the ACLs can be modified.
Users can use this API to create a copy, modify object metadata (the source object and destination file have the same attributes), and move or rename the object (first copy the object, and then call the delete API separately).

Note：

We recommend that you use this API to download an object of 1 MB-5 GB. For objects greater than 5 GB, please use the advanced copy API Slice Copy File.

Use case

cos.putObjectCopy({
    Bucket: 'examplebucket-1250000000', /*Required*/
    Region: 'COS_REGION',/*Required*/
    Key: 'exampleobject', /*Required*/
    CopySource: 'sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/sourceObject', /*Required*/
}, function(err, data) {
    console.log(err || data);
});

Parameter description

Callback function description

function(err, data) { ... }

Deleting a single object

API description

This API (DELETE Object) is used to delete an object from a COS bucket. To call this API, you need to have permission to write the bucket.

Use case

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

Parameter description

Callback function description

function(err, data) { ... }

Deleting multiple objects

API description

This API (DELETE Multiple Objects) is used to delete multiple objects from a bucket in a single request. You can delete up to 1,000 objects in a single request. There are two response modes you to choose from: Verbose and Quiet. The Verbose mode returns information about the deletion of each object, whereas the Quiet mode returns only information about error objects.

Use case

Deleting multiple files:

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

Parameter description

Callback function description

function(err, data) { ... }

Restoring an archived object

API description

This API (POST Object restore) is used to restore an archived COS object. The restored readable object is temporary. You can configure the object to keep it readable and set the time for the object to be deleted. You can use the Days parameter to specify the expiration time of the temporary object. If you have not initiated any operation on the object, such as copying it or extending its validity period, before it expires, the temporary object will be automatically deleted. A temporary object is only a copy of the archived object and the source archived object will always exist throughout this period.

Use case

cos.restoreObject({
    Bucket: 'examplebucket-1250000000', /*Required*/
    Region: 'COS_REGION',    /* Required */
    Key: 'exampleobject',
    RestoreRequest: {
        Days: 1,
        CASJobParameters: {
            Tier: 'Expedited'
        }
    },
}, function(err, data) {
    console.log(err || data);
});

Parameter description

Callback function description

function(err, data) { ... }

Multipart Operations

Querying multipart uploads

API description

This API (List Multipart Uploads) is used to query the ongoing multipart uploads. Up to 1,000 multipart uploads can be listed at a time.

Use case

Get the list of unfinished UploadIds prefixed with exampleobject. The following is an example:

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

Parameter description

Callback function description

function(err, data) { ... }

Initializing a multipart upload operation

API description

This API (Initiate Multipart Uploads) is used to initialize a multipart upload. After a successful operation, an upload ID will be returned, which can be used in the subsequent Upload Part requests.

Use case

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

Parameter description

Callback function description

function(err, data) { ... }

Uploading parts

API description

This API (Upload Part) is used to upload a part after a multipart upload is initialized. It can upload up to 10,000 parts of 1 MB to 5 GB for a multipart upload.

When you use the `Initiate Multipart Upload` API to initiate a multipart upload, you can obtain the `uploadId`. This ID uniquely identifies the part and its position in the entire object.

Every time you call the `Upload Part` API, you need to pass `partNumber` (the part number) and `uploadId`. You can upload multiple parts out of order.

When the `uploadId` and `partNumber` of a new part are the same as those of a previously uploaded part, the old part will be overwritten. If the `uploadId` does not exist, the 404 error, "NoSuchUpload", will be returned.

Use case

const filePath = "temp-file-to-upload" // Local file path
cos.multipartUpload({
    Bucket: 'examplebucket-1250000000', /*Required*/
    Region: 'COS_REGION',    /* Required */
    Key: 'exampleobject', /*Required*/
    ContentLength: '1024',
    UploadId: 'exampleUploadId',
    PartNumber: '1',
    Body: fs.createReadStream(filePath)
}, function(err, data) {
    console.log(err || data);
    if (data) {
      eTag = data.ETag;
    }
});

Parameter description

Callback function description

function(err, data) { ... }

Copying Parts

API description

This API (Upload Part - Copy) is used to copy the parts of an object from the source path to the destination path.

Note：

To upload an object in parts, you must first initialize the multipart upload. A unique descriptor (upload ID) will be returned in the response of the multipart upload initialization. This ID needs to be carried in the multipart upload request.

Use case

cos.uploadPartCopy({
    Bucket: 'examplebucket-1250000000', /*Required*/
    Region: 'COS_REGION',    /* Required */
    Key: 'exampleobject', /*Required*/
    CopySource: 'sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/sourceObject', /*Required*/
    UploadId: 'exampleUploadId', /*Required*/
    PartNumber: '1', /*Required*/
}, function(err, data) {
    console.log(err || data);
    if (data) {
      eTag = data.ETag;
    }
});

Parameter description

Callback function description

function(err, data) { ... }

Querying uploaded parts

API description

This API (List Parts) is used to query the uploaded parts of a specified multipart upload, i.e., listing all successfully uploaded parts of a multipart upload with a specified uploadId.

Use case

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

Parameter description

Callback function description

function(err, data) { ... }

Completing a multipart upload

API description

This API (Complete Multipart Upload) is used to complete a multipart upload. After all parts are uploaded via the Upload Part API, you need to call this API to complete the multipart upload. When using this API, you need to specify the PartNumber and ETag of each part in the request body for the part information to be verified.
As the parts need to be merged after they are uploaded, and the merge takes several minutes, when the merge starts, COS will immediately return status code "200" and periodically return space information during the merge process to keep the connection active until the merge is completed. After that, COS will return the content of the merged parts in the body.

• If the uploaded part size is below 1 MB, "400 EntityTooSmall" will be returned when this API is called.
• If the uploaded part numbers are not continuous, "400 InvalidPart" will be returned when this API is called.
• If the part information entries in the request body are not sorted by number in ascending order, "400 InvalidPartOrder" will be returned when this API is called.
• If the UploadId does not exist, "404 NoSuchUpload" will be returned when this API is called.

Note：

We recommend you either complete or abort a multipart upload as early as possible, as the uploaded parts of an incomplete multipart upload will take up storage capacity and incur storage fees.

Use case

cos.multipartComplete({
    Bucket: 'examplebucket-1250000000', /*Required*/
    Region: 'COS_REGION',    /* Required */
    Key: 'exampleobject', /*Required*/
    UploadId: 'exampleUploadId', /*Required*/
    Parts: [
        {PartNumber: '1', ETag: 'exampleETag'},
    ]
}, function(err, data) {
    console.log(err || data);
});

Parameter description

Callback function description

function(err, data) { ... }

Aborting a multipart upload operation

API description

This API (Abort Multipart Upload) is used to abort a multipart upload and delete the uploaded parts. If you call this API and there is an Upload Part request that is using the multipart upload, the request will fail. If the uploadId does not exist, "404 NoSuchUpload" will be returned.

Note：

We recommend you either complete or abort a multipart upload as early as possible, as the uploaded parts of an incomplete multipart upload will take up storage capacity and incur storage fees.

Use case

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

Parameter description

Callback function description

function(err, data) { ... }

Advanced APIs (Recommended)

The following methods encapsulate the native methods mentioned above. They can implement the complete process of multipart upload/copy and support concurrent multipart upload/copy, checkpoint restart as well as canceling, pausing, and restarting upload tasks.

Uploading an object in parts

API description

This API is used to upload large files in parts.

Use case

const filePath = "temp-file-to-upload" // Local file path
cos.sliceUploadFile({
    Bucket: 'examplebucket-1250000000', /*Required*/
    Region: 'COS_REGION',    /* Required */
    Key: 'exampleobject', /*Required*/
    FilePath: filePath, /*Required*/
    TaskReady: function(taskId) { /*Optional*/
        console.log(taskId);
    },
    onHashProgress: function (progressData) { /* Optional */
        console.log(JSON.stringify(progressData));
    },
    onProgress: function (progressData) { /* Optional */
        console.log(JSON.stringify(progressData));
    }
}, function(err, data) {
    console.log(err || data);
});

Parameter description

Callback function description

function(err, data) { ... }

Copying an object

API description

This API (Slice Copy File) is used to copy an object from the source path to the destination path through multipart copy. During the copy, the object metadata and ACL can be modified. You can use this API to move, rename, and copy a file or modify its attributes.

Method prototype

Call Slice Copy File:

cos.sliceCopyFile({
    Bucket: 'examplebucket-1250000000', /*Required*/
    Region: 'COS_REGION',/*Required*/
    Key: 'exampleobject', /*Required*/
    CopySource: 'sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/sourceObject', /*Required*/
    onProgress:function (progressData) { /*Optional*/
        console.log(JSON.stringify(progressData));
    }
},function (err,data) {
    console.log(err || data);
});

Parameter description

Callback function description

function(err, data) { ... }

Batch upload

API description

Method 1:
You can call putObject and sliceUploadFile multiple times to implement batch uploads. You can instantiate the FileParallelLimit parameter to limit how many objects (default value: 3) can be uploaded at the same time.

Method 2:
You can call cos.uploadFiles to implement batch uploads. The SliceSize parameter can be used to set a size limit to determine whether multipart upload is used. The following describes how to use the uploadFiles method:

Method prototype

Call the uploadFiles operation:

const filePath1 = "temp-file-to-upload" // Local file path
const filePath2 = "temp-file-to-upload" // Local file path
cos.uploadFiles({
    files: [{
        Bucket: 'examplebucket-1250000000',
        Region: 'COS_REGION',
        Key: 'exampleobject',
        FilePath: filePath1,
    }, {
        Bucket: 'examplebucket-1250000000',
        Region: 'COS_REGION',
        Key: '2.jpg',
        FilePath: filePath2,
    }],
    SliceSize: 1024 * 1024,
    onProgress: function (info) {
        var percent = parseInt(info.percent * 10000) / 100;
        var speed = parseInt(info.speed / 1024 / 1024 * 100) / 100;
        console.log('progress:' + percent + '%; speed:' + speed + 'Mb/s;');
    },
    onFileFinish: function (err, data, options) {
        console.log(options.Key + 'upload' + (err ? 'failed' : 'completed'));
    },
}, function (err, data) {
    console.log(err || data);
});

Parameter description

Callback function description

function(err, data) { ... }

Uploading queue

The SDK for Node.js records all the upload tasks initiated with putObject and sliceUploadFile in an upload queue. You can use the queue in the following ways:

1. Use cos.getTaskList to get the task list.
2. Use cos.pauseTask, cos.restartTask, and cos.cancelTask to perform operations on upload tasks.
3. cos.on('list-update', callback); can listen to the list and progress changes.

For a complete sample of how to use the upload queue, please see Queue Demo.

Canceling an upload task

This API is used to cancel an upload task by taskId.

Use case

var taskId = 'xxxxx';                   /* Required */
cos.cancelTask(taskId);

Parameter description

Suspending an upload task

This API is used to suspend an upload task by taskId.

Use case

var taskId = 'xxxxx';                   /* Required */
cos.pauseTask(taskId);

Parameter description

Restarting an upload task

This API is used to restart an upload task by taskId. You can restart tasks that have been manually suspended through the pauseTask API, or automatically suspended due to an upload error.

Use case

var taskId = 'xxxxx';                   /* Required */
cos.restartTask(taskId);

Parameter description