tencent cloud

简介

本文档提供关于对象的复制、移动操作相关的 API 概览以及 SDK 示例代码。

简单操作

API	操作名	操作描述
PUT Object - Copy	对象复制	复制文件到目标路径

分块操作

API	操作名	操作描述
List Multipart Uploads	查询分块上传/复制	查询正在进行中的分块上传/复制信息
Initiate Multipart Upload	初始化分块上传/复制	初始化分块上传/复制操作
Upload Part - Copy	复制分块	将其他对象复制为一个分块
List Parts	查询已上传/复制块	查询特定分块操作中的已上传/复制的块
Complete Multipart Upload	完成分块上传/复制	完成整个文件的分块上传/复制
Abort Multipart Upload	终止分块上传/复制	终止一个分块操作并删除已上传/复制的块

高级接口（推荐）

高级 API 由类 TransferManager 通过封装各个简单接口，来提供更便捷操作的接口。内部使用一个线程池，来并发接受和处理用户的请求，因此用户也可选择提交多个任务之后异步的执行任务。

TransferManager 实例是并发安全的，这里推荐一个进程只创建一个 TransferManager 实例，当不会再通过这个实例调用高级接口的时候，再选择关闭这个实例。

功能说明

高级接口封装了简单复制、分块复制接口，根据文件大小选择复制方式。

创建 TransferManager

使用高级接口的操作之前，必须先创建一个 TransferManager 的实例。

// 创建 TransferManager 实例，这个实例用来后续调用高级接口
TransferManager createTransferManager() {
  // 创建一个 COSClient 实例，这是访问 COS 服务的基础实例。
  // 这里创建的 cosClient 是以复制的目的端信息为基础的
  // 详细代码参见本页: 简单操作 -> 创建 COSClient
  COSClient cosClient = createCOSClient();
   // 自定义线程池大小，建议在客户端与 COS 网络充足（例如使用腾讯云的 CVM，同地域上传 COS）的情况下，设置成16或32即可，可较充分的利用网络资源
  // 对于使用公网传输且网络带宽质量不高的情况，建议减小该值，避免因网速过慢，造成请求超时。
  ExecutorService threadPool = Executors.newFixedThreadPool(32);
   // 传入一个 threadpool, 若不传入线程池，默认 TransferManager 中会生成一个单线程的线程池。
  TransferManager transferManager = new TransferManager(cosClient, threadPool);
   // 设置高级接口的配置项
  // 分块复制阈值和分块大小分别为 5MB 和 1MB
  TransferManagerConfiguration transferManagerConfiguration = new TransferManagerConfiguration();
  transferManagerConfiguration.setMultipartCopyThreshold(5*1024*1024);
  transferManagerConfiguration.setMultipartCopyPartSize(1*1024*1024);
  transferManager.setConfiguration(transferManagerConfiguration);
   return transferManager;
}

参数说明

TransferManagerConfiguration 类用于记录高级接口的配置信息，其主要成员说明如下：

成员名	设置方法	描述	类型
minimumUploadPartSize	set 方法	分块上传的块大小，单位：字节（Byte），默认为5MB	long
multipartUploadThreshold	set 方法	大于等于该值则并发的分块上传文件，单位：字节（Byte），默认为5MB	long
multipartCopyThreshold	set 方法	大于等于该值则并发的分块复制文件，单位：字节（Byte），默认为5GB	long
multipartCopyPartSize	set 方法	分块复制的块大小，单位：字节（Byte），默认为100MB	long

关闭 TransferManager

在确定不再通过 TransferManager 的实例调用高级接口之后，一定要关闭这个实例，防止资源泄露。

void shutdownTransferManager(TransferManager transferManager) {
  // 指定参数为 true, 则同时会关闭 transferManager 内部的 COSClient 实例。
  // 指定参数为 false, 则不会关闭 transferManager 内部的 COSClient 实例。
  transferManager.shutdownNow(true);
}

同地域复制

复制的源对象和目的对象属于同一个 Region。

方法原型

// 上传对象
public Copy copy(final CopyObjectRequest copyObjectRequest);

请求示例

// 使用高级接口必须先保证本进程存在一个 TransferManager 实例，如果没有则创建
// 详细代码参见本页：高级接口 -> 创建 TransferManager
TransferManager transferManager = createTransferManager();
// 复制的源桶所在的地域
Region srcBucketRegion = new Region("ap-beijing");
// 复制的源桶，命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String srcBucketName = "srcbucket-1250000000";
// 复制的源文件路径
String srcKey = "path/srckey";
// 复制的目的桶名, 命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String destBucketName = "destbucket-1250000000";
// 复制的目的文件路径
String destKey = "path/destkey";
CopyObjectRequest copyObjectRequest = new CopyObjectRequest(srcBucketRegion, srcBucketName,
      srcKey, destBucketName, destKey);
try {
  Copy copy = transferManager.copy(copyObjectRequest);
  // 高级接口会返回一个异步结果 Copy
  // 可同步的调用 waitForCopyResult 等待复制结束, 成功返回 CopyResult, 失败抛出异常
  CopyResult copyResult = copy.waitForCopyResult();
  System.out.println(copyResult.getRequestId());
} catch (CosServiceException e) {
  e.printStackTrace();
} catch (CosClientException e) {
  e.printStackTrace();
} catch (InterruptedException e) {
  e.printStackTrace();
}
// 确定本进程不再使用 transferManager 实例之后，关闭之
// 详细代码参见本页：高级接口 -> 关闭 TransferManager
shutdownTransferManager(transferManager);

参数说明

参数名称	描述	类型
copyObjectRequest	复制文件请求	CopyObjectRequest

Request 成员说明：

参数名称	描述	类型
sourceBucketRegion	源 Bucket Region 。默认值：与当前 clientconfig 的 region 一致，表示统一地域复制	String
sourceBucketName	源存储桶名称，存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式	String
sourceKey	源对象键，对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中，对象键为 doc/picture.jpg，详情请参见 对象键	String
sourceVersionId	源文件 version id（适用于开启了版本控制的源 Bucket）。默认值：源文件当前最新版本	String
destinationBucketName	目标存储桶名称，存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式	String
destinationKey	目的对象键，对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中，对象键为 doc/picture.jpg，详情请参见 对象键	String
storageClass	复制的目标文件的存储类型。枚举值：Standard，Standard_IA。默认值：Standard。更多存储类型请参见 存储类型概述	String

返回值

• 成功：返回 Copy，可以查询 Copy 是否结束，也可同步的等待上传结束。
• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。

跨地域复制

复制的源对象和目的对象属于不同的 Region。例如：源对象在北京的桶，需要复制到上海的桶中。

说明：

金融云地域和公有云地域不互通，所以不能够进行跨地域复制操作。

方法原型

// 上传对象
public Copy copy(final CopyObjectRequest copyObjectRequest);

请求示例

// 这里创建以复制的目的端信息为基础
// 使用高级接口必须先保证本进程存在一个 TransferManager 实例，如果没有则创建
// 详细代码参见本页：高级接口 -> 创建 TransferManager
TransferManager transferManager = createTransferManager();
// 复制的源桶所在的地域
Region srcBucketRegion = new Region("ap-beijing");
// 复制的源桶，命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String srcBucketName = "srcbucket-1250000000";
// 复制的源文件路径
String srcKey = "path/srckey";
// 复制的目的桶名, 命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String destBucketName = "destbucket-1250000000";
// 复制的目的文件路径
String destKey = "path/destkey";
// 这里创建的 cosClient 是以复制的源端信息为基础的
// 详细代码参见本页: 简单操作 -> 创建 COSClient
COSClient srcCOSClient = createCOSClient();
CopyObjectRequest copyObjectRequest = new CopyObjectRequest(srcBucketRegion, srcBucketName,
      srcKey, destBucketName, destKey);
try {
  Copy copy = transferManager.copy(copyObjectRequest, srcCOSClient, null);
  // 高级接口会返回一个异步结果 Copy
  // 可同步的调用 waitForCopyResult 等待复制结束, 成功返回 CopyResult, 失败抛出异常
  CopyResult copyResult = copy.waitForCopyResult();
} catch (CosServiceException e) {
  e.printStackTrace();
} catch (CosClientException e) {
  e.printStackTrace();
} catch (InterruptedException e) {
  e.printStackTrace();
}
// 确定本进程不再使用 transferManager 实例之后，关闭之
// 详细代码参见本页：高级接口 -> 关闭 TransferManager
shutdownTransferManager(transferManager);

参数说明

参数名称	描述	类型
copyObjectRequest	复制文件请求	CopyObjectRequest

Request 成员说明：

参数名称	描述	类型
sourceBucketRegion	源 Bucket Region 。默认值：与当前 clientconfig 的 region 一致，表示统一地域复制	String
sourceBucketName	源存储桶名称，存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式	String
sourceKey	源对象键，对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中，对象键为 doc/picture.jpg，详情请参见 对象键	String
sourceVersionId	源文件 version id（适用于开启了版本控制的源 Bucket）。默认值：源文件当前最新版本	String
destinationBucketName	目标存储桶名称，存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式	String
destinationKey	目的对象键，对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中，对象键为 doc/picture.jpg，详情请参见 对象键	String
storageClass	复制的目标文件的存储类型。枚举值：Standard，Standard_IA。默认值：Standard。更多存储类型请参见 存储类型概述	String

返回值

• 成功：返回 Copy，可以查询 Copy 是否结束，也可同步的等待上传结束。
• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。

移动对象

移动对象操作包括两个步骤：复制源对象到目标位置，删除源对象。

由于 COS 通过存储桶名称（Bucket）和对象键（ObjectKey）来标识对象。移动对象也就意味着修改这个对象的标识，COS Java SDK 目前没有提供修改对象唯一标识名的单独接口，但是可以通过组合 复制对象 加上 删除对象 的基本操作，来达到修改对象标识的目的，从而实现移动对象。

例如将 mybucket-1250000000 这个存储桶中的 picture.jpg 这个对象移动到同个存储桶的 doc 路径下。首先可以复制 picture.jpg 对象到存储桶的 doc 路径下，即对象键设定为 doc/picture.jpg，复制完成后删除 picture.jpg 这个对象，来实现“移动”的效果。

同样的，如果想将 mybucket-1250000000 这个存储桶里的 picture.jpg 这个对象移动到 myanothorbucket-1250000000 这个存储桶里，可以先将对象复制到 myanothorbucket-1250000000 存储桶，然后删除原来的对象。

请求示例

// 复制的源桶所在的地域
Region srcBucketRegion = new Region("ap-beijing");
// 复制的源桶，命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String srcBucketName = "srcbucket-1250000000";
// 复制的源文件路径
String srcKey = "path/srckey";
// 复制的目的桶所在的地域
Region destBucketRegion = new Region("ap-shanghai");
// 复制的目的桶名, 命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String destBucketName = "destbucket-1250000000";
// 复制的目的文件路径
String destKey = "path/destkey";
// 实现参考本页：高级接口 -> 复制对象
copyObject();
// 实现参考：删除对象
deleteObject();

简单操作

简单操作由 COSClient 类型发起请求，使用简单操作之前必须先创建一个 COSClient 实例。

COSClient 实例是并发安全的，这里推荐一个进程只创建一个 COSClient 实例，当不会再通过这个实例发起请求的时候，再选择关闭这个实例。

创建 COSClient

调用 COS 的接口之前，必须先创建一个 COSClient 的实例。

// 创建 COSClient 实例，这个实例用来后续调用请求
COSClient createCOSClient() {
  // 设置用户身份信息。
  // SECRETID 和 SECRETKEY 请登录访问管理控制台 https://console.cloud.tencent.com/cam/capi 进行查看和管理
  String secretId = "SECRETID";
  String secretKey = "SECRETKEY";
  COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);
   // ClientConfig 中包含了后续请求 COS 的客户端设置：
  ClientConfig clientConfig = new ClientConfig();
   // 设置 bucket 的地域
  // COS_REGION 请参照 https://intl.cloud.tencent.com/document/product/436/6224
  clientConfig.setRegion(new Region("COS_REGION"));
   // 设置请求协议, http 或者 https
  // 5.6.53 及更低的版本，建议设置使用 https 协议
  // 5.6.54 及更高版本，默认使用了 https
  clientConfig.setHttpProtocol(HttpProtocol.https);
   // 以下的设置，是可选的：
   // 设置 socket 读取超时，默认 30s
  clientConfig.setSocketTimeout(30*1000);
  // 设置建立连接超时，默认 30s
  clientConfig.setConnectionTimeout(30*1000);
   // 如果需要的话，设置 http 代理，ip 以及 port
  clientConfig.setHttpProxyIp("httpProxyIp");
  clientConfig.setHttpProxyPort(80);
   // 生成 cos 客户端。
  return new COSClient(cred, clientConfig);
}

使用临时密钥创建 COSClient

如果要使用临时密钥请求 COS，则需要用临时密钥创建 COSClient。
本 SDK 并不能生成临时密钥，而需要使用额外的操作来生成，参考 临时密钥生成。

// 创建 COSClient 实例，这个实例用来后续调用请求
COSClient createCOSClient() {
  // 这里需要已经获取到临时密钥的结果。
  // 临时密钥的生成参考 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 中包含了后续请求 COS 的客户端设置：
  ClientConfig clientConfig = new ClientConfig();
   // 设置 bucket 的地域
  // COS_REGION 请参照 https://intl.cloud.tencent.com/document/product/436/6224
  clientConfig.setRegion(new Region("COS_REGION"));
   // 设置请求协议, http 或者 https
  // 5.6.53 及更低的版本，建议设置使用 https 协议
  // 5.6.54 及更高版本，默认使用了 https
  clientConfig.setHttpProtocol(HttpProtocol.https);
   // 以下的设置，是可选的：
   // 设置 socket 读取超时，默认 30s
  clientConfig.setSocketTimeout(30*1000);
  // 设置建立连接超时，默认 30s
  clientConfig.setConnectionTimeout(30*1000);
   // 如果需要的话，设置 http 代理，ip 以及 port
  clientConfig.setHttpProxyIp("httpProxyIp");
  clientConfig.setHttpProxyPort(80);
   // 生成 cos 客户端。
  return new COSClient(cred, clientConfig);
}

复制对象

复制文件到目标路径（PUT Object-Copy）。

说明：

推荐直接使用高级接口的复制。

方法原型

public CopyObjectResult copyObject(CopyObjectRequest copyObjectRequest)
          throws CosClientException, CosServiceException

请求示例

// 复制的源桶所在的地域
Region srcBucketRegion = new Region("ap-beijing");
// 复制的源桶，命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String srcBucketName = "srcbucket-1250000000";
// 复制的源文件路径
String srcKey = "path/srckey";
// 复制的目的桶所在的地域
Region destBucketRegion = new Region("ap-beijing");
// 复制的目的桶名, 命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String destBucketName = "destbucket-1250000000";
// 复制的目的文件路径
String destKey = "path/destkey";
// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例，如果没有则创建
// 这里创建的 cosClient 是以复制的目的端信息为基础的
// 详细代码参见本页：简单上传 -> 创建 COSClient
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();
}
// 确认本进程不再使用 cosClient 实例之后，关闭之
cosclient.shutdown();

参数说明

参数名称	描述	类型
copyObjectRequest	拷贝文件请求	CopyObjectRequest

Request 成员说明：

参数名称	描述	类型
sourceBucketRegion	源 Bucket region。默认值：与当前 clientConfig 的 region 一致，表示同地域拷贝	String
sourceBucketName	源存储桶名称，命名格式为 BucketName-APPID，详情请参见 命名规范	String
sourceKey	源对象键，对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg中，对象键为 doc/picture.jpg，详情请参见 对象键	String
sourceVersionId	源文件 version id（适用于开启了版本控制的源 Bucket）。默认值：源文件当前最新版本	String
destinationBucketName	目标存储桶名称，Bucket 的命名格式为 BucketName-APPID ，name 由字母数字和中划线构成	String
destinationKey	目的对象键，对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg中，对象键为 doc/picture.jpg，详情请参见 对象键	String
storageClass	拷贝的目的文件的存储类型。枚举值：Standard，Standard_IA。默认值：Standard。更多存储类型请参见 存储类型概述	String

返回结果说明

• 成功：返回 CopyObjectResult，包含新文件的 Etag 等信息。
• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。

分块操作

大文件复制时，使用一系列小分块复制，改善大文件上传耗时太久可能导致的各种中断问题。

说明：

推荐直接使用高级接口的复制。

操作流程

分块复制的流程

1. 初始化分块复制（Initiate Multipart Upload），得到 UploadId
2. 使用 UploadId 复制分块（Upload Part）
3. 完成分块复制（Complete Multipart Upload）

分块继续复制的流程

1. 如果没有记录 UploadId，则要先查询分块复制任务（List Multipart Uploads），得到对应文件的 UploadId
2. 使用 UploadId 列出已复制的分块（List Parts）
3. 使用 UploadId 复制剩余的分块（Upload Part）
4. 完成分块复制（Complete Multipart Upload）

终止分块复制的流程

1. 如果没有记录 UploadId，则查询分块复制任务（List Multipart Uploads），得到对应文件的 UploadId
2. 终止分块复制并删除已复制分块（Abort Multipart Upload）

初始化分块复制

初始化分块复制操作，获取对应的 uploadId 用于后续的操作。

方法原型

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

请求示例

// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例，如果没有则创建
// 这里创建的 cosClient 是以复制的目的端信息为基础的
// 详细代码参见本页：简单操作 -> 创建 COSClient
COSClient cosClient = createCOSClient();
// 存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。详情请参见 [对象键](https://intl.cloud.tencent.com/document/product/436/13324)
String key = "exampleobject";
InitiateMultipartUploadRequest request = new InitiateMultipartUploadRequest(bucketName, key);
// 分块复制的过程中，仅能通过初始化分块指定文件复制之后的metadata
// 需要的头部可以在这里指定
ObjectMetadata objectMetadata = new ObjectMetadata();
request.setObjectMetadata(objectMetadata);
try {
  InitiateMultipartUploadResult initResult = cosClient.initiateMultipartUpload(request);
  // 获取uploadid
  String uploadId = initResult.getUploadId();
  System.out.println(uploadId);
} catch (CosServiceException e) {
  throw e;
} catch (CosClientException e) {
  throw e;
}

参数说明

参数名称	描述	类型
initiateMultipartUploadRequest	请求	InitiateMultipartUploadRequest

Request 成员说明：

参数名称	设置方法	描述	类型
bucketName	构造函数或 set 方法	Bucket 的命名格式为 BucketName-APPID ，详情请参见 命名规范	String
key	构造函数或 set 方法	指定分块上传到 COS 上的路径，即 对象键。例如对象键为 folder/picture.jpg	String

返回结果说明

• 成功：返回 InitiateMultipartUploadResult ，包含标志本次分块上传的 uploadId。
• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。

查询分块复制任务

查询分块复制任务（List Multipart Uploads），获取当前正在进行的所有复制任务，从中找到需要处理的 uploadId。

方法原型

public MultipartUploadListing listMultipartUploads(
          ListMultipartUploadsRequest listMultipartUploadsRequest)
          throws CosClientException, CosServiceException

请求示例

// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例，如果没有则创建
// 这里创建的 cosClient 是以复制的目的端信息为基础的
// 详细代码参见本页：简单操作 -> 创建 COSClient
COSClient cosClient = createCOSClient();
// 存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 需要查询的分块复制任务对应的 key
String targetKey = "targetKey";
ListMultipartUploadsRequest listMultipartUploadsRequest = new ListMultipartUploadsRequest(bucketName);
// 每次请求最多列出多少个
listMultipartUploadsRequest.setMaxUploads(100);
// 设置要查询的分块复制任务的目标前缀，直接设置要查询的 key
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);
}

参数说明

参数名称	描述	类型
listMultipartUploadsRequest	请求	ListMultipartUploadsRequest

Request 成员说明：

参数名称	描述	类型
bucketName	Bucket 的命名格式为 BucketName-APPID ，详情请参见 命名规范	String
keyMarker	列出条目从该 Key 值开始	String
delimiter	定界符为一个符号，如果有 Prefix，则将 Prefix 到 delimiter 之间的相同路径归为一类，定义为 Common Prefix，然后列出所有 Common Prefix。如果没有 Prefix，则从路径起点开始	String
prefix	限定返回的 Object key 必须以 Prefix 作为前缀。注意使用 prefix 查询时，返回的 key 中仍会包含 Prefix	String
uploadIdMarker	列出条目从该 UploadId 值开始	String
maxUploads	设置最大返回的 multipart 数量，合法值1到1000	String
encodingType	规定返回值的编码方式，可选值：url	String

返回结果说明

• 成功：返回 MultipartUploadListing，包含正在进行分块上传的信息。
• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。

复制分块

分块复制对象（Upload Part - Copy)。

方法原型

public CopyPartResult copyPart(CopyPartRequest copyPartRequest) throws CosClientException, CosServiceException

请求示例

// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例，如果没有则创建
// 这里创建的 cosClient 是以复制的目的端信息为基础的
// 详细代码参见本页：简单操作 -> 创建 COSClient
COSClient cosClient = createCOSClient();
// 存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。详情请参见 [对象键](https://intl.cloud.tencent.com/document/product/436/13324)
String key = "exampleobject";
// uploadId 是一次分块复制任务的唯一标识，通过初始化分块复制或者查询分块复制任务获得
String uploadId = "exampleuploadid";
// 复制的源桶所在的地域
Region srcBucketRegion = new Region("ap-beijing");
// 复制的源桶，命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String srcBucketName = "srcbucket-1250000000";
// 复制的源文件路径
String srcKey = "path/srckey";
// 复制的目的桶所在的地域
Region destBucketRegion = new Region("ap-beijing");
// 复制的目的桶名, 命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String destBucketName = "destbucket-1250000000";
// 复制的目的文件路径
String destKey = "path/destkey";
CopyPartRequest copyPartRequest = new CopyPartRequest();
copyPartRequest.setSourceBucketRegion(srcBucketRegion);
copyPartRequest.setSourceBucketName(srcBucketName);
copyPartRequest.setSourceKey(srcKey);
// 指定要拷贝的源文件的数据范围(类似content-range)
copyPartRequest.setFirstByte(0L);
copyPartRequest.setLastByte(1048575L);
copyPartRequest.setDestinationBucketName(destBucketName);
copyPartRequest.setDestinationKey(destKey);
// 设置本次复制的分块的序号，从 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();
}

参数说明

参数名称	描述	类型
copyPartRequest	请求	CopyPartRequest

Request 成员说明：

参数名称	设置方法	描述	类型
destinationBucketName	set 方法	目标存储桶名称，Bucket 的命名格式为 BucketName-APPID ，详情请参见 命名规范	String
destinationKey	set 方法	目标对象名称，指定分块被复制后所存放的 COS 路径，即 对象键。例如对象键为 folder/picture.jpg	String
uploadId	set 方法	标识指定分块上传的 uploadId	String
partNumber	set 方法	标识指定分块的编号，必须 >= 1	int
sourceBucketRegion	set 方法	源存储桶的地域	Region
sourceBucketName	set 方法	源存储桶的名称	String
sourceKey	set 方法	源对象名称，分块在复制前所在的 COS 上的路径，即 对象键。例如对象键为 folder/picture.jpg	String
firstByte	set 方法	源对象的首字节偏移	Long
lastByte	set 方法	源对象的最后一字节偏移	Long

返回结果说明

• 成功：返回 CopyPartResult，包含分块的 ETag 信息。
• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。

查询已复制的分块

查询特定分块复制操作中的已复制的块（List Parts）。

方法原型

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

请求示例

// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例，如果没有则创建
// 这里创建的 cosClient 是以复制的目的端信息为基础的
// 详细代码参见本页：简单操作 -> 创建 COSClient
COSClient cosClient = createCOSClient();
// 存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。详情请参见 [对象键](https://intl.cloud.tencent.com/document/product/436/13324)
String key = "exampleobject";
// uploadId 是一次分块复制任务的唯一标识，通过初始化分块复制或者查询分块复制任务获得
String uploadId = "exampleuploadid";
// 用于保存已复制的分片信息
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());

参数说明

参数名称	设置方法	描述	类型
bucketName	构造函数或 set 方法	Bucket 的命名格式为 BucketName-APPID ，详情请参见 命名规范	String
key	构造函数或 set 方法	对象的名称	String
uploadId	构造函数或 set 方法	本次要查询的分块上传的 uploadId	String
maxParts	set 方法	单次返回最大的条目数量，默认1000	String
partNumberMarker	set 方法	默认以 UTF-8 二进制顺序列出条目，所有列出条目从 marker 开始	String
encodingType	set 方法	规定返回值的编码方式	String

返回结果说明

• 成功：返回 PartListing，包含每一分块的 ETag 和编号，以及下一次 list 的起点 marker。
• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。

完成分块复制

完成整个文件的分块复制（Complete Multipart Upload）。

说明：

完成分块复制之后，分块复制任务将删除，任务对应的 uploadId 不再有效。

方法原型

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

请求示例

// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例，如果没有则创建
// 这里创建的 cosClient 是以复制的目的端信息为基础的
// 详细代码参见本页：简单操作 -> 创建 COSClient
COSClient cosClient = createCOSClient();
// 存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。详情请参见 [对象键](https://intl.cloud.tencent.com/document/product/436/13324)
String key = "exampleobject";
// uploadId 是一次分块复制任务的唯一标识，通过初始化分块复制或者查询分块复制任务获得
String uploadId = "exampleuploadid";
// 保存已上传的分片信息，实际情况里，这里的内容是从上传分块接口中获取到的
List<PartETag> partETags = new LinkedList<>();
// 分片上传结束后，调用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;
}
// 确保不再使用 cosClient 之后，关闭之
cosClient.shutdown();

参数说明

参数名称	设置方法	描述	类型
bucketName	构造函数或 set 方法	Bucket 的命名格式为 BucketName-APPID ，详情请参见 命名规范	String
key	构造函数或 set 方法	指定分块上传到 COS 上的路径，即 对象键。例如对象键为 folder/picture.jpg	String
uploadId	构造函数或 set 方法	标识指定分块上传的 uploadId	String
partETags	构造函数或 set 方法	标识分块块的编号和上传返回的 eTag	List<PartETag>

返回结果说明

• 成功：返回 CompleteMultipartUploadResult，包含完成对象的 eTag 信息。
• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。

终止分块复制

终止一个分块复制操作并删除已复制的分块（Abort Multipart Upload）。

说明：

终止分块复制之后，分块复制任务和已经复制的分块都会被删除，对应的 uploadId 不再有效。

方法原型

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

请求示例

// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例，如果没有则创建
// 这里创建的 cosClient 是以复制的目的端信息为基础的
// 详细代码参见本页：简单操作 -> 创建 COSClient
COSClient cosClient = createCOSClient();
// 存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。详情请参见 [对象键](https://intl.cloud.tencent.com/document/product/436/13324)
String key = "exampleobject";
// uploadId 是一次分块复制任务的唯一标识，通过初始化分块复制或者查询分块复制任务获得
String uploadId = "exampleuploadid";
AbortMultipartUploadRequest abortMultipartUploadRequest = new AbortMultipartUploadRequest(bucketName, key, uploadId);
try {
  cosClient.abortMultipartUpload(abortMultipartUploadRequest);
} catch (CosServiceException e) {
  e.printStackTrace();
} catch (CosClientException e) {
  e.printStackTrace();
}
// 确保不再使用 cosClient 之后，关闭之
cosClient.shutdown();

参数说明

参数名称	设置方法	描述	类型
bucketName	构造函数或 set 方法	Bucket 的命名格式为 BucketName-APPID，详情请参见 命名规范	String
key	构造函数或 set 方法	分块上传到 COS 上的路径，即 对象键。例如对象键为 folder/picture.jpg	String
uploadId	构造函数或 set 方法	标识指定分块上传的 uploadId	String

返回结果说明

• 成功：无返回值。
• 失败：发生错误（例如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。 详情请参见 异常处理。