tencent cloud

Feedback

Copying and Moving Objects

Last updated: 2022-03-04 10:08:30

    Overview

    This document provides an overview of APIs and SDK code samples related to object copy and movement.

    Simple operations

    API Operation Description
    PUT Object - Copy Copying an object Copies an object to a destination path

    Multipart operations

    API Operation Description
    List Multipart Uploads Querying multipart uploads/copy Queries in-progress multipart uploads/copy.
    Initiate Multipart Upload Initializing a multipart upload/copy operation Initializes a multipart upload/copy operation.
    Upload Part - Copy Copying a part Copies an object as a part.
    List Parts Querying uploaded/copied parts Queries the uploaded/copied parts of a multipart operation.
    Complete Multipart Upload Completing a multipart upload/copy Completes the multipart upload/copy of a file.
    Abort Multipart Upload Aborting a multipart upload/copy Aborts a multipart operation and deletes the 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 from users, so users can choose to execute tasks asynchronously after submitting multiple tasks.

    TransferManager instances are concurrency safe. You are advised to create only one TransferManager instance for a process and then close it when it is no longer used to call advanced APIs.

    Description

    The advanced APIs encapsulate the simple copy and multipart copy APIs and automatically choose the copy mode based on the file size.

    Creating a TransferManager instance

    Before using the advanced API, you need to create a TransferManager instance.

    // Create a TransferManager instance, which is used to call the advanced API 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 a COSClient instance" on the current page.
      COSClient cosClient = createCOSClient();
       // Set the thread pool size. You are advised to 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, by using Tencent Cloud CVM and uploading to COS in the same region).
      // We recommend using a smaller value to avoid timeout due to 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 xopy 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 of the advanced API. Its main members are described as follows:

    Member Name Setting Method Description Type
    minimumUploadPartSize Set method Part size of the multipart upload in bytes. Default: 5 MB long
    multipartUploadThreshold Set method If a file is greater than or equal to this value, it will be uploaded in concurrent parts. Unit: byte; default: 5 MB long
    multipartCopyThreshold Set method If a file is greater than or equal to this value, it will be replicated in concurrent parts. Unit: byte; default: 5 GB long
    multipartCopyPartSize Set method Part size in bytes for multipart replication. Default: 100 MB long

    Closing a TransferManager instance

    After confirming that the process does not use the TransferManager instance to call the advanced API anymore, be sure to close it to avoid leaking resources.

    void shutdownTransferManager(TransferManager transferManager) {
      // If the parameter is set to `true`, the COSClient instance in the TransferManager instance will also be closed at the same time.
      // If the parameter is set to `false`, the COSClient instance in the TransferManager instance will not be closed.
      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 the advanced API, ensure that the process contains a TransferManager instance. If such an instance does not exist, create one.
    // For the detailed code, see "Advanced APIs -> Creating a TransferManager instance" on the current page.
    TransferManager transferManager = createTransferManager();
    // Source bucket region
    Region srcBucketRegion = new Region("ap-beijing");
    // Source bucket. Enter the bucket name in the format of `BucketName-APPID`.
    String srcBucketName = "srcbucket-1250000000";
    // Source file path
    String srcKey = "path/srckey";
    // Destination bucket. Enter the 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 replication to end. If the replication is successful, `CopyResult` is returned; otherwise, an exception will be thrown.
      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 does not use the TransferManager instance anymore, close it.
    // For the detailed code, see "Advanced APIs -> Closing a TransferManager instance" on the current page.
    shutdownTransferManager(transferManager);
    

    Parameter description

    Parameter Description Type
    copyObjectRequest Object copy request CopyObjectRequest

    The request members are described as follows:

    Parameter Description Type
    sourceBucketRegion Region of the source bucket. Default value: the value of "region" in clientconfig, meaning intra-region replication String
    sourceBucketName Source bucket name in the format of BucketName-APPID String
    sourceKey Source object key. The object key is the unique identifier of the object in the bucket. For example, in the object’s access endpoint examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/do/picture.jpg, the object key is doc/picture.jpg. For more information, please see Object Key. String
    sourceVersionId Version ID of the source file (for source buckets with versioning enabled). Default: The latest version of the source file. String
    destinationBucketName Destination bucket name in the format of BucketName-APPID String
    destinationKey Destination object key. The object key is the unique identifier of the object in the bucket. For example, in the object’s access endpoint examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/do/picture.jpg, the object key is doc/picture.jpg. For more information, please see Object Key. String
    storageClass Storage class for the destination file. For the enumerated values, such as Standard (default) and Standard_IA, please see Storage Class Overview. String

    Returned values

    • Success: returns Copy. You can query whether the copy is completed, or wait until the copy finishes synchronously.
    • Failure: if an error (such as authentication failure) occurs, the CosClientException or CosServiceException exception will be thrown. For more information, please see Troubleshooting.

    Cross-region replication

    This API applies to scenarios where the source and destination objects for replication belong to different regions, for example, when you need to replicate 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

    // Before using the advanced API, ensure that the process contains a TransferManager instance. If such an instance does not exist, create one.
    // For the detailed code, see "Advanced APIs -> Creating a TransferManager instance" on the current page.
    TransferManager transferManager = createTransferManager();
    // Source bucket region
    Region srcBucketRegion = new Region("ap-beijing");
    // Source bucket. Enter the bucket name in the format of `BucketName-APPID`.
    String srcBucketName = "srcbucket-1250000000";
    // Source file path
    String srcKey = "path/srckey";
    // Destination bucket. Enter the 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 replication source.
    // For the detailed code, see "Simple Operations -> Creating a COSClient instance" on the current 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 replication to end. If the replication is successful, `CopyResult` is returned; otherwise, an exception will be thrown.
      CopyResult copyResult = copy.waitForCopyResult();
    } catch (CosServiceException e) {
      e.printStackTrace();
    } catch (CosClientException e) {
      e.printStackTrace();
    } catch (InterruptedException e) {
      e.printStackTrace();
    }
    // After confirming that the process does not use the TransferManager instance anymore, close it.
    // For the detailed code, see "Advanced APIs -> Closing a TransferManager instance" on the current page.
    shutdownTransferManager(transferManager);;
    

    Parameter description

    Parameter Description Type
    copyObjectRequest Object copy request CopyObjectRequest

    The request members are described as follows:

    Parameter Description Type
    sourceBucketRegion Region of the source bucket. Default value: the value of "region" in clientconfig, meaning intra-region replication String
    sourceBucketName Source bucket name in the format of BucketName-APPID String
    sourceKey Source object key. The object key is the unique identifier of the object in the bucket. For example, in the object’s access endpoint examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/do/picture.jpg, the object key is doc/picture.jpg. For more information, please see Object Key. String
    sourceVersionId Version ID of the source file (for source buckets with versioning enabled). Default: The latest version of the source file. String
    destinationBucketName Destination bucket name in the format of BucketName-APPID String
    destinationKey Destination object key. The object key is the unique identifier of the object in the bucket. For example, in the object’s access endpoint examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/do/picture.jpg, the object key is doc/picture.jpg. For more information, please see Object Key. String
    storageClass Storage class for the destination file. For the enumerated values, such as Standard (default) and Standard_IA, please see Storage Class Overview. String

    Returned values

    • Success: returns Copy. You can query whether the copy is completed, or wait until the copy finishes synchronously.
    • Failure: if an error (such as authentication failure) occurs, the CosClientException or CosServiceException exception will be thrown. For more information, please see Troubleshooting.

    Moving an object

    Object movement involves two steps: copying the source object to the destination location and then deleting the source object.

    Since 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 the object with 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 to the “doc” directory (making the object key doc/picture.jpg) and then delete the source object.

    Likewise, if you need to move picture.jpg 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");
    // Source bucket. Enter the 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");
    // Destination bucket. Enter the 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 objects" on the current page.
    copyObject();
    // For the implementation details, see "Deleting objects".
    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. You are advised to create only one COSClient instance for a process and then close it when it is no longer used to initiate requests.

    Creating a COSClient instance

    Before calling the COS API, you need to create a COSClient instance.

    // 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.cloud.tencent.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, please visit https://intl.cloud.tencent.com/document/product/436/6224.
      clientConfig.setRegion(new Region("COS_REGION"));
       // Set the request protocol, `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 a COSClient client with a 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, please see Generating a Temporary Keys.

    // Create a COSClient instance, which is used to initiate requests later.
    COSClient createCOSClient() {
      // Here, the temporary key information is needed.
      // For how to generate temporary keys, please visit https://intl.cloud.tencent.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, please visit https://intl.cloud.tencent.com/document/product/436/6224.
      clientConfig.setRegion(new Region("COS_REGION"));
       // Set the request protocol, `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 objects

    This API (PUT Object-Copy) is used to copy an object to a destination path.

    Note:

    It is recommended to 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");
    // Source bucket. Enter the 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");
    // Destination bucket. Enter the bucket name in the format of `BucketName-APPID`.
    String destBucketName = "destbucket-1250000000";
    // Destination file path
    String destKey = "path/destkey";
    // Before using the COS API, ensure that the process contains a COSClient instance. If such an instance does not exist, create one.
    // The COSClient instance created here is based on the information of the destination for copying.
    // For the detailed code, see "Simple Upload -> Creating a COSClient instance" on the current 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 does not use the COSClient instance anymore, close it.
    cosclient.shutdown();
    

    Parameter description

    Parameter Description Type
    copyObjectRequest File copy request CopyObjectRequest

    The request members are described as follows:

    Parameter Description Type
    sourceBucketRegion Region of the source bucket. Default: same as the region value in the current clientConfig, which represents intra-region replication String
    sourceBucketName Source bucket name in the format of BucketName-APPID. For details, see Naming Conventions String
    sourceKey Source object key. An object key is the unique identifier of an object in a bucket. For example, in the object’s access endpoint examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/do/picture.jpg, the object key is doc/picture.jpg. For more information, please see Object Key. String
    sourceVersionId Version ID of the source file (for source buckets with versioning enabled). Default: The latest version of the source file. String
    destinationBucketName Destination bucket name in the format of BucketName-APPID. It should contain letters, numbers, and hyphens. String
    destinationKey Destination object key. An object key is the unique identifier of an object in a bucket. For example, in the object’s access endpoint examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/do/picture.jpg, the object key is doc/picture.jpg. For more information, please see Object Key. String
    storageClass Storage class for the destination file. For the enumerated values, such as Standard (default) and Standard_IA, please see Storage Class Overview. String

    Response description

    • Success: returns CopyObjectResult, including the ETag and other information on the new file.
    • Failure: if an error (such as authentication failure) occurs, the CosClientException or CosServiceException exception will be thrown. For more information, please see Troubleshooting.

    Multipart Operations

    When a large file is copied, the file is copied as a series of parts to address the possible interruptions caused by the long upload time of the large file.

    Note:

    It is recommended to use the advanced API for copying directly.

    Operation procedures

    Performing a multipart copy

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

    Resuming a 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. 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.

    Multipart copy abortion process

    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 a multipart copy

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

    Method prototype

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

    Sample request

    // Before using the COS API, ensure that the process contains a COSClient instance. If such an instance does not exist, 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 a COSClient instance" on the current page.
    COSClient cosClient = createCOSClient();
    // Enter the bucket name in the format of `BucketName-APPID`.
    String bucketName = "examplebucket-1250000000";
    // Object key, the unique ID of an object in a bucket. For more information, please see [Object Key](https://intl.cloud.tencent.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 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 described as follows:

    Parameter Setting Method Description Type
    bucketName Constructor or set method Bucket name in the format of BucketName-APPID. For details, see Naming Conventions String
    key Constructor or set method Specifies the path (i.e., object key) to upload the part to, for example, folder/picture.jpg. String

    Response description

    • Success: returns InitiateMultipartUploadResult, including the uploadId that identifies the multipart upload.
    • Failure: if an error (such as authentication failure) occurs, the CosClientException or CosServiceException exception will be thrown. For more information, please see Troubleshooting.

    Querying multipart copies

    This API (List Multipart Uploads) is used to get all ongoing multipart copy tasks to obtain the UploadId of a desired multipart copy task.

    Method prototype

    public MultipartUploadListing listMultipartUploads(
              ListMultipartUploadsRequest listMultipartUploadsRequest)
              throws CosClientException, CosServiceException
    
    

    Sample request

    // Before using the COS API, ensure that the process contains a COSClient instance. If such an instance does not exist, 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 a COSClient instance" on the current page.
    COSClient cosClient = createCOSClient();
    // Enter the bucket name in the format of `BucketName-APPID`.
    String bucketName = "examplebucket-1250000000";
    // Key of the multipart copy tasks to be queried
    String targetKey = "targetKey";
    ListMultipartUploadsRequest listMultipartUploadsRequest = new ListMultipartUploadsRequest(bucketName);
    // Maximum number of multipart upload tasks listed per request
    listMultipartUploadsRequest.setMaxUploads(100);
    // Set the target prefix (key) of the multipart copy tasks 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 described as follows:

    Parameter Description Type
    bucketName Bucket naming format is BucketName-APPID. For details, see Naming Conventions String
    keyMarker Specifies the key after which the listing should begin String
    delimiter A symbol used to limit the results of a list operation. If a particular 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 the returned object key must be prefixed with this value. Note that when you use a prefix to query object keys, the returned key will contain the same prefix. String
    uploadIdMarker Specifies the uploadId after which the listing should begin String
    maxUploads Sets the maximum number of multipart uploads returned. Valid values: 1-1000 String
    encodingType Encoding type of returned values. Valid value: url String

    Response description

    • Success: returns MultipartUploadListing, including the in-progress multipart uploads.
    • Failure: if an error (such as authentication failure) occurs, the CosClientException or CosServiceException exception will be thrown. For more information, please see Troubleshooting.

    Copying an 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, ensure that the process contains a COSClient instance. If such an instance does not exist, 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 a COSClient instance" on the current page.
    COSClient cosClient = createCOSClient();
    // Enter the bucket name in the format of `BucketName-APPID`.
    String bucketName = "examplebucket-1250000000";
    // Object key, the unique ID of an object in a bucket. For more information, please see [Object Key](https://intl.cloud.tencent.com/document/product/436/13324).
    String key = "exampleobject";
    // `UploadId` is the unique identifier of a multipart copy task. You can obtain it by initializing the multipart copy or querying the multipart copy task.
    String uploadId = "exampleuploadid";
    // Source bucket region
    Region srcBucketRegion = new Region("ap-beijing");
    // Source bucket. Enter the 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");
    // Destination bucket. Enter the 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 range of data of 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 described as follows:

    Parameter Set Method Description Type
    destinationBucketName Set method Destination bucket name in the format of BucketName-APPID. For details, see Naming Conventions String
    destinationKey Set method Name of the destination object (i.e., object key) to store the replicated part, for example, folder/picture.jpg String
    uploadId Set method Identifies the uploadId of 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, for example, 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: returns CopyPartResult, including the ETag of the part.
    • Failure: if an error (such as authentication failure) occurs, the CosClientException or CosServiceException exception will be thrown. For more information, please 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, ensure that the process contains a COSClient instance. If such an instance does not exist, 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 a COSClient instance" on the current page.
    COSClient cosClient = createCOSClient();
    // Enter the bucket name in the format of `BucketName-APPID`.
    String bucketName = "examplebucket-1250000000";
    // Object key, the unique ID of an object in a bucket. For more information, please see [Object Key](https://intl.cloud.tencent.com/document/product/436/13324).
    String key = "exampleobject";
    // `UploadId` is the unique identifier of a multipart copy task. You can obtain it by initializing the multipart copy or querying the multipart copy task.
    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 Set Method Description Type
    bucketName Constructor or set method Bucket naming format is BucketName-APPID. For details, see Naming Conventions 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 returned at a time. Default value: 1000 String
    partNumberMarker Set method By default, entries are listed in UTF-8 binary order, starting from the part number after the marker. String
    encodingType Set method Encoding type of the returned value String

    Response description

    • Success: returns PartListing, including 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 thrown. For more information, please see Troubleshooting.

    Completing a multipart copy

    This API (Complete Multipart Upload) is used to complete the multipart copy of a file.

    Note:

    After the multipart copy is completed, the multipart copy task is deleted and the UploadId corresponding to the task is no longer valid.

    Method prototype

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

    Sample request

    // Before using the COS API, ensure that the process contains a COSClient instance. If such an instance does not exist, 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 a COSClient instance" on the current page.
    COSClient cosClient = createCOSClient();
    // Enter the bucket name in the format of `BucketName-APPID`.
    String bucketName = "examplebucket-1250000000";
    // Object key, the unique ID of an object in a bucket. For more information, please see [Object Key](https://intl.cloud.tencent.com/document/product/436/13324).
    String key = "exampleobject";
    // `UploadId` is the unique identifier of a multipart copy task. You can obtain it by initializing the multipart copy or querying the multipart copy task.
    String uploadId = "exampleuploadid";
    // It is used to store the information of the uploaded parts. In actual practice, the content here is obtained from the multipart upload API.
    List<PartETag> partETags = new LinkedList<>();
    // After the multipart upload is completed, call `complete` to complete the multipart copy.
    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 COSClint is not used any more, close it.
    cosClient.shutdown();
    

    Parameter description

    Parameter Set Method                Description Type
    bucketName Constructor or set method Bucket name in the format of BucketName-APPID. For details, see Naming Conventions String
    key Constructor or set method Specifies the path (i.e., object key) to upload the part to, for example, folder/picture.jpg. String
    uploadId Constructor or set method Identifies a specified multipart upload. String
    partETags Constructor or set method Identifies the number and ETag returned for an uploaded part. List<PartETag>

    Response description

    • Success: returns CompleteMultipartUploadResult, including the ETag of the completed object.
    • Failure: if an error (such as authentication failure) occurs, the CosClientException or CosServiceException exception will be thrown. For more information, please see Troubleshooting.

    Aborting a 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 task and the copied parts are deleted, and the corresponding UploadId is no longer valid.

    Method prototype

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

    Sample request

    // Before using the COS API, ensure that the process contains a COSClient instance. If such an instance does not exist, 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 a COSClient instance" on the current page.
    COSClient cosClient = createCOSClient();
    // Enter the bucket name in the format of `BucketName-APPID`.
    String bucketName = "examplebucket-1250000000";
    // Object key, the unique ID of an object in a bucket. For more information, please see [Object Key](https://intl.cloud.tencent.com/document/product/436/13324).
    String key = "exampleobject";
    // `UploadId` is the unique identifier of a multipart copy task. You can obtain it by initializing the multipart copy or querying the multipart copy task.
    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 COSClint is not used any more, close it.
    cosClient.shutdown();
    

    Parameter description

    Parameter Setting Method Description Type
    bucketName Constructor or set method Bucket name in the format of BucketName-APPID. For details, see Naming Conventions String
    key Constructor or set method Specifies the path (i.e., object key) to upload the part to, for example, folder/picture.jpg. String
    uploadId Constructor or set method Identifies a specified multipart upload. String

    Response description

    • Success: No value is returned.
    • Failure: An error occurs (such as authentication failure), throwing the "CosClientException" or "CosServiceException" exception. For more information, please 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