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
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 | 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 | 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 | 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.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 uploadvar 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 | 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/13318var 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/13318var 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 |