Overview

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

Simple operations

Multipart operations

Other operations

Simple Operations

Querying an object list

API description

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

Samples

Sample 1. List all the 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 is used to upload an object to a bucket. To make this request, you need to have write permission for the bucket.

Note：

1. The Key (file name) 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 access control for an object, you can choose not to configure an ACL for the object during upload, and 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 others for download. However, please note that if your file is set to private-read, the pre-signed URL will only be valid for a certain period of time.

Samples

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 strings as 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.

Samples

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. To download a file using your browser, you should first get a download URL through the cos.getObjectUrl method. For more information, please see Pre-signed URL.

API description

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

Samples

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

Get 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 a pre-flight request for cross-origin access

API description

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

Samples

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 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 replication, object metadata and access control lists (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 replication API Slice Copy File.

Samples

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 is used to delete an object from a COS bucket. To make this request, you need to have write permission for the bucket.

Samples

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 is used to delete multiple objects from a bucket in a single request, which allows a maximum number of 1,000 objects. There are two response modes for you to choose from: Verbose and Quiet. The Verbose mode returns information on the deletion of each object, whereas the Quiet mode only returns information on the objects for which errors were reported.

Samples

Deleting 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 is used to query ongoing multipart uploads. A single request operation can list up to 1,000 multipart uploads.

Samples

The sample below gets a list of UploadIds prefixed with exampleobject for which the multiple upload was incomplete:

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

API description

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

Samples

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 is used to upload a part after a multipart upload was initialized. It can upload up to 10,000 parts of 1 MB to 5 GB for a multiple upload.

Samples

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