Uploading Objects

Last updated: 2025-07-25 09:22:37

Feature Overview

This document provides an overview of APIs and SDK code samples for advanced upload, upload in whole, multipart upload, and other object operations.
Note
For SDK FAQs, see FAQs.
Simple operations
API
Operation
Description
Uploading an object using simple upload
Uploads an object to a bucket
Appending parts
Appends object parts to a bucket.
Uploading an object using a form
Uploads an object using form request
Multipart operations
API
Operation
Description
Querying multipart upload
Queries the information on ongoing multipart uploads
Initializing a multipart upload operation
Initializes a multipart upload task
Uploading parts
Uploads a part in multipart upload
Querying uploaded parts
Queries uploaded parts in a specified multipart upload
Completing multipart upload
Completes the multipart upload of an entire object
Aborting a multipart upload
Aborts a multipart upload operation and deletes the uploaded parts

Advanced APIs (Recommended)

We strongly recommend you use advanced APIs, which encapsulate the native methods mentioned above. They can implement the complete process of multipart upload and support concurrent multipart upload, checkpoint restart as well as canceling, pausing, and resuming upload tasks.

Advanced upload

Note

This API (Upload File) 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 (sliceUploadFile); otherwise, it will be uploaded in whole (putObject).

Use Cases

cos.uploadFile({
Bucket: 'examplebucket-1250000000', /* Enter your own bucket, required field */
Region: 'COS_REGION', /* Required field specifying the region where the bucket is located, e.g., ap-beijing */
Key: '1.jpg', /* The object key stored in the bucket (e.g., 1.jpg, a/b/test.txt), required field */
Body: fileObject, /* Required, uploaded file object, can be the file object obtained after selecting a local file using the input[type="file"] tag */
SliceSize: 1024 * 1024 * 5, /* Threshold for triggering multipart upload, files larger than 5 MB will use multipart upload, optional */
onTaskReady: function(taskId) { /* Optional */
console.log(taskId);
},
onProgress: function (progressData) { /* Optional */
console.log(JSON.stringify(progressData));
},
onFileFinish: function (err, data, options) { /* Optional */
console.log(options.Key + ' upload ' + (err ? 'failed' : 'completed'));
},
// Custom headers are supported (optional)
Headers: {
'x-cos-meta-test': 123
},
}, function(err, data) {
console.log(err || data);
});

Description

Parameter
ParameterDescription
Local Disk Types
Required
Bucket
Bucket name in the format of BucketName-APPID.
String
Required
Region
Bucket region. For the enumerated values, see Regions and Access Endpoints.
String
Required
Key
Object key (object name), the unique identifier of an object in a bucket. For more information, see Object Overview.
String
Required
Body
Content of the file part to be uploaded. This parameter can be a File object, or a Blob object.
File\Blob
Required
SliceSize
Specifies the minimum file size (in bytes) to use multipart upload. The default value is 1048576 (1 MB). 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
Not required
AsyncLimit
Maximum number of concurrently uploaded parts allowed. This parameter is valid only when a multipart upload is triggered.
Number
Not required
StorageClass
The storage types of objects include STANDARD, STANDARD_IA, ARCHIVE, DEEP_ARCHIVE, etc. For more information on storage types, please refer to Storage Class Overview.
String
Not required
UploadAddMetaMd5
Sets x-cos-meta-md5 as the object’s MD5 value in the object’s metadata during upload in the format of a 32-bit lowercase string. For example: 4d00d79b6733c9cc066584a02ed03410
String
Not required
CacheControl
Cache policy as defined in RFC 2616. It will be stored as the object metadata.
String
Not required
ContentDisposition
Filename as defined in RFC 2616, which will be stored as object metadata
String
Not required
ContentEncoding
Encoding format as defined in RFC 2616, which will be stored as object metadata
String
Not required
ContentLength
The length of the content of an HTTP request in bytes as defined in RFC 2616
String
Not required
ContentType
Content type (MIME) as defined in RFC 2616. It will be stored as the object metadata.
String
Not required
Expires
Cache expiration time as defined in RFC 2616. It will be stored as the object metadata.
String
Not required
Expect
If Expect: 100-continue is used, the request content will be sent only after the confirmation from the server is received.
String
Not required
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 restart (restartTask) the task
Function
Not required
- taskId
Upload task number
String
Not required
onProgress
Callback of the upload progress. The callback parameter is the progress object progressData.
Function
Not required
- progressData.loaded
Size of the uploaded parts, in bytes
Number
Not required
- progressData.total
Total file size in bytes
Number
Not required
- progressData.speed
File upload speed in bytes/s
Number
Not required
- progressData.percent
File upload progress, in decimal form. For example, 0.5 means 50% has been uploaded.
Number
Not required
onFileFinish
Callback for file upload success or failure
Function
Not required
- err
Upload error message
Object
Not required
- data
Information about the completion of object upload
Object
Not required
- options
Parameter information of the files that have been uploaded
Object
Not required

Callback function description

function(err, data) { ... }
Parameter
ParameterDescription
Local Disk Types
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, see Error Codes.
Object
- statusCode
HTTP status code, such as 200, 403, and 404
Number
- headers
Returned headers
Object
data
Object 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
Returned headers
Object
- Location
The location where the uploaded file can be accessed
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), the unique identifier 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
The unique ID of the merged file, in the format: "uuid-<number of parts>"
For example, "22ca88419e2ed4721c23807c678adbe4c08a7880-3", ensure to include double quotes before and after.
String
- VersionId
When uploading an object to a bucket with versioning enabled, the object's version ID is returned. If the bucket has never enabled versioning, this parameter is not returned. The VersionId field needs to be set in the Expose-Headers. See reference documentation for more information.
String

Uploading an object using multipart upload (checkpoint restart)

Note

This API (Slice Upload File) is used to upload large files in parts.
Note
If the browser is not closed, you can suspend, restart, or cancel the upload job.
If you upload the same file to the same bucket path after refreshing the browser, the file content will be verified based on UploadId and the upload will proceed if the verification is passed.

Use Cases

cos.sliceUploadFile({
Bucket: 'examplebucket-1250000000', /* Enter your own bucket, required field */
Region: 'COS_REGION', /* Required field specifying the region where the bucket is located, e.g., ap-beijing */
Key: '1.jpg', /* The object key stored in the bucket (e.g., 1.jpg, a/b/test.txt), required field */
Body: fileObject, /* Required, uploaded file object, can be the file object obtained after selecting a local file using the input[type="file"] tag */
onTaskReady: function(taskId) { /* Optional */
console.log(taskId);
},
onHashProgress: function (progressData) { /* Optional */
console.log(JSON.stringify(progressData));
},
onProgress: function (progressData) { /* Optional */
console.log(JSON.stringify(progressData));
},
// Custom headers are supported (optional)
Headers: {
'x-cos-meta-test': 123
},
}, function(err, data) {
console.log(err || data);
});

Description

Parameter
ParameterDescription
Local Disk Types
Required
Bucket
Bucket name in the format of BucketName-APPID.
String
Required
Region
Bucket region. For the enumerated values, see Regions and Access Endpoints.
String
Required
Key
Object key (object name), the unique identifier of an object in a bucket. For more information, see Object Overview.
String
Required
Body
Content of the file part to be uploaded. This parameter can be a File object, or a Blob object.
File\Blob
Required
SliceSize
Part size
Number
Not required
AsyncLimit
Maximum number of parts for concurrent upload
Number
Not required
StorageClass
The storage types of objects include STANDARD, STANDARD_IA, ARCHIVE, DEEP_ARCHIVE, etc. For more information on storage types, please refer to Storage Class Overview.
String
Not required
UploadAddMetaMd5
Sets x-cos-meta-md5 as the object’s MD5 value in the object’s metadata during upload in the format of a 32-bit lowercase string. For example: 4d00d79b6733c9cc066584a02ed03410
String
Not required
CacheControl
Cache policy as defined in RFC 2616. It will be stored as the object metadata.
String
Not required
ContentDisposition
Filename as defined in RFC 2616, which will be stored as object metadata
String
Not required
ContentEncoding
Encoding format as defined in RFC 2616, which will be stored as object metadata
String
Not required
ContentLength
The length of the content of an HTTP request in bytes as defined in RFC 2616
String
Not required
ContentType
Content type (MIME) as defined in RFC 2616. It will be stored as the object metadata.
String
Not required
Expires
Cache expiration time as defined in RFC 2616. It will be stored as the object metadata.
String
Not required
Expect
If Expect: 100-continue is used, the request content will be sent only after the confirmation from the server is received.
String
Not required
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 restart (restartTask) the task
Function
Not required
- taskId
Upload task number
String
Not required
onHashProgress
Progress callback function for the MD5 checksum of the object. The callback parameter is the progress object progressData.
Function
Not required
- progressData.loaded
Size of the verified parts, in bytes
Number
Not required
- progressData.total
Total file size in bytes
Number
Not required
- progressData.speed
File verification speed in bytes/s
Number
Not required
- progressData.percent
Percentage of the file verification progress, in decimal form. For example, 0.5 means 50% has been verified.
Number
Not required
onProgress
Callback of the upload progress. The callback parameter is the progress object progressData.
Function
Not required
- progressData.loaded
Size of the uploaded parts, in bytes
Number
Not required
- progressData.total
Total file size in bytes
Number
Not required
- progressData.speed
File upload speed in bytes/s
Number
Not required
- progressData.percent
File upload progress, in decimal form. For example, 0.5 means 50% has been uploaded.
Number
Not required

Callback function description

function(err, data) { ... }
Parameter
ParameterDescription
Local Disk Types
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, see Error Codes.
Object
- statusCode
HTTP status code, such as 200, 403, and 404
Number
- headers
Returned headers
Object
data
Object 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
Returned headers
Object
- Location
The location where the uploaded file can be accessed
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, see Object Overview.
String
- ETag
The unique ID of the merged file, in the format: "uuid-<number of parts>"
For example, "22ca88419e2ed4721c23807c678adbe4c08a7880-3", ensure to include double quotes before and after.
String
- VersionId
When uploading an object to a bucket with versioning enabled, the object's version ID is returned. If the bucket has never enabled versioning, this parameter is not returned. The VersionId field needs to be set in the Expose-Headers. See reference documentation for more information.
String

Batch upload

Note

Method 1: Batch uploading can be achieved by calling putObject and sliceUploadFile multiple times. Control the file concurrency by instantiating the FileParallelLimit parameter, with a default of 3 concurrent files.
Method 2: You can call the cos.uploadFiles function to implement batch uploading. The SliceSize parameter can control the file. The following is a description of the uploadFiles method.

Method prototype

Call uploadFiles:
cos.uploadFiles({
files: [{
Bucket: 'examplebucket-1250000000', /* Enter your own bucket, required field */
Region: 'COS_REGION', /* Required field specifying the region where the bucket is located, e.g., ap-beijing */
Key: '1.jpg', /* The object key stored in the bucket (e.g., 1.jpg, a/b/test.txt), required field */
Body: fileObject1, /* Required, uploaded file object, can be the file object obtained after selecting a local file using the input[type="file"] tag */
onTaskReady: function(taskId) {
/* taskId can be used to cancel the upload with cos.cancelTask(taskId), pause the upload with cos.pauseTask(taskId), or restart the upload with cos.restartTask(taskId) */
console.log(taskId);
},
// Custom headers are supported (optional)
Headers: {
'x-cos-meta-test': 123
},
}, {
Bucket: 'examplebucket-1250000000', /* Enter your own bucket, required field */
Region: 'COS_REGION', /* Required field specifying the region where the bucket is located, e.g., ap-beijing */
Key: '2.jpg', /* The object key stored in the bucket (e.g., 1.jpg, a/b/test.txt), required field */
Body: fileObject2, /* Required, uploaded file object, can be the file object obtained after selecting a local file using the input[type="file"] tag */
onTaskReady: function(taskId) {
/* taskId can be used to cancel the upload with cos.cancelTask(taskId), pause the upload with cos.pauseTask(taskId), or restart the upload with cos.restartTask(taskId) */
console.log(taskId);
},
// Custom headers are supported (optional)
Headers: {
'x-cos-meta-test': 123
},
}],
SliceSize: 1024 * 1024 * 10, /* Set to use multipart upload for files larger than 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);
});

Description

Parameter
ParameterDescription
Local Disk Types
Required
files
File list. Each item is a parameter object to be passed to putObject and sliceUploadFile.
Object
Required
- Bucket
Bucket name in the format of BucketName-APPID.
String
Required
- Region
Bucket region. For the enumerated values, see Regions and Access Endpoints.
String
Required
- Key
Object key (object name), the unique identifier of an object in a bucket. For more information, see Object Overview.
String
Required
- Body
Content of the file part to be uploaded. This parameter can be a File object, or a Blob object.
File\Blob
Required
- CacheControl
Cache policy as defined in RFC 2616. It will be stored as the object metadata.
String
Not required
- ContentDisposition
Filename as defined in RFC 2616, which will be stored as object metadata
String
Not required
- ContentEncoding
Encoding format as defined in RFC 2616, which will be stored as object metadata
String
Not required
- ContentLength
The length of the content of an HTTP request in bytes as defined in RFC 2616
String
Not required
- ContentType
Content type (MIME) as defined in RFC 2616. It will be stored as the object metadata.
String
Not required
- Expires
Cache expiration time as defined in RFC 2616. It will be stored as the object metadata.
String
Not required
- Expect
If Expect: 100-continue is used, the request content will be sent only after the confirmation from the server is received.
String
Not required
- 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 restart (restartTask) the task
Function
Not required
-- taskId
Upload task number
String
Not required
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
Required
AsyncLimit
Maximum number of concurrently uploaded parts allowed. This parameter is valid only when a multipart upload is triggered.
Number
Not required
onProgress
Upload progress calculated by averaging out the progress of all tasks
String
Required
- progressData.loaded
Size of the uploaded parts, in bytes
Number
Not required
- progressData.total
Total file size in bytes
Number
Not required
- progressData.speed
File upload speed in bytes/s
Number
Not required
- progressData.percent
File upload progress, in decimal form. For example, 0.5 means 50% has been uploaded.
Number
Not required
onFileFinish
Callback for file upload success or failure
Function
Not required
- err
Upload error message
Object
Not required
- data
Information about the completion of object upload
Object
Not required
- options
Parameter information of the files that have been uploaded
Object
Not required

Callback function description

function(err, data) { ... }
Parameter
ParameterDescription
Local Disk Types
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, see Error Codes.
Object
- statusCode
HTTP status code, such as 200, 403, and 404
Number
- headers
Returned headers
Object
data
Object returned when the request is successful. If the request fails, this parameter is empty.
Object
- files
The error or data for each file
ObjectArray
- - error
Upload error message
Object
- - data
Information about the completion of object upload
Object
- - options
Parameter information of the files that have been uploaded
Object

Upload queue

The JavaScript SDK records all the putObject and sliceUploadFile upload tasks in a queue. Relevant queue operations are as follows:
1. Use var taskList = cos.getTaskList() to get the task list.
2. Use cos.pauseTask(), cos.restartTask(), or cos.cancelTask() to manage the task.
3. Use cos.on('list-update', callback); to listen for list and progress changes.
For a complete sample of how to use the upload queue, please see Queue Demo.

Canceling upload task

This API is used to cancel an upload task by taskId.
Use case
var taskId = 'xxxxx'; /* Required */
cos.cancelTask(taskId);
Parameter Description
Parameter
ParameterDescription
Local Disk Types
Required
taskId
ID of the upload task. When sliceUploadFile is called, TaskReady in the callback will return the taskId of the upload task.
String
Required

Pausing upload task

This API is used to pause an upload task by taskId.
Use case
var taskId = 'xxxxx'; /* Required */
cos.pauseTask(taskId);
Parameter Description
Parameter
ParameterDescription
Local Disk Types
Required
taskId
ID of the upload task. When sliceUploadFile is called, TaskReady in the callback will return the taskId of the upload task.
String
Required

Resuming an upload task

This API is used to restart an upload task by taskId. You can restart tasks that have been manually suspended through the pauseTask API, or automatically suspended due to an upload error.
Use case
var taskId = 'xxxxx'; /* Required */
cos.restartTask(taskId);
Parameter Description
Parameter
ParameterDescription
Local Disk Types
Required
taskId
ID of the upload task. When sliceUploadFile is called, TaskReady in the callback will return the taskId of the upload task.
String
Required

Simple Operations

Uploading an object using simple upload

Note

This API is used to upload an object to a bucket. To make this request, you need to have write permission for the bucket.
Note
The Key (filename) cannot end with /; otherwise, it will be identified as a folder.
Uploading the Key (file name) with the same name is identified as an overwritten operation by default. If you have not enabled version control and do not want to overwrite the file on the cloud, ensure that the Key to be uploaded is not duplicated.
The total number of bucket ACL rules under a single root account (i.e., under the same APPID) cannot exceed 1,000. There is no upper limit on the number of object ACL rules. If you do not need access control for an object, you can choose not to configure an ACL for the object during upload, and the object will inherit the permissions of its bucket by default.
After uploading, you can generate a pre-signed URL with the same key (for downloading, set the method to GET; see the detailed API description below) to share with others for downloading. However, if your file has private-read access, the pre-signed URL will have a limited validity period.
The upload progress onProgress depends on the native xhr.upload.onprogress method. If you find that the upload progress is inaccurate, please check whether a library (such as nuysoft/Mock) that intercepts XHR methods is referenced in your project.

Use Cases

Uploading a small file:
cos.putObject({
Bucket: 'examplebucket-1250000000', /* Enter your own bucket, required field */
Region: 'COS_REGION', /* Required field specifying the region where the bucket is located, e.g., ap-beijing */
Key: '1.jpg', /* The object key stored in the bucket (e.g., 1.jpg, a/b/test.txt), required field */
Body: fileObject, /* Required, uploaded file object, can be the file object obtained after selecting a local file using the input[type="file"] tag */
onProgress: function(progressData) {
console.log(JSON.stringify(progressData));
}
}, function(err, data) {
console.log(err || data);
});
Upload a string as the file content:
cos.putObject({
Bucket: 'examplebucket-1250000000', /* Enter your own bucket, required field */
Region: 'COS_REGION', /* Required field specifying the region where the bucket is located, e.g., ap-beijing */
Key: '1.txt', /* The object key stored in the bucket (e.g., 1.jpg, a/b/test.txt), required field */
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', /* Enter your own bucket, required field */
Region: 'COS_REGION', /* Required field specifying the region where the bucket is located, e.g., ap-beijing */
Key: '1.png', /* The object key stored in the bucket (e.g., 1.jpg, a/b/test.txt), required field */
Body: body,
}, function(err, data) {
console.log(err || data);
});
Create directory a:
cos.putObject({
Bucket: 'examplebucket-1250000000', /* Enter your own bucket, required field */
Region: 'COS_REGION', /* Required field specifying the region where the bucket is located, e.g., ap-beijing */
Key: 'a/', /* The object key stored in the bucket (e.g., 1.jpg, a/b/test.txt), required field */
Body: '',
}, function(err, data) {
console.log(err || data);
});
Upload objects to directory a/b:
cos.putObject({
Bucket: 'examplebucket-1250000000', /* Enter your own bucket, required field */
Region: 'COS_REGION', /* Required field specifying the region where the bucket is located, e.g., ap-beijing */
Key: 'a/b/1.jpg', /* The object key stored in the bucket (e.g., 1.jpg, a/b/test.txt), required field */
Body: fileObject, /* Required, uploaded file object, can be the file object obtained after selecting a local file using the input[type="file"] tag */
onProgress: function(progressData) {
console.log(JSON.stringify(progressData));
}
}, function(err, data) {
console.log(err || data);
});
Custom Headers:
cos.putObject({
Bucket: 'examplebucket-1250000000', /* Required */
Region: 'ap-beijing', /* Required */
Key: 'a', /* Required */
Body: 'hello', /* Required */
// Custom headers are supported (optional)
Headers: {
'x-cos-meta-test': 123
},
}, function(err, data) {
console.log(err || data);
});
Uploading an object (limiting single-URL speed):
Note
For more information about the speed limits on object uploads, see Single-Connection Bandwidth Limit.
cos.putObject({
Bucket: 'examplebucket-1250000000', /* Enter your own bucket, required field */
Region: 'COS_REGION', /* Required field specifying the region where the bucket is located, e.g., ap-beijing */
Key: '1.jpg', /* The object key stored in the bucket (e.g., 1.jpg, a/b/test.txt), required field */
Body: fileObject, /* Required, uploaded file object, can be the file object obtained after selecting a local file using the input[type="file"] tag */
Headers: {
'x-cos-traffic-limit': 819200, // The valid range for the limit value is 819,200 - 838,860,800, with the default unit being bit/s, i.e., 800Kb/s - 800Mb/s. If it exceeds this range, a 400 error will be returned.
},
onProgress: function(progressData) {
console.log(JSON.stringify(progressData));
}
}, function(err, data) {
console.log(err || data);
});

Description

Parameter
ParameterDescription
Local Disk Types
Required
Bucket
Bucket name in the format of BucketName-APPID.
String
Required
Region
Bucket region. For the enumerated values, see Regions and Access Endpoints.
String
Required
Key
Object key (object name), the unique identifier of an object in a bucket. For more information, see Object Overview.
String
Required
Body
Content of the file to be uploaded, which can be a string, a File object, or a Blob object
String\File\Blob\ArrayBuffer
Required
CacheControl
Cache policy as defined in RFC 2616. It will be stored as the object metadata.
String
Not required
ContentDisposition
Filename as defined in RFC 2616, which will be stored as object metadata
String
Not required
ContentEncoding
Encoding format as defined in RFC 2616, which will be stored as object metadata
String
Not required
ContentLength
The length of the content of an HTTP request in bytes as defined in RFC 2616
String
Not required
ContentType
Content type (MIME) as defined in RFC 2616. It will be stored as the object metadata.
String
Not required
Expires
Cache expiration time as defined in RFC 2616. It will be stored as the object metadata.
String
Not required
Expect
If Expect: 100-continue is used, the request content will be sent only after the confirmation from the server is received.
String
Not required
ACL
Define the Access Control List (ACL) attribute for an object. For enumeration values, please refer to the Preset ACL section for objects in the ACL Overview document, such as default, private, public-read, etc.
Note: If you do not require object ACL control, set it to default or leave it unset. By default, it will inherit the bucket permissions.
String
Not required
GrantRead
Grant the permission to read the object to the authorized party, format: id="[OwnerUin]". Multiple authorized parties can be separated using a comma (,):
When granting permissions to a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
When granting permissions to the root account, id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
For example: 'id="qcs::cam::uin/100000000001:uin/100000000001",id="qcs::cam::uin/100000000001:uin/100000000011"'
String
Not required
GrantReadAcp
Grant the grantee permission to read the object's Access Control List (ACL), format: id="[OwnerUin]", multiple grantees can be separated by a comma (,):
When granting permissions to a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
When granting permissions to the root account, id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
For example: 'id="qcs::cam::uin/100000000001:uin/100000000001",id="qcs::cam::uin/100000000001:uin/100000000011"'
String
Not required
GrantWriteAcp
Grant the grantee permission to write the object's Access Control List (ACL), in the format: id="[OwnerUin]". Multiple grantees can be separated by a comma (,):
When granting permissions to a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
When granting permissions to the root account, id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
For example: 'id="qcs::cam::uin/100000000001:uin/100000000001",id="qcs::cam::uin/100000000001:uin/100000000011"'
String
Not required
GrantFullControl
Grant all permissions for the authorized user to operate on the object, format: id="[OwnerUin]". Multiple authorized users can be separated by a comma (,):
When granting permissions to a sub-account, use id="qcs::cam::uin/:uin/<SubUin>"
When granting permissions to the root account, id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
For example: 'id="qcs::cam::uin/100000000001:uin/100000000001",id="qcs::cam::uin/100000000001:uin/100000000011"'
String
Not required
StorageClass
Set the object's storage type with enumeration values: STANDARD, STANDARD_IA, ARCHIVE, DEEP_ARCHIVE, etc. The default value is STANDARD. For more storage types, see Storage Class Overview.
String
Not required
x-cos-meta-*
User-defined headers, which will be returned as the object metadata. The maximum size is 2 KB.
String
Not required
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
Not required
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 restart (restartTask) the task
Function
Not required
- taskId
Upload task number
String
Not required
onProgress
Progress callback, whose response object is progressData
Function
Not required
- progressData.loaded
Size of the uploaded parts, in bytes
Number
Not required
- progressData.total
Total file size in bytes
Number
Not required
- progressData.speed
File upload speed in bytes/s
Number
Not required
- progressData.percent
Percentage of the file upload progress, in decimal form. For example, 0.5 means 50% has been uploaded.
Number
Not required

Callback function description

function(err, data) { ... }
Parameter
ParameterDescription
Local Disk Types
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, see Error Codes.
Object
- statusCode
HTTP status code, such as 200, 403, and 404
Number
- headers
Returned headers
Object
data
Object 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
Returned headers
Object
- ETag
Returns the MD5 checksum value of the file. The ETag value can be used to verify whether the object has been damaged during the upload process.
For example, "09cba091df696af91549de27b8e7d0f6", Note: The ETag value here is enclosed in double quotes
String
- Location
The location where the uploaded file can be accessed
String
- VersionId
When uploading an object to a bucket with versioning enabled, the object's version ID is returned. If the bucket has never enabled versioning, this parameter is not returned. The VersionId field needs to be set in the Expose-Headers. See reference documentation for more information.
String

Appending parts

Note

This API (APPEND Object) is used to append object parts to a bucket.
Note
The COS JavaScript SDK should be v1.3.1 or higher.
This API can append data only to appendable objects.
If an object is uploaded using the APPEND Object API for the first time, it will be automatically determined as "appendable".
You can use the GET Object or HEAD Object API to get the x-cos-object-type response header to determine the object type.

Use Cases

Append parts for the first time:
cos.appendObject({
Bucket: 'examplebucket-1250000000', /* Enter your own bucket, required field */
Region: 'COS_REGION', /* Required field specifying the region where the bucket is located, e.g., ap-beijing */
Key: 'test.txt', /* The object key stored in the bucket (e.g., 1.jpg, a/b/test.txt), required field */
Body: fileObject, /* Required, uploaded file object, can be the file object obtained after selecting a local file using the input[type="file"] tag */
Position: 0, // Set to 0 for the initial upload
}, function(err, data) {
console.log(err || data);
});
Check whether parts can be appended to an object in a bucket:
cos.headObject({
Bucket: 'examplebucket-1250000000', /* Enter your own bucket, required field */
Region: 'COS_REGION', /* Required field specifying the region where the bucket is located, e.g., ap-beijing */
Key: 'test.txt', /* The object key stored in the bucket (e.g., 1.jpg, a/b/test.txt), required field */
}, function(err, data) {
if (err) return console.log(err);
// If data.headers does not have the x-cos-object-type field, configure expose-headers. Refer to the documentation: https://cloud.tencent.com/document/product/436/13318
var objectType = data.headers['x-cos-object-type'];
console.log(objectType === 'appendable');
});
Query the position of the object for parts appending and start upload:
cos.headObject({
Bucket: 'examplebucket-1250000000', /* Enter your own bucket, required field */
Region: 'COS_REGION', /* Required field specifying the region where the bucket is located, e.g., ap-beijing */
Key: 'test.txt', /* The object key stored in the bucket (e.g., 1.jpg, a/b/test.txt), required field */
}, function(err, data) {
if (err) return console.log(err);
// First, obtain the current length of the file to be appended, which is the Position to be submitted.
var position = data.headers['content-length'];
cos.appendObject({
Bucket: 'examplebucket-1250000000', /* Enter your own bucket, required field */
Region: 'COS_REGION', /* Required field specifying the region where the bucket is located, e.g., ap-beijing */
Key: 'test.txt', /* The object key stored in the bucket (e.g., 1.jpg, a/b/test.txt), required field */
Body: '66666',
Position: position,
},
function(err, data) {
if (err) return console.log(err);
// You can also obtain the position for the next upload to continue appending
// If data.headers does not have the x-cos-next-append-position field, configure expose-headers. Refer to the documentation: https://cloud.tencent.com/document/product/436/13318
var nextPosition = data.headers['x-cos-next-append-position'];
console.log(nextPosition);
})
});

Description

Parameter
ParameterDescription
Local Disk Types
Required
Bucket
Bucket name in the format of BucketName-APPID.
String
Required
Region
Bucket region. For the enumerated values, see Regions and Access Endpoints.
String
Required
Key
Object key (object name), the unique identifier of an object in a bucket. For more information, see Object Overview.
String
Required
Body
Content of the file to be uploaded, which can be a string, a File object, or a Blob object
String\File\Blob\ArrayBuffer
Required
Position
Starting point for the append operation (in bytes). For the first append, the value of this parameter is 0. For subsequent appends, the value is the content-length of the current object.
Number
Required
CacheControl
Cache policy as defined in RFC 2616. It will be stored as the object metadata.
String
Not required
ContentDisposition
Filename as defined in RFC 2616, which will be stored as object metadata
String
Not required
ContentEncoding
Encoding format as defined in RFC 2616, which will be stored as object metadata
String
Not required
ContentLength
The length of the content of an HTTP request in bytes as defined in RFC 2616
String
Not required
ContentType
Content type (MIME) as defined in RFC 2616. It will be stored as the object metadata.
String
Not required
Expires
Cache expiration time as defined in RFC 2616. It will be stored as the object metadata.
String
Not required
Expect
If Expect: 100-continue is used, the request content will be sent only after the confirmation from the server is received.
String
Not required
GrantRead
Grant the permission to read the object to the authorized party, format: id="[OwnerUin]". Multiple authorized parties can be separated using a comma (,):
When granting permissions to a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
When granting permissions to the root account, id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
For example: 'id="qcs::cam::uin/100000000001:uin/100000000001",id="qcs::cam::uin/100000000001:uin/100000000011"'
String
Not required
GrantReadAcp
Grant the grantee permission to read the object's Access Control List (ACL), format: id="[OwnerUin]", multiple grantees can be separated by a comma (,):
When granting permissions to a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
When granting permissions to the root account, id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
For example: 'id="qcs::cam::uin/100000000001:uin/100000000001",id="qcs::cam::uin/100000000001:uin/100000000011"'
String
Not required
GrantWriteAcp
Grant the grantee permission to write the object's Access Control List (ACL), in the format: id="[OwnerUin]". Multiple grantees can be separated by a comma (,):
When granting permissions to a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
When granting permissions to the root account, id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
For example: 'id="qcs::cam::uin/100000000001:uin/100000000001",id="qcs::cam::uin/100000000001:uin/100000000011"'
String
Not required
GrantFullControl
Grant all permissions for the authorized user to operate on the object, format: id="[OwnerUin]". Multiple authorized users can be separated by a comma (,):
When granting permissions to a sub-account, use the following format: id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
When granting permissions to the root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
For example: 'id="qcs::cam::uin/100000000001:uin/100000000001",id="qcs::cam::uin/100000000001:uin/100000000011"'
String
Not required
StorageClass
Set the object's storage type with enumeration values: STANDARD, STANDARD_IA, ARCHIVE, DEEP_ARCHIVE, etc. The default value is STANDARD. For more storage types, see Storage Class Overview.
String
Not required
x-cos-meta-*
User-defined headers, which will be returned as the object metadata. The maximum size is 2 KB.
String
Not required

Callback function description

function(err, data) { ... }
Parameter
ParameterDescription
Local Disk Types
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, see Error Codes.
Object
- statusCode
HTTP status code, such as 200, 403, and 404
Number
- headers
Returned headers
Object
data
Object 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
Returned headers
Object
- RequestId
Unique ID of the request
String

Uploading an object using a form

The JS SDK does not provide a method for the POST Object interface. If you need to use this interface, please refer to "Solution B: Using Form Upload" in Web Direct Upload Practice.

Multipart Operations

For more information on multipart uploads, see Multipart Upload. The operations that can be included in a multipart upload are as follows:
Uploading objects with multipart upload: initializing a multipart upload, uploading parts, and completing a multipart upload.
Resuming a multipart upload: querying uploaded parts, uploading remaining parts, and completing a multipart upload.
Deleting uploaded parts.
Note
Generally, you don't need to care about these methods. sliceUploadFile has encapsulated the following multipart operations, which can be called directly. We recommend you use the advanced upload method uploadFile.

Querying multipart upload

Note

This API is used to query ongoing multipart uploads. A single request operation can list up to 1,000 multipart uploads.

Use Cases

Get the list of incomplete multipart uploads whose UploadId is prefixed with a:
cos.multipartList({
Bucket: 'examplebucket-1250000000', /* Required */
Region: 'COS_REGION', /* The region where the bucket is located, required field */
Prefix: 'a', /* Optional */
}, function(err, data) {
console.log(err || data);
});

Description

Parameter
ParameterDescription
Local Disk Types
Required
Bucket
Bucket name in the format of BucketName-APPID.
String
Required
Region
Bucket region. For the enumerated values, see Regions and Access Endpoints.
String
Required
Prefix
Limits the response to keys that begin with the specified prefix. Note that when you make a query with the specified prefix, the returned keys will still contain Prefix
String
Not required
Delimiter
Delimiter. A separator used for grouping object keys. Typically, it is set to /. All object keys with the same path from the Prefix or from the beginning (e.g., when Prefix is not specified) to the first delimiter are classified as a Common Prefix. The list of all Common Prefixes is then displayed.
String
Not required
EncodingType
Encoding type of the returned value. Valid value: url
String
Not required
MaxUploads
Sets the maximum number of entries returned. Value range: 1-1000; default value: 1000
String
Not required
KeyMarker
Used in conjunction with upload-id-marker
When the upload-id-marker is not specified:
- Entries with ObjectName in alphabetical order greater than the key-marker will be listed.
When the upload-id-marker is specified:
- Entries with ObjectName alphabetically greater than key-marker are listed.
- Entries with ObjectName alphabetically equal to key-marker and UploadID greater than upload-id-marker will be listed.
String
Not required
UploadIdMarker
Used in conjunction with key-marker
When the key-marker is not specified:
- The upload-id-marker will be ignored.
When the key-marker is specified:
- Entries with ObjectName alphabetically greater than key-marker are listed.
- Entries with ObjectName alphabetically equal to key-marker and UploadID greater than upload-id-marker will be listed.
String
Not required

Callback function description

function(err, data) { ... }
Parameter
ParameterDescription
Local Disk Types
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, see Error Codes.
Object
- statusCode
HTTP status code, such as 200, 403, and 404
Number
- headers
Returned headers
Object
data
Object 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
Returned headers
Object
- Bucket
Destination bucket for the multipart upload
String
- Encoding-Type
Encoding type of the returned value. 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
The maximum number of returned entries. Valid value range: 1-1000
String
- IsTruncated
Whether the returned list is truncated. Valid values: true, false.
String
- Prefix
Limits the response to keys that begin with the specified prefix
String
- Delimiter
Delimiter. A separator used for grouping object keys. Typically, it is set to /. All object keys with the same path from the Prefix or from the beginning (if no Prefix is specified) to the first delimiter are classified as a Common Prefix. Then, all Common Prefixes are listed.
String
- CommonPrefixs
The identical paths between Prefix and Delimiter are grouped and defined as a common prefix
ObjectArray
- - Prefix
Specific prefixes
String
- Upload
A collection of multipart upload information
ObjectArray
- - Key
Name of the object, i.e. object key
String
- - UploadId
ID of the multipart upload
String
- - StorageClass
Indicates the storage class for each part, with enumeration values such as STANDARD, STANDARD_IA, ARCHIVE, DEEP_ARCHIVE, etc. For more information on storage classes, see Storage Class Overview.
String
- - Initiator
Initiator of the multipart upload
Object
- - - DisplayName
Name of the upload initiator
String
- - - ID
Initiator ID format: qcs::cam::uin/<OwnerUin>:uin/<SubUin>
If it is a root account, <OwnerUin> and <SubUin> have the same value.
String
- - Owner
Information about the part owner
Object
- - - DisplayName
Name of the parts’ owner
String
- - - ID
Multipart holder ID, format: qcs::cam::uin/<OwnerUin>:uin/<SubUin>
If it is a root account, <OwnerUin> and <SubUin> have the same value.
String
- - Initiated
Start time of the multipart upload
String

Initializing a multipart upload operation

Note

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

Use Cases

cos.multipartInit({
Bucket: 'examplebucket-1250000000', /* Enter your own bucket, required field */
Region: 'COS_REGION', /* Required field specifying the region where the bucket is located, e.g., ap-beijing */
Key: '1.jpg', /* The object key stored in the bucket (e.g., 1.jpg, a/b/test.txt), required field */
Body: fileObject, /* Required, uploaded file object, can be the file object obtained after selecting a local file using the input[type="file"] tag */
}, function(err, data) {
console.log(err || data);
if (data) {
uploadId = data.UploadId;
}
});

Description

Parameter
ParameterDescription
Local Disk Types
Required
Bucket
Bucket name in the format of BucketName-APPID.
String
Required
Region
Bucket region. For the enumerated values, see Regions and Access Endpoints.
String
Required
Key
Object key (object name), the unique identifier of an object in a bucket. For more information, see Object Overview.
String
Required
CacheControl
Cache policy as defined in RFC 2616. It will be stored as the object metadata.
String
Not required
ContentDisposition
Filename as defined in RFC 2616, which will be stored as object metadata
String
Not required
ContentEncoding
Encoding format as defined in RFC 2616, which will be stored as object metadata
String
Not required
ContentType
Content type (MIME) as defined in RFC 2616. It will be stored as the object metadata.
String
Not required
Expires
Cache expiration time as defined in RFC 2616. It will be stored as the object metadata.
String
Not required
ACL
Define the Access Control List (ACL) attribute for an object. For enumeration values, please refer to the Preset ACL section for objects in the ACL Overview document, such as default, private, public-read, etc.
Note: If you do not require object ACL control, set it to default or leave it unset. By default, it will inherit the bucket permissions.
String
Not required
GrantRead
Grant the permission to read the object to the authorized party, format: id="[OwnerUin]". Multiple authorized parties can be separated using a comma (,):
When granting permissions to a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
When granting permissions to the root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>" For example, 'id="qcs::cam::uin/100000000001:uin/100000000001"id="qcs::cam::uin/100000000001:uin/100000000011"'
String
Not required
GrantFullControl
Grant all permissions for the authorized user to operate on the object, format: id="[OwnerUin]". Multiple authorized users can be separated by a comma (,):
When granting permissions to a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
When granting permissions to the root account, id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
For example: 'id="qcs::cam::uin/100000000001:uin/100000000001",id="qcs::cam::uin/100000000001:uin/100000000011"'
String
Not required
StorageClass
Set the object's storage type with enumeration values: STANDARD, STANDARD_IA, ARCHIVE, DEEP_ARCHIVE, etc. The default value is STANDARD. For more storage types, see Storage Class Overview.
String
Not required
x-cos-meta-*
User-defined headers, which will be returned as the object metadata. The maximum size is 2 KB.
String
Not required
UploadAddMetaMd5
Sets x-cos-meta-md5 as the object’s MD5 value in the object’s metadata during upload in the format of a 32-bit lowercase string. For example: 4d00d79b6733c9cc066584a02ed03410
String
Not required

Callback function description

function(err, data) { ... }
Parameter
ParameterDescription
Local Disk Types
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, see Error Codes.
Object
data
Object 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, see Object Overview.
String
UploadId
Upload ID, which is required for the subsequent upload
String

Uploading parts

Note

This API 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 multiple upload.
When you use the Initiate Multipart Upload API to initiate a multipart upload, you can obtain the uploadId. This ID uniquely identifies the part and its position in the entire object.
Every time you call the Upload Part API, you need to pass partNumber (the part number) and uploadId. You can upload multiple parts out of order.
When the uploadId and partNumber of a new part are the same as those of a previously uploaded part, the old part will be overwritten. If the uploadId does not exist, the 404 error, "NoSuchUpload", will be returned.

Use Cases

cos.multipartUpload({
Bucket: 'examplebucket-1250000000', /* Enter your own bucket, required field */
Region: 'COS_REGION', /* Required field specifying the region where the bucket is located, e.g., ap-beijing */
Key: '1.jpg', /* The object key stored in the bucket (e.g., 1.jpg, a/b/test.txt), required field */
UploadId: 'exampleUploadId',
PartNumber: 1,
Body: fileObject, /* Required, uploaded file object, can be the file object obtained after selecting a local file using the input[type="file"] tag */
}, function(err, data) {
console.log(err || data);
if (data) {
eTag = data.ETag;
}
});

Description

Parameter
ParameterDescription
Local Disk Types
Required
Bucket
Bucket name in the format of BucketName-APPID.
String
Required
Region
Bucket region. For the enumerated values, see Regions and Access Endpoints.
String
Required
Key
Object key (object name), the unique identifier of an object in a bucket. For more information, see Object Overview.
String
Required
ContentLength
The length of the content of an HTTP request in bytes as defined in RFC 2616
String
Required
PartNumber
Part number
Number
Required
UploadId
ID of the multipart upload task
String
Required
Body
Content of the file part to be uploaded. This parameter can be a File object or a Blob object.
String\File\Blob\ArrayBuffer
Required
Expect
If Expect: 100-continue is used, the request content will be sent only after confirmation from the server is received.
String
Not required
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
Not required

Callback function description

function(err, data) { ... }
Parameter
ParameterDescription
Local Disk Types
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, see Error Codes.
Object
- statusCode
HTTP status code, such as 200, 403, and 404
Number
- headers
Returned headers
Object
data
Object 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
Returned headers
Object

Querying uploaded parts

Note

This API (List Parts) is used to query the uploaded parts of a specified multipart upload, i.e., listing all successfully uploaded parts of a multipart upload with a specified uploadId.

Use Cases

cos.multipartListPart({
Bucket: 'examplebucket-1250000000', /* Enter your own bucket, required field */
Region: 'COS_REGION', /* Required field specifying the region where the bucket is located, e.g., ap-beijing */
Key: '1.jpg', /* The object key stored in the bucket (e.g., 1.jpg, a/b/test.txt), required field */
UploadId: 'exampleUploadId', /* Required */
}, function(err, data) {
console.log(err || data);
});

Description

Parameter
ParameterDescription
Local Disk Types
Required
Bucket
Bucket name in the format of BucketName-APPID.
String
Required
Region
Bucket region. For the enumerated values, see Regions and Access Endpoints.
String
Required
Key
Object key (object name), the unique identifier of an object in a bucket. For more information, see Object Overview.
String
Required
UploadId
Multipart upload ID obtained from the Initiate Multipart Upload API
String
Required
EncodingType
Encoding type of the returned value
String
Not required
MaxParts
Maximum number of parts to return at a time. Defaults to 1000
String
Not required
PartNumberMarker
By default, entries are listed in UTF-8 binary order, starting from the part number after the marker.
String
Not required

Callback function description

function(err, data) { ... }
Parameter
ParameterDescription
Local Disk Types
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, see Error Codes.
Object
- statusCode
HTTP status code, such as 200, 403, and 404
Number
- headers
Returned headers
Object
data
Object 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
Returned headers
Object
- Bucket
Destination bucket for the multipart upload
String
- Encoding-type
Encoding type of the returned value
String
- Key
Object key (object name), the unique identifier of an object in a bucket. For more information, see Object Overview.
String
- UploadId
ID of the multipart upload
String
- Initiator
Indicates information about the initiator of this upload
Object
- - DisplayName
Name of the upload initiator
String
- - ID
Initiator ID format: qcs::cam::uin/<OwnerUin>:uin/<SubUin>,
If it is a root account, <OwnerUin> and <SubUin> have the same value.
String
- Owner
Information about the request initiator
Object
- - DisplayName
Name of the bucket owner
String
- - ID
ID of the bucket owner. This parameter is usually the user’s UIN.
String
- StorageClass
The storage classes for these parts include STANDARD, STANDARD_IA, ARCHIVE, DEEP_ARCHIVE, etc. For more information on storage classes, see Storage Class Overview.
String
- PartNumberMarker
By default, entries are listed in UTF-8 binary order, starting from the part number 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
Whether the returned list is truncated. Valid values: true, false.
String
- Part
Part information list
ObjectArray
- - PartNumber
Part number
String
- - LastModified
Last modified time of a part
String
- - ETag
MD5 checksum of a part
String
- - Size
Part size, in bytes
String

Completing multipart upload

Note

The Complete Multipart Upload API request is used to complete the entire multipart upload process. After uploading all parts using Upload Parts, you must call this API to finalize the multipart upload of the entire file. When using this API, you must provide the PartNumber and ETag of each part in the request body to verify the accuracy of the parts. Since it takes a few minutes to merge the parts after the multipart upload is completed, COS immediately returns a 200 status code when the merging process begins. During the merging process, COS periodically sends whitespace information to maintain an active connection until the merge is complete. Upon completion, COS returns the merged content in the response body.
If any uploaded part is less than 1 MB in size, 400 (EntityTooSmall) will be returned when this API is called.
If the uploaded part numbers are not continuous, "400 InvalidPart" will be returned when this API is called.
If the part information entries in the request body are not sorted by number in ascending order, "400 InvalidPartOrder" will be returned when this API is called.
If the uploadId does not exist, "404 NoSuchUpload" will be returned when this API is called.
Note:
We recommend you either complete or abort a multipart upload as early as possible, as the uploaded parts of an incomplete multipart upload will take up storage capacity and incur storage fees.

Use Cases

cos.multipartComplete({
Bucket: 'examplebucket-1250000000', /* Enter your own bucket, required field */
Region: 'COS_REGION', /* Required field specifying the region where the bucket is located, e.g., ap-beijing */
Key: '1.jpg', /* The object key stored in the bucket (e.g., 1.jpg, a/b/test.txt), required field */
UploadId: 'exampleUploadId', /* Required */
Parts: [
{PartNumber: 1, ETag: 'exampleETag'},
]
}, function(err, data) {
console.log(err || data);
});

Description

Parameter
ParameterDescription
Local Disk Types
Required
Bucket
Bucket name in the format of BucketName-APPID.
String
Required
Region
Bucket region. For the enumerated values, see Regions and Access Endpoints.
String
Required
Key
Object key (object name), the unique identifier of an object in a bucket. For more information, see Object Overview.
String
Required
UploadId
ID of the upload task
String
Required
Parts
A list of information about the parts of the multipart upload
ObjectArray
Required
- PartNumber
Part number
Number
Required
- ETag
The MD5 checksum value for each block file
For example, "22ca88419e2ed4721c23807c678adbe4c08a7880", please note the double quotes before and after the value
String
Required

Callback function description

function(err, data) { ... }
Parameter
ParameterDescription
Local Disk Types
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, see Error Codes.
Object
- statusCode
HTTP status code, such as 200, 403, and 404
Number
- headers
Returned headers
Object
data
Object 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
Returned headers
Object
- Location
The location where the uploaded file can be accessed
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, see Object Overview.
String
- ETag
The unique ID of the merged file, in the format: "uuid-<number of parts>"
For example, "22ca88419e2ed4721c23807c678adbe4c08a7880-3", note the double quotes before and after.
String

Aborting a multipart upload

Note

This API (Abort Multipart Upload) is used to abort a multipart upload and delete the uploaded parts. If you call this API and there is an Upload Part request that is using the multipart upload, the request will fail. If the uploadId does not exist, "404 NoSuchUpload" will be returned.
Note:
We recommend you either complete or abort a multipart upload as early as possible, as the uploaded parts of an incomplete multipart upload will take up storage capacity and incur storage fees.

Use Cases

cos.multipartAbort({
Bucket: 'examplebucket-1250000000', /* Enter your own bucket, required field */
Region: 'COS_REGION', /* Required field specifying the region where the bucket is located, e.g., ap-beijing */
Key: '1.jpg', /* The object key stored in the bucket (e.g., 1.jpg, a/b/test.txt), required field */
UploadId: 'exampleUploadId' /* Required */
}, function(err, data) {
console.log(err || data);
});


Description

Parameter
ParameterDescription
Local Disk Types
Required
Bucket
Bucket name in the format of BucketName-APPID.
String
Required
Region
Bucket region. For the enumerated values, see Regions and Access Endpoints.
String
Required
Key
Object key (object name), the unique identifier of an object in a bucket. For more information, see Object Overview.
String
Required
UploadId
Multipart upload ID obtained from the Initiate Multipart Upload API
String
Required

Callback function description

function(err, data) { ... }
Parameter
ParameterDescription
Local Disk Types
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, see Error Codes.
Object
- statusCode
HTTP status code, such as 200, 403, and 404
Number
- headers
Returned headers
Object
data
Object 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
Returned headers
Object