复制与移动对象

最近更新时间:2024-08-14 17:37:42

我的收藏

简介

本文介绍对象存储 COS 通过 Java SDK 实现复制与移动对象功能的示例代码和描述。包括高级接口、简单操作、分块操作三个部分。

注意事项

若您使用简单接口复制对象,需要具有源对象的读权限和目标对象的写权限:在您进行 授权策略 时,目标对象的授权 action 需要设置为cos:PutObject ,源对象的授权 action 需要设置为cos:GetObject ,更多授权请参见 支持CAM的业务接口
若您使用高级接口的自动分块复制或使用简单接口的分块操作实现分块复制,需要具有源对象的读权限以及目标对象的初始化分块上传、上传对象、完成分块上传的权限:在您进行 授权策略 时,目标对象的授权 action 需要设置为 cos:InitiateMultipartUploadcos:PutObjectcos:CompleteMultipartUpload,源对象的授权 action 需要设置为cos:GetObject ,更多授权请参见 支持CAM的业务接口

相关示例

功能名称
描述
示例代码
高级接口
高级接口封装了简单拷贝、分块拷贝接口,根据文件大小智能的选择拷贝对象的方式。
简单操作
简单操作的拷贝接口可以拷贝一个对象至指定存储桶中,不支持自动分块拷贝。最大支持拷贝不超过5GB的对象,5GB以上对象请使用 分块拷贝 或 高级接口 拷贝。
分块操作
分块操作基于多个简单接口可以实现将整个源对象切分为多个分块,然后再将这些分块拷贝到目标存储桶中。

高级接口(推荐)

注意:
分块阈值用来区分使用简单拷贝还是分块拷贝,阈值支持用户自行配置,默认为5GB。
分块大小支持用户自行配置,默认为100MB。

前期准备:创建 TransferManager

使用高级接口的操作之前,必须先创建一个 TransferManager 的实例。创建 TransferManager 的实例之前,需要创建一个 COSClient 实例,详细代码可以参见 创建 COSClient
说明:
TransferManager 实例是并发安全的,这里推荐一个进程只创建一个 TransferManager 实例,当不会再通过这个实例调用高级接口的时候,再选择关闭这个实例。
// 创建 TransferManager 实例,这个实例用来后续调用高级接口
TransferManager createTransferManager() {
// 创建一个 COSClient 实例,这是访问 COS 服务的基础实例。
// 详细代码参见本页: 简单操作 -> 创建 COSClient
// 复制的目的桶所在的地域
String destBucketRegion = "ap-beijing";
COSClient cosClient = createCOSClient(destBucketRegion);

// 自定义线程池大小,建议在客户端与 COS 网络充足(例如使用腾讯云的 CVM,同地域上传 COS)的情况下,设置成16或32即可,可较充分的利用网络资源
// 对于使用公网传输且网络带宽质量不高的情况,建议减小该值,避免因网速过慢,造成请求超时。
ExecutorService threadPool = Executors.newFixedThreadPool(32);

// 传入一个 threadpool, 若不传入线程池,默认 TransferManager 中会生成一个单线程的线程池。
TransferManager transferManager = new TransferManager(cosClient, threadPool);

return transferManager;
}

前期准备:关闭 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, final COS srcCOS, final TransferStateChangeListener stateChangeListener) throws CosServiceException, CosClientException

请求示例

// 这里创建以复制的目的端信息为基础
// 使用高级接口必须先保证本进程存在一个 TransferManager 实例,如果没有则创建
// 详细代码参见本页:高级接口 -> 创建 TransferManager
TransferManager transferManager = createTransferManager();
// 复制的源桶所在的地域
String srcRegion = "ap-guangzhou";
Region srcBucketRegion = new Region(srcRegion);
// 复制的源桶,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String srcBucketName = "srcbucket-1250000000";
// 复制的源文件路径
String srcKey = "path/srckey";

// 注意:复制的目的桶所在地域是在创建 TransferManager/CosClient 时通过函数: createTransferManager() -> createCOSClient() -> clientConfig.setRegion(dstRegion) 设置的
// 复制的目的桶名, 命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String destBucketName = "destbucket-1250000000";
// 复制的目的文件路径
String destKey = "path/destkey";

// 这里创建的 cosClient 是以复制的源端信息为基础的
// 详细代码参见本页: 简单操作 -> 创建 COSClient
COSClient srcCOSClient = createCOSClient(srcRegion);

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
srcCOS
源桶的COSClient实例
COS
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。详情请参见 异常处理

简单操作

前期准备:创建 COSClient

调用 COS 的接口之前,必须先创建一个 COSClient 的实例。
说明:
COSClient 实例是并发安全的,这里推荐一个进程只创建一个 COSClient 实例,当不会再通过这个实例发起请求的时候,再选择关闭这个实例。
// 创建 COSClient 实例,这个实例用来后续调用请求
COSClient createCOSClient(String region) {
// 设置用户身份信息。
// SECRETID 和 SECRETKEY 请登录访问管理控制台 https://console.cloud.tencent.com/cam/capi 进行查看和管理
String secretId = System.getenv("secretId");//用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
String secretKey = System.getenv("secretKey");//用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);
// ClientConfig 中包含了后续请求 COS 的客户端设置:
ClientConfig clientConfig = new ClientConfig();
// 设置 bucket 的地域
// COS_REGION 请参见 https://cloud.tencent.com/document/product/436/6224
clientConfig.setRegion(new Region(region));
// 以下的设置,是可选的:
// 设置 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 实例。
说明:
COSClient 实例是并发安全的,这里推荐一个进程只创建一个 COSClient 实例,当不会再通过这个实例发起请求的时候,再选择关闭这个实例。
使用临时密钥创建 COSClient 实例之前,需要先生成临时密钥,本 SDK 并不能生成临时密钥,而需要使用额外的操作来生成,参考 临时密钥生成及使用指引
// 创建 COSClient 实例,这个实例用来后续调用请求
COSClient createCOSClient(String region) {
// 这里需要已经获取到临时密钥的结果。
// 临时密钥的生成参见 https://cloud.tencent.com/document/product/436/14048#cos-sts-sdk
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://cloud.tencent.com/document/product/436/6224
clientConfig.setRegion(new Region(region));

// 以下的设置,是可选的:

// 设置 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

当不会再通过一个COSClient实例发起请求的时候,请及时将其关闭,防止资源泄露。
cosclient.shutdown();

使用案例:复制对象

方法原型

public CopyObjectResult copyObject(CopyObjectRequest copyObjectRequest)
throws CosClientException, CosServiceException

请求示例

// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例,如果没有则创建
// 这里创建的 cosClient 是以复制的目的端信息为基础的
// 详细代码参见本页:简单上传 -> 创建 COSClient
// 复制的目的桶所在的地域
String destBucketRegion = "ap-beijing";
COSClient cosClient = createCOSClient(destBucketRegion);

// 复制的源桶所在的地域
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 {
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
目标存储桶名称,存储桶的命名格式为 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

返回值

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

使用案例:移动对象

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

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

方法原型

public CopyObjectResult copyObject(CopyObjectRequest copyObjectRequest)
throws CosClientException, CosServiceException
public void deleteObject(String bucketName, String key)
throws CosClientException, CosServiceException;

请求示例

// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例,如果没有则创建
// 这里创建的 cosClient 是以复制的目的端信息为基础的
// 详细代码参见本页:简单上传 -> 创建 COSClient
// 复制的目的桶所在的地域
String destBucketRegion = "ap-beijing";
COSClient cosClient = createCOSClient(destBucketRegion);

// 复制的源桶所在的地域
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";

// 实现参考本页:简单操作 -> 复制对象
copyObject();

// 实现参考:删除对象:https://cloud.tencent.com/document/product/436/65939
deleteObject();

分块操作

前期准备:创建 COSClient

调用 COS 的接口之前,必须先创建一个 COSClient 的实例。
说明:
COSClient 实例是并发安全的,这里推荐一个进程只创建一个 COSClient 实例,当不会再通过这个实例发起请求的时候,再选择关闭这个实例。
// 创建 COSClient 实例,这个实例用来后续调用请求
COSClient createCOSClient(String region) {
// 设置用户身份信息。
// SECRETID 和 SECRETKEY 请登录访问管理控制台 https://console.cloud.tencent.com/cam/capi 进行查看和管理
String secretId = System.getenv("secretId");//用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
String secretKey = System.getenv("secretKey");//用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);
// ClientConfig 中包含了后续请求 COS 的客户端设置:
ClientConfig clientConfig = new ClientConfig();
// 设置 bucket 的地域
// COS_REGION 请参见 https://cloud.tencent.com/document/product/436/6224
clientConfig.setRegion(new Region(region));
// 以下的设置,是可选的:
// 设置 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 实例。
说明:
COSClient 实例是并发安全的,这里推荐一个进程只创建一个 COSClient 实例,当不会再通过这个实例发起请求的时候,再选择关闭这个实例。
使用临时密钥创建 COSClient 实例之前,需要先生成临时密钥,本 SDK 并不能生成临时密钥,而需要使用额外的操作来生成,参考 临时密钥生成及使用指引
// 创建 COSClient 实例,这个实例用来后续调用请求
COSClient createCOSClient(String region) {
// 这里需要已经获取到临时密钥的结果。
// 临时密钥的生成参见 https://cloud.tencent.com/document/product/436/14048#cos-sts-sdk
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://cloud.tencent.com/document/product/436/6224
clientConfig.setRegion(new Region(region));

// 以下的设置,是可选的:

// 设置 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

当不会再通过一个COSClient实例发起请求的时候,请及时将其关闭,防止资源泄露。
cosclient.shutdown();

操作流程

分块复制的流程

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
// 复制的目的桶所在的地域
String destBucketRegion = "ap-beijing";
COSClient cosClient = createCOSClient(destBucketRegion);
// 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。详情请参见 [对象键](https://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
// 复制的目的桶所在的地域
String destBucketRegion = "ap-beijing";
COSClient cosClient = createCOSClient(destBucketRegion);
// 存储桶的命名格式为 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
// 复制的目的桶所在的地域
String destBucketRegion = "ap-beijing";
COSClient cosClient = createCOSClient(destBucketRegion);

// uploadId 是一次分块复制任务的唯一标识,通过初始化分块复制或者查询分块复制任务获得
String uploadId = "exampleuploadid";

// 复制的源桶所在的地域
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";

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
// 复制的目的桶所在的地域
String destBucketRegion = "ap-beijing";
COSClient cosClient = createCOSClient(destBucketRegion);
// 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。详情请参见 [对象键](https://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());

参数说明

参数名称
描述
类型
listPartsRequest
查询已复制的分块请求
ListPartsRequest
Request 成员说明:
参数名称
设置方法
描述
类型
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
// 复制的目的桶所在的地域
String destBucketRegion = "ap-beijing";
COSClient cosClient = createCOSClient(destBucketRegion);
// 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。详情请参见 [对象键](https://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();

参数说明

参数名称
描述
类型
completeMultipartUploadRequest
完成分块复制请求
CompleteMultipartUploadRequest
Request 成员说明:
参数名称
设置方法
描述
类型
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
// 复制的目的桶所在的地域
String destBucketRegion = "ap-beijing";
COSClient cosClient = createCOSClient(destBucketRegion);
// 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。详情请参见 [对象键](https://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();

参数说明

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

返回结果说明

成功:无返回值。
失败:发生错误(例如身份认证失败),抛出异常 CosClientException 或者 CosServiceException。 详情请参见 异常处理

API 操作

关于简单操作的 API 接口说明,请参见 PUT Object - Copy 文档。