tencent cloud

All product documents
Cloud Object Storage
Copying and Moving Objects
Last updated: 2024-02-02 16:24:05
Copying and Moving Objects
Last updated: 2024-02-02 16:24:05

Overview

This document provides an overview of APIs and SDK code samples for copying and moving an object.
Simple operations
API
Operation
Description
Copying object
Copies object to destination path.
Multipart upload operations
API
Operation
Description
Querying multipart uploads/copies
Queries multipart uploads/copies in progress.
Initializing multipart upload/copy operation
Initializes multipart upload/copy operation.
Copying part
Copies object as part.
Querying uploaded/copied parts
Queries uploaded/copied parts of multipart upload.
Completing multipart upload/copy
Completes multipart upload/copy.
Aborting multipart upload/copy
Aborts multipart upload operation and deletes uploaded/copied parts.

Advanced APIs (Recommended)

The advanced APIs encapsulate simple APIs via the TransferManager class to provide APIs for easier operations. Internally, a thread pool is used to concurrently accept and process requests, so you can choose to execute tasks asynchronously after submitting multiple tasks.
TransferManager instances are concurrency safe. We recommend you create only one TransferManager instance for a process and then shut it down when it is no longer used to call advanced APIs.

Feature description

The advanced APIs encapsulate the APIs for copy in whole and multipart copy and automatically select the copy method based on the file size.

Creating TransferManager instance

Before using advanced APIs, you must create a TransferManager instance first.
// Create a TransferManager instance, which is used to call advanced APIs later.
TransferManager createTransferManager() {
// Create a COSClient client, which is the basic instance for accessing the COS service.
// The COSClient instance created here is based on the information of the destination for copying.
// For the detailed code, see **Simple Operations** > **Creating COSClient instance** on this page.
COSClient cosClient = createCOSClient();

// Set the thread pool size. We recommend you set the size of your thread pool to 16 or 32 to maximize network resource utilization, provided your client and COS networks are sufficient (for example, uploading a file to a COS bucket from a CVM instance in the same region).
// We recommend you use a smaller value to avoid timeout caused by slow network speed if you are transferring data over a public network with poor bandwidth quality.
ExecutorService threadPool = Executors.newFixedThreadPool(32);

// Pass a `threadpool`; otherwise, a single-thread pool will be generated in `TransferManager` by default.
TransferManager transferManager = new TransferManager(cosClient, threadPool);

// Set the configuration items of the advanced API.
// Set the threshold and part size for multipart copy to 5 MB and 1 MB respectively.
TransferManagerConfiguration transferManagerConfiguration = new TransferManagerConfiguration();
transferManagerConfiguration.setMultipartCopyThreshold(5*1024*1024);
transferManagerConfiguration.setMultipartCopyPartSize(1*1024*1024);
transferManager.setConfiguration(transferManagerConfiguration);

return transferManager;
}

Parameter description

The TransferManagerConfiguration class is used to record the configuration information of advanced APIs. Its main members are as described below:
Member Name
Configuration Method
Description
Type
minimumUploadPartSize
Set method
Part size of the multipart upload in bytes. Default value: 5 MB.
long
multipartUploadThreshold
Set method
If a file is greater than or equal to this value in bytes, it will be uploaded in concurrent parts. Default value: 5 MB.
long
multipartCopyThreshold
Set method
If a file is greater than or equal to this value in bytes, it will be copied in concurrent parts. Default value: 5 GB.
long
multipartCopyPartSize
Set method
Part size in bytes for multipart copy. Default value: 100 MB.
long

Shutting down TransferManager instance

After confirming that the process no longer uses the TransferManager instance to call advanced APIs, be sure to shut it down to avoid resource leakage.
void shutdownTransferManager(TransferManager transferManager) {
// If the parameter is set to `true`, the COSClient instance in the TransferManager instance will also be shut down at the same time.
// If the parameter is set to `false`, the COSClient instance in the TransferManager instance will not be shut down.
transferManager.shutdownNow(true);
}

Intra-region replication

Intra-region replication is possible only when the source and destination objects belong to the same region.

Method prototype

// Upload an object.
public Copy copy(final CopyObjectRequest copyObjectRequest);

Sample request

// Before using advanced APIs, you must make sure that the process contains a TransferManager instance; if not, then create one.
// For the detailed code, see **Advanced APIs** > **Creating TransferManager instance** on this page.
TransferManager transferManager = createTransferManager();
// Source bucket region.
Region srcBucketRegion = new Region("ap-beijing");
// Enter the source bucket name in the format of `BucketName-APPID`.
String srcBucketName = "srcbucket-1250000000";
// Source file path.
String srcKey = "path/srckey";

// Enter the destination bucket name in the format of `BucketName-APPID`.
String destBucketName = "destbucket-1250000000";
// Destination file path.
String destKey = "path/destkey";

CopyObjectRequest copyObjectRequest = new CopyObjectRequest(srcBucketRegion, srcBucketName,
srcKey, destBucketName, destKey);
try {
Copy copy = transferManager.copy(copyObjectRequest);
// The advanced API returns an asynchronous result `Copy`.
// You can synchronously call `waitForCopyResult` to wait for the copy to complete. If the copy is successful, `CopyResult` is returned; otherwise, an exception will be reported.
CopyResult copyResult = copy.waitForCopyResult();
System.out.println(copyResult.getRequestId());
} catch (CosServiceException e) {
e.printStackTrace();
} catch (CosClientException e) {
e.printStackTrace();
} catch (InterruptedException e) {
e.printStackTrace();
}

// After confirming that the process no longer uses the TransferManager instance, shut it down.
// For the detailed code, see **Advanced APIs** > **Shutting down TransferManager instance** on this page.
shutdownTransferManager(transferManager);

Parameter description

Parameter
Description
Type
copyObjectRequest
Object copy request
CopyObjectRequest
The request members are as described below:
Parameter
Description
Type
sourceBucketRegion
Region of the source bucket. Default value: The value of region in clientconfig, indicating intra-region replication.
String
sourceBucketName
Source bucket name in the format of BucketName-APPID
String
sourceKey
Unique identifier of the source object in the bucket. For example, if an object's access endpoint is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/do/picture.jpg, its key is doc/picture.jpg. For more information, see Object Overview.
String
sourceVersionId
Version number of the source file (for source buckets with versioning enabled). Default value: The latest version of the source file.
String
destinationBucketName
Destination bucket name in the format of BucketName-APPID.
String
destinationKey
Unique identifier of the destination object in the bucket. For example, if an object's access endpoint is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/do/picture.jpg, its key is doc/picture.jpg. For more information, see Object Overview.
String
storageClass
Storage class of the destination file, such as STANDARD (default) and STANDARD_IA. For more information, see Storage Class Overview.
String

Returned values

Success: Copy is returned. You can query whether the copy is complete, or wait for the copy to complete.
Failure: If an error (such as authentication failure) occurs, the CosClientException or CosServiceException exception will be reported. For more information, see Troubleshooting.

Cross-region replication

Cross-region replication is possible only when the source and destination objects belong to different regions, for example, when you want to copy an object from the Beijing bucket to the Shanghai bucket.
Note:
Cross-region replication is not supported between Finance Cloud regions and Public Cloud regions because these regions are not interconnected.

Method prototype

// Upload an object.
public Copy copy(final CopyObjectRequest copyObjectRequest);

Sample request

// The COSClient instance created here is based on the information of the destination for copying.
// Before using advanced APIs, you must make sure that the process contains a TransferManager instance; if not, then create one.
// For the detailed code, see **Advanced APIs** > **Creating TransferManager instance** on this page.
TransferManager transferManager = createTransferManager();
// Source bucket region.
Region srcBucketRegion = new Region("ap-beijing");
// Enter the source bucket name in the format of `BucketName-APPID`.
String srcBucketName = "srcbucket-1250000000";
// Source file path.
String srcKey = "path/srckey";

// Note: The region of the destination bucket is set through the `createTransferManager() -> createCOSClient() -> clientConfig.setRegion(dstRegion)` function when TransferManager/COSClient is created.
// Enter the destination bucket name in the format of `BucketName-APPID`.
String destBucketName = "destbucket-1250000000";
// Destination file path.
String destKey = "path/destkey";

// The COSClient instance created here is based on the information of the source for copying.
// For the detailed code, see **Simple Operations** > **Creating COSClient instance** on this page.
COSClient srcCOSClient = createCOSClient();

CopyObjectRequest copyObjectRequest = new CopyObjectRequest(srcBucketRegion, srcBucketName,
srcKey, destBucketName, destKey);
try {
Copy copy = transferManager.copy(copyObjectRequest, srcCOSClient, null);
// The advanced API returns an asynchronous result `Copy`.
// You can synchronously call `waitForCopyResult` to wait for the copy to complete. If the copy is successful, `CopyResult` is returned; otherwise, an exception will be reported.
CopyResult copyResult = copy.waitForCopyResult();
} catch (CosServiceException e) {
e.printStackTrace();
} catch (CosClientException e) {
e.printStackTrace();
} catch (InterruptedException e) {
e.printStackTrace();
}

// After confirming that the process no longer uses the TransferManager instance, shut it down.
// For the detailed code, see **Advanced APIs** > **Shutting down TransferManager instance** on this page.
shutdownTransferManager(transferManager);

Parameter description

Parameter
Description
Type
copyObjectRequest
Object copy request
CopyObjectRequest
The request members are as described below:
Parameter
Description
Type
sourceBucketRegion
Region of the source bucket. Default value: The value of region in clientconfig, indicating intra-region replication.
String
sourceBucketName
Source bucket name in the format of BucketName-APPID
String
sourceKey
Unique identifier of the source object in the bucket. For example, if an object's access endpoint is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/do/picture.jpg, its key is doc/picture.jpg. For more information, see Object Overview.
String
sourceVersionId
Version number of the source file (for source buckets with versioning enabled). Default value: The latest version of the source file.
String
destinationBucketName
Destination bucket name in the format of BucketName-APPID.
String
destinationKey
Unique identifier of the destination object in the bucket. For example, if an object's access endpoint is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/do/picture.jpg, its key is doc/picture.jpg. For more information, see Object Overview.
String
storageClass
Storage class of the destination file, such as STANDARD (default) and STANDARD_IA. For more information, see Storage Class Overview.
String

Returned values

Success: Copy is returned. You can query whether the copy is complete, or wait for the copy to complete.
Failure: If an error (such as authentication failure) occurs, the CosClientException or CosServiceException exception will be reported. For more information, see Troubleshooting.

Moving object

Object movement involves two steps: copying the source object to the destination location and then deleting the source object.
As COS uses the bucket name (Bucket) and object key (ObjectKey) to identify objects, moving an object will change the object identifier. Currently, COS's Java SDK does not provide a standalone API to change object identifiers. However, you can still move an object through a combination of basic operations (object copy and object delete).
For example, if you want to move the picture.jpg object to the doc directory that is in the same bucket (mybucket-1250000000), you can copy the picture.jpg object to the doc directory first (making the object key doc/picture.jpg) and then delete the source object.
Similarly, if you want to move the picture.jpg object in the mybucket-1250000000 bucket to another bucket myanothorbucket-1250000000, you can copy the object to the myanothorbucket-1250000000 bucket first and then delete the source object.

Sample request

// Source bucket region.
Region srcBucketRegion = new Region("ap-beijing");
// Enter the source bucket name in the format of `BucketName-APPID`.
String srcBucketName = "srcbucket-1250000000";
// Source file path.
String srcKey = "path/srckey";

// Destination bucket region.
Region destBucketRegion = new Region("ap-shanghai");
// Enter the destination bucket name in the format of `BucketName-APPID`.
String destBucketName = "destbucket-1250000000";
// Destination file path.
String destKey = "path/destkey";

// For the implementation details, see **Advanced APIs** > **Copying object** on this page.
copyObject();
// For the implementation details, see **Deleting object**.
deleteObject();

Simple Operations

Requests for simple operations need to be initiated through COSClient instances. You need to create a COSClient instance before performing simple operations.
COSClient instances are concurrency safe. We recommend you create only one COSClient instance for a process and then shut it down when it is no longer used to initiate requests.

Creating COSClient instance

Before calling the COS API, you must create a COSClient instance first.
// Create a COSClient instance, which is used to initiate requests later.
COSClient createCOSClient() {
// Set the user identity information.
// Log in to the [CAM console](https://console.tencentcloud.com/cam/capi) to view and manage the `SECRETID` and `SECRETKEY` of your project.
String secretId = "SECRETID";
String secretKey = "SECRETKEY";
COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);

// `ClientConfig` contains the COS client configuration for subsequent COS requests.
ClientConfig clientConfig = new ClientConfig();

// Set the bucket region.
// For more information on COS regions, visit https://www.tencentcloud.com/document/product/436/6224?from_cn_redirect=1.
clientConfig.setRegion(new Region("COS_REGION"));

// Set the request protocol to `http` or `https`.
// For 5.6.53 and earlier versions, HTTPS is recommended.
// Starting from 5.6.54, HTTPS is used by default.
clientConfig.setHttpProtocol(HttpProtocol.https);

// The following settings are optional:

// Set the read timeout period, which is 30s by default.
clientConfig.setSocketTimeout(30*1000);
// Set the connection timeout period, which is 30s by default.
clientConfig.setConnectionTimeout(30*1000);

// If necessary, set the HTTP proxy, IP, and port.
clientConfig.setHttpProxyIp("httpProxyIp");
clientConfig.setHttpProxyPort(80);

// Generate a COS client.
return new COSClient(cred, clientConfig);
}

Creating COSClient instance with temporary key

If you want to request COS with a temporary key, you need to create a COSClient instance with the temporary key. This SDK does not generate temporary keys. For how to generate a temporary key, see Generating and Using Temporary Keys.

// Create a COSClient instance, which is used to initiate requests later.
COSClient createCOSClient() {
// Here, the temporary key information is needed.
// For directions on how to generate a temporary key, visit https://www.tencentcloud.com/document/product//436/14048.
String tmpSecretId = "TMPSECRETID";
String tmpSecretKey = "TMPSECRETKEY";
String sessionToken = "SESSIONTOKEN";

COSCredentials cred = new BasicSessionCredentials(tmpSecretId, tmpSecretKey, sessionToken);

// `ClientConfig` contains the COS client configuration for subsequent COS requests.
ClientConfig clientConfig = new ClientConfig();

// Set the bucket region.
// For more information on COS regions, visit https://www.tencentcloud.com/document/product/436/6224?from_cn_redirect=1.
clientConfig.setRegion(new Region("COS_REGION"));

// Set the request protocol to `http` or `https`.
// For 5.6.53 and earlier versions, HTTPS is recommended.
// Starting from 5.6.54, HTTPS is used by default.
clientConfig.setHttpProtocol(HttpProtocol.https);

// The following settings are optional:

// Set the read timeout period, which is 30s by default.
clientConfig.setSocketTimeout(30*1000);
// Set the connection timeout period, which is 30s by default.
clientConfig.setConnectionTimeout(30*1000);

// If necessary, set the HTTP proxy, IP, and port.
clientConfig.setHttpProxyIp("httpProxyIp");
clientConfig.setHttpProxyPort(80);

// Generate a COS client.
return new COSClient(cred, clientConfig);
}

Copying object

This API (PUT Object-Copy) is used to copy an object to a destination path.
Note:
We recommend you use the advanced API for copying directly.

Method prototype

public CopyObjectResult copyObject(CopyObjectRequest copyObjectRequest)
throws CosClientException, CosServiceException

Sample request

// Source bucket region.
Region srcBucketRegion = new Region("ap-beijing");
// Enter the source bucket name in the format of `BucketName-APPID`.
String srcBucketName = "srcbucket-1250000000";
// Source file path.
String srcKey = "path/srckey";

// Destination bucket region.
Region destBucketRegion = new Region("ap-beijing");
// Enter the destination bucket name in the format of `BucketName-APPID`.
String destBucketName = "destbucket-1250000000";
// Destination file path.
String destKey = "path/destkey";

// Before using the COS API, you must make sure that the process contains a COSClient instance; if not, then create one.
// The COSClient instance created here is based on the information of the destination for copying.
// For the detailed code, see **Upload in Whole** > **Creating COSClient instance** on this page.
COSClient cosClient = createCOSClient();

CopyObjectRequest copyObjectRequest = new CopyObjectRequest(srcBucketRegion, srcBucketName,
srcKey, destBucketName, destKey);
try {
CopyObjectResult copyObjectResult = cosClient.copyObject(copyObjectRequest);
System.out.println(copyObjectResult.getRequestId());
} catch (CosServiceException e) {
e.printStackTrace();
} catch (CosClientException e) {
e.printStackTrace();
}

// After confirming that the process no longer uses the COSClient instance, shut it down.
cosClient.shutdown();

Parameter description

Parameter
Description
Type
copyObjectRequest
File copy request
CopyObjectRequest
The request members are as described below:
Parameter
Description
Type
sourceBucketRegion
Region of the source bucket. Default value: The value of region in clientConfig, indicating intra-region replication.
String
sourceBucketName
Source bucket name in the format of BucketName-APPID. For more information, see Bucket Overview.
String
sourceKey
Unique identifier of the source object in the bucket. For example, if an object's access endpoint is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/do/picture.jpg, its key is doc/picture.jpg. For more information, see Object Overview.
String
sourceVersionId
Version number of the source file (for source buckets with versioning enabled). Default value: The latest version of the source file.
String
destinationBucketName
Destination bucket name in the format of BucketName-APPID, which can contain letters, numbers, and hyphens.
String
destinationKey
Unique identifier of the destination object in the bucket. For example, if an object's access endpoint is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/do/picture.jpg, its key is doc/picture.jpg. For more information, see Object Overview.
String
storageClass
Storage class of the destination file, such as STANDARD (default) and STANDARD_IA. For more information, see Storage Class Overview.
String

Response description

Success: CopyObjectResult is returned, which contains the Etag and other information of the new file.
Failure: If an error (such as authentication failure) occurs, the CosClientException or CosServiceException exception will be reported. For more information, see Troubleshooting.

Multipart Upload Operations

When a large file is copied, the file is copied in a series of parts to eliminate the possible interruptions caused by the long upload time of the large file.
Note:
We recommend you use the advanced API for copying directly.

Directions

Performing multipart copy

1. Initialize the multipart copy with Initiate Multipart Upload to get the UploadId.
2. Use the UploadId to copy the parts with Upload Part.
3. Complete the multipart copy with Complete Multipart Upload.

Resuming multipart copy

1. If you did not record the UploadId of the multipart copy, you can query the multipart copy job with List Multipart Uploads to get the UploadId of the file.
2. Use the UploadId to list the copied parts with List Parts.
3. Use the UploadId to copy the remaining parts with Upload Part.
4. Complete the multipart copy with Complete Multipart Upload.

Aborting multipart copy

1. If you did not record the UploadId of the multipart copy, you can query the multipart copy job with List Multipart Uploads to get the UploadId of the corresponding file.
2. Abort the multipart copy and delete the copied parts with Abort Multipart Upload.

Initializing multipart copy

This API is used to initialize a multipart copy and get the UploadId for subsequent operations.

Method prototype

public InitiateMultipartUploadResult initiateMultipartUpload(
InitiateMultipartUploadRequest request) throws CosClientException, CosServiceException;

Sample request

// Before using the COS API, you must make sure that the process contains a COSClient instance; if not, then create one.
// The COSClient instance created here is based on the information of the destination for copying.
// For the detailed code, see **Simple Operations** > **Creating COSClient instance** on this page.
COSClient cosClient = createCOSClient();
// Enter the bucket name in the format of `BucketName-APPID`.
String bucketName = "examplebucket-1250000000";
// Object key, which is the unique identifier of the object in the bucket. For more information, see [Object Overview](https://www.tencentcloud.com/document/product//436/13324).
String key = "exampleobject";

InitiateMultipartUploadRequest request = new InitiateMultipartUploadRequest(bucketName, key);

// During multipart copy, you can specify the metadata of a copied file only by initializing the multipart copy.
// Specify the desired headers.
ObjectMetadata objectMetadata = new ObjectMetadata();
request.setObjectMetadata(objectMetadata);

try {
InitiateMultipartUploadResult initResult = cosClient.initiateMultipartUpload(request);
// Get `uploadid`.
String uploadId = initResult.getUploadId();
System.out.println(uploadId);
} catch (CosServiceException e) {
throw e;
} catch (CosClientException e) {
throw e;
}

Parameter description

Parameter
Description
Type
initiateMultipartUploadRequest
Request
InitiateMultipartUploadRequest
The request members are as described below:
Parameter
Configuration Method
Description
Type
bucketName
Constructor or set method
Bucket name in the format of BucketName-APPID. For more information, see Bucket Overview.
String
key
Constructor or set method
Path (i.e., object key) to upload the part to, such as folder/picture.jpg.
String

Response description

Success: InitiateMultipartUploadResult is returned, which contains the uploadId that identifies the multipart upload.
Failure: If an error (such as authentication failure) occurs, the CosClientException or CosServiceException exception will be reported. For more information, see Troubleshooting.

Querying multipart copy

This API (List Multipart Uploads) is used to get all multipart copy jobs in progress and get the uploadId of a desired multipart copy job.

Method prototype

public MultipartUploadListing listMultipartUploads(
ListMultipartUploadsRequest listMultipartUploadsRequest)
throws CosClientException, CosServiceException

Sample request

// Before using the COS API, you must make sure that the process contains a COSClient instance; if not, then create one.
// The COSClient instance created here is based on the information of the destination for copying.
// For the detailed code, see **Simple Operations** > **Creating COSClient instance** on this page.
COSClient cosClient = createCOSClient();
// Enter the bucket name in the format of `BucketName-APPID`.
String bucketName = "examplebucket-1250000000";

// Key of the multipart copy jobs to be queried.
String targetKey = "targetKey";

ListMultipartUploadsRequest listMultipartUploadsRequest = new ListMultipartUploadsRequest(bucketName);
// Maximum number of multipart upload jobs that can be listed per request.
listMultipartUploadsRequest.setMaxUploads(100);
// Set the target prefix (key) of the multipart copy jobs to be queried.
listMultipartUploadsRequest.setPrefix("targetKey");

MultipartUploadListing multipartUploadListing = null;

boolean found = false;

do {
multipartUploadListing = cosClient.listMultipartUploads(listMultipartUploadsRequest);
List<MultipartUpload> multipartUploads = multipartUploadListing.getMultipartUploads();

for (MultipartUpload mUpload : multipartUploads) {
if (mUpload.getKey().equals(targetKey)) {
System.out.println(mUpload.getUploadId());
found = true;
break;
}
}

if (found) {
break;
}

} while (multipartUploadListing.isTruncated());

if (!found) {
System.out.printf("do not found upload task with key: %s\\n", targetKey);
}

Parameter description

Parameter
Description
Type
listMultipartUploadsRequest
Request
ListMultipartUploadsRequest
The request members are as described below:
Parameter
Description
Type
bucketName
Bucket name in the format of BucketName-APPID. For more information, see Bucket Overview.
String
keyMarker
Specifies the key where the list starts
String
delimiter
A symbol used to limit the results of a listing operation. If a prefix is specified, identical paths between the prefix and the delimiter will be grouped together and defined as a common prefix, and then all common prefixes will be listed. If no prefix is specified, the listing will start from the beginning of the path.
String
prefix
Specifies that returned object keys must be prefixed with the value of this parameter. Note that if you use this parameter, returned keys will contain the prefix.
String
uploadIdMarker
Specifies the uploadId where the list starts
String
maxUploads
Sets the maximum number of multipart uploads that can be returned at a time. Value range: 1–1000.
String
encodingType
Encoding type of the returned value. Valid value: url.
String

Response description

Success: MultipartUploadListing is returned, which contains the information of the multipart uploads in progress.
Failure: If an error (such as authentication failure) occurs, the CosClientException or CosServiceException exception will be reported. For more information, see Troubleshooting.

Copying object part

This API (Upload Part - Copy) is used to copy an object by parts.

Method prototype

public CopyPartResult copyPart(CopyPartRequest copyPartRequest) throws CosClientException, CosServiceException

Sample request

// Before using the COS API, you must make sure that the process contains a COSClient instance; if not, then create one.
// The COSClient instance created here is based on the information of the destination for copying.
// For the detailed code, see **Simple Operations** > **Creating COSClient instance** on this page.
COSClient cosClient = createCOSClient();
// Enter the bucket name in the format of `BucketName-APPID`.
String bucketName = "examplebucket-1250000000";
// Object key, which is the unique identifier of the object in the bucket. For more information, see [Object Overview](https://www.tencentcloud.com/document/product//436/13324).
String key = "exampleobject";
// `uploadId` is the unique identifier of a multipart copy job. It can be obtained by initializing the multipart copy or querying the multipart copy job.
String uploadId = "exampleuploadid";

// Source bucket region.
Region srcBucketRegion = new Region("ap-beijing");
// Enter the source bucket name in the format of `BucketName-APPID`.
String srcBucketName = "srcbucket-1250000000";
// Source file path.
String srcKey = "path/srckey";

// Destination bucket region.
Region destBucketRegion = new Region("ap-beijing");
// Enter the destination bucket name in the format of `BucketName-APPID`.
String destBucketName = "destbucket-1250000000";
// Destination file path.
String destKey = "path/destkey";

CopyPartRequest copyPartRequest = new CopyPartRequest();
copyPartRequest.setSourceBucketRegion(srcBucketRegion);
copyPartRequest.setSourceBucketName(srcBucketName);
copyPartRequest.setSourceKey(srcKey);

// Specify the scope of data in the source file to be copied (similar to `content-range`).
copyPartRequest.setFirstByte(0L);
copyPartRequest.setLastByte(1048575L);

copyPartRequest.setDestinationBucketName(destBucketName);
copyPartRequest.setDestinationKey(destKey);

// Set the part number for the current copy, which starts from 1.
copyPartRequest.setPartNumber(1);
copyPartRequest.setUploadId(uploadId);

try {
CopyPartResult copyPartResult = cosClient.copyPart(copyPartRequest);
PartETag partETag = copyPartResult.getPartETag();
System.out.println(partETag);
} catch (CosServiceException e) {
e.printStackTrace();
} catch (CosClientException e) {
e.printStackTrace();
}

Parameter description

Parameter
Description
Type
copyPartRequest
Request
CopyPartRequest
The request members are as described below:
Parameter
Configuration Method
Description
Type
destinationBucketName
Set method
Destination bucket name in the format of BucketName-APPID. For more information, see Bucket Overview.
String
destinationKey
Set method
Name of the destination object (i.e., object key) to store the replicated part, such as folder/picture.jpg.
String
uploadId
Set method
ID that identifies the specified multipart upload
String
partNumber
Set method
Number (≥1) that identifies the specified part
int
sourceBucketRegion
Set method
Region of the source bucket
Region
sourceBucketName
Set method
Source bucket name
String
sourceKey
Set method
Name/Path (i.e., object key) of the source object before the replication, such as folder/picture.jpg.
String
firstByte
Set method
First byte offset of the source object
Long
lastByte
Set method
Last byte offset of the source object
Long

Response description

Success: CopyPartResult is returned, which contains the ETag of the part.
Failure: If an error (such as authentication failure) occurs, the CosClientException or CosServiceException exception will be reported. For more information, see Troubleshooting.

Querying copied parts

This API (List Parts) is used to query the copied parts of a multipart copy.

Method prototype

public PartListing listParts(ListPartsRequest request)
throws CosClientException, CosServiceException;

Sample request

// Before using the COS API, you must make sure that the process contains a COSClient instance; if not, then create one.
// The COSClient instance created here is based on the information of the destination for copying.
// For the detailed code, see **Simple Operations** > **Creating COSClient instance** on this page.
COSClient cosClient = createCOSClient();
// Enter the bucket name in the format of `BucketName-APPID`.
String bucketName = "examplebucket-1250000000";
// Object key, which is the unique identifier of the object in the bucket. For more information, see [Object Overview](https://www.tencentcloud.com/document/product//436/13324).
String key = "exampleobject";
// `uploadId` is the unique identifier of a multipart copy job. It can be obtained by initializing the multipart copy or querying the multipart copy job.
String uploadId = "exampleuploadid";

// It is used to store the information of the copied parts.
List<PartETag> partETags = new LinkedList<>();

PartListing partListing = null;
ListPartsRequest listPartsRequest = new ListPartsRequest(bucketName, key, uploadId);
do {
try {
partListing = cosClient.listParts(listPartsRequest);
} catch (CosServiceException e) {
throw e;
} catch (CosClientException e) {
throw e;
}

for (PartSummary partSummary : partListing.getParts()) {
partETags.add(new PartETag(partSummary.getPartNumber(), partSummary.getETag()));
}

listPartsRequest.setPartNumberMarker(partListing.getNextPartNumberMarker());
} while (partListing.isTruncated());

Parameter description

Parameter
Configuration Method
Description
Type
bucketName
Constructor or set method
Bucket name in the format of BucketName-APPID. For more information, see Bucket Overview.
String
key
Constructor or set method
Object name
String
uploadId
Constructor or set method
uploadId of the multipart upload to be queried
String
maxParts
Set method
Maximum number of entries that can be returned at a time. Default value: 1000.
String
partNumberMarker
Set method
The marker after which the returned list begins. By default, entries are listed in UTF-8 binary order.
String
encodingType
Set method
Encoding type of the returned value.
String

Response description

Success: PartListing is returned, which contains the ETag and number of each part as well as the starting marker of the next list.
Failure: If an error (such as authentication failure) occurs, the CosClientException or CosServiceException exception will be reported. For more information, see Troubleshooting.

Completing multipart copy

This API (Complete Multipart Upload) is used to complete a multipart copy.
Note:
After the multipart copy is complete, the multipart copy job will be deleted, and the UploadId of the job will no longer be valid.

Method prototype

public CompleteMultipartUploadResult completeMultipartUpload(CompleteMultipartUploadRequest request) throws CosClientException, CosServiceException;

Sample request

// Before using the COS API, you must make sure that the process contains a COSClient instance; if not, then create one.
// The COSClient instance created here is based on the information of the destination for copying.
// For the detailed code, see **Simple Operations** > **Creating COSClient instance** on this page.
COSClient cosClient = createCOSClient();
// Enter the bucket name in the format of `BucketName-APPID`.
String bucketName = "examplebucket-1250000000";
// Object key, which is the unique identifier of the object in the bucket. For more information, see [Object Overview](https://www.tencentcloud.com/document/product//436/13324).
String key = "exampleobject";
// `uploadId` is the unique identifier of a multipart copy job. It can be obtained by initializing the multipart copy or querying the multipart copy job.
String uploadId = "exampleuploadid";

// It is used to store the information of the uploaded parts and is obtained from the multipart upload API.
List<PartETag> partETags = new LinkedList<>();

// Call `complete` to complete the multipart copy after the multipart upload is complete.
CompleteMultipartUploadRequest completeMultipartUploadRequest =
new CompleteMultipartUploadRequest(bucketName, key, uploadId, partETags);
try {
CompleteMultipartUploadResult completeResult =
cosClient.completeMultipartUpload(completeMultipartUploadRequest);
System.out.println(completeResult.getRequestId());
} catch (CosServiceException e) {
throw e;
} catch (CosClientException e) {
throw e;
}

// After confirming that the COSClient instance is no longer used, shut it down.
cosClient.shutdown();

Parameter description

Parameter
Configuration Method
Description
Type
bucketName
Constructor or set method
Bucket name in the format of BucketName-APPID. For more information, see Bucket Overview.
String
key
Constructor or set method
Path (i.e., object key) to upload the part to, such as folder/picture.jpg.
String
uploadId
Constructor or set method
ID that identifies the specified multipart upload
String
partETags
Constructor or set method
Number that identifies the specified part and eTag returned for it
List<PartETag>

Response description

Success: CompleteMultipartUploadResult is returned, which contains the eTag of the completed object.
Failure: If an error (such as authentication failure) occurs, the CosClientException or CosServiceException exception will be reported. For more information, see Troubleshooting.

Aborting multipart copy

This API (Abort Multipart Upload) is used to abort a multipart copy and delete the copied parts.
Note:
After a multipart copy is aborted, both the multipart copy job and the copied parts will be deleted, and the UploadId will no longer be valid.

Method prototype

public void abortMultipartUpload(AbortMultipartUploadRequest request) throws CosClientException, CosServiceException;

Sample request

// Before using the COS API, you must make sure that the process contains a COSClient instance; if not, then create one.
// The COSClient instance created here is based on the information of the destination for copying.
// For the detailed code, see **Simple Operations** > **Creating COSClient instance** on this page.
COSClient cosClient = createCOSClient();
// Enter the bucket name in the format of `BucketName-APPID`.
String bucketName = "examplebucket-1250000000";
// Object key, which is the unique identifier of the object in the bucket. For more information, see [Object Overview](https://www.tencentcloud.com/document/product//436/13324).
String key = "exampleobject";
// `uploadId` is the unique identifier of a multipart copy job. It can be obtained by initializing the multipart copy or querying the multipart copy job.
String uploadId = "exampleuploadid";

AbortMultipartUploadRequest abortMultipartUploadRequest = new AbortMultipartUploadRequest(bucketName, key, uploadId);
try {
cosClient.abortMultipartUpload(abortMultipartUploadRequest);
} catch (CosServiceException e) {
e.printStackTrace();
} catch (CosClientException e) {
e.printStackTrace();
}

// After confirming that the COSClient instance is no longer used, shut it down.
cosClient.shutdown();

Parameter description

Parameter
Configuration Method
Description
Type
bucketName
Constructor or set method
Bucket name in the format of BucketName-APPID. For more information, see Bucket Overview.
String
key
Constructor or set method
Path (i.e., object key) to upload the part to, such as folder/picture.jpg.
String
uploadId
Constructor or set method
ID that identifies the specified multipart upload
String

Response description

Success: No value is returned.
Failure: If an error (such as authentication failure) occurs, the CosClientException or CosServiceException exception will be reported. For more information, see Troubleshooting.
Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback

Contact Us

Contact our sales team or business advisors to help your business.

Technical Support

Open a ticket if you're looking for further assistance. Our Ticket is 7x24 available.

7x24 Phone Support