Overview

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

API	Operation	Description
GET Bucket (List Objects)	Querying an object list	Queries some or all objects in a bucket
PUT Object	Uploads an object using simple upload	Uploads an object to a bucket
POST Object	Uploading an object using an HTML form	Uploads an object using an HTML form
HEAD Object	Querying object metadata	Queries the metadata of an object
GET Object	Downloading an object	Downloads an object to the local file system
OPTIONS Object	Pre-requesting cross-origin configuration	Uses a pre-request to confirm whether a real cross-origin request can be sent
PUT Object - Copy	Copying an object	Copies an object to a destination path (object key)
DELETE Object	Deleting a single object	Deletes a specified object from a bucket
DELETE Multiple Objects	Deleting multiple objects	Deletes multiple objects in a single request
POST Object restore	Restoring an archived object	Restores an archived object for access

Multipart upload operations

API	Operation	Description
List Multipart Uploads	Querying a multipart upload	Queries the information about an ongoing multipart upload
Initiate Multipart Upload	Initializing a multipart upload	Initializes a multipart upload task
Upload Part	Uploading a part	Uploads a part in a multipart upload
Upload Part - Copy	Copying a part	Uploads a part by copying data from an existing object as the data source
List Parts	Querying uploaded parts	Queries the uploaded parts of a specified multipart upload
Complete Multipart Upload	Completing a multipart upload	Completes the multipart upload of an entire object
Abort Multipart Upload	Aborting a multipart upload	Aborts a multipart upload and deletes the uploaded parts

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.

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

Response:

json
{
  "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.

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

Response:

json
{
  "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": {}
}

Sample 3. Listing all files in a directory

js
var bucket = 'examplebucket-1250000000';
var region = 'ap-beijing';
var prefix = 'examplefolder/';  /* A directory/prefix to delete */
var listFolder = function(marker) {
  cos.getBucket({
      Bucket: bucket,
      Region: region,
      Prefix: prefix,
      Marker: marker,
      MaxKeys: 1000,
  }, function(err, data) {
      if (err) {
          return console.log('list error:', err);
      } else {
          console.log('list result:', data.Contents);
          if (data.IsTruncated === 'true') listFolder(data.NextMarker);
          else return console.log('list complete');
      }
  });
};
listFolder();

Parameter description

Parameter	Description	Type	Required
Bucket	Bucket name in the format: BucketName-APPID	String	Yes
Region	Bucket region. For the enumerated values, please see Regions and Access Endpoints.	String	Yes
Prefix	Matching prefix for object keys. This parameter limits the response to contain only object keys with the specified prefix.	String
Delimiter	A delimiter is a separating symbol used to group object keys. It is usually /. The identical paths between Prefix or, if no Prefix is specified, the beginning and the first delimiter are grouped and defined as a common prefix. All common prefixes will be listed.	String	No
Marker	Indicates where the object key listing begins. Entries are listed starting from the key after the Marker in UTF-8 lexicographical order by default.	String	No
MaxKeys	Maximum number of entries returned in a single response. Defaults to 1000.	String	No
EncodingType	Encoding type of the returned value. Valid value: url, meaning that the returned object keys are URL-encoded (percent-encoded) values. For example, "Tencent Cloud" will be encoded to %E8%85%BE%E8%AE%AF%E4%BA%91.	String	No

Callback function description

function(err, data) { ... }

Parameter Name	Description	Type
err	Object returned when an error (network error or service error) occurs. If the request is successful, this parameter is left empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code returned by the request, such as 200, 403, and 404	Number
- headers	Headers returned by the request	Object
data	Object returned when the request succeeds. If the request fails, this is null	Object
- headers	Headers returned by the request	Object
- statusCode	HTTP status code returned by the request, such as 200, 403, and 404	Number
- Name	Bucket name in the format of <BucketName-APPID>, such as examplebucket-1250000000	string
- Prefix	Matching prefix for object keys. Object key entries will be returned in UTF-8 lexicographical order, starting from the key after the marker.	String
- Marker	By default, parts are listed in UTF-8 binary order, starting from the part after the marker.	String
- MaxKeys	Maximum number of entries returned in a single response	String
- Delimiter	Delimiter	String
- IsTruncated	Specifies whether returned entries are truncated. Valid values: true, false	String
- NextMarker	If returned entries are truncated, then NextMarker marks where the next listing should begin	String
- CommonPrefixes	The identical paths between a specified prefix and the delimiter are grouped and defined as a common prefix.	ObjectArray
- - Prefix	A single common prefix	String
- EncodingType	Encoding type of the returned values. This parameter is applicable to Delimiter, Marker, Prefix, NextMarker, and Key,	String
- Contents	A list of object metadata	ObjectArray
- - Key	Object name, i.e., object key	String
- - ETag	MD5 checksum of the object, such as "22ca88419e2ed4721c23807c678adbe4c08a7880". Note that double quotation marks are required at the beginning and the end.	String
- - Size	Part size, in bytes	String
- - LastModified	Last modified time of the object, in ISO 8601 format, for example, 2019-05-24T10:56:40Z	String
- - Owner	Information about the object owner	Object
- - - ID	Complete ID of object owner in the format of qcs::cam::uin/[OwnerUin]:uin/[OwnerUin], for example, qcs::cam::uin/100000000001:uin/100000000001, where 100000000001 is the uin.	String
- - - DisplayName	Name of the part owner	String
- - StorageClass	Storage class of the object. For the enumerated values, such as STANDARD, STANDARD_IA and ARCHIVE, please see Storage Class Overview.	String

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.

js
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:

js
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:

js
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:

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

Uploading an object to a specified directory:

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

Parameter description

Parameter	Description	Type	Required
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 to be uploaded. This parameter can be file stream, buffer, or a string.	Stream/Buffer/String	Yes
CacheControl	Cache policy as defined in RFC 2616. It will be stored as the object metadata.	String	No
ContentDisposition	Filename as defined in RFC 2616. It will be stored as the object metadata.	String	No
ContentEncoding	Encoding format as defined in RFC 2616. It will be stored as the object metadata.	String	No
ContentLength	HTTP request length (in bytes) as defined in RFC 2616	String	No
ContentType	Content type (MIME) as defined in RFC 2616. It will be stored as the object metadata.	String	No
Expires	Expiration time as defined in RFC 2616. It will be stored as the object metadata.	String	No
Expect	If Expect: 100-continue is used, the request content will be sent only after confirmation from the server is received.	String	No
ACL	Defines the access control list (ACL) attribute of the object. For the enumerated values, such as default, private, and public-read, please see the Preset ACL section in ACL Overview. Note: if you do not need access control for the object, set default for this parameter or simply leave it blank. In this way, the object will inherit the permissions of the bucket.	String	No
GrantRead	Grants the grantee Read access in the format of id=" ",id=" ". To authorize a sub-account, use id="qcs::cam::uin/<owneruin>:uin/<subuin>". To authorize a root account, use id="qcs::cam::uin/<owneruin>:uin/<owneruin>". Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'	String	No
GrantReadAcp	Grants the grantee Read access to ACL and policies in the format of id=" ",id=" ". To authorize a sub-account, use id="qcs::cam::uin/<owneruin>:uin/<subuin>". To authorize a root account, use id="qcs::cam::uin/<owneruin>:uin/<owneruin>". Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'	String	No
GrantWriteAcp	Grants the grantee Write access to ACL and policies in the format of id=" ",id=" ". To authorize a sub-account, use id="qcs::cam::uin/<owneruin>:uin/<subuin>". To authorize a root account, use id="qcs::cam::uin/<owneruin>:uin/<owneruin>". Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'	String	No
GrantFullControl	Grants the grantee Read/Write access in the format of id=" ",id=" ". To authorize a sub-account, use id="qcs::cam::uin/<owneruin>:uin/<subuin>". To authorize a root account, use id="qcs::cam::uin/<owneruin>:uin/<owneruin>". Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'	String	No
StorageClass	Storage class of the object. For the enumerated values, such as STANDARD (default), STANDARD_IA and ARCHIVE, please see Storage Class Overview.	String	No
x-cos-meta-*	User-defined headers, which will be returned as the object metadata. The maximum size is 2 KB.	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	ID of the upload task	String	No
onProgress	Callback of the progress. Attributes of the response object progressData are as follows:	Function	No
- progressData.loaded	Size of the uploaded parts, in bytes	Number	No
- progressData.total	Size of the entire object, in bytes	Number	No
- progressData.speed	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) { ... }

Parameter	Description	Type
err	Object returned when an error (network error or service error) occurs. If the request is successful, this is null. For more information, see Error Codes	Object
- statusCode	HTTP status code returned by the request, such as "200", "403", and "404"	Number
- headers	Header information returned by the request	Object
data	Object returned when the request is successful. If the request fails, this parameter is left empty.	Object
- statusCode	HTTP status code returned by the request, such as "200", "403", and "404"	Number
- headers	Headers returned by the request	Object
- ETag	MD5 checksum of the object. The value of ETag can be used to check whether the object was corrupted during the upload. Example: "09cba091df696af91549de27b8e7d0f6" Note that double quotation marks are required at the beginning and the end.	String
- Location	Public network access endpoint of the object	String
- VersionId	Returns the version ID for versioning-enabled buckets. For buckets that have never had versioning enabled, this parameter is not returned.	String

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

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

Parameter description

Parameter	Description	Type	Required
Bucket	Bucket name in the format: 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
IfModifiedSince	If the object is modified after the specified time, the corresponding object metadata will be returned; otherwise, 304 will be returned.	String	No

Callback function description

function(err, data) { ... }

Parameter	Description	Type
err	Object returned when an error (network error or service error) occurs. If the request is successful, this parameter is left empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code returned by the request, such as 200, 403, and 404	Number
- headers	Header information returned by the request	Object
data	Data returned when the request is successful. If the request fails, this is null.	Object
- statusCode	HTTP status code returned by the request, such as 200 and 304. If no modification is made after the specified time, 304 will be returned.	Number
- headers	Headers returned by the request	Object
- x-cos-object-type	Indicates whether an object is appendable. Enumerated values: normal, appendable. The default value normal is not displayed if returned.	String
- x-cos-storage-class	Storage class of the object. Enumerated values: STANDARD (default), STANDARD_IA, ARCHIVE. STANDARD is not displayed if returned.	String
- x-cos-meta-*	User-defined metadata	String
- NotModified	Indicates whether an object is unmodified after the specified time.	Boolean
- ETag	MD5 checksum of the object. The value can be used to check whether the object was corrupted during the upload. Example: "09cba091df696af91549de27b8e7d0f6" Note that double quotation marks are required at the beginning and the end.	String
- VersionId	Returns the version ID for versioning-enabled buckets. For buckets that have never had versioning enabled, this parameter is not returned.	String

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

js
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:

js
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:

js
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:

js
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

Parameter	Description	Type	Required
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
Output	An output file path or a write stream. If this parameter is specified, the full content will be written to data in the callback function.	String/WriteStream	No
ResponseContentType	Sets the Content-Type parameter in the response header.	String	No
ResponseContentLanguage	Sets the Content-Language parameter in the response header.	String	No
ResponseExpires	Sets the Content-Expires parameter in the response header.	String	No
ResponseCacheControl	Sets the Cache-Control parameter in the response header.	String	No
ResponseContentDisposition	Sets the Content-Disposition parameter in the response header.	String	No
ResponseContentEncoding	Sets the Content-Encoding parameter in the response header.	String	No
Range	Byte range of the object as defined in RFC 2616. The range value must be in the format of bytes=first-last, where both first and last are offsets starting from 0. For example, bytes=0-9 means that you want to copy the first 10 bytes of data of the source object. If this parameter is not specified, the entire object will be downloaded.	String	No
If-Modified-Since	If the object is modified after the specified time, the corresponding object metadata will be returned; otherwise, "304 (not modified)" will be returned.	String	No
If-Unmodified-Since	If the object is not modified after the specified time, the object will be returned; otherwise, "412 (precondition failed)" will be returned.	String	No
IfMatch	The object will be returned only if the value of ETag matches the specified content; otherwise, "412 (precondition failed)" will be returned.	String	No
IfNoneMatch	The file will be returned only if the value of ETag does not match the specified content; otherwise, "304 (not modified)" will be returned.	String	No
VersionId	Version ID of the object to download	String	No
onProgress	Callback of the progress. Attributes of the response object progressData are as follows:	Function	No
- progressData.loaded	Size of the downloaded parts, in bytes	Number	No
- progressData.total	Size of the entire object, in bytes	Number	No
- progressData.speed	Download speed, in bytes/s	Number	No
- progressData.percent	Percentage of the file download progress, in decimal form. For example, 0.5 means 50% has been downloaded.	Number	No

Callback function description

function(err, data) { ... }

Parameter	Description	Type
err	Object returned when an error (network error or service error) occurs. If the request is successful, this parameter is left empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code returned by the request, such as 200, 403, and 404	Number
- headers	Headers returned by the request	Object
data	Data returned when the request is successful. If the request fails, this is null.	Object
- statusCode	HTTP status code returned by the request, such as 200, 304, 403, and 404	Number
- headers	Headers returned by the request	Object
Cache-Control	Cache directives as defined in RFC 2616. It will be returned only if it is contained in the object metadata or specified through the request parameter.	string
Content-Disposition	Filename as defined in RFC 2616. It will be returned only if it is contained in the object metadata or specified through the request parameter.	string
- ContentEncoding	Encoding format as defined in RFC 2616. It will be returned only if it is contained in the object metadata or specified through the request parameter.	string
Expires	Cache expiration time as defined in RFC 2616. It will be returned only if it is contained in the object metadata or specified through the request parameter.	string
- x-cos-storage-class	Storage class of the object. Enumerated values: STANDARD, STANDARD_IA, ARCHIVE Note: If this header is not returned, the storage class is automatically set to STANDARD	String
- x-cos-meta-*	User-defined metadata	String
- NotModified	This attribute will be returned if the request contains IfModifiedSince. If the file has been modified, false will be returned. If not, true will be returned.	Boolean
- ETag	MD5 checksum of the object. The value of ETag can be used to check whether the object was corrupted during the upload. Example: "09cba091df696af91549de27b8e7d0f6" Note that double quotation marks are required at the beginning and the end.	String
- VersionId	Returns the version ID for versioning-enabled buckets. For buckets that have never had versioning enabled, this parameter is not returned.	String
- Body	Content of the returned file. The default form is buffer.	Buffer

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

js
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

Parameter	Description	Type	Required
Bucket	Bucket name in the format: 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
Origin	Origin domain name of the simulated CORS request	String	Yes
AccessControlRequestMethod	HTTP method of the simulated CORS request	String	Yes
AccessControlRequestHeaders	Headers of the simulated CORS request	String	No

Callback function description

function(err, data) { ... }

Parameter	Description	Type
err	Object returned when an error (network error or service error) occurs. If the request is successful, this parameter is left empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code returned by the request, such as 200, 403, and 404	Number
- headers	Headers returned by the request	Object
data	Object returned when the request is successful. If the request fails, this parameter is left empty.	Object
- headers	Headers returned by the request	Object
- statusCode	HTTP status code returned by the request, such as 200, 403, and 404	Number
- AccessControlAllowOrigin	Source origins (separated by commas) of the simulated CORS request. If the origins are not allowed, this header will not be returned. Example: *	String
- AccessControlAllowMethods	HTTP methods (separated by commas) of the simulated CORS request (for example, PUT,GET,POST,DELETE,HEAD). If the request method is not allowed, this header will not be returned.	String
- AccessControlAllowHeaders	Headers (separated by commas) of the simulated CORS request (for example, accept,content-type,origin,authorization). If none of the stimulated request headers is allowed, this header will not be returned.	String
- AccessControlExposeHeaders	CORS-supported headers (separated by commas) that can be returned, for example, ETag	String
- AccessControlMaxAge	Validity period of the result of the OPTIONS request, for example, 3600	String
- OptionsForbidden	Indicates whether the OPTIONS request is forbidden. If the returned HTTP status code is 403, this value is true.	Boolean

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

js
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

Parameter	Description	Type	Required
Bucket	Bucket name in the format: 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
CopySource	URL path of the source object. A historical version can be specified using the URL parameter ?versionId=<versionId>.	String	Yes
ACL	Defines the ACL attribute of the object. For the enumerated values, such as default, private, and public-read, please see the Preset ACL section in ACL Overview. Default value: default Note: If you do not need access control for the object, set this parameter to default or leave it empty. In this way, the object will inherit the permissions of the bucket it is stored in.	String	No
GrantReadAcp	Grants the grantee Read access to ACL and policies in the format of id=" ",id=" ". To authorize a sub-account, use id="qcs::cam::uin/<owneruin>:uin/<subuin>". To authorize a root account, use id="qcs::cam::uin/<owneruin>:uin/<owneruin>". Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'	String	No
GrantWrite	Grants the grantee Write access in the format of id=" ",id=" ". To authorize a sub-account, use id="qcs::cam::uin/<owneruin>:uin/<subuin>". To authorize a root account, use id="qcs::cam::uin/<owneruin>:uin/<owneruin>". Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'	String	No
GrantFullControl	Grants the grantee Read/Write access in the format of id=" ",id=" ". To authorize a sub-account, use id="qcs::cam::uin/<owneruin>:uin/<subuin>". To authorize a root account, use id="qcs::cam::uin/<owneruin>:uin/<owneruin>". Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'	String	No
MetadataDirective	Indicates whether to copy the metadata. Enumerated values: Copy (default), Replaced. If set to Copy, the metadata of the source object will be copied directly and the user-defined metadata in the header will be ignored. If set to Replaced, the metadata of the source object will be replaced with the user-defined metadata in the header. If the destination and source paths are the same, that is, you want to modify the metadata, this parameter must be set to Replaced.	String	No
CopySourceIfModifiedSince	If the object is modified after the specified time, the operation will be performed; otherwise, 412 will be returned. This parameter can be used together with CopySourceIfNoneMatch. If it is used together with other conditions, a conflict will be returned.	String	No
CopySourceIfUnmodifiedSince	If the object is not modified after the specified time, the operation will be performed; otherwise, 412 will be returned. This parameter can be used together with CopySourceIfMatch. If it is used together with other conditions, a conflict will be returned.	String	No
CopySourceIfMatch	If the ETag of the object is the same as the specified one, the operation will be performed; otherwise, 412 will be returned. This parameter can be used together with CopySourceIfUnmodifiedSince. If it is used together with other conditions, a conflict will be returned.	String	No
CopySourceIfNoneMatch	If the Etag of the object is different from the specified one, the operation will be performed; otherwise, 412 will be returned. This parameter can be used together with CopySourceIfModifiedSince. If it is used together with other conditions, a conflict will be returned.	string	No
StorageClass	Storage class of the object. For the enumerated values, such as STANDARD (default), STANDARD_IA and ARCHIVE, please see Storage Class Overview.	String	No
x-cos-meta-*	Other user-defined file headers	String	No

Callback function description

function(err, data) { ... }

Parameter Name	Description	Type
err	Object returned when an error (network error or service error) occurs. If the request is successful, this parameter is left empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code returned by the request, such as 200, 403, and 404	Number
- headers	Headers returned by the request	Object
data	Object returned when the request is successful. If the request fails, this parameter is left empty.	Object
- statusCode	HTTP status code returned by the request, such as 200, 403, and 404	Number
- headers	Headers returned by the request	Object
- ETag	MD5 checksum of the object, such as "22ca88419e2ed4721c23807c678adbe4c08a7880". Note that double quotation marks are required at the beginning and the end.	String
- LastModified	Last modified time of the object, for example, 2017-06-23T12:33:27.000Z	String
- VersionId	Returns the version ID for versioning-enabled buckets. For buckets that have never had versioning enabled, this parameter is not returned.	String

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

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

Parameter description

Parameter	Description	Type	Required
Bucket	Bucket name is in the format of BucketName-APPID. The bucket name entered here must be in this format	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
VersionId	Version ID of the object or delete marker to delete	String	No

Callback function description

function(err, data) { ... }

Parameter	Description	Type
err	Object returned when an error (network error or service error) occurs. If the request is successful, this is null. For more information, see Error Codes	Object
- statusCode	HTTP status code returned by the request, such as "200", "403", and "404"	Number
- headers	Header information returned by the request	Object
data	Object returned when the request is successful. If the request fails, this parameter is left empty.	Object
- statusCode	HTTP status code returned by the request, such as 200, 204, 403, and 404. If the deletion is successful or the object does not exist, an HTTP 204 or 200 status code will be returned. If the specified bucket is not found, an HTTP 404 status code will be returned.	Number
- headers	Headers returned by the request	Object

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:

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

Deleting multiple objects with a specified prefix (deleting files in a specified directory):

js
var bucket: 'examplebucket-1250000000'; /* Required */
var region: 'ap-beijing';     /* Region of the bucket (required) */
var prefix = 'examplefolder/';  /* A directory/prefix to delete */
var deleteFolder = function (marker) {
  cos.getBucket({
      Bucket: bucket,
      Region: region,
      Prefix: prefix,
      Marker: marker,
      MaxKeys: 1000,
  }, function (listError, listResult) {
      if (listError) return console.log('list error:', listError);
      var nextMarker = listResult.NextMarker;
      var objects = listResult.Contents.map(function (item) {
          return {Key: item.Key}
      });
      cos.deleteMultipleObject({
          Bucket: bucket,
          Region: region,
          Objects: objects,
      }, function (delError, deleteResult) {
          if (delError) {
              console.log('delete error', delError);
              console.log('delete stop');
          } else {
              console.log('delete result', deleteResult);
              if (listResult.IsTruncated === 'true') deleteFolder(nextMarker);
              else console.log('delete complete');
          }
      });
  });
}
deleteFolder();

Parameter description

Parameter	Description	Type	Required
Bucket	Bucket name in the format: BucketName-APPID	String	Yes
Region	Bucket region. For the enumerated values, please see Regions and Access Endpoints.	String	Yes
Quiet	Specifies whether to use the Quiet mode. If set to true, the Quiet mode is enabled. If set to false (default), the Verbose mode is enabled.	Boolean	No
Objects	The list of objects to delete	ObjectArray	Yes
- Key	Object key (object name), the unique identifier of an object in a bucket. For more information, please see Object Overview.	String	Yes
- VersionId	Version ID of the object or delete marker to delete	String	No

Callback function description

function(err, data) { ... }

Parameter	Description	Type
err	Object returned when an error (network error or service error) occurs. If the request is successful, this parameter is left empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code returned by the request, such as 200, 204, 403, and 404	Number
- headers	Headers returned by the request	Object
data	Object returned when the request is successful. If the request fails, this parameter is left empty.	Object
- statusCode	HTTP status code returned by the request, such as 200, 204, 403, and 404	Number
- headers	Headers returned by the request	Object
- Deleted	A list of objects that are successfully deleted	ObjectArray
- - Key	Object key (object name), the unique identifier of an object in a bucket. For more information, please see Object Overview.	String
- - VersionId	If the VersionId parameter is passed in, it will also be included in the response, indicating the version of the object or delete marker.	String
- - DeleteMarker	If versioning is enabled and the VersionId parameter is not specified, the deletion operation will not actually delete the object; instead, it will only add a delete marker, meaning that the visible object has been deleted. Enumerated values: true, false	String
- - DeleteMarkerVersionId	Returns the VersionId of the generated delete marker if DeleteMarker is set to true.	String
- Error	A list of objects whose deletion failed	ObjectArray
- - Key	ObjectKey (object name) is the unique identifier of an object in a bucket. For more information, see Object Overview.	String
- - Code	Deletion failure error codes	String
- - Message	Error messages of the deletion failure	String

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

js
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

Parameter	Description	Type	Required
Bucket	Bucket name in the format: BucketName-APPID	String	Yes
Region	Bucket region. For the enumerated values, please see Regions and Access Endpoints.	String	Yes
Key	ObjectKey (object name) is the unique ID of an object in a bucket. For more information, see Object Overview.	String	Yes
RestoreRequest	A container for data restoration	Object	Yes
- Days	Sets the expiration time of the temporary copy.	Number	Yes
- CASJobParameters	A container for the archive job parameters	Object	Yes
- - Tier	Specifies the restoration mode. The following three restoration modes are supported for the ARCHIVE storage class: Standard: restores an object within 3-5 hours. Expedited: restores an object within 15 minutes. Bulk: restores an object within 5-12 hours. The following two restoration modes are supported for the DEEP ARCHIVE storage class: Standard: restores an object within 12-24 hours. Bulk: restores an object within 24-48 hours.	String	Yes

Callback function description

function(err, data) { ... }

Parameter	Description	Type
err	Object returned when an error (network error or service error) occurs. If the request is successful, this is null. For more information, see Error Codes	Object
- statusCode	HTTP status code returned by the request, such as "200", "403", and "404"	Number
- headers	Header information returned by the request	Object
data	Object returned when the request is successful. If the request fails, this parameter is left empty.	Object
- statusCode	HTTP status code returned by the request, such as "200", "403", and "404"	Number
- headers	Headers returned by the request	Object

Multipart Operations

Querying multipart upload operations

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:

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

Parameter description

Parameter	Description	Type	Required
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
Prefix	This parameter limits the response to contain only object keys with the specified prefix. Note that when you query with the prefix specified, the returned object keys will still contain the prefix.	String	No
Delimiter	A delimiter is a separating symbol used to group object keys. It is usually /. The identical paths between Prefix or, if no Prefix is specified, the beginning and the first delimiter are grouped and defined as a common prefix. All common prefixes will be listed.	String	No
EncodingType	Encoding type of the returned value. Valid value: url	String	No
MaxUploads	Sets the maximum number of entries that can be returned at a time. Valid range: 1-1000. Defaults to 1000.	String	No
KeyMarker	Used together with upload-id-marker. If upload-id-marker is not specified:  - Only multipart uploads whose ObjectName is lexicographically greater than the specified key-marker will be listed. If upload-id-marker is specified:  - Multipart uploads whose ObjectName is lexicographically greater than the specified key-marker will be listed;  - Multipart uploads whose ObjectName is lexicographically equal to the specified key-marker and the UploadID is larger than the upload-id-marker will be listed.	String	No
UploadIdMarker	Used together with key-marker. If key-marker is not specified:  - upload-id-marker will be ignored. If key-marker is specified:  - Multipart uploads whose ObjectName is lexicographically greater than the specified key-marker will be listed;  - Multipart uploads whose ObjectName is equal to the specified key-marker and the UploadID is greater than the upload-id-marker will be listed.	String	No

Callback function description

function(err, data) { ... }

Parameter	Description	Type
err	Object returned when an error (network error or service error) occurs. If the request is successful, this parameter is left empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code returned by the request, such as 200, 403, and 404	Number
- headers	Headers returned by the request	Object
data	Object returned when the request succeeds. If the request fails, this parameter is left empty.	Object
- statusCode	HTTP status code returned by the request, such as 200, 403, and 404	Number
- headers	Headers returned by the request	Object
- Bucket	Destination bucket for the multipart upload	String
- Encoding-Type	Encoding type for the returned values. Valid value: url	String
- KeyMarker	Specifies the key where the list starts.	String
- UploadIdMarker	Specifies the UploadId where the list starts.	String
- NextKeyMarker	If the returned list is truncated, the NextKeyMarker returned will be the starting point of the subsequent list.	String
- NextUploadIdMarker	If the returned list is truncated, the UploadId returned will be the starting point of the subsequent list.	String
MaxUploads	Sets the maximum number of entries returned. Value range: 1-1000; default value: 1000	String
- IsTruncated	Indicates whether returned objects are truncated. Valid value: true or false	String
- Prefix	Matching prefix for object keys. This parameter limits the response to contain only object keys with the specified prefix.	String
- Delimiter	A delimiter is a separating symbol used to group object keys. It is usually /. The identical paths between Prefix or, if no Prefix is specified, the beginning and the first delimiter are grouped and defined as a common prefix. All common prefixes will be listed.	String
- CommonPrefixes	The identical paths between prefix and delimiter are grouped and defined as a common prefix.	ObjectArray
- - Prefix	Displays specific common prefixes	String
- Upload	A set of information about multipart uploads	ObjectArray
- - Key	Object key, i.e., object name	String
- - UploadId	ID of the multipart upload	String
- - StorageClass	Storage class of the parts. For the enumerated values, such as STANDARD, STANDARD_IA and ARCHIVE, please see Storage Class Overview.	String
- - Initiator	Information about the upload initiator	Object
- - - DisplayName	Name of the upload initiator	String
- - - ID	ID of the upload initiator in the format of qcs::cam::uin/<owneruin>:uin/<subuin>. For the root account, <OwnerUin> and <SubUin> have the same value.	String
- - Owner	Information about the part owner	Object
- - - DisplayName	Name of the part owner	String
- - - ID	ID of the part owner in the format of qcs::cam::uin/<owneruin>:uin/<subuin>. For the root account, <OwnerUin> and <SubUin> have the same value.	String
- - Initiated	Starting time of the multipart upload	String

Initializing a multipart upload

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

js
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

Parameter	Description	Type	Required
Bucket	Bucket name in the format: 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
CacheControl	Cache policy as defined in RFC 2616. It will be stored as the object metadata.	String	No
Content-Disposition	Filename as defined in RFC 2616. It will be stored as the object metadata.	String	No
ContentEncoding	Encoding format as defined in RFC 2616. It will be stored as the object metadata.	String	No
ContentType	Content type (MIME) as defined in RFC 2616. It will be stored as the object metadata.	String	No
Expires	Cache expiration time as defined in RFC 2616. It will be stored as the object metadata.	String	No
ACL	Defines the ACL attribute of the object. For the enumerated values, such as default, private, and public-read, please see the Preset ACL section in ACL Overview. Default value: default Note: If you do not need access control for the object, set default for this parameter or leave it empty. In this way, the object will inherit the permissions of the bucket it is stored in.	String	No
GrantRead	Grants the grantee Read access in the format of id=" ",id=" ". To authorize a sub-account, use id="qcs::cam::uin/<owneruin>:uin/<subuin>". To authorize a root account, use id="qcs::cam::uin/<owneruin>:uin/<owneruin>". Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'	String	No
GrantFullControl	Grants the grantee Read/Write access in the format of id=" ",id=" ". To authorize a sub-account, use id="qcs::cam::uin/<owneruin>:uin/<subuin>". To authorize a root account, use id="qcs::cam::uin/<owneruin>:uin/<owneruin>". Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'	String	No
StorageClass	Storage class of the object. For the enumerated values, such as STANDARD (default), STANDARD_IA and ARCHIVE, please see Storage Class Overview.	String	No
x-cos-meta-*	User-defined headers, which will be returned as the object metadata. The maximum size is 2 KB.	String	No

Callback function description

function(err, data) { ... }

Parameter Name	Description	Type
err	Object returned when an error (network error or service error) occurs. If the request is successful, this parameter is left empty. For more information, please see Error Codes.	Object
data	Object returned when the request is successful. If the request fails, this parameter is left empty.	Object
Bucket	Destination bucket for the multipart upload in the format of BucketName-APPID, for example. examplebucket-1250000000	String
Key	Object key (object name), the unique identifier of an object in a bucket. For more information, please see Object Overview.	String
UploadId	ID that can be used in subsequent uploads	String

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

js
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

Parameter	Description	Type	Required
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
ContentLength	HTTP request length (in bytes) as defined in RFC 2616	String	Yes
PartNumber	Part number	String	Yes
UploadId	ID of the multipart upload task	String	Yes
Body	Content of the file part to be uploaded. This parameter can be a File object or a Blob object.	String\File\Blob	Yes
Expect	If Expect: 100-continue is used, the request content will be sent only after confirmation from the server is received.	String	No
ContentMD5	Base64-encoded 128-bit MD5 checksum as defined in RFC 1864. This header is used to verify whether the file content has changed.	String	No

Callback function description

function(err, data) { ... }

Parameter	Description	Type
err	Object returned when an error (network error or service error) occurs. If the request is successful, this is null. For more information, see Error Codes	Object
- statusCode	HTTP status code returned by the request, such as "200", "403", and "404"	Number
- headers	Header information returned by the request	Object
data	Object returned when the request is successful. If the request fails, this parameter is left empty.	Object
- statusCode	HTTP status code returned by the request, such as "200", "403", and "404"	Number
- headers	Headers returned by the request	Object

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

js
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

Parameter	Description	Type	Required
Bucket	Bucket name in the format: 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
CopySource	URL path of the source object. A historical version can be specified using the URL parameter ?versionId=<versionId>.	String	Yes
PartNumber	Part number	String	Yes
UploadId	To upload an object in parts, you must first initialize the multipart upload. The response of the multipart upload initialization will carry a unique descriptor (an upload ID), which needs to be carried in the multipart upload request.	String	Yes
CopySourceRange	Byte range of the source object. The range value must be in the format of bytes=first-last, where both first and last are offsets starting from 0. For example, bytes=0-9 means that you want to copy the first 10 bytes of data of the source object. If this parameter is not specified, the entire object will be copied.	String	No
CopySourceIfMatch	If the Etag of the object is the same as the specified one, the operation will be performed; otherwise, 412 will be returned. This parameter can be used together with x-cos-copy-source-If-Unmodified-Since. If it is used together with other conditions, a conflict will be returned.	String	No
CopySourceIfNoneMatch	If the ETag of the object is different from the specified one, the operation will be performed; otherwise, 412 will be returned. This parameter can be used together with x-cos-copy-source-If-Modified-Since. If it is used together with other conditions, a conflict will be returned.	string	No
CopySourceIfUnmodifiedSince	If the object is not modified after the specified time, the operation will be performed; otherwise, 412 will be returned. This parameter can be used together with x-cos-copy-source-If-Match. If it is used together with other conditions, a conflict will be returned.	String	No
CopySourceIfModifiedSince	If the object is modified after the specified time, the operation will be performed; otherwise, 412 will be returned. This parameter can be used together with x-cos-copy-source-If-None-Match. If it is used together with other conditions, a conflict will be returned.	String	No

Callback function description

function(err, data) { ... }

Parameter	Description	Type
err	Object returned when an error (network error or service error) occurs. If the request is successful, this parameter is left empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code returned by the request, such as 200, 403, and 404	Number
- headers	Headers returned by the request	Object
data	Object returned when the request is successful. If the request fails, this parameter is left empty.	Object
- statusCode	HTTP status code returned by the request, such as 200, 403, and 404	Number
- headers	Headers returned by the request	Object
- ETag	MD5 checksum of the object, such as "22ca88419e2ed4721c23807c678adbe4c08a7880". Note that double quotation marks are required at the beginning and the end.	String
- LastModified	Last modified time of the object, in GMT format	String

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

js
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

Parameter	Description	Type	Required
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
UploadId	Multipart upload ID obtained from the Initiate Multipart Upload API	String	Yes
EncodingType	Encoding type of the returned value	String	No
MaxParts	Maximum number of parts to return at a time. Defaults to 1000.	String	No
PartNumberMarker	By default, parts are listed in UTF-8 binary order, starting from the part after the marker.	String	No

Callback function description

function(err, data) { ... }

Parameter	Description	Type
err	Object returned when an error (network error or service error) occurs. If the request is successful, this parameter is left empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code returned by the request, such as 200, 403, and 404	Number
- headers	Headers returned by the request	Object
data	Object returned when the request succeeds. If the request fails, this parameter is left empty.	Object
- statusCode	HTTP status code returned by the request, such as 200, 403, and 404	Number
- headers	Headers returned by the request	Object
- Bucket	Destination bucket for the multipart upload	String
- Encoding-type	Encoding type for the returned value	String
- Key	Object key (object name), the unique identifier of an object in a bucket. For more information, please see Object Overview	String
- UploadId	Multipart upload ID obtained from the Initiate Multipart Upload API	String
- Initiator	Initiator of the upload	Object
- - DisplayName	Name of the upload initiator	String
- - ID	ID of the upload initiator in the format of qcs::cam::uin/<owneruin>:uin/<subuin> For the root account, <OwnerUin> and <SubUin> have the same value.	String
- Owner	Information about the part owner	Object
- - DisplayName	Name of the bucket owner	String
- - ID	ID of the bucket owner. This parameter is usually the user’s UIN.	String
- StorageClass	Storage class of the parts. For the enumerated values, such as STANDARD, STANDARD_IA and ARCHIVE, please see Storage Classes Overview.	String
- PartNumberMarker	By default, parts are listed in UTF-8 binary order, starting from the part after the marker.	String
NextPartNumberMarker	If the returned list is truncated, the NextMarker returned will be the starting point of the subsequent list.	string
- MaxParts	Maximum number of entries returned at a time	String
- IsTruncated	Indicates whether the returned list is truncated. Valid values: true, false	String
- Part	Array	Part information list
- - PartNumber	Part number	String
- - LastModified	Last modified time of a part	String
- - ETag	MD5 checksum of a part	String
- - Size	Part size, in bytes	String

Completing a multipart upload

API description

This API is used to complete a multipart upload operation. 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

js
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

Parameter	Description	Type	Required
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
UploadId	ID of the upload task	String	Yes
Parts	A list of information about the parts of the multipart upload	ObjectArray	Yes
- PartNumber	Part number	String	Yes
- ETag	MD5 checksum of each part. Example: "22ca88419e2ed4721c23807c678adbe4c08a7880" Note that double quotation marks are required at the beginning and the end.	String	Yes

Callback function description

function(err, data) { ... }

Parameter	Description	Type
err	Object returned when an error (network error or service error) occurs. If the request is successful, this is null. For more information, see Error Codes	Object
- statusCode	HTTP status code returned by the request, such as "200", "403", and "404"	Number
- headers	Header information returned by the request	Object
data	Object returned when the request is successful. If the request fails, this parameter is left empty.	Object
- statusCode	HTTP status code returned by the request, such as "200", "403", and "404"	Number
- headers	Headers returned by the request	Object
- Location	Public network access endpoint of the object	String
- Bucket	Destination bucket for the multipart upload	String
- Key	Object key (object name), the unique identifier of an object in a bucket. For more information, please see Object Overview.	String
- ETag	Unique ID of the merged file in the format of "uuid-<part quantity>". Example: "22ca88419e2ed4721c23807c678adbe4c08a7880-3". Note that double quotation marks are required at the beginning and the end	String

Aborting a multipart upload

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

js
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

Parameter	Description	Type	Required
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
UploadId	Multipart upload ID obtained from the Initiate Multipart Upload API	String	Yes

Callback function description

function(err, data) { ... }

Parameter	Description	Type
err	Object returned when an error (network error or service error) occurs. If the request is successful, this is null. For more information, see Error Codes	Object
- statusCode	HTTP status code returned by the request, such as "200", "403", and "404"	Number
- headers	Header information returned by the request	Object
data	Object returned when the request is successful. If the request fails, this parameter is left empty.	Object
- statusCode	HTTP status code returned by the request, such as "200", "403", and "404"	Number
- headers	Headers returned by the request	Object

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

js
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

Parameter	Description	Type	Required
Bucket	Bucket name in the format: 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
FilePath	Path to the file to upload	String	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 and ARCHIVE, please see Storage Class Overview.	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	ID of the upload task	String	No
onHashProgress	Progress callback function for the MD5 checksum of the object. The callback parameter is the progress object progressData.	Function	No
- progressData.loaded	Size of the verified parts, in bytes	Number	No
- progressData.total	Size of the entire object, in bytes	Number	No
- progressData.speed	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	Progress callback function for file upload. The callback parameter is the progress object progressData	Function	No
- progressData.loaded	Size of the uploaded parts, in bytes	Number	No
- progressData.total	Size of the entire object, in bytes	Number	No
- progressData.speed	Upload speed, in bytes/s	Number	No
- progressData.percent	Percentage of the file copy progress, in decimal form. For example, 0.5 means 50% has been copied.	Number	No

Callback function description

function(err, data) { ... }

Parameter	Description	Type
err	Object returned when an error (network error or service error) occurs. If the request is successful, this is null. For more information, see Error Codes	Object
- statusCode	HTTP status code returned by the request, such as "200", "403", and "404"	Number
- headers	Header information returned by the request	Object
data	Object returned when the request is successful. If the request fails, this parameter is left empty.	Object
- statusCode	HTTP status code returned by the request, such as "200", "403", and "404"	Number
- headers	Headers returned by the request	Object
- Location	Public network access endpoint of the object	String
- Bucket	Destination bucket for the multipart upload	String
- Key	Object key (object name), the unique identifier of an object in a bucket. For more information, please see Object Overview.	String
- ETag	Unique ID of the merged file in the format of "uuid-<part quantity>". Example: "22ca88419e2ed4721c23807c678adbe4c08a7880-3" Note that double quotation marks are required at the beginning and the end.	String
- VersionId	The version ID will be returned for buckets that have enabled versioning. If the bucket has never enabled versioning, no value will be returned	String

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:

js
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

Parameter	Description	Type	Required
Bucket	Bucket name in the format: 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
CopySource	URL path of the source object. A historical version can be specified using the URL parameter ?versionId=<versionId>.	String	Yes
ChunkSize	Size (in bytes) of each part in the multipart copy. Defaults to 1048576 (1 MB).	Number	No
SliceSize	Specifies the minimum file size (in bytes) to use multipart copy. The default value is 5 GB. If the file size is equal to or smaller than this value, the file will be uploaded using putObjectCopy; otherwise, it will be uploaded using sliceCopyFile.	Number	No
onProgress	Callback of the upload progress. The callback parameter is the progress object progressData.	Function	No
- progressData.loaded	Size of the uploaded parts, in bytes	Number	No
- progressData.total	Size of the entire object, in bytes	Number	No
- progressData.speed	Upload speed, in bytes/s	Number	No
- progressData.percent	Percentage of the file copy progress, in decimal form. For example, 0.5 means 50% has been copied.	Number	No

Callback function description

function(err, data) { ... }

Parameter	Description	Type
err	Object returned when an error (network error or service error) occurs. If the request is successful, this is null. For more information, see Error Codes	Object
- statusCode	HTTP status code returned by the request, such as "200", "403", and "404"	Number
- headers	Header information returned by the request	Object
data	Object returned when the request is successful. If the request fails, this parameter is left empty.	Object
- statusCode	HTTP status code returned by the request, such as "200", "403", and "404"	Number
- headers	Headers returned by the request	Object
- Location	Public network access endpoint of the object	String
- Bucket	Destination bucket for the multipart upload	String
- Key	Object key (object name), the unique identifier of an object in a bucket. For more information, please see Object Overview.	String
- ETag	MD5 checksum of the merged file. Example: "22ca88419e2ed4721c23807c678adbe4c08a7880" Note that double quotation marks are required at the beginning and the end.	String
- VersionId	Returns the version ID for versioning-enabled buckets. For buckets that have never had versioning enabled, this parameter is not returned.	String

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 uploadFiles:

js
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

Parameter	Description	Type	Required
files	File list. Each item is a parameter object to be passed to putObject and sliceUploadFile.	Object	Yes
- 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 identifier of an object in a bucket. For more information, please see Object Overview.	String	Yes
- FilePath	Path to the file to upload	String	Yes
SliceSize	Specifies the minimum file size (in bytes) to use multipart upload. If the file size is equal to or smaller than this value, the file will be uploaded using putObject; otherwise, it will be uploaded using sliceUploadFile.	Number	Yes
onProgress	Upload progress calculated by averaging out the progress of all tasks	String	Yes
- progressData.loaded	Size of the uploaded parts, in bytes	Number	No
- progressData.total	Size of the entire object, in bytes	Number	No
- progressData.speed	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
onFileFinish	The completion or error callback for each file	String	Yes
- err	Upload error message	Object	No
- data	Information about the completion of object upload	Object	No
- options	Parameter information about the files that have been uploaded	Object	No

Callback function description

function(err, data) { ... }

Parameter	Description	Type
err	Object returned when an error (network error or service error) occurs. If the request is successful, this parameter is left empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code returned by the request, such as 200, 403, and 404	Number
- headers	Header information returned by the request	Object
data	Object returned when the request is successful. If the request fails, this parameter is left empty.	Object
- files	The error or data for each file	ObjectArray
- - error	Upload error message	Object
- - data	Information about the object upload completion	Object
- - options	Parameter information about files that have been uploaded	Object

Multipart download

API description

This API is used to perform multipart download. Downloading parts concurrently is supported.

Method prototype

Multipart download sample:

js
var Key = 'test.zip';
cos.downloadFile({
  Bucket: 'examplebucket-1250000000',
  Region: 'ap-beijing,
  Key: Key,
  FilePath: './' + Key, // Local path
  ChunkSize: 1024 * 1024 * 8, // Part size
  ParallelLimit: 5, // Number of concurrent parts
  RetryTimes: 3, // Number of retries for multipart download failures
  onTaskReady: function (taskId) {
      console.log(taskId);
  },
  onProgress: function (progressData) {
      console.log(JSON.stringify(progressData));
  },
}, function (err, data) {
  console.log(err || data);
});
// Cancel the download task.
// cos.emit('inner-kill-task', {TaskId: '123'});

Parameter description

Parameter	Description	Type	Required
Bucket	Bucket name, formatted as 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
FilePath	A path to store the downloaded file	String	Yes
ChunkSize	Part size	Number	No
ParallelLimit	Number of parts to download concurrently	Number	No
RetryTimes	Number of retries for multipart download failures	Number	No
onProgress	Download progress	String	No
- progressData.loaded	Size of the uploaded parts, in bytes	Number	No
- progressData.total	Size of the entire object, in bytes	Number	No
- progressData.speed	Upload speed, in bytes/s	Number	No
- progressData.percent	Percentage of the file copy progress, in decimal form. For example, 0.5 means 50% has been copied.	Number	No

Callback function description

function(err, data) { ... }

Parameter	Description	Type
err	Object returned when an error (network error or service error) occurs. If the request is successful, this parameter is left empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code returned by the request, such as 200, 403, and 404	Number
- headers	Header information returned by the request	Object
data	Data returned when the request is successful. If the request fails, this is null.	Object
- statusCode	HTTP status code returned by the request, such as 200, 304, 403, and 404	Number
- headers	Headers returned by the request	Object
Cache-Control	Cache directives as defined in RFC 2616. It will be returned only if it is contained in the object metadata or specified through the request parameter.	string
Content-Disposition	Filename as defined in RFC 2616. It will be returned only if it is contained in the object metadata or specified through the request parameter.	string
- ContentEncoding	Encoding format as defined in RFC 2616. It will be returned only if it is contained in the object metadata or specified through the request parameter.	string
Expires	Cache expiration time as defined in RFC 2616. It will be returned only if it is contained in the object metadata or specified through the request parameter.	string
- x-cos-storage-class	Storage class of the object. Enumerated values: STANDARD, STANDARD_IA, ARCHIVE Note: If this header is not returned, the storage class is automatically set to STANDARD	String
- x-cos-meta-*	User-defined metadata	String
- NotModified	This attribute will be returned if the request contains IfModifiedSince. If the file has been modified, false will be returned. If not, true will be returned.	Boolean
- ETag	MD5 checksum of the object. The value of ETag can be used to check whether the object was corrupted during the upload. Example: "09cba091df696af91549de27b8e7d0f6" Note that double quotation marks are required at the beginning and the end.	String
- VersionId	Returns the version ID for versioning-enabled buckets. For buckets that have never had versioning enabled, this parameter is not returned.	String

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 cancels an upload task by taskId.

Use case

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

Parameter description

Parameter	Description	Type	Required
taskId	ID of the upload task. When sliceUploadFile is called, TaskReady in the callback will return the taskId of the upload task.	String	Yes

Pausing an upload task

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

Use case

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

Parameter description

Parameter	Description	Type	Required
taskId	ID of the upload task. When sliceUploadFile is called, TaskReady in the callback will return the taskId of the upload task.	String	Yes

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

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

Parameter description

Parameter	Description	Type	Required
taskId	ID of the upload task. When sliceUploadFile is called, TaskReady in the callback will return the taskId of the upload task.	String	Yes