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 | Uploading 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 | Configuring a pre-flight request for CORS | Sends a pre-flight request to confirm whether a real CORS 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 an 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 |
Upload Part | Uploading a part | Uploads a part in a multipart upload |
Upload Part - Copy | Copying a part | Copies an object as part |
List Parts | Querying parts | Queries uploaded parts in 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 |
This API is used to query some or all objects in a bucket.
Sample 1. List all files in directory a
.
cos.getBucket({
Bucket: 'examplebucket-1250000000', /*Required*/
Region: 'COS_REGION', /* Required */
Prefix: 'a/', /*Optional*/
}, function(err, data) {
console.log(err || data.Contents);
});
Response:
{
"Name": "examplebucket-1250000000",
"Prefix": "",
"Marker": "a/",
"MaxKeys": "1000",
"Delimiter": "",
"IsTruncated": "false",
"Contents": [{
"Key": "a/3mb.zip",
"LastModified": "2018-10-18T07:08:03.000Z",
"ETag": "\"05a9a30179f3db7b63136f30aa6aacae-3\"",
"Size": "3145728",
"Owner": {
"ID": "1250000000",
"DisplayName": "1250000000"
},
"StorageClass": "STANDARD"
}],
"statusCode": 200,
"headers": {}
}
Sample 2. List the files in directory a
without deep traversal.
cos.getBucket({
Bucket: 'examplebucket-1250000000', /*Required*/
Region: 'COS_REGION',/*Required*/
Prefix: 'a/', /*Optional*/
Delimiter: '/', /* Optional */
}, function(err, data) {
console.log(err || data.CommonPrefixes);
});
Response:
{
"Name": "examplebucket-1250000000",
"Prefix": "a/",
"Marker": "",
"MaxKeys": "1000",
"Delimiter": "/",
"IsTruncated": "false",
"CommonPrefixes": [{
"Prefix": "a/1/"
}],
"Contents": [{
"Key": "a/3mb.zip",
"LastModified": "2018-10-18T07:08:03.000Z",
"ETag": "\"05a9a30179f3db7b63136f30aa6aacae-3\"",
"Size": "3145728",
"Owner": {
"ID": "1250000000",
"DisplayName": "1250000000"
},
"StorageClass": "STANDARD"
}],
"statusCode": 200,
"headers": {}
}
Parameter | Description | 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 | 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 |
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 |
- 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, entries are listed in UTF-8 binary order starting from the entry 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 key, i.e., object name | 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 |
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:
- 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. 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.- 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.
Simple upload is suitable for uploading small files.
const filePath = "temp-file-to-upload" // Local file path
cos.putObject({
Bucket: 'examplebucket-1250000000', /*Required*/
Region: 'COS_REGION', /* Required */
Key: 'exampleobject', /*Required*/
StorageClass: 'STANDARD',
Body: fs.createReadStream(filePath), // Upload file object
onProgress: function(progressData) {
console.log(JSON.stringify(progressData));
}
}, function(err, data) {
console.log(err || data);
});
Upload the buffer as the file content:
cos.putObject({
Bucket: 'examplebucket-1250000000', /*Required*/
Region: 'COS_REGION', /* Required */
Key: 'exampleobject', /*Required*/
Body: Buffer.from('hello!'), /*Required*/
}, function(err, data) {
console.log(err || data);
});
Upload a string as the file content:
cos.putObject({
Bucket: 'examplebucket-1250000000', /*Required*/
Region: 'COS_REGION', /* Required */
Key: 'exampleobject', /*Required*/
Body: 'hello!',
}, function(err, data) {
console.log(err || data);
});
Create a directory:
cos.putObject({
Bucket: 'examplebucket-1250000000', /*Required*/
Region: 'COS_REGION', /* Required */
Key: 'a/', /*Required*/
Body: '',
}, function(err, data) {
console.log(err || data);
});
Parameter | Description | 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 |
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. 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 |
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.
This API is used to query the metadata of an object.
cos.headObject({
Bucket: 'examplebucket-1250000000', /*Required*/
Region: 'COS_REGION', /* Required */
Key: 'exampleobject', /*Required*/
}, function(err, data) {
console.log(err || data);
});
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 | If the object is modified after the specified time, the corresponding object metadata will be returned; otherwise, 304 will be returned. | String | No |
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 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 |
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
.
cos.getObject({
Bucket: 'examplebucket-1250000000', /*Required*/
Region: 'COS_REGION', /* Required */
Key: 'exampleobject', /*Required*/
}, function(err, data) {
console.log(err || data.Body);
});
Get the file content with Range
specified:
cos.getObject({
Bucket: 'examplebucket-1250000000', /*Required*/
Region: 'COS_REGION', /* Required */
Key: 'exampleobject', /*Required*/
Range: 'bytes=1-3', /*Optional*/
}, function(err, data) {
console.log(err || data.Body);
});
Download the file to a specified path:
cos.getObject({
Bucket: 'examplebucket-1250000000', /*Required*/
Region: 'COS_REGION', /* Required */
Key: 'exampleobject', /*Required*/
Output: './exampleobject',
}, function(err, data) {
console.log(err || data);
});
Download the file to a specified write file stream:
cos.getObject({
Bucket: 'examplebucket-1250000000', /*Required*/
Region: 'COS_REGION', /* Required */
Key: 'exampleobject', /*Required*/
Output: fs.createWriteStream('./exampleobject'),
}, function(err, data) {
console.log(err || data);
});
Parameter | Description | 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 |
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, 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 |
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.
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 | 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 |
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 |
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.
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 | 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 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 |
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, 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 |
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.
cos.deleteObject({
Bucket: 'examplebucket-1250000000', /*Required*/
Region: 'COS_REGION', /* Required */
Key: 'exampleobject' /*Required*/
}, function(err, data) {
console.log(err || data);
});
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 |
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, 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 |
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.
Deleting multiple files:
cos.deleteMultipleObject({
Bucket: 'examplebucket-1250000000', /*Required*/
Region: 'COS_REGION', /* Required */
Objects: [
{Key: 'exampleobject'},
{Key: 'exampleobject2'},
]
}, function(err, data) {
console.log(err || data);
});
Parameter | Description | 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 | 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 |
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 | Object key (object name), the unique identifier of an object in a bucket. For more information, please see Object Overview. | String |
- - Code | Error code of the deletion failure | String |
- - Message | Error messages of the deletion failure | String |
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.
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 | 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 | 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: The following two restoration modes are supported for the DEEP ARCHIVE storage class: |
String | Yes |
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 |
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.
Get the list of unfinished UploadIds prefixed with exampleobject
. The following is an example:
cos.multipartList({
Bucket: 'examplebucket-1250000000', /*Required*/
Region: 'COS_REGION', /* Required */
Prefix: 'exampleobject', /*Optional*/
}, function(err, data) {
console.log(err || data);
});
Parameter | Description | 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 . upload-id-marker is not specified: - Only multipart uploads whose ObjectName is lexicographically greater than the specified key-marker will be listed. 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 . key-marker is not specified: - upload-id-marker will be ignored. 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 |
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 |
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.
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 | 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 | 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 |
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 |
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 |
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.
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 | 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 |
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 |
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.
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 | 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 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 |
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 |
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
.
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 | 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 |
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 |
This API (Complete Multipart Upload) is used to complete a multipart upload. After all parts are uploaded via the Upload Part
API, you need to call this API to complete the multipart upload. When using this API, you need to specify the PartNumber
and ETag
of each part in the request body for the part information to be verified.
As the parts need to be merged after they are uploaded, and the merge takes several minutes, when the merge starts, COS will immediately return status code "200" and periodically return space information during the merge process to keep the connection active until the merge is completed. After that, COS will return the content of the merged parts in the body.
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.
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 | 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 |
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 |
- 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 |
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.
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 | 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 |
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 |
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.
This API is used to upload large files in parts.
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 | 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 |
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 | 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 upload progress, in decimal form. For example, 0.5 means 50% has been uploaded. | Number | No |
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 |
- 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 | Returns the version ID for versioning-enabled buckets. For buckets that have never had versioning enabled, this parameter is not returned. | String |
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.
Call Slice Copy File
:
cos.sliceCopyFile({
Bucket: 'examplebucket-1250000000', /*Required*/
Region: 'COS_REGION',/*Required*/
Key: 'exampleobject', /*Required*/
CopySource: 'sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/sourceObject', /*Required*/
onProgress:function (progressData) { /*Optional*/
console.log(JSON.stringify(progressData));
}
},function (err,data) {
console.log(err || data);
});
Parameter | Description | 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 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 |
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 |
- 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 |
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:
Call the uploadFiles
operation:
const filePath1 = "temp-file-to-upload" // Local file path
const filePath2 = "temp-file-to-upload" // Local file path
cos.uploadFiles({
files: [{
Bucket: 'examplebucket-1250000000',
Region: 'COS_REGION',
Key: 'exampleobject',
FilePath: filePath1,
}, {
Bucket: 'examplebucket-1250000000',
Region: 'COS_REGION',
Key: '2.jpg',
FilePath: filePath2,
}],
SliceSize: 1024 * 1024,
onProgress: function (info) {
var percent = parseInt(info.percent * 10000) / 100;
var speed = parseInt(info.speed / 1024 / 1024 * 100) / 100;
console.log('progress:' + percent + '%; speed:' + speed + 'Mb/s;');
},
onFileFinish: function (err, data, options) {
console.log(options.Key + 'upload' + (err ? 'failed' : 'completed'));
},
}, function (err, data) {
console.log(err || data);
});
Parameter | Description | 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 |
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 |
- files | The error or data for each file | ObjectArray |
- - err | Upload error message | Object |
- - data | Information about the object upload completion | Object |
- - options | Parameter information about files that have been uploaded | Object |
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:
cos.getTaskList
to get the task list.cos.pauseTask
, cos.restartTask
, and cos.cancelTask
to perform operations on upload tasks.For a complete sample of how to use the upload queue, please see Queue Demo.
This API is used to cancel an upload task by taskId
.
Use case
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 |
This API is used to suspend an upload task by taskId
.
Use case
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 |
This API is used to restart an upload task by taskId
. You can restart tasks that have been manually suspended through the pauseTask
API, or automatically suspended due to an upload error.
Use case
var taskId = 'xxxxx'; /* Required */
cos.restartTask(taskId);
Parameter description
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 |
Was this page helpful?