tencent cloud

Feedback

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.
    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 avaliable.

    7x24 Phone Support