The content of this page has been automatically translated by AI. If you encounter any problems while reading, you can view the corresponding content in Chinese.
Help & Documentation>Cloud Object Storage>SDK Documentation>JavaScript SDK>Object Operations>Copying and Moving Objects

Copying and Moving Objects

Last updated: 2026-05-12 09:28:30

On this page:

Introduction

This document provides example code and descriptions for implementing the copy and move object features in COS using the JavaScript.js SDK. The content is divided into three parts: the advanced API, simple operations, and multipart operations.

Must-Knows

To copy objects using the simple API, you must have read permission for the source object and write permission for the target object. When you create an authorization policy, set the authorization action for the target object to cos:PutObject and the authorization action for the source object to cos:GetObject. For more information on authorization, see CAM-supported APIs.
To perform multipart copy using the automatic multipart copy feature of the advanced API or the multipart operation of the simple API, you must have read permission for the source object and permissions for the target object to initiate multipart upload, upload objects, and complete multipart upload. When you create an authorization policy, set the authorization action for the target object to cos:InitiateMultipartUpload, cos:PutObject, and cos:CompleteMultipartUpload, and set the authorization action for the source object to cos:GetObject. For more information on authorization, see CAM-supported APIs.

Preliminary Preparation

Before you start using it, ensure that you have completed cross-domain configuration and SDK initialization.

Advanced API (recommended)

It is strongly recommended that you use the advanced API. This method encapsulates the native methods described below and implements the entire multipart copy process.

Copying Objects in Chunks

Feature Overview

The Slice Copy File API can be used to copy a file from a source path to a target path via multipart copy. During the copy process, object metadata and ACLs can be modified. Users can use this API to move files, rename files, modify file attributes, and create copies.
// Copy a/1.jpg to b/1.jpg
cos.sliceCopyFile({
    Bucket: 'examplebucket-1250000000', // Enter your own bucket, required field
    Region: 'COS_REGION', // The region where the bucket resides, for example, ap-beijing, required field
    Key: 'b/1.jpg', // The object key stored in the bucket (for example, 1.jpg, a/b/test.txt), required field
    CopySource: 'sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/a/1.jpg', // Required
    onProgress:function (progressData) {                     // Optional
        console.log(JSON.stringify(progressData));
    }
},function (err,data) {
    console.log(err || data);
});

Parameter Description

Parameter Name
Parameter Description
Type
Required
Bucket
Name of the bucket, in BucketName-APPID format. The bucket name entered here must be in this format.
String
Yes
Region
Region of the bucket. For the enumeration values, see Regions and Access Domains.
String
Yes
Key
Object key (name of the Object), which uniquely identifies an object within a bucket. For details, see Object Overview.
String
Yes
CopySource
URL path of the source object. A historical version can be specified using the URL parameter ?versionId=<versionId>.
String
Yes
ChunkSize
Size of each part during multipart copying, in bytes. Default value: 1048576 (1MB).
Number
No
SliceSize
Indicates that multipart copy is used when the file size exceeds a threshold, in bytes. Default value: 5G. If the file size is less than or equal to this threshold, putObjectCopy is used for copying. If the file size is greater than this threshold, sliceCopyFile is used for copying.
Number
No
onProgress
Callback function for the file copy progress. The callback parameter is the progress object progressData.
Function
No
- progressData.loaded
Size of the copied portion of the file, in Bytes.
Number
No
- progressData.total
Size of the entire file, in bytes.
Number
No
- progressData.speed
Copy speed of the file, in Bytes/s.
Number
No
- progressData.percent
Percentage of the file that has been copied, presented as a decimal. For example: 50% copied is 0.5.
Number
No

Callback Function Description

function(err, data) { ... }
Parameter Name
Parameter Description
Type
err
The object returned when a request error occurs, including network errors and business errors. It is null if the request is successful. For more details, see the Error Codes document.
Object
- statusCode
HTTP status code returned by the request, such as 200, 403, 404, and so on
Number
- headers
Header returned by the request
Object
data
The object returned when the request is successful, or null if an error occurs in the request
Object
- statusCode
HTTP status code returned by the request, such as 200, 403, 404, and so on
Number
- headers
Header returned by the request
Object
- Location
Public network access endpoint for the created object
String
- Bucket
Target bucket
String
- Key
Object key (name of the Object), which uniquely identifies an object within a bucket. For details, see Object Overview.
String
- ETag
MD5 algorithm check value of the merged file
For example, "22ca88419e2ed4721c23807c678adbe4c08a7880". Note that double quotation marks are required at both ends.
String
- VersionId
Version ID of an object.
String

Simple Operations

The PUT Object - Copy request creates a copy of an object that already exists in COS, which copies an object from a source path (object key) to a target path (object key). During the copy process, object metadata and Access Control Lists (ACLs) can be modified. Users can use this API to create copies, modify object metadata (where the source object and target file have the same attributes), or move or rename objects (by copying first and then calling the delete API separately).
Note:
It is recommended that the object size be between 1 MB and 5 GB. For objects larger than 5 GB, use the advanced API Slice Copy File to copy the object.

Copying Objects

// Copy a/1.jpg to b/1.jpg
cos.putObjectCopy({
    Bucket: 'examplebucket-1250000000', // Enter your own bucket, required field
    Region: 'COS_REGION', // The region where the bucket resides, for example, ap-beijing, required field
    Key: 'b/1.jpg', // The object key stored in the bucket (for example, 1.jpg, a/b/test.txt), required field
    CopySource: 'examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/a/1.jpg', // Required
    // When the Key in CopySource contains Chinese characters, it must be escaped.
    // CopySource: `examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/${encodeURIComponent('a/ChineseFileName.jpg')}`,
}, function(err, data) {
    console.log(err || data);
});

Moving Objects

Feature Overview

Moving an object primarily involves two operations: copying the source object to the target location and deleting the source object.
COS identifies objects by Bucket name and object key. Therefore, moving an object means modifying its identifier. COS does not currently provide a dedicated API for modifying an object's unique identifier. However, you can achieve this by combining the basic operations of copying an object and deleting an object, which allows you to modify the object's identifier and thereby move the object.
// Move a/1.jpg to b/1.jpg
// Alternatively, you can replace it with the advanced copy implementation, cos.sliceCopyFile.
cos.putObjectCopy({
    Bucket: 'examplebucket-1250000000', // Enter your own bucket, required field
    Region: 'COS_REGION', // The region where the bucket resides, for example, ap-beijing, required field
    Key: 'b/1.jpg', // The object key stored in the bucket (for example, 1.jpg, a/b/test.txt), required field
    CopySource: 'sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/a/1.jpg', // Required
}, function(err, data) {
    if (err) return console.log(err);
    // Delete a/1.jpg
    cos.deleteObject({
        Bucket: 'examplebucket-1250000000', // Enter your own bucket, required field
        Region: 'COS_REGION', // The region where the bucket resides, for example, ap-beijing, required field
        Key: 'b/1.jpg', // The object key stored in the bucket (for example, 1.jpg, a/b/test.txt), required field
    }, function(err, data) {
        console.log(err || data);
    });
});

Modifying the COS Storage Class

Feature Overview

To modify the storage class of an object, set the StorageClass when copying the object (where the source and destination are the same object).
// Set the storage class of 1.jpg in the root directory to ARCHIVE
// Alternatively, you can replace it with the advanced copy implementation, cos.sliceCopyFile.
cos.putObjectCopy({
    Bucket: 'examplebucket-1250000000', // Enter your own bucket, required field
    Region: 'COS_REGION', // The region where the bucket resides, for example, ap-beijing, required field
    Key: '1.jpg', // The object key stored in the bucket (for example, 1.jpg, a/b/test.txt), required field
    CopySource: 'sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/1.jpg', // Required
    StorageClass: 'ARCHIVE', // Set to ARCHIVE storage class
}, function(err, data) {
    console.log(err || data);
});

Parameter Description

Description of Input Parameters

Parameter Name
Parameter Description
Type
Required
Bucket
Name of the bucket, in BucketName-APPID format. The bucket name entered here must be in this format.
String
Yes
Region
Region of the bucket. For the enumeration values, see Regions and Access Domains.
String
Yes
Key
Object key (name of the Object), which uniquely identifies an object within a bucket. For details, see Object Overview.
String
Yes
CopySource
URL path of the source object. A historical version can be specified using the URL parameter ?versionId=<versionId>.
String
Yes
ACL
Defines the Access Control List (ACL) property of the object. For the enumeration values, see the Preset ACL section for objects in the ACL Overview document, such as default, private, public-read, and so on.
Note: If you do not need to control the object ACL, set it to default or leave this field unset, and it will inherit the bucket permissions by default.
String
No
GrantRead
Grants the grantee permission to read the object. Format: id="[OwnerUin]". Multiple grantees can be separated by commas (,).
When you need to grant permissions to a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
When you need to grant permissions to a 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
No
GrantWrite
Grants the grantee permission to write to the object. Format: id="[OwnerUin]". Multiple grantees can be separated by commas (,).
When you need to grant permissions to a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
When you need to grant permissions to a 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
No
GrantFullControl
Grants the grantee full control permissions over the object. Format: id="[OwnerUin]". Multiple grantees can be separated by commas (,).
When you need to grant permissions to a sub-account, set id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
When you need to grant permissions to a root account, set id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
For example, 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String
No
MetadataDirective
Whether to copy metadata. Enumeration values: Copy, Replaced. Default value: Copy. If set to Copy, the user metadata information in the Header is ignored and copied directly. If set to Replaced, the metadata is modified according to the Header information. When the target path is the same as the source path, meaning the user attempts to modify the metadata, it must be set to Replaced.
String
No
CopySourceIfModifiedSince
If the object has been modified after the specified time, the operation is performed; otherwise, 412 is returned. Can be used together with CopySourceIfNoneMatch. Using it with other conditions returns a conflict.
String
No
CopySourceIfUnmodifiedSince
If the object has not been modified after the specified time, the operation is performed; otherwise, 412 is returned. Can be used together with CopySourceIfMatch. Using it in conjunction with other conditions returns a conflict.
String
No
CopySourceIfMatch
If the object's Etag matches the given one, the operation is performed; otherwise, 412 is returned. Can be used together with CopySourceIfUnmodifiedSince. Using it in conjunction with other conditions returns a conflict.
String
No
CopySourceIfNoneMatch
If the object's Etag does not match the given one, the operation is performed; otherwise, 412 is returned. Can be used together with CopySourceIfModifiedSince. Using it in conjunction with other conditions returns a conflict.
String
No
StorageClass
Sets the storage class of the object. Enumeration values: STANDARD, STANDARD_IA, and so on. Default value: STANDARD. For more storage classes, see Storage Class Overview.
String
No
x-cos-meta-*
Other custom file headers
String
No

Callback function description

function(err, data) { ... }
Parameter Name
Parameter Description
Type
err
The object returned when a request error occurs, including network errors and business errors. It is null if the request is successful. For more details, see Error Codes.
Object
- statusCode
HTTP status code returned by the request, such as 200, 403, 404, and so on.
Number
- headers
Header returned by the request
Object
data
The object returned when the request is successful, or null if an error occurs in the request
Object
- statusCode
HTTP status code returned by the request, such as 200, 403, 404, and so on.
Number
- headers
Header returned by the request
Object
- ETag
MD5 algorithm checksum of the file, for example "22ca88419e2ed4721c23807c678adbe4c08a7880". Note that double quotation marks are required at both ends.
String
- LastModified
Last modification time of the returned object, for example 2017-06-23T12:33:27.000Z.
String
- VersionId
Version ID of an object.
String

Multipart Operations

Operation Process

Multipart Copy Process

1. Initialize the multipart copy (Initiate Multipart Upload) to obtain the UploadId.
2. Copy the parts using the UploadId (Upload Part).
3. Complete the multipart copy (Complete Multipart Upload).

Multipart Copy Process

1. If you have not recorded the UploadId, first query the multipart uploads (List Multipart Uploads) to obtain the UploadId for the corresponding file.
2. List the copied parts using the UploadId (List Parts).
3. Copy the remaining parts using the UploadId (Upload Part).
4. Complete the multipart copy (Complete Multipart Upload).

Terminating a Multipart Copy Process

1. If you have not recorded the UploadId, query the multipart uploads (List Multipart Uploads) to obtain the UploadId for the corresponding file.
2. Abort the multipart copy and delete the copied parts (Abort Multipart Upload).
Note:
Generally, you do not need to focus on the following methods. The sliceCopyFile function has encapsulated the multipart operations, so you can call it directly.

Use Case: Initializing a Multipart Copy

Feature Overview

The Initiate Multipart Upload request initializes a multipart copy. Upon successful execution, it returns an Upload ID for subsequent Upload Part - Copy requests.

Use Case

cos.multipartInit({
    Bucket: 'examplebucket-1250000000', // Enter your own bucket, required field
    Region: 'COS_REGION', // The region where the bucket resides, for example, ap-beijing, required field
    Key: '1.jpg', // The object key stored in the bucket (for example, 1.jpg, a/b/test.txt), required field
}, function(err, data) {
    console.log(err || data);
    if (data) {
      uploadId = data.UploadId;
    }
});

Parameter Description

Parameter Name
Parameter Description
Type
Required
Bucket
Name of the bucket, in BucketName-APPID format. The bucket name entered here must be in this format.
String
Yes
Region
Region of the bucket. For the enumeration values, see Regions and Access Domains.
String
Yes
Key
Object key (name of the Object), which uniquely identifies an object within a bucket. For details, see Object Overview.
String
Yes
CacheControl
Cache policy defined in RFC 2616, to be saved as object metadata.
String
No
ContentDisposition
File name defined in RFC 2616, to be saved as object metadata.
String
No
ContentEncoding
Encoding format defined in RFC 2616, to be saved as object metadata.
String
No
ContentType
Content type (MIME) defined in RFC 2616, to be saved as object metadata.
String
No
Expires
Expiration time defined in RFC 2616, to be saved as object metadata.
String
No
ACL
Defines the Access Control List (ACL) property of the object. For the enumeration values, see the Preset ACL section for objects in the ACL Overview document, such as default, private, public-read, and so on.
Note: If you do not need to control the object ACL, set it to default or leave this field unset, and it will inherit the bucket permissions by default.
String
No
GrantRead
Grants the grantee permission to read the object. Format: id="[OwnerUin]". Multiple grantees can be separated by commas (,).
When you need to grant permissions to a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
When you need to grant permissions to a 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
No
GrantFullControl
Grants the grantee full control permissions over the object. Format: id="[OwnerUin]". Multiple grantees can be separated by commas (,).
When you need to grant permissions to a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
When you need to grant permissions to a 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
No
StorageClass
Sets the storage class of the object. Enumeration values: STANDARD, STANDARD_IA, ARCHIVE, DEEP_ARCHIVE, and so on. Default value: STANDARD. For more storage classes, see Storage Class Overview.
String
No
x-cos-meta-*
Allows user-defined headers, which will be returned as object metadata. Size limit: 2KB.
String
No
UploadAddMetaMd5
When copying is performed, adds the x-cos-meta-md5 field to the object's metadata and sets its value to the MD5 hash of the object content, in the format of a 32-character lowercase string. For example: 4d00d79b6733c9cc066584a02ed03410.
String
No

Callback function description

function(err, data) { ... }
Parameter Name
Parameter Description
Type
err
The object returned when a request error occurs, including network errors and business errors. It is null if the request is successful. For more details, see Error Codes.
Object
data
The object returned when the request is successful, or null if an error occurs in the request
Object
Bucket
The destination bucket, formed by concatenating a user-defined string and a system-generated APPID numeric string with a hyphen, for example, examplebucket-1250000000.
String
Key
Object key (name of the Object), which uniquely identifies an object within a bucket. For details, see Object Overview.
String
UploadId
ID used in subsequent replication
String

Use Case: Copying a Multipart

Feature Overview

The Upload Part - Copy API request copies the multipart content of an object from a source path to a destination path.
Note:
To copy a multipart object, you must first initialize a multipart copy. The response to initializing a multipart copy returns a unique descriptor (upload ID), which you need to include in your multipart copy request.

Use Case

cos.uploadPartCopy({
    Bucket: 'examplebucket-1250000000', // Enter your own bucket, required field
    Region: 'COS_REGION', // The region where the bucket resides, for example, ap-beijing, required field
    Key: '1.jpg', // The object key stored in the bucket (for example, 1.jpg, a/b/test.txt), required field
    CopySource: 'sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/sourceObject', // Required
    UploadId: 'exampleUploadId', // Required
    PartNumber: '1', // Required
}, function(err, data) {
    console.log(err || data);
    if (data) {
      eTag = data.ETag;
    }
});

Parameter Description

Parameter Name
Parameter Description
Type
Required
Bucket
Name of the bucket, in BucketName-APPID format. The bucket name entered here must be in this format.
String
Yes
Region
Region of the bucket. For the enumeration values, see Regions and Access Domains.
String
Yes
Key
Object key (name of the Object), which uniquely identifies an object within a bucket. For details, see Object Overview.
String
Yes
CopySource
URL path of the source object. A historical version can be specified using the URL parameter ?versionId=<versionId>.
String
Yes
partNumber
Number of a part during multipart copying.
String
Yes
uploadId
To use multipart copy, you must first initialize the multipart copy operation. The response to the initialization returns a unique descriptor (upload ID), which you need to include in the multipart copy request.
String
Yes
CopySourceRange
Byte range of the source object. The range value must be in the bytes=first-last format, where first and last are zero-based offsets. For example, bytes=0-9 indicates that you want to copy the first 10 bytes of the source object. If not specified, the entire object is copied.
String
No
CopySourceIfMatch
If the object's Etag matches the given one, the operation is performed; otherwise, 412 is returned. It can be used together with x-cos-copy-source-If-Unmodified-Since. Using it in conjunction with other conditions returns a conflict.
String
No
CopySourceIfNoneMatch
If the object's Etag does not match the given one, the operation is performed; otherwise, 412 is returned. It can be used together with x-cos-copy-source-If-Modified-Since. Using it in conjunction with other conditions returns a conflict.
String
No
CopySourceIfUnmodifiedSince
If the object has not been modified after the specified time, the operation is performed; otherwise, 412 is returned. It can be used together with x-cos-copy-source-If-Match. Using it in conjunction with other conditions returns a conflict.
String
No
CopySourceIfModifiedSince
If the object has been modified after the specified time, the operation is performed; otherwise, 412 is returned. It can be used together with x-cos-copy-source-If-None-Match. Using it in conjunction with other conditions returns a conflict.
String
No

Callback function description

function(err, data) { ... }
Parameter Name
Parameter Description
Type
err
The object returned when a request error occurs, including network errors and business errors. It is null if the request is successful. For more details, see Error Codes.
Object
- statusCode
HTTP status code returned by the request, such as 200, 403, 404, and so on
Number
- headers
Header returned by the request
Object
data
The object returned when the request is successful, or null if an error occurs in the request
Object
- statusCode
HTTP status code returned by the request, such as 200, 403, 404, and so on
Number
- headers
Header returned by the request
Object
- ETag
MD5 algorithm checksum of the file, for example "22ca88419e2ed4721c23807c678adbe4c08a7880". Note that double quotation marks are required at both ends.
String
- LastModified
Last modification time of the object, in GMT format.
String

Use Case: Completing a Multipart Copy

Feature Overview

The Complete Multipart Upload API request is used to complete the entire multipart copy operation. After you have copied all parts using Copy Parts, you must call this API to complete the multipart copy of the entire file. When using this API, you must provide the PartNumber and ETag for each part in the request Body to verify the accuracy of the parts. Because the parts need to be merged after the multipart copy, and merging takes several minutes, COS immediately returns a 200 status code when the part merging begins. During the merging process, COS periodically returns whitespace information to keep the connection alive. Once the merge is complete, COS returns the content of the merged part in the response Body.
When the copied part is smaller than 1 MB, calling this API returns 400 EntityTooSmall.
When the part numbers are not consecutive, calling this API returns 400 InvalidPart.
When the part information in the request body is not arranged in ascending order by sequence number, calling this API will return 400 InvalidPartOrder.
When the UploadId does not exist, calling this API will return 404 NoSuchUpload.
Note:
We recommend that you promptly complete or abort the multipart copy operation, as parts that have been copied but not finalized occupy storage space and consequently incur storage costs.

Use Case

cos.multipartComplete({
    Bucket: 'examplebucket-1250000000', // Enter your own bucket, required field
    Region: 'COS_REGION', // The region where the bucket resides, for example, ap-beijing, required field
    Key: '1.jpg', // The object key stored in the bucket (for example, 1.jpg, a/b/test.txt), required field
    UploadId: 'exampleUploadId', // Obtained when initializing the multipart task, required
    Parts: [
        {PartNumber: '1', ETag: 'exampleETag'},
    ]
}, function(err, data) {
    console.log(err || data);
});

Parameter Description

Parameter Name
Parameter Description
Type
Required
Bucket
Name of the bucket, in BucketName-APPID format. The bucket name entered here must be in this format.
String
Yes
Region
Region of the bucket. For the enumeration values, see Regions and Access Domains.
String
Yes
Key
Object key (name of the Object), which uniquely identifies an object within a bucket. For details, see Object Overview.
String
Yes
UploadId
Copy job ID
String
Yes
Parts
List of information for the parts in this multipart copy operation.
ObjectArray
Yes
- PartNumber
Number of a part
String
Yes
- ETag
MD5 algorithm checksum value of each part file
For example, "22ca88419e2ed4721c23807c678adbe4c08a7880". Note that double quotation marks are required at both ends.
String
Yes

Callback function description

function(err, data) { ... }
Parameter Name
Parameter Description
Type
err
The object returned when a request error occurs, including network errors and business errors. It is null if the request is successful. For more details, see Error Codes.
Object
- statusCode
HTTP status code returned by the request, such as 200, 403, 404, and so on
Number
- headers
Header returned by the request
Object
data
The object returned when the request is successful, or null if an error occurs in the request
Object
- statusCode
HTTP status code returned by the request, such as 200, 403, 404, and so on
Number
- headers
Header returned by the request
Object
- Location
Access URL of the copied file
String
- Bucket
Target bucket
String
- Key
Object key (name of the Object), which uniquely identifies an object within a bucket. For details, see Object Overview.
String
- ETag
Unique ID of the merged file, in the format: "uuid-<number of parts>"
For example, "22ca88419e2ed4721c23807c678adbe4c08a7880-3". Note that double quotation marks are required at both ends.
String

API Operations

For the description of the API for simple operations, see the PUT Object - Copy document.
For the description of the APIs for multipart operations, see the List Multipart Uploads, Initiate Multipart Upload, Upload Part - Copy, List Parts, Abort Multipart Upload, and Complete Multipart Upload documents.
中国站 - English