Overview

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

Simple operations

Multipart operations

Other operations

Simple Operations

Querying an object list

API description

Queries 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',     /* Bucket 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',     /* Bucket 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 to a bucket. To call this API, you need to have permission to write the bucket.

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.

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

Upload a string as the file content:

cos.putObject({
    Bucket: 'examplebucket-1250000000',                               /* Required */
    Region: 'COS_REGION',     /* Bucket 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',     /* Bucket 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 an HTML form

The SDK for JS does not provide a method for the POST Object API. If you need to use this API, please see "Solution B: Upload with 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',     /* Bucket region. Required */
    Key: 'exampleobject', /*Required*/
}, function(err, data) {
    console.log(err || data);
});

Parameter description

Callback function description

function(err, data) { ... }

Downloading an object

Note：

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

API description

This API (GET Object) is used to get the content, in string format, of a specified file in a bucket.

Use case

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

Parameter description

Callback function description

function(err, data) { ... }

Configuring pre-flight requests for cross-origin access

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',     /* Bucket 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',     /* Bucket 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',     /* Bucket 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

Deletee multiple files:

cos.deleteMultipleObject({
    Bucket: 'examplebucket-1250000000',                               /* Required */
    Region: 'COS_REGION',     /* Bucket region. Required */
    Objects: [
        {Key: 'exampleobject'},
        {Key: 'exampleobject2'},
    ]
}, 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',     /* Bucket 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 Upload) 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',     /* Bucket region. Required */
    Key: 'exampleobject',              /* Required */
    UploadId: 'exampleUploadId',
    Body: fileObject
}, function(err, data) {
    console.log(err || data);
    if (data) {
      uploadId = data.UploadId;
    }
});

Parameter description

Callback function description

function(err, data) { ... }

Uploading a part

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

cos.multipartUpload({
    Bucket: 'examplebucket-1250000000',                               /* Required */
    Region: 'COS_REGION',     /* Bucket region. Required */
    Key: 'exampleobject', /*Required*/
    UploadId: 'exampleUploadId',
    PartNumber: '1',
    Body: fileObject
}, function(err, data) {
    console.log(err || data);
    if (data) {
      eTag = data.ETag;
    }
});

Parameter description

Callback function description

function(err, data) { ... }

Copying a part

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',     /* Bucket 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',     /* Bucket 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 any uploaded part is less than 1 MB in size, 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',     /* Bucket 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

API description

This API is used to abort a multipart upload operation 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',     /* Bucket region. Required */
    Key: 'exampleobject', /*Required*/
    UploadId: 'exampleUploadId' /*Required*/
}, function(err, data) {
    console.log(err || data);
});

Parameter description

Callback function description

function(err, data) { ... }

Other Operations

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',     /* Bucket 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) { ... }

Setting object ACL

API description

This API (PUT Object acl) is used to set the ACL of an object in a bucket.

Note：

The total number of policies associated with bucket ACL, Policy, and CAM under a single root account (i.e., under the same APPID) cannot exceed 1,000. There is no upper limit on the number of object ACL rules. If you do not need access control for an object, do not make any configuration. In this way, the object will inherit the permissions of its bucket.

Use case

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

Grant a user all permissions to an object:

cos.putObjectAcl({
    Bucket: 'examplebucket-1250000000',                               /* Required */
    Region: 'COS_REGION',     /* Bucket region. Required */
    Key: 'exampleobject',              /* Required */
    GrantFullControl: 'id="100000000001"' // 100000000001 is the uin of the root account.
}, function(err, data) {
    console.log(err || data);
});

Grant permission to write the object via AccessControlPolicy:

cos.putObjectAcl({
    Bucket: 'examplebucket-1250000000',                               /* Required */
    Region: 'COS_REGION',     /* Bucket region. Required */
    Key: 'exampleobject',              /* Required */
    AccessControlPolicy: {
        "Owner": { // `Owner` is required in `AccessControlPolicy`
            "ID": 'qcs::cam::uin/100000000001:uin/100000000001' // 100000000001 is the QQ account number of the user owning the bucket
        },
        "Grants": [{
            "Grantee": {
                "ID": "qcs::cam::uin/100000000011:uin/100000000011", // 100000000011 is the QQ account number
            },
            "Permission": "WRITE"
        }]
    }
}, function(err, data) {
    console.log(err || data);
});

Parameter description

Callback function description

function(err, data) { ... }

Querying object ACL

API description

The API (GET Object acl) is used to query the ACL of an object. Only the owner of the bucket has the permission to use this API.

Use case

cos.getObjectAcl({
    Bucket: 'examplebucket-1250000000',                               /* Required */
    Region: 'COS_REGION',     /* Bucket region. Required */
    Key: 'exampleobject',              /* 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 (Slice Upload File) is used to upload large files in parts.

Note：

• If the browser is not closed, you can suspend, restart, or cancel the upload job.
• If you upload the same file to the same bucket path after refreshing the browser, the file content will be verified based on UploadId and the upload will proceed if the verification is passed.

Use case

cos.sliceUploadFile({
    Bucket: 'examplebucket-1250000000',                               /* Required */
    Region: 'COS_REGION',     /* Bucket region. Required */
    Key: 'exampleobject',              /* Required */
    Body: fileObject,               /*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

| Parameter                                  | Description | Type |
| ------------------------------------------------------------ | ------------------------------------------------------------ | --------- | ---- |
| Bucket | Bucket name in the format of BucketName-APPID | String | Yes |
| Region | Bucket region. For the enumerated values, please see Regions and Access Endpoints. | String | Yes |
| Key | Object key (object name), the unique ID of an object in a bucket. For more information, please see Object Overview. | String | Yes |
| Body | Content of the file part to be uploaded, which can be a File object, or a Blob object | File\Blob | Yes |
| SliceSize | Part size | String | No |
| AsyncLimit | Concurrent number of parts being uploaded | String | No |
| StorageClass | Storage class of the object. For the enumerated values, such as STANDARD, STANDARD_IA, ARCHIVE, and DEEP_ARCHIVE, please see Storage Class Overview. | String | No |
| UploadAddMetaMd5 | Sets x-cos-meta-md5 as the object’s MD5 checksum in the object’s metadata during upload in the format of a 32-bit lowercase string. Example: 4d00d79b6733c9cc066584a02ed03410 | String | No |
| TaskReady | Callback function when an upload task is created. The callback returns a taskId, which uniquely identifies the task and can be used to cancel (cancelTask), pause (pauseTask), or restart (restartTask) the task. | Function | No |
| - taskId | Upload task number | String | No |
| onHashProgress | Progress callback function for file MD5 checksum calculation. The callback parameter is the progress object progressData | Function | No |
| - progressData.loaded | Size of the verified parts, in bytes | Number | No |
| - progressData.total | Total file size in bytes | Number | No |
| - progressData.speed | File verification speed in bytes/s | Number | No |
| - progressData.percent | Percentage of the file verification progress, in decimal form. For example, 0.5 means 50% has been verified. | Number | No |
| onProgress | File upload progress callback function. The callback parameter is the object in progress progressData | Function | No |
| - progressData.loaded | Size of the uploaded parts, in bytes | Number | No |
| - progressData.total | Total file size in bytes | Number | No |
| - progressData.speed | File upload speed in bytes/s | Number | No |
| - progressData.percent | Percentage of the file upload progress, in decimal form. For example, 0.5 means 50% has been uploaded. | Number | No |

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',     /* Bucket 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 sliceUploadFile is used. The following describes how to use the uploadFiles method:

Method prototype

Call uploadFiles:

cos.uploadFiles({
    files: [{
        Bucket: 'examplebucket-1250000000', // Format: BucketName-APPID
        Region: 'COS_REGION',     /* Bucket region. Required */
        Key: 'exampleobject',
        Body: fileObject1,
    }, {
        Bucket: 'examplebucket-1250000000', // Format: BucketName-APPID
        Region: 'COS_REGION',     /* Bucket region. Required */
        Key: 'exampleobject2',
        Body: fileObject2,
    }],
    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 JavaScript 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. Use cos.on('list-update', callback); to monitor changes in the list and the upload progress.

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

Canceling an upload task

This API cancels an upload task by taskId.

Use case

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

Parameter description

Suspending an upload task

This API suspends 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