Overview

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

Simple operations

API	Operation	Description
GET Bucket (List Objects)	Querying objects	Queries some or all the objects in a bucket.
PUT Object	Uploading an object in whole	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	Checking cross-origin resource sharing (CORS) configuration	Sends a preflight request to determine whether an actual CORS request can be sent.
PUT Object - Copy	Copying an object	Copies an object to the destination path.
DELETE Object	Deleting an object	Deletes an object from a bucket.
DELETE Multiple Objects	Deleting multiple objects	Deletes multiple objects from a bucket.
POST Object restore	Restoring an archived object	Restores an archived object for access.

Multipart operations

API	Operation	Description
List Multipart Uploads	Querying multipart uploads	Queries in-progress multipart uploads.
Initiate Multipart Upload	Initializing a multipart upload	Initializes a multipart upload.
Upload Part	Uploading an object in parts	Uploads an object in parts.
Upload Part - Copy	Copying an object part	Copies a part of an object.
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 object.
Abort Multipart Upload	Aborting a multipart upload	Aborts a multipart upload and deletes the uploaded parts.

Simple Operations

Querying objects

API description

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

Samples

Sample 1. Listing all files in the a directory

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. Listing the files in the a directory 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": {}
}

Sample 3. Listing all files in a directory

var bucket = 'examplebucket-1250000000';
var region = 'ap-beijing';
var prefix = 'examplefolder/';  /* The directory/prefix of the objects to query*/
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 of BucketName-APPID.	String	Yes
Region	Bucket region. For the enumerated values, please see Regions and Access Endpoints.	String	Yes
Prefix	Key prefix to query objects by	String	No
Delimiter	Separating symbol used to group object keys, which is usually /. Objects with identical paths between Prefix or, if no Prefix is specified, the beginning of their keys, and the first delimiter are grouped together and defined as common prefixes. All common prefixes are listed.	String	No
Marker	Key of the object after which the returned list begins. Entries are listed in UTF-8 lexicographical order by default.	String	No
MaxKeys	Maximum number of entries returned in a single response, which is 1000 (the maximum value allowed) by default	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	Error code, which is returned when an error (network error or service error) occurs. If the request is successful, this parameter is empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code, such as 200, 403, and 404	Number
- headers	Headers	Object
data	Content returned when the request succeeds. If the request fails, it will be empty.	Object
- headers	Headers	Object
- statusCode	HTTP status code, such as 200, 403, and 404	Number
- Name	Bucket name in the format of BucketName-APPID, such as examplebucket-1250000000	String
- Prefix	Key prefix by which objects are queried. Returned objects are listed according to the UTF-8 lexicographical order of their keys after the prefix.	String
- Marker	The marker after which the returned list begins. By default, entries are listed in UTF-8 binary order.	String
- MaxKeys	Maximum number of entries returned in a single response	String
- Delimiter	Delimiter	String
- IsTruncated	Whether the returned list is truncated. Valid values: true; false	String
- NextMarker	Key of the object after which the next returned list begins if the list is truncated	String
- CommonPrefixes	Objects with identical paths between the specified prefix and the delimiter, which are grouped together and defined as common prefixes	ObjectArray
- - Prefix	A 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 key, i.e., object name	String
- - ETag	MD5 checksum of the object Example: "22ca88419e2ed4721c23807c678adbe4c08a7880". Note that double quotation marks are required at the beginning and the end.	String
- - Size	Object 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 the object owner in the format of qcs::cam::uin/[OwnerUin]:uin/[OwnerUin] Example: qcs::cam::uin/100000000001:uin/100000000001, where 100000000001 is the UIN	String
- - - DisplayName	Name of the object owner	String
- - StorageClass	Storage class of the object. Enumerated values: STANDARD, STANDARD_IA, ARCHIVE, DEEP_ARCHIVE. For more information, please see Storage Class Overview.	String

Uploading an object in whole

API description

This API (PUT Object) is used to upload an object to a bucket. To call this API, you must have write access to the bucket.

Note：

• The key (filename) cannot end with /; otherwise, it will be identified as a folder.
• Each root account (AAPID) can have up to 1,000 bucket ACLs and an unlimited number of object ACLs. Do not configure ACLs for an object during upload if you don’t need to control access to it. The object will inherit the permissions of its bucket by default.
• 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.

Examples

Uploading a small file

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

Uploading a string

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

Upload a Base64-encoded string

var base64Url = 'data:image/png;base64,iVBORw0KGgo.....';
var dataURLtoBlob = function (dataurl) {
   var arr = dataurl.split(',');
   var mime = arr[0].match(/:(.*?);/)[1];
   var bstr = atob(arr[1]);
   var n = bstr.length;
   var u8arr = new Uint8Array(n);
   while (n--) {
       u8arr[n] = bstr.charCodeAt(n);
   }
   return new Blob([u8arr], { type: mime });
};
// Convert to BLOB for upload
var body = dataURLtoBlob(base64Url);
cos.putObject({
   Bucket: 'examplebucket-1250000000',                               /* Required */
   Region: 'COS_REGION',     /* Bucket region. Required */
   Key: 'exampleobject.png',              /* Required */
   Body: body,
}, function(err, data) {
   console.log(err || data);
});

Creating a directory

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

Uploading a file to a specified directory

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 upload. This parameter can be a file or a BLOB.	String\File\Blob	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	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 this parameter to default or do not specify it, in which case the object will inherit the permissions of the bucket.	String	No
GrantRead	Grants a user read access to the object in the format of id="[OwnerUin]". You can use commas (,) to separate multiple users. To authorize a sub-account, use id="qcs::cam::uin/&dxlt;OwnerUin&dxgt;:uin/&dxlt;SubUin&dxgt;". To authorize a root account, use id="qcs::cam::uin/&dxlt;OwnerUin&dxgt;:uin/&dxlt;OwnerUin&dxgt;". Example: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'	String	No
GrantReadAcp	Grants a user read access to the object in the format of id="[OwnerUin]". You can use commas (,) to separate multiple users. To authorize a sub-account, use id="qcs::cam::uin/&dxlt;OwnerUin&dxgt;:uin/&dxlt;SubUin&dxgt;". To authorize a root account, use id="qcs::cam::uin/&dxlt;OwnerUin&dxgt;:uin/&dxlt;OwnerUin&dxgt;". Example: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'	String	No
GrantWriteAcp	Grants a user write access to the object in the format of id="[OwnerUin]". You can use commas (,) to separate multiple users. To authorize a sub-account, use id="qcs::cam::uin/&dxlt;OwnerUin&dxgt;:uin/&dxlt;SubUin&dxgt;". To authorize a root account, use id="qcs::cam::uin/&dxlt;OwnerUin&dxgt;:uin/&dxlt;OwnerUin&dxgt;". Example: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'	String	No
GrantFullControl	Grants a user full access in the format of id="[OwnerUin]". You can use commas (,) to separate multiple users. To authorize a sub-account, use id="qcs::cam::uin/:uin/&dxlt;SubUin&dxgt;". To authorize a root account, use id="qcs::cam::uin/&dxlt;OwnerUin&dxgt;:uin/&dxlt;OwnerUin&dxgt;". Example: '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, ARCHIVE, and DEEP_ARCHIVE, please see Storage Class Overview.	String	No
x-cos-meta-*	User-defined headers, which will be saved as the object metadata. The maximum size is 2 KB.	String	No
UploadAddMetaMd5	Sets x-cos-meta-md5 as the object’s MD5 checksum in the object's metadata during upload in the format of a 32-bit lowercase string. Example: 4d00d79b6733c9cc066584a02ed03410	String	No
TaskReady	Callback function when an upload task is created. The callback returns a taskId, which uniquely identifies the task and can be used to cancel (cancelTask), pause (pauseTask), or resume (restartTask) the task.	Function	No
- taskId	ID of the upload task	String	No
onProgress	Progress callback, whose response object is progressData	Function	No
- progressData.loaded	Size of the uploaded parts, in bytes	Number	No
- progressData.total	Size of the entire file, in bytes	Number	No
- progressData.speed	File upload speed, in bytes/s	Number	No
- progressData.percent	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	Error code, which is returned when an error (network error or service error) occurs. If the request is successful, this parameter is empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code, such as 200, 403, and 404	Number
- headers	Headers	Object
data	Object returned when the request is successful. If the request fails, this parameter is left empty.	Object
- statusCode	HTTP status code, such as 200, 403, and 404	Number
- headers	Headers	Object
- ETag	MD5 checksum of the object. The value of this parameter 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	Access address of the uploaded file	String
- VersionId	Version ID of the uploaded object if versioning is enabled for its bucket. If versioning is not enabled, this parameter is not returned.	String

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 object metadata.

Examples

cos.headObject({
   Bucket: 'examplebucket-1250000000',                               /* Required */
   Region: 'COS_REGION',     /* Bucket region. Required */
   Key: 'exampleobject', /*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
IfModifiedSince	Required modification time. Metadata is returned only if the object has been modified after the specified time. Otherwise, 304 is returned.	String	No

Callback function description

function(err, data) { ... }

Parameter	Description	Type
err	Error code, which is returned when an error (network error or service error) occurs. If the request is successful, this parameter is empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code, such as 200, 403, and 404	Number
- headers	Headers	Object
data	Content returned when the request succeeds. If the request fails, it will be empty.	Object
- statusCode	HTTP status code, such as 200 and 304. 304 is returned if no modification is made after the specified time.	Number
- headers	Headers returned by the request	Object
- x-cos-object-type	Whether an object is appendable. Enumerated values: normal, appendable. The default value normal is not displayed.	String
- x-cos-storage-class	Storage class of the object. For the enumerated values, such as STANDARD (default), STANDARD_IA, ARCHIVE, and DEEP_ARCHIVE, please see Storage Class Overview. Note that STANDARD is not displayed if returned.	String
- x-cos-meta-*	User-defined metadata	String
- NotModified	Whether an object hasn’t been modified after the specified time	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	Version ID of the uploaded object if versioning is enabled for its bucket. If versioning is not enabled, this parameter is not returned.	String

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 URLs.

API description

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

Examples

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

Getting 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

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
ResponseContentType	Content-Type parameter in the response header	String	No
ResponseContentLanguage	Content-Language in the response header	String	No
ResponseExpires	Content-Expires in the response header	String	No
ResponseCacheControl	Cache-Control in the response header	String	No
ResponseContentDisposition	Content-Disposition in the response header	String	No
ResponseContentEncoding	Content-Encoding 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 to download the first 10 bytes of the object. If this parameter is not specified, the entire object will be downloaded.	String	No
IfModifiedSince	Required modification time. The object is downloaded only if it has been modified after the specified time. Otherwise, 304 (not modified) will be returned.	String	No
If-Unmodified-Since	Required unmodified time. The object is downloaded only if it has not been modified since the specified time. Otherwise, 412 (precondition failed) will be returned.	String	No
IfMatch	ETag that must be matched. The object is downloaded only if its ETag matches the specified value. Otherwise, 412 (precondition failed) will be returned.	String	No
IfNoneMatch	ETag that cannot be matched. The object is downloaded only if its ETag does not match the specified value. Otherwise, 304 (not modified) will be returned.	String	No
VersionId	Version ID of the object to download	String	No
onProgress	Progress callback. The 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	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	Error code, which is returned when an error (network error or service error) occurs. If the request is successful, this parameter is empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code, such as 200, 403, and 404	Number
- headers	Headers	Object
data	Content returned when the request is successful. If the request fails, this parameter is empty.	Object
- statusCode	HTTP status code, such as 200, 304, 403, and 404	Number
- headers	Headers	Object
- CacheControl	Cache directives as defined in RFC 2616, which will be returned only if it is contained in the object metadata or if it is specified in the request parameter.	string
- ContentDisposition	Filename as defined in RFC 2616, which will be returned only if it is contained in the object metadata or if it is specified in the request parameter	String
- ContentEncoding	Encoding format as defined in RFC 2616, which will be returned only if it is contained in the object metadata or if it is specified in the request parameter	String
- Expires	Cache expiration time as defined in RFC 2616, which will be returned only if it is contained in the object metadata or if it is specified in the request parameter	String
- x-cos-storage-class	Storage class of the object. For the enumerated values, such as STANDARD and STANDARD_IA, please see Storage Class Overview. Note: If this header is not returned, the storage class is STANDARD.	String
- x-cos-meta-*	User defined metadata	String
- NotModified	This field is returned if the request has IfModifiedSince. If the file hasn’t been modified after the specified time, true is returned. If not, false is returned.	Boolean
- ETag	MD5 checksum of the object. The value of this parameter 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	Version ID of the uploaded object if versioning is enabled for its bucket. If versioning is not enabled, this parameter is not returned.	String
- Body	Returned file content, in string format by default	String

Checking CORS configuration

API description

This API (OPTIONS Object) is used to send a preflight request to check the CORS configuration of an object. Before making an actual CORS request, you can send an OPTIONS request that includes the source origin, HTTP method, and headers to COS to determine whether an actual 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.

Examples

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

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
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	Error code, which is returned when an error (network error or service error) occurs. If the request is successful, this parameter is empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code, such as 200, 403, and 404	Number
- headers	Headers	Object
data	Content returned when the request is successful. If the request fails, this parameter is empty.	Object
- headers	Headers	Object
- statusCode	HTTP status code, 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	Headers (separated by commas) returned if CORS is supported. Example: ETag	String
- AccessControlMaxAge	The validity duration of results returned by the OPTIONS request, e.g. 3600	String
- OptionsForbidden	Whether the OPTIONS request is forbidden. It is true if the HTTP status code 403 is returned.	Boolean

Copying an object

API description

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

Note：

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

Examples

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

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
CopySource	URL of the source object. You can specify a previous version using the URL parameter ?versionId=&dxlt;versionId>.	String	Yes
ACL	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 this parameter to default or do not specify it, in which case the object will inherit the permissions of its bucket.	String	No
GrantRead	Grants a user read access to the object in the format of id="[OwnerUin]". You can use commas (,) to separate multiple users. To authorize a sub-account, use id="qcs::cam::uin/&dxlt;OwnerUin&dxgt;:uin/&dxlt;SubUin&dxgt;". To authorize a root account, use id="qcs::cam::uin/&dxlt;OwnerUin&dxgt;:uin/&dxlt;OwnerUin&dxgt;". Example: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'	String	No
GrantWrite	Grants a user write access to the object in the format of id="[OwnerUin]". You can use commas (,) to separate multiple users. To authorize a sub-account, use id="qcs::cam::uin/&dxlt;OwnerUin&dxgt;:uin/&dxlt;SubUin&dxgt;". To authorize a root account, use id="qcs::cam::uin/&dxlt;OwnerUin&dxgt;:uin/&dxlt;OwnerUin&dxgt;". Example: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'	String	No
GrantFullControl	Grants a user full access in the format of id="[OwnerUin]". You can use commas (,) to separate multiple users. To authorize a sub-account, use id="qcs::cam::uin/&dxlt;OwnerUin&dxgt;:uin/&dxlt;SubUin&dxgt;". To authorize a root account, use id="qcs::cam::uin/&dxlt;OwnerUin&dxgt;:uin/&dxlt;OwnerUin&dxgt;". Example: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'	String	No
MetadataDirective	Whether to copy the metadata. Enumerated values: Copy (default), Replaced. If it is set to Copy, the metadata of the source object will be copied and the user-defined metadata in the header will be ignored. If it is 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, if you want to modify the metadata, this parameter must be set to Replaced.	String	No
CopySourceIfModifiedSince	Required modification time. The object is copied only if it has been modified after the specified time. Otherwise, 412 will be returned. This parameter can be used together with CopySourceIfNoneMatch. Using it together with other conditions may cause a conflict.	String	No
CopySourceIfUnmodifiedSince	Required unmodified time. The object is copied only if it hasn’t been modified since the specified time. Otherwise, 412 will be returned. This parameter can be used together with CopySourceIfMatch. Using it together with other conditions may cause a conflict.	String	No
CopySourceIfMatch	ETag that must be matched. The object is copied only if its ETag matches the specified value. Otherwise, 412 will be returned. This parameter can be used together with CopySourceIfUnmodifiedSince. Using it together with other conditions may cause a conflict.	String	No
CopySourceIfNoneMatch	ETag that cannot be matched. The object is copied only if its ETag does not match the specified value. Otherwise, 412 will be returned. This parameter can be used together with CopySourceIfModifiedSince. Using it together with other conditions may cause a conflict.	string	No
StorageClass	Storage class of the object. For the enumerated values, such as STANDARD (default) and STANDARD_IA, please see Storage Class Overview.	String	No
x-cos-meta-*	Other user-defined file headers	String	No

Callback function description

function(err, data) { ... }

Parameter	Description	Type
err	Error code, which is returned when an error (network error or service error) occurs. If the request is successful, this parameter is empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code, such as 200, 403, and 404	Number
- headers	Headers	Object
data	Content returned when the request is successful. If the request fails, this parameter is empty.	Object
- statusCode	HTTP status code, such as 200, 403, and 404	Number
- headers	Headers	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	Version ID of the uploaded object if versioning is enabled for its bucket. If versioning is not enabled, this parameter is not returned.	String

Deleting an object

API description

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

Examples

cos.deleteObject({
   Bucket: 'examplebucket-1250000000',                               /* Required */
   Region: 'COS_REGION',     /* Bucket region. Required */
   Key: 'exampleobject'        /* 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
VersionId	Version ID of the object or delete marker to delete	String	No

Callback function description

function(err, data) { ... }

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

Deleting multiple objects

API description

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

Examples

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

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

var bucket: 'examplebucket-1250000000'; /* Required */
var region: 'ap-beijing';     /* Region of the bucket (required) */
var prefix = 'examplefolder/';  /* The directory/prefix of the objects to delete */
var deleteFiles = 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') deleteFiles(nextMarker);
              else console.log('delete complete');
          }
      });
  });
}
deleteFiles();

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
Quiet	Whether to use the Quiet mode. If it is set to true, the Quiet mode is enabled. If it is set to false (default), the Verbose mode is enabled.	Boolean	No
Objects	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	Error code, which is returned when an error (network error or service error) occurs. If the request is successful, this parameter is empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code, such as 200, 204, 403, and 404	Number
- headers	Headers	Object
data	Content returned when the request is successful. If the request fails, this parameter is empty.	Object
- statusCode	HTTP status code, such as 200, 204, 403, and 404	Number
- headers	Headers	Object
- Deleted	List of objects deleted successfully	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 deleted.	String
- - DeleteMarker	If versioning is enabled and the VersionId parameter is not specified, the deletion will not actually delete the file; instead, it will only add a new delete marker, indicating that the visible file has been deleted. Enumerated values: true, false	String
- - DeleteMarkerVersionId	VersionId of the newly added delete marker if DeleteMarker is true	String
- Error	List of objects whose deletion failed	ObjectArray
- - Key	Object key (object name), the unique identifier of an object in a bucket. For more information, please see Object Overview.	String
- - Code	Error code for failed deletion	String
- - Message	Error message for failed deletion	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 set the time during which the temporary object remains readable and the time to delete it. You can use the Days parameter to specify the expiration time of the temporary object. If you have not performed any operation on the object, such as copying it or extending its validity period, when it expires, the temporary object will be automatically deleted. A temporary object is only a copy of the archived object. The source object continues to exist throughout this period.

Examples

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

Parameter description

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
RestoreRequest	A container for data restoration	Object	Yes
- Days	Expiration time of the temporary copy	Number	Yes
- CASJobParameters	A container for the archive job parameters	Object	Yes
- - Tier	Restoration mode. Valid values: Standard, which completes a restoration task in 3-5 hours; Expedited, which completes a restoration job in 15 minutes; Bulk, which completes multiple restoration tasks in 5-12 hours	String	Yes

Callback function description

function(err, data) { ... }

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

Multipart Operations

Querying multipart uploads

API description

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

Examples

Getting a list of UploadId of uploads with the object key prefix exampleobject

cos.multipartList({
   Bucket: 'examplebucket-1250000000',                               /* Required */
   Region: 'COS_REGION',     /* Bucket 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	Object key prefix to query uploads by. Note that when you query uploads with the prefix specified, the returned object keys will also contain the prefix.	String	No
Delimiter	Separating symbol used to group object keys, which is usually /. Objects with identical paths between Prefix or, if no Prefix is specified, the beginning of their keys, and the first delimiter are grouped together and defined as common prefixes. All common prefixes are listed.	String	No
EncodingType	Encoding type of the returned value. Valid value: url	String	No
MaxUploads	Maximum number of entries to return at a time. Valid range: 1-1000 (default)	String	No
KeyMarker	This parameter is 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 whose UploadID is greater than the specified upload-id-marker will be listed.	String	No
UploadIdMarker	This parameter is 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 lexicographically equal to the specified key-marker and whose UploadID is greater than the specified upload-id-marker will be listed.	String	No

Callback function description

function(err, data) { ... }

Parameter	Description	Type
err	Error code, which is returned when an error (network error or service error) occurs. If the request is successful, this parameter is empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code, such as 200, 403, and 404	Number
- headers	Headers	Object
data	Content returned when the request is successful. If the request fails, this parameter is empty.	Object
- statusCode	HTTP status code, such as 200, 403, and 404	Number
- headers	Headers	Object
- Bucket	Destination bucket for the multipart upload	String
- Encoding-Type	Encoding type of the returned value. Valid value: url	String
- KeyMarker	The key after which the returned listing begins	String
- UploadIdMarker	The UploadId after which the returned list begins	String
- NextKeyMarker	The key after which the next returned list begins if the list is truncated	String
- NextUploadIdMarker	The UploadId after which the next returned list begins if the list is truncated	String
- MaxUploads	The maximum number of returned entries. Valid value range: 1-1000	String
- IsTruncated	Whether the returned list is truncated. Valid value: true; false	String
- Prefix	Object key prefix by which uploads are queried	String
Delimiter	Separating symbol used to group object keys, which is usually /. Objects with identical paths between Prefix or, if no Prefix is specified, the beginning of their keys, and the first delimiter are grouped together and defined as common prefixes. All common prefixes are listed.	String
- CommonPrefixs	Objects with identical paths between Prefix and the delimiter, which are grouped together and defined as common prefixes	ObjectArray
- - Prefix	Specific prefixes	String
- Upload	Information of the multipart uploads	ObjectArray
- - Key	Name of the object, i.e. object key	String
- - UploadId	ID of the multipart upload	String
- - StorageClass	Storage class of the parts. For the enumerated values, such as STANDARD, STANDARD_IA, ARCHIVE, and DEEP_ARCHIVE, please see Storage Class Overview.	String
- - Initiator	Initiator of the multipart 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 root accounts, &dxlt;OwnerUin> and &dxlt;SubUin> have the same value.	String
- - Owner	Owner of the parts	Object
- - - DisplayName	Name of the part owner	String
- - - ID	ID of the parts owner in the format of qcs::cam::uin/<owneruin>:uin/<subuin>. For root accounts, &dxlt;OwnerUin> and &dxlt;SubUin> have the same value.	String
- - Initiated	Start time of the multipart upload	String

Initializing a multipart upload

API description

This API (Initiate Multipart Upload) is used to initialize a multipart upload. After a successful initialization operation, an upload ID will be returned, which is required for the subsequent Upload Part request.

Examples

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

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
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	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 this parameter to default or do not specify it, in which case the object will inherit the permissions of its bucket.	String	No
GrantRead	Grants a user read access to the object in the format of id="[OwnerUin]". You can use commas (,) to separate multiple users. To authorize a sub-account, use id="qcs::cam::uin/&dxlt;OwnerUin&dxgt;:uin/&dxlt;SubUin&dxgt;". To authorize a root account, use id="qcs::cam::uin/&dxlt;OwnerUin&dxgt;:uin/&dxlt;OwnerUin&dxgt;". Example: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'	String	No
GrantFullControl	Grants a user full access in the format of id="[OwnerUin]". You can use commas (,) to separate multiple users. To authorize a sub-account, use id="qcs::cam::uin/&dxlt;OwnerUin&dxgt;:uin/&dxlt;SubUin&dxgt;". To authorize a root account, use id="qcs::cam::uin/&dxlt;OwnerUin&dxgt;:uin/&dxlt;OwnerUin&dxgt;". Example: '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, ARCHIVE, and DEEP_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
UploadAddMetaMd5	Sets x-cos-meta-md5 as the object’s MD5 checksum in the object’s metadata during upload in the format of a 32-bit lowercase string. Example: 4d00d79b6733c9cc066584a02ed03410	String	No

Callback function description

function(err, data) { ... }

Parameter	Description	Type
err	Error code, which is returned when an error (network error or service error) occurs. If the request is successful, this parameter is empty. For more information, please see Error Codes.	Object
data	Content returned when the request is successful. If the request fails, this parameter is empty.	Object
Bucket	Name of the destination bucket for the multipart upload. The value is formed by connecting a user-defined string and the system-generated APPID with a hyphen, 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	Upload ID, which is required for the subsequent upload	String

Uploading parts

API description

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

• After calling the Initiate Multipart Upload API to initialize a multipart upload, you will get an upload ID. This ID uniquely identifies the part and marks its position in the object.
• Every time you call the Upload Part API, you need to pass in 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, 404 (NoSuchUpload) will be returned.

Examples

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

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	String	Yes
Body	Content of the part to upload This parameter can be a file or a BLOB.	String\File\Blob	Yes
Expect	HTTP request length (in bytes) defined in RFC 2616. 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	Error code, which is returned when an error (network error or service error) occurs. If the request is successful, this parameter is empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code, such as 200, 403, and 404	Number
- headers	Headers	Object
data	Content returned when the request is successful. If the request fails, this parameter is empty.	Object
- statusCode	HTTP status code, such as 200, 403, and 404	Number
- headers	Headers	Object

Copying an object part

API description

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

Note：

To copy an object part, you must first initialize a multipart upload, after which a unique upload ID will be returned. This ID is required in the copy request.

Examples

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

Parameter description

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
CopySource	URL of the source object. You can specify a previous version using the URL parameter ?versionId=<versionid>.	String	Yes
PartNumber	Part number	String	Yes
uploadId	To copy an object part, you must first initialize a multipart upload, after which a unique upload ID will be returned. This ID is required in the copy 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 to copy the first 10 bytes of the source object. If this parameter is not specified, the entire object will be copied.	String	No
CopySourceIfMatch	Etag that must be matched. The part will be copied only if its ETag matches the specified value. Otherwise, 412 will be returned. This parameter can be used together with x-cos-copy-source-If-Unmodified-Since. Using it together with other conditions may cause a conflict.	String	No
CopySourceIfNoneMatch	ETag that cannot be matched. The part is copied only if its ETag does not match the specified value. Otherwise, 412 will be returned. This parameter can be used together with x-cos-copy-source-If-Modified-Since. Using it together with other conditions may cause a conflict.	string	No
CopySourceIfUnmodifiedSince	Required unmodified time. The object is copied only if it hasn’t been modified since the specified time. Otherwise, 412 will be returned. This parameter can be used together with x-cos-copy-source-If-Match. Using it together with other conditions may cause a conflict.	String	No
CopySourceIfModifiedSince	Required modification time. The object is copied only if it has been modified after the specified time. Otherwise, 412 will be returned. This parameter can be used together with x-cos-copy-source-If-None-Match. Using it together with other conditions may cause a conflict.	String	No

Callback function description

function(err, data) { ... }

Parameter	Description	Type
err	Error code, which is returned when an error (network error or service error) occurs. If the request is successful, this parameter is empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code, such as 200, 403, and 404	Number
- headers	Headers	Object
data	Content returned when the request is successful. If the request fails, this parameter is empty.	Object
- statusCode	HTTP status code, such as 200, 403, and 404	Number
- headers	Headers	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 the specified uploadId.

Examples

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

Parameter description

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, which is obtained from the response of the Initiate Multipart Upload API	String	Yes
EncodingType	Encoding type of the returned value	String	No
max-parts	Maximum number of parts to return at a time. Default: 1000	string	No
PartNumberMarker	The marker after which the returned list begins. By default, entries are listed in UTF-8 binary order.	String	No

Callback function description

function(err, data) { ... }

Parameter	Description	Type
err	Error code, which is returned when an error (network error or service error) occurs. If the request is successful, this parameter is empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code, such as 200, 403, and 404	Number
- headers	Headers	Object
data	Content returned when the request is successful. If the request fails, this parameter is empty.	Object
- statusCode	HTTP status code, such as 200, 403, and 404	Number
- headers	Headers	Object
- Bucket	Destination bucket for the multipart upload	String
EncodingType	Encoding type of 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	ID of the multipart upload	String
- Initiator	Initiator of the multipart 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 root accounts, &dxlt;OwnerUin> and &dxlt;SubUin> have the same value.	String
- Owner	Owner of the parts	Object
- - DisplayName	Name of the bucket owner	String
- - ID	Bucket owner ID, generally the user's UIN	String
- StorageClass	Storage class of the parts. For the enumerated values, such as STANDARD, STANDARD_IA, ARCHIVE, and DEEP_ARCHIVE, please see Storage Classes Overview.	String
- PartNumberMarker	The marker after which the returned list begins. By default, entries are listed in UTF-8 binary order.	String
NextPartNumberMarker	The part after which the next returned list begins if the list is truncated	String
- MaxUploads	The maximum number of entries returned in a single request	String
- IsTruncated	Whether the returned list is truncated. Valid value: true; false	String
- Part	Parts information list	ObjectArray
- - PartNumber	Part number	String
- - LastModified	Last modified time of the part	String
- - ETag	MD5 algorithm checksum of the part	String
- - Size	Part size, in bytes	String

Completing a multipart upload

API description

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

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

Note：

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

Examples

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

Parameter description

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	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	Error code, which is returned when an error (network error or service error) occurs. If the request is successful, this parameter is empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code, such as 200, 403, and 404	Number
- headers	Headers	Object
data	Content returned when the request is successful. If the request fails, this parameter is empty.	Object
- statusCode	HTTP status code, such as 200, 403, and 404	Number
- headers	Headers	Object
- Location	Access address of the uploaded file	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 file after assembly 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 in-progress upload request with the specified UploadId, the upload 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.

Examples

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

Parameter description

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
UploadId	Multipart upload ID, which is obtained from the response of the Initiate Multipart Upload API	String	Yes

Callback function description

function(err, data) { ... }

Parameter	Description	Type
err	Error code, which is returned when an error (network error or service error) occurs. If the request is successful, this parameter is empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code, such as 200, 403, and 404	Number
- headers	Headers	Object
data	Content returned when the request is successful. If the request fails, this parameter is empty.	Object
- statusCode	HTTP status code, such as 200, 403, and 404	Number
- headers	Headers	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 resuming upload tasks.

Advanced upload

API description

This API is used to implement an advanced upload. You can use the SliceSize parameter to specify a file size threshold (1 MB by default). If a file is larger than this threshold, it will be uploaded in parts; otherwise, it will be uploaded in whole.

Examples

cos.uploadFile({
   Bucket: 'examplebucket-1250000000',                               /* Required */
   Region: 'COS_REGION',     /* Bucket region. Required */
   Key: 'exampleobject',              /* Required */
   Body: fileObject,               /*Required*/
   SliceSize: 1024 * 1024 * 5,     /* Threshold (5 MB in this example) to trigger multipart upload. Optional */
   TaskReady: function(taskId) { /*Optional*/
       console.log(taskId);
   },
   onProgress: function (progressData) { /* Optional */
       console.log(JSON.stringify(progressData));
   },
   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
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 upload, which can be a file or a BLOB	File\Blob	Yes
SliceSize	File size threshold in bytes, 1048576 (1 MB) by default. 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	No
AsyncLimit	Maximum number of concurrently uploaded parts allowed. This parameter is valid only when a multipart upload is triggered.	Number	No
StorageClass	Storage class of the object. For the enumerated values, such as STANDARD, STANDARD_IA, ARCHIVE, and DEEP_ARCHIVE, please see Storage Class Overview.	String	No
UploadAddMetaMd5	Sets x-cos-meta-md5 as the object’s MD5 checksum in the object’s metadata during upload in the format of a 32-bit lowercase string. Example: 4d00d79b6733c9cc066584a02ed03410	String	No
onTaskReady	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 resume (restartTask) the task.	Function	No
- taskId	ID of the upload task	String	No
onProgress	Callback for the upload progress, whose parameter is progressData	Function	No
- progressData.loaded	Size of the uploaded parts, in bytes	Number	No
- progressData.total	Size of the entire file, in bytes	Number	No
- progressData.speed	File upload speed, in bytes/s	Number	No
- progressData.percent	File upload progress, in decimal form. For example, 0.5 means 50% has been uploaded.	Number	No
onFileFinish	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	Error code, which is returned when an error (network error or service error) occurs. If the request is successful, this parameter is empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code, such as 200, 403, and 404	Number
- headers	Headers	Object
data	Content returned when the request is successful. If the request fails, this parameter is empty.	Object
- statusCode	HTTP status code, such as 200, 403, and 404	Number
- headers	Headers	Object
- Location	Access address of the uploaded file	String
- Bucket	Destination bucket for the multipart upload. This parameter is returned only when a multipart upload is triggered.	String
- Key	Object key (object name), a unique ID of an object in a bucket. For more information, see Object Overview > Object Key. This parameter is returned only when multipart upload is triggered.	String
- ETag	Unique ID of the file after assembly 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	Version ID of the uploaded object if versioning is enabled for its bucket. If versioning is not enabled, this parameter is not returned.	String

Uploading an object in parts

API description

This API (Slice Upload File) is used to upload large files in parts.

Note：

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

Examples

cos.sliceUploadFile({
   Bucket: 'examplebucket-1250000000',                               /* Required */
   Region: 'COS_REGION',     /* Bucket region. Required */
   Key: 'exampleobject',              /* Required */
   Body: fileObject,               /*Required*/
   TaskReady: function(taskId) { /*Optional*/
       console.log(taskId);
   },
   onHashProgress: function (progressData) { /* Optional */
       console.log(JSON.stringify(progressData));
   },
   onProgress: function (progressData) { /* Optional */
       console.log(JSON.stringify(progressData));
   }
}, function(err, data) {
   console.log(err || data);
});

Parameter description

Parameter	Description	Type	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 upload, which can be a file or a BLOB	File\Blob	Yes
SliceSize	Part size	Number	No
AsyncLimit	Maximum number of concurrently uploaded parts allowed	String	No
StorageClass	Storage class of the object. For the enumerated values, such as STANDARD, STANDARD_IA, ARCHIVE, and DEEP_ARCHIVE, please see Storage Class Overview.	String	No
UploadAddMetaMd5	Sets x-cos-meta-md5 as the object’s MD5 checksum in the object’s metadata during upload in the format of a 32-bit lowercase string. Example: 4d00d79b6733c9cc066584a02ed03410	String	No
onTaskReady	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 resume (restartTask) the task.	Function	No
- taskId	ID of the upload task	String	No
onHashProgress	Callback for the progress of MD5 checksum calculation, whose parameter is progressData	Function	No
- progressData.loaded	Size of the verified parts, in bytes	Number	No
- progressData.total	Size of the entire file, in bytes	Number	No
- progressData.speed	File verification speed in bytes/s	Number	No
- progressData.percent	Percentage of the file verification progress, in decimal form. For example, 0.5 means 50% has been verified.	Number	No
onProgress	Callback for the upload progress, whose parameter is progressData	Function	No
- progressData.loaded	Size of the uploaded parts, in bytes	Number	No
- progressData.total	Size of the entire file, in bytes	Number	No
- progressData.speed	File upload speed, in bytes/s	Number	No
- progressData.percent	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	Error code, which is returned when an error (network error or service error) occurs. If the request is successful, this parameter is empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code, such as 200, 403, and 404	Number
- headers	Headers	Object
data	Content returned when the request is successful. If the request fails, this parameter is empty.	Object
- statusCode	HTTP status code, such as 200, 403, and 404	Number
- headers	Headers	Object
- Location	Access address of the uploaded file	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 file after assembly 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	Version ID of the uploaded object if versioning is enabled for its bucket. If versioning is not enabled, this parameter is not 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 in parts. During the process, the object metadata and ACL can be modified. You can use this API to move, rename, and copy a file, as well as modify its attributes.

Method prototype

Calling Slice Copy File

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

Parameter description

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
CopySource	URL of the source object. You can specify a previous version using the URL parameter ?versionId=<versionid>.	String	Yes
ChunkSize	Size (in bytes) of each part in the multipart copy. Default: 1048576 (1 MB)	Number	No
SliceSize	File size threshold in bytes, 5 GB by default. 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 for the upload progress, whose parameter is progressData	Function	No
- progressData.loaded	Size of the uploaded parts, in bytes	Number	No
- progressData.total	Size of the entire file, in bytes	Number	No
- progressData.speed	File upload speed, in bytes/s	Number	No
- progressData.percent	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	Error code, which is returned when an error (network error or service error) occurs. If the request is successful, this parameter is empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code, such as 200, 403, and 404	Number
- headers	Headers	Object
data	Content returned when the request is successful. If the request fails, this parameter is empty.	Object
- statusCode	HTTP status code, such as 200, 403, and 404	Number
- headers	Headers	Object
- Location	Access address of the uploaded file	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 file after assembly. Example: "22ca88419e2ed4721c23807c678adbe4c08a7880". Note that double quotation marks are required at the beginning and the end.	String
- VersionId	Version ID of the uploaded object if versioning is enabled for its bucket. If versioning is not enabled, this parameter is not returned.	String

Batch upload

API description

Method 1:
You can call putObject or sliceUploadFile multiple times to implement batch uploads. Instantiate the FileParallelLimit parameter to limit the maximum number (default value: 3) of concurrently uploaded files allowed.

Method 2:
You can also call cos.uploadFiles to implement batch uploads. The SliceSize parameter can be used to determine whether to use sliceUploadFile. See below for how to use the uploadFiles method.

Method prototype

Calling uploadFiles

cos.uploadFiles({
   files: [{
       Bucket: 'examplebucket-1250000000', // Format: BucketName-APPID
       Region: 'COS_REGION',     /* Bucket region. Required */
       Key: 'exampleobject',
       Body: fileObject1,
       onTaskReady: function(taskId) {
         /* Based on `taskId`, you can use queue operations to cancel upload `cos.cancelTask(taskId)`, pause upload `cos.pauseTask(taskId)`, and resume upload `cos.restartTask(taskId)` */
         console.log(taskId);
       }
   }, {
       Bucket: 'examplebucket-1250000000', // Format: BucketName-APPID
       Region: 'COS_REGION',     /* Bucket region. Required */
       Key: 'exampleobject2',
       Body: fileObject2,
       onTaskReady: function(taskId) {
       /* Based on `taskId`, you can use queue operations to cancel upload `cos.cancelTask(taskId)`, pause upload `cos.pauseTask(taskId)`, and resume upload `cos.restartTask(taskId)` */
       console.log(taskId);
     }
   }],
   SliceSize: 1024 * 1024 * 10,    /* Set the file size threshold to trigger a multipart upload to 10 MB */
   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
- Body	Content of the file to upload, which can be a file or a BLOB	File\Blob	Yes
- onTaskReady	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 resume (restartTask) the task.	Function	No
-- taskId	ID of the upload task	String	No
SliceSize	File size threshold in bytes, 1048576 (1 MB) by default. If the file size is equal to or smaller than this value, it will be uploaded using putObject; otherwise, it will be uploaded using sliceUploadFile.	Number	Yes
AsyncLimit	Maximum number of concurrently uploaded parts allowed. This parameter is valid only when a multipart upload is triggered.	Number	No
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 file, in bytes	Number	No
- progressData.speed	File upload speed, in bytes/s	Number	No
- progressData.percent	File upload progress, in decimal form. For example, 0.5 means 50% has been uploaded.	Number	No
onFileFinish	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	Error code, which is returned when an error (network error or service error) occurs. If the request is successful, this parameter is empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code, such as 200, 403, and 404	Number
- headers	Headers	Object
data	Content returned when the request is successful. If the request fails, this parameter is empty.	Object
- files	Error or data for each file	ObjectArray
- - error	Upload error message	Object
- - data	Information about the completion of object upload	Object
- - options	Parameter information about the files that have been uploaded	Object

Uploading queue

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

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

For detailed instructions on ohow to use the upload queue, please see Queue Demo.

Canceling an upload task

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

Example

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

Parameter description

Parameter	Description	Type	Required
taskId	ID of the upload task. When sliceUploadFile is called, the taskId is returned via the TaskReadycallback.	String	Yes

Pausing an upload task

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

Example

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

Parameter description

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

Resuming an upload task

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

Example

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

Parameter description

Parameter	Description	Type	Required
taskId	ID of the upload task. When `sliceUploadFile` is called, the `taskId` is returned via the `TaskReady` callback.	String	Yes