有奖捉虫:云通信与企业服务文档专题,速来> HOT

简介

本文档提供关于对象的高级上传、简单上传、分块上传等操作相关的 API 概览以及 SDK 示例代码。
简单操作
API
操作名
操作描述
简单上传对象
上传一个对象至存储桶
表单上传对象
使用表单请求上传对象
分块操作
API
操作名
操作描述
查询分块上传
查询正在进行中的分块上传信息
初始化分块上传
初始化分块上传任务
上传分块
分块上传对象
查询已上传块
查询特定分块上传操作中的已上传的块
完成分块上传
完成整个文件的分块上传
终止分块上传
终止一个分块上传操作并删除已上传的块

高级接口(推荐)

高级 API 由类 TransferManager 通过封装各个简单接口,来提供更便捷操作的接口。内部使用一个线程池,来并发接受和处理用户的请求,因此用户也可选择提交多个任务之后异步的执行任务。
TransferManager 实例是并发安全的,这里推荐一个进程只创建一个 TransferManager 实例,当不会再通过这个实例调用高级接口的时候,再选择关闭这个实例。

功能说明

高级接口封装了简单上传、分块上传接口,根据文件大小智能的选择上传方式,同时支持续传、上传时显示进度等功能。
说明
分块阈值用来区分使用简单上传还是分块上传,阈值支持用户自行配置,默认为5MB。
分块大小支持用户自行配置,默认为5MB。
对流类型的上传,小于分块阈值或未指定 Content-Length 头部的上传,高级接口会选择简单上传。
对流类型的上传,大于分块阈值且指定 Content-Length 头部的上传,高级接口会选择分块上传。
对文件类型的上传,小于分块阈值的文件,高级接口会选择简单上传,大于分块阈值的文件,高级接口会选择分块上传。
对于文件类型的分块上传,高级接口会多线程并发同时上传多个分块。
对于分块上传,高级上传接口提供获取进度的功能,具体参见下面的示例。

创建 TransferManager

使用高级接口的操作之前,必须先创建一个 TransferManager 的实例。
// 创建 TransferManager 实例,这个实例用来后续调用高级接口
TransferManager createTransferManager() {
// 创建一个 COSClient 实例,这是访问 COS 服务的基础实例。
// 详细代码参见本页: 简单操作 -> 创建 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.setMultipartUploadThreshold(5*1024*1024);
transferManagerConfiguration.setMinimumUploadPartSize(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);
}

上传本地文件

上传的源是本地的一个文件。

方法原型

// 上传对象
public Upload upload(final PutObjectRequest putObjectRequest)
throws CosServiceException, CosClientException;

请求示例

// 使用高级接口必须先保证本进程存在一个 TransferManager 实例,如果没有则创建
// 详细代码参见本页:高级接口 -> 创建 TransferManager
TransferManager transferManager = createTransferManager();

// 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。
String key = "exampleobject";
// 本地文件路径
String localFilePath = "/path/to/localFile";
File localFile = new File(localFilePath);

PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, localFile);

// 设置存储类型(如有需要,不需要请忽略此行代码), 默认是标准(Standard), 低频(standard_ia)
// 更多存储类型请参见 https://cloud.tencent.com/document/product/436/33417
putObjectRequest.setStorageClass(StorageClass.Standard_IA);

//若需要设置对象的自定义 Headers 可参照下列代码,若不需要可省略下面这几行,对象自定义 Headers 的详细信息可参考 https://cloud.tencent.com/document/product/436/13361
ObjectMetadata objectMetadata = new ObjectMetadata();

//若设置 Content-Type、Cache-Control、Content-Disposition、Content-Encoding、Expires 这五个字自定义 Headers,推荐采用 objectMetadata.setHeader()
//自定义header尽量避免特殊字符,使用中文前请先手动对其进行URLEncode
objectMetadata.setHeader(key, value);
//若要设置 “x-cos-meta-[自定义后缀]” 这样的自定义 Header,推荐采用
Map<String, String> userMeta = new HashMap<String, String>();
userMeta.put("x-cos-meta-[自定义后缀]", "value");
objectMetadata.setUserMetadata(userMeta);

putObjectRequest.withMetadata(objectMetadata);

try {
// 高级接口会返回一个异步结果Upload
// 可同步地调用 waitForUploadResult 方法等待上传完成,成功返回 UploadResult, 失败抛出异常
Upload upload = transferManager.upload(putObjectRequest);
UploadResult uploadResult = upload.waitForUploadResult();
} catch (CosServiceException e) {
e.printStackTrace();
} catch (CosClientException e) {
e.printStackTrace();
} catch (InterruptedException e) {
e.printStackTrace();
}

// 确定本进程不再使用 transferManager 实例之后,关闭即可
// 详细代码参见本页:高级接口 -> 关闭 TransferManager
shutdownTransferManager(transferManager);

参数说明

参数名称
描述
类型
putObjectRequest
上传文件请求
PutObjectRequest
Request 成员说明:
Request 成员
设置方法
描述
类型
bucketName
构造函数或 set 方法
存储桶的命名格式为 BucketName-APPID,详情请参见 命名规范
String
key
构造函数或 set 方法
对象键(Key)是对象在存储桶中的唯一标识。
例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中,对象键为 doc/picture.jpg,详情请参见 对象键
String
file
构造函数或 set 方法
本地文件
File
input
构造函数或 set 方法
输入流
InputStream
metadata
构造函数或 set 方法
文件的元数据
ObjectMetadata
trafficLimit
set 方法
用于对上传对象进行流量控制,单位:bit/s,默认不进行流量控制
Int
storageClass
set 方法
存储类型
String

返回值

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

返回参数说明

通过调用 Upload 的 waitForUploadResult() 方法获取的上传对象信息记录在类 UploadResult 中,类 UploadResult 主要成员说明如下:
成员名称
描述
类型
bucketName
存储桶的命名格式为 BucketName-APPID,详情请参见 命名规范
String
key
对象键(Key)是对象在存储桶中的唯一标识。
例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中,对象键为 doc/picture.jpg,详情请参见 对象键
String
requestId
请求 ID。
String
dateStr
当前服务端时间。
String
versionId
当存储桶开启了版本控制功能,返回对象的版本号 ID。
String
crc64Ecma
服务端根据对象内容计算出来的 CRC64。
String

上传流类型

上传的源是一个 InputStream 类型(和其子类型)的流实例。

方法原型

// 上传对象
public Upload upload(final PutObjectRequest putObjectRequest)
throws CosServiceException, CosClientException;

请求示例

// 使用高级接口必须先保证本进程存在一个 TransferManager 实例,如果没有则创建
// 详细代码参见本页:高级接口 -> 创建 TransferManager
TransferManager transferManager = createTransferManager();

// 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。
String key = "exampleobject";

// 这里创建一个 ByteArrayInputStream 来作为示例,实际中这里应该是您要上传的 InputStream 类型的流
long inputStreamLength = 1024 * 1024;
byte data[] = new byte[inputStreamLength];
InputStream inputStream = new ByteArrayInputStream(data);

ObjectMetadata objectMetadata = new ObjectMetadata();
// 上传的流如果能够获取准确的流长度,则推荐一定填写 content-length
// 如果确实没办法获取到,则下面这行可以省略,但同时高级接口也没办法使用分块上传了
objectMetadata.setContentLength(inputStreamLength);

PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, inputStream, objectMetadata);

// 设置存储类型(如有需要,不需要请忽略此行代码), 默认是标准(Standard), 低频(standard_ia)
// 更多存储类型请参见 https://cloud.tencent.com/document/product/436/33417
putObjectRequest.setStorageClass(StorageClass.Standard_IA);

try {
// 高级接口会返回一个异步结果Upload
// 可同步地调用 waitForUploadResult 方法等待上传完成,成功返回 UploadResult, 失败抛出异常
Upload upload = transferManager.upload(putObjectRequest);
UploadResult uploadResult = upload.waitForUploadResult();
} catch (CosServiceException e) {
e.printStackTrace();
} catch (CosClientException e) {
e.printStackTrace();
} catch (InterruptedException e) {
e.printStackTrace();
}

// 确定本进程不再使用 transferManager 实例之后,关闭即可
// 详细代码参见本页:高级接口 -> 关闭 TransferManager
shutdownTransferManager(transferManager);

参数说明

参数名称
描述
类型
putObjectRequest
上传文件请求
PutObjectRequest
Request 成员说明:
Request 成员
设置方法
描述
类型
bucketName
构造函数或 set 方法
存储桶的命名格式为 BucketName-APPID,详情请参见 命名规范
String
key
构造函数或 set 方法
对象键(Key)是对象在存储桶中的唯一标识。
例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中,对象键为 doc/picture.jpg,详情请参见 对象键
String
file
构造函数或 set 方法
本地文件
File
input
构造函数或 set 方法
输入流
InputStream
metadata
构造函数或 set 方法
文件的元数据
ObjectMetadata
trafficLimit
set 方法
用于对上传对象进行流量控制,单位:bit/s,默认不进行流量控制
Int
storageClass
set 方法
存储类型
String

返回值

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

返回参数说明

通过调用 Upload 的 waitForUploadResult() 方法获取的上传对象信息记录在类 UploadResult 中,类 UploadResult 主要成员说明如下:
成员名称
描述
类型
bucketName
存储桶的命名格式为 BucketName-APPID,详情请参见 命名规范
String
key
对象键(Key)是对象在存储桶中的唯一标识。
例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中,对象键为 doc/picture.jpg,详情请参见 对象键
String
requestId
请求 ID。
String
dateStr
当前服务端时间。
String
versionId
当存储桶开启了版本控制功能,返回对象的版本号 ID。
String
crc64Ecma
服务端根据对象内容计算出来的 CRC64。
String

显示上传进度

说明
只有使用了分块上传的接口才能显示上传进度。
要显示上传进度首先需要一个自己的打印上传进度的函数,在这个函数里通过调用接口来获取已经成功上传的大小从而计算出当前进度。

方法原型

// 上传对象
public Upload upload(final PutObjectRequest putObjectRequest)
throws CosServiceException, CosClientException;

请求示例

// 可以参考下面的例子,结合实际情况做调整
void showTransferProgress(Transfer transfer) {
// 这里的 Transfer 是异步上传结果 Upload 的父类
System.out.println(transfer.getDescription());

// transfer.isDone() 查询上传是否已经完成
while (transfer.isDone() == false) {
try {
// 每 2 秒获取一次进度
Thread.sleep(2000);
} catch (InterruptedException e) {
return;
}

TransferProgress progress = transfer.getProgress();
long sofar = progress.getBytesTransferred();
long total = progress.getTotalBytesToTransfer();
double pct = progress.getPercentTransferred();
System.out.printf("upload progress: [%d / %d] = %.02f%%\\n", sofar, total, pct);
}

// 完成了 Completed,或者失败了 Failed
System.out.println(transfer.getState());
}
结合上传文件的代码示例如下:
// 使用高级接口必须先保证本进程存在一个 TransferManager 实例,如果没有则创建
// 详细代码参见本页:高级接口 -> 创建 TransferManager
TransferManager transferManager = createTransferManager();

// 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。
String key = "exampleobject";
// 本地文件路径
String localFilePath = "/path/to/localFile";
File localFile = new File(localFilePath);

PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, localFile);

try {
// 高级接口会返回一个异步结果Upload
Upload upload = transferManager.upload(putObjectRequest);
// 打印上传进度,直到上传结束
showTransferProgress(upload);
// 捕获可能出现的异常
UploadResult uploadResult = upload.waitForUploadResult();
} catch (CosServiceException e) {
e.printStackTrace();
} catch (CosClientException e) {
e.printStackTrace();
} catch (InterruptedException e) {
e.printStackTrace();
}

// 确定本进程不再使用 transferManager 实例之后,关闭即可
// 详细代码参见本页:高级接口 -> 关闭 TransferManager
shutdownTransferManager(transferManager);

获取进度说明

通过 upload 这个类的 getProgress 可以获得一个 TransferProgress 类,这个类的下面三个方法用来获取上传进度,说明如下:
方法名称
描述
类型
getBytesTransferred
获取已上传的字节数
long
getTotalBytesToTransfer
获取总文件的字节数
long
getPercentTransferred
获取已上传的字节百分比
double

参数说明

参数名称
描述
类型
putObjectRequest
上传文件请求
PutObjectRequest
Request 成员说明:
Request 成员
设置方法
描述
类型
bucketName
构造函数或 set 方法
存储桶的命名格式为 BucketName-APPID,详情请参见 命名规范
String
key
构造函数或 set 方法
对象键(Key)是对象在存储桶中的唯一标识。
例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中,对象键为 doc/picture.jpg,详情请参见 对象键
String
file
构造函数或 set 方法
本地文件。
File
input
构造函数或 set 方法
输入流。
InputStream
metadata
构造函数或 set 方法
文件的元数据。
ObjectMetadata
trafficLimit
set 方法
用于对上传对象进行流量控制,单位:bit/s,默认不进行流量控制。
Int

返回值

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

返回参数说明

通过调用 Upload 的 waitForUploadResult() 方法获取的上传对象信息记录在类 UploadResult 中,类 UploadResult 主要成员说明如下:
成员名称
描述
类型
bucketName
存储桶的命名格式为 BucketName-APPID,详情请参见 命名规范
String
key
对象键(Key)是对象在存储桶中的唯一标识。
例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中,对象键为 doc/picture.jpg,详情请参见 对象键
String
requestId
请求 ID。
String
dateStr
当前服务端时间。
String
versionId
当存储桶开启了版本控制功能,返回对象的版本号 ID。
String
crc64Ecma
服务端根据对象内容计算出来的 CRC64。
String

上传时暂停、继续与取消

使用高级接口可以暂停上传任务、随后继续上传,或者直接取消一个上传任务。
说明
流式上传不可以暂停、继续与取消。
简单上传不可以暂停、继续与取消。
加密上传不可以暂停、继续与取消。

方法原型

// 上传对象
public Upload upload(final PutObjectRequest putObjectRequest)
throws CosServiceException, CosClientException;

请求示例

// 使用高级接口必须先保证本进程存在一个 TransferManager 实例,如果没有则创建
// 详细代码参见本页:高级接口 -> 示例代码:创建 TransferManager
TransferManager transferManager = createTransferManager();

// 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。
String key = "exampleobject";
// 本地文件路径
String localFilePath = "/path/to/localFile";
File localFile = new File(localFilePath);

PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, localFile);

try {
// 高级接口会返回一个异步结果 Upload
Upload upload = transferManager.upload(putObjectRequest);
// 等待 3 秒,上传一部分
Thread.sleep(3000);
// 暂停上传,获取一个 PersistableUpload 实例,用来随后的恢复
PersistableUpload persistableUpload = upload.pause();
// 复杂的暂停与继续用法:
// PersistableUpload 实例也可以通过 serialize 序列化后存储起来,之后再通过 deserialize 反序列化来恢复继续上传
// persistableUpload.serialize(out);
// 继续上传
upload = transferManager.resumeUpload(persistableUpload);
// 捕获可能出现的异常
UploadResult uploadResult = upload.waitForUploadResult();

// 或者直接取消这次上传
// upload.abort();
} catch (CosServiceException e) {
e.printStackTrace();
} catch (CosClientException e) {
e.printStackTrace();
} catch (InterruptedException e) {
e.printStackTrace();
}

// 确定本进程不再使用 transferManager 实例之后,关闭即可
// 详细代码参见本页:高级接口 -> 示例代码:关闭 TransferManager
shutdownTransferManager(transferManager);

参数说明

参数名称
描述
类型
putObjectRequest
上传文件请求
PutObjectRequest
Request 成员说明:
Request 成员
设置方法
描述
类型
bucketName
构造函数或 set 方法
存储桶的命名格式为 BucketName-APPID,详情请参见 命名规范
String
key
构造函数或 set 方法
对象键(Key)是对象在存储桶中的唯一标识。
例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中,对象键为 doc/picture.jpg,详情请参见 对象键
String
file
构造函数或 set 方法
本地文件。
File
input
构造函数或 set 方法
输入流。
InputStream
metadata
构造函数或 set 方法
文件的元数据。
ObjectMetadata
trafficLimit
set 方法
用于对上传对象进行流量控制,单位:bit/s,默认不进行流量控制。
Int

返回值

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

返回参数说明

通过调用 Upload 的 waitForUploadResult() 方法获取的上传对象信息记录在类 UploadResult 中,类 UploadResult 主要成员说明如下:
成员名称
描述
类型
bucketName
存储桶的命名格式为 BucketName-APPID,详情请参见 命名规范
String
key
对象键(Key)是对象在存储桶中的唯一标识。
例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中,对象键为 doc/picture.jpg,详情请参见 对象键
String
requestId
请求 ID。
String
dateStr
当前服务端时间。
String
versionId
当存储桶开启了版本控制功能,返回对象的版本号 ID。
String
crc64Ecma
服务端根据对象内容计算出来的 CRC64。
String

上传本地目录

TransferManager 实例封装了从本地一个目录来读取文件并且上传到 COS 的功能,这个功能可以在不破坏目录结构的情况下,将文件上传。同时,也可以指定将目录下的文件上传到另一个目录。
说明
支持递归上传目录,如果上传目录太大,可能会存在上传较慢或阻塞太久的情况。如果需要递归上传目录,则建议上传小容量的目录(例如有 1024 以上个文件)。如果需要上传大容量目录,建议分成多个小目录进行分次调用。

方法原型

public MultipleFileUpload uploadDirectory(String bucketName, String virtualDirectoryKeyPrefix,
File directory, boolean includeSubdirectories);

请求示例

// 使用高级接口必须先保证本进程存在一个 TransferManager 实例,如果没有则创建
// 详细代码参见本页:高级接口 -> 示例代码:创建 TransferManager
TransferManager transferManager = createTransferManager();
// 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";

// 设置文件上传到 bucket 之后的前缀目录,设置为 “”,表示上传到 bucket 的根目录
String cos_path = "/prefix";
// 要上传的文件夹的绝对路径
String dir_path = "/path/to/localdir";
// 是否递归上传目录下的子目录,如果是 true,子目录下的文件也会上传,且 cos 上会保持目录结构
Boolean recursive = false;

try {
// 返回一个异步结果Upload, 可同步的调用 waitForUploadResult 等待 upload结束, 成功返回 UploadResult, 失败抛出异常.
MultipleFileUpload upload = transferManager.uploadDirectory(bucketName, cos_path, new File(dir_path), recursive);

// 可以选择查看上传进度,这个函数参见 高级接口 -> 上传文件 -> 显示上传进度
showTransferProgress(upload);

// 或者阻塞等待完成
upload.waitForCompletion();
} catch (CosServiceException e) {
e.printStackTrace();
} catch (CosClientException e) {
e.printStackTrace();
} catch (InterruptedException e) {
e.printStackTrace();
}

// 确定本进程不再使用 transferManager 实例之后,关闭即可
// 详细代码参见本页:高级接口 -> 示例代码:关闭 TransferManager
shutdownTransferManager(transferManager);

参数说明

参数名称
描述
类型
bucketName
cos 上的 bucket
GetObjectRequest
virtualDirectoryKeyPrefix
cos 上 object 的前缀
String
directory
要上传的文件夹的绝对路径
File
includeSubDirectory
是否递归上传子目录
Boolean

返回值

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

简单操作

简单操作由 COSClient 类型发起请求,使用简单操作之前必须先创建一个 COSClient 实例。
COSClient 实例是并发安全的,这里推荐一个进程只创建一个 COSClient 实例,当不会再通过这个实例发起请求的时候,再选择关闭这个实例。

创建 COSClient

调用 COS 的接口之前,必须先创建一个 COSClient 的实例。
// 创建 COSClient 实例,这个实例用来后续调用请求
COSClient createCOSClient() {
// 设置用户身份信息。
// 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("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://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("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);
}

上传本地文件

上传的源是本地的一个文件。

方法原型

// 方法1 将本地文件上传到 COS
public PutObjectResult putObject(String bucketName, String key, File file)
throws CosClientException, CosServiceException;
// 方法2 输入流上传到 COS
public PutObjectResult putObject(String bucketName, String key, InputStream input, ObjectMetadata metadata)
throws CosClientException, CosServiceException;
// 方法3 对以上两个方法的包装, 支持更细粒度的参数控制, 如 content-type, content-disposition 等
public PutObjectResult putObject(PutObjectRequest putObjectRequest)
throws CosClientException, CosServiceException;

请求示例

// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例,如果没有则创建
// 详细代码参见本页:简单操作 -> 创建 COSClient
COSClient cosClient = createCOSClient();

// 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。
String key = "exampleobject";
// 本地文件路径
String localFilePath = "/path/to/localFile";
File localFile = new File(localFilePath);

PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, localFile);

// 设置存储类型(如有需要,不需要请忽略此行代码), 默认是标准(Standard), 低频(standard_ia)
// 更多存储类型请参见 https://cloud.tencent.com/document/product/436/33417
putObjectRequest.setStorageClass(StorageClass.Standard_IA);

try {
PutObjectResult putObjectResult = cosClient.putObject(putObjectRequest);
System.out.println(putObjectResult.getRequestId());
} catch (CosServiceException e) {
e.printStackTrace();
} catch (CosClientException e) {
e.printStackTrace();
} catch (InterruptedException e) {
e.printStackTrace();
}

// 确认本进程不再使用 cosClient 实例之后,关闭即可
cosClient.shutdown();

参数说明

参数名称
描述
类型
putObjectRequest
上传文件请求
PutObjectRequest
Request 成员说明:
Request 成员
设置方法
描述
类型
必填
bucketName
构造函数或 set 方法
Bucket 的命名格式为 BucketName-APPID,详情请参见 命名规范
String
key
构造函数或 set 方法
对象键(Key)是对象在存储桶中的唯一标识。
例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中,对象键为 doc/picture.jpg,详情请参见 对象键
String
file
构造函数或 set 方法
本地文件。
File
input
构造函数或 set 方法
输入流。
InputStream
metadata
构造函数或 set 方法
对象的元数据。
ObjectMetadata
trafficLimit
set 方法
用于对上传对象进行流量控制,单位:bit/s,默认不进行流量控制。
Int
storageClass
set 方法
存储类型。
String
ObjectMetadata 类用于记录对象的元信息,其主要成员说明如下:
成员名称
描述
类型
httpExpiresDate
缓存的超时时间,为 HTTP 响应头部中 Expires 字段的值。
Date
ongoingRestore
正在从归档存储类型恢复该对象。
Boolean
userMetadata
前缀为 x-cos-meta- 的用户自定义元信息。
Map<String, String>
metadata
除用户自定义元信息以外的其他头部。
Map<String, String>
restoreExpirationTime
归档对象恢复副本的过期时间。
Date

返回结果说明

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

返回参数说明

PutObjectResult 类用于返回结果信息,其主要成员说明如下:
成员名称
描述
类型
requestId
请求 ID。
String
dateStr
当前服务端时间。
String
versionId
开启版本控制的存储桶,返回对象的版本号 ID。
String
eTag
简单上传接口返回对象的 MD5 值,例如:09cba091df696af91549de27b8e7d0f6。
注意:虽然在请求响应头域 ETag 的值是有双引号的,但是这里解析后的字符串 eTag 值是没有双引号的。
String
crc64Ecma
服务端根据对象内容计算出来的 CRC64。
String

上传流类型

上传的源是一个 InputStream 类型(和其子类型)的流实例。

方法原型

// 方法1 将本地文件上传到 COS
public PutObjectResult putObject(String bucketName, String key, File file)
throws CosClientException, CosServiceException;
// 方法2 输入流上传到 COS
public PutObjectResult putObject(String bucketName, String key, InputStream input, ObjectMetadata metadata)
throws CosClientException, CosServiceException;
// 方法3 对以上两个方法的包装, 支持更细粒度的参数控制, 如 content-type, content-disposition 等
public PutObjectResult putObject(PutObjectRequest putObjectRequest)
throws CosClientException, CosServiceException;

请求示例

// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例,如果没有则创建
// 详细代码参见本页:简单操作 -> 创建 COSClient
COSClient cosClient = createCOSClient();

// 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。
String key = "exampleobject";

// 这里创建一个 ByteArrayInputStream 来作为示例,实际中这里应该是您要上传的 InputStream 类型的流
long inputStreamLength = 1024 * 1024;
byte data[] = new byte[inputStreamLength];
InputStream inputStream = new ByteArrayInputStream(data);

ObjectMetadata objectMetadata = new ObjectMetadata();
// 上传的流如果能够获取准确的流长度,则推荐一定填写 content-length
// 如果确实没办法获取到,则下面这行可以省略,但同时高级接口也没办法使用分块上传了
objectMetadata.setContentLength(inputStreamLength);

PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, inputStream, objectMetadata);

// 设置存储类型(如有需要,不需要请忽略此行代码), 默认是标准(Standard), 低频(standard_ia)
// 更多存储类型请参见 https://cloud.tencent.com/document/product/436/33417
putObjectRequest.setStorageClass(StorageClass.Standard_IA);

try {
PutObjectResult putObjectResult = cosClient.putObject(putObjectRequest);
System.out.println(putObjectResult.getRequestId());
} catch (CosServiceException e) {
e.printStackTrace();
} catch (CosClientException e) {
e.printStackTrace();
} catch (InterruptedException e) {
e.printStackTrace();
}

// 确认本进程不再使用 cosClient 实例之后,关闭即可
cosClient.shutdown();

参数说明

参数名称
描述
类型
putObjectRequest
上传文件请求
PutObjectRequest
Request 成员说明:
Request 成员
设置方法
描述
类型
必填
bucketName
构造函数或 set 方法
Bucket 的命名格式为 BucketName-APPID,详情请参见 命名规范
String
key
构造函数或 set 方法
对象键(Key)是对象在存储桶中的唯一标识。
例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中,对象键为 doc/picture.jpg,详情请参见 对象键
String
file
构造函数或 set 方法
本地文件。
File
input
构造函数或 set 方法
输入流。
InputStream
metadata
构造函数或 set 方法
对象的元数据。
ObjectMetadata
trafficLimit
set 方法
用于对上传对象进行流量控制,单位:bit/s,默认不进行流量控制。
Int
storageClass
set 方法
存储类型。
String
ObjectMetadata 类用于记录对象的元信息,其主要成员说明如下:
成员名称
描述
类型
httpExpiresDate
缓存的超时时间,为 HTTP 响应头部中 Expires 字段的值。
Date
ongoingRestore
正在从归档存储类型恢复该对象。
Boolean
userMetadata
前缀为 x-cos-meta- 的用户自定义元信息。
Map<String, String>
metadata
除用户自定义元信息以外的其他头部。
Map<String, String>
restoreExpirationTime
归档对象恢复副本的过期时间。
Date

返回结果说明

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

返回参数说明

PutObjectResult 类用于返回结果信息,其主要成员说明如下:
成员名称
描述
类型
requestId
请求 ID
String
dateStr
当前服务端时间
String
versionId
开启版本控制的存储桶,返回对象的版本号 ID
String
eTag
简单上传接口返回对象的 MD5 值,例如:09cba091df696af91549de27b8e7d0f6。
注意:虽然在请求响应头域 ETag 的值是有双引号的,但是这里解析后的字符串 eTag 值是没有双引号的
String
crc64Ecma
服务端根据对象内容计算出来的 CRC64
String

创建目录

COS 本身没有目录的概念,但是可以将以 '/' 分隔的对象路径看做虚拟文件夹。
说明
如果需要一个目录,可以直接往需要的目录上传一个文件,则目录会自动创建。例如:上传一个 /dir/example.txt 这样的文件,则 /dir 这个目录就自动生成了。这种情况请参考本页的上传本地文件。
如果需要一个下面没有文件的目录,则使用这里的办法:上传一个空流到一个以 '/' 结尾的路径,这样就有了一个虚拟的目录。
// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例,如果没有则创建
// 详细代码参见本页:简单操作 -> 创建 COSClient
COSClient cosClient = createCOSClient();

// 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 在这里指定要创建的目录的路径
String key = "/example/dir/";

// 这里创建一个空的 ByteArrayInputStream 来作为示例
byte data[] = new byte[0];
InputStream inputStream = new ByteArrayInputStream(data);

ObjectMetadata objectMetadata = new ObjectMetadata();
objectMetadata.setContentLength(0);

PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, inputStream, objectMetadata);

try {
PutObjectResult putObjectResult = cosClient.putObject(putObjectRequest);
System.out.println(putObjectResult.getRequestId());
} catch (CosServiceException e) {
e.printStackTrace();
} catch (CosClientException e) {
e.printStackTrace();
} catch (InterruptedException e) {
e.printStackTrace();
}

// 确认本进程不再使用 cosClient 实例之后,关闭即可
cosClient.shutdown();


表单上传对象

使用表单请求上传对象。

构造表单上传的 form body

根据表单参数,构造上传最开始的 form body 部分。
String buildPostObjectBody(String boundary, Map<String, String> formFields, String filename, String contentType) {
StringBuffer stringBuffer = new StringBuffer();
for(Map.Entry entry: formFields.entrySet()) {
// 添加 boundary 行,行首以--开头
stringBuffer.append("--").append(boundary).append("\\r\\n");
// 字段名
stringBuffer.append("Content-Disposition: form-data; name=\\""
+ entry.getKey() + "\\"\\r\\n\\r\\n");
// 字段值
stringBuffer.append(entry.getValue() + "\\r\\n");
}
// 添加 boundary 行,行首以--开头
stringBuffer.append("--").append(boundary).append("\\r\\n");
// 文件名
stringBuffer.append("Content-Disposition: form-data; name=\\"file\\"; "
+ "filename=\\"" + filename + "\\"\\r\\n");
// 文件类型
stringBuffer.append("Content-Type: " + contentType + "\\r\\n\\r\\n");
return stringBuffer.toString();
}

上传本地文件

// 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// COS_REGION 请参见 https://cloud.tencent.com/document/product/436/6224
String endpoint = "cos.{COS_REGION}.myqcloud.com";
// 对象键(Key)是对象在存储桶中的唯一标识。
String key = "exampleobject";
// SECRETID 和 SECRETKEY 请登录访问管理控制台进行查看和管理
String secretId = "AKIDXXXXXXXX";
String seretKey = "1A2Z3YYYYYYYYYY";

String localFilePath = "/path/to/localFile";
String contentType = "image/jpeg";

long startTimestamp = System.currentTimeMillis() / 1000;
long endTimestamp = startTimestamp + 30 * 60;
String endTimestampStr = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'").format(endTimestamp * 1000);

String keyTime = startTimestamp + ";" + endTimestamp;
String boundary = "----WebKitFormBoundaryZBPbaoYE2gqeB21N";

// 设置表单的 body 字段值
Map<String, String> formFields = new HashMap<>();
formFields.put("q-sign-algorithm", "sha1");
formFields.put("key", key);
formFields.put("q-ak", secretId);
formFields.put("q-key-time", keyTime);

// 构造 policy,参见文档: https://cloud.tencent.com/document/product/436/14690
String policy = "{\\n" +
" \\"expiration\\": \\"" + endTimestampStr + "\\",\\n" +
" \\"conditions\\": [\\n" +
" { \\"bucket\\": \\"" + bucketName + "\\" },\\n" +
" { \\"q-sign-algorithm\\": \\"sha1\\" },\\n" +
" { \\"q-ak\\": \\"" + secretId + "\\" },\\n" +
" { \\"q-sign-time\\":\\"" + keyTime + "\\" }\\n" +
" ]\\n" +
"}";

// policy 需要 base64后算放入表单中
String encodedPolicy = new String(Base64.encodeBase64(policy.getBytes()));
// 设置 policy
formFields.put("policy", encodedPolicy);
// 根据编码后的 policy 和 secretKey 计算签名
COSSigner cosSigner = new COSSigner();
String signature = cosSigner.buildPostObjectSignature(seretKey,
keyTime, policy);
// 设置签名
formFields.put("q-signature", signature);

// 根据以上表单参数,构造最开始的 body 部分
String formBody = buildPostObjectBody(boundary, formFields,
localFilePath, contentType);

HttpURLConnection conn = null;
try {
String urlStr = "http://" + bucketName + "." + endpoint;
URL url = new URL(urlStr);
conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setRequestProperty("User-Agent", VersionInfoUtils.getUserAgent());
conn.setRequestProperty("Content-Type", "multipart/form-data; boundary=" + boundary);
conn.setDoOutput(true);
conn.setDoInput(true);

OutputStream out = new DataOutputStream(conn.getOutputStream());
// 写入表单的最开始部分
out.write(formBody.getBytes());

// 将文件内容写入到输出流中
File file = new File(localFilePath);
DataInputStream in = new DataInputStream(new FileInputStream(file));
int readBytes;
byte[] bytes = new byte[4096];
while ((readBytes = in.read(bytes)) != -1) {
out.write(bytes, 0, readBytes);
}
in.close();

// 添加最后一个分割符,行首和行尾都是--
byte[] endData = ("\\r\\n--" + boundary + "--\\r\\n").getBytes();
out.write(endData);
out.flush();
out.close();

// 读取响应头部
for (Map.Entry<String, List<String>> entries : conn.getHeaderFields().entrySet()) {
String values = "";
for (String value : entries.getValue()) {
values += value + ",";
}
if(entries.getKey() == null) {
System.out.println("reponse line:" + values );
} else {
System.out.println(entries.getKey() + ":" + values );
}
}
} catch (Exception e) {
e.printStackTrace();
throw e;
} finally {
if (conn != null) {
conn.disconnect();
}
}

分块操作

分块操作是大文件上传时,使用一系列分块,改善大文件上传耗时太久可能导致的各种中断问题。关于分块上传的更多说明请参见 分块上传。分块上传对象的操作流程如下。
说明
如果要上传的文件或者流可以完整获取,推荐使用高级接口。

操作流程

分块上传的流程

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 = createCOSClient();
// 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。
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 = 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;
}
listMultipartUploadsRequest.setKeyMarker(multipartUploadListing.getNextKeyMarker());
listMultipartUploadsRequest.setUploadIdMarker(multipartUploadListing.getNextUploadIdMarker());
} 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)。

方法原型

public UploadPartResult uploadPart(UploadPartRequest uploadPartRequest) throws CosClientException, CosServiceException;

请求示例

// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例,如果没有则创建
// 详细代码参见本页:简单操作 -> 创建 COSClient
COSClient cosClient = createCOSClient();
// 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。
String key = "exampleobject";
// uploadId 是一次分块上传任务的唯一标识,通过初始化分块上传或者查询分块上传任务获得
String uploadId = "exampleuploadid";

// 每个分块上传之后都会得到一个返回值 etag,保存起来用于最后合并分块时使用
List<PartETag> partETags = new LinkedList<>();

// 上传数据, 这里上传 10 个 1M 的分块数据
for (int i = 1; i <= 10; i++) {
// 这里创建一个 ByteArrayInputStream 来作为示例,实际中这里应该是您要上传的 InputStream 类型的流
long inputStreamLength = 1024 * 1024;
byte data[] = new byte[inputStreamLength];
InputStream inputStream = new ByteArrayInputStream(data);

UploadPartRequest uploadPartRequest = new UploadPartRequest();
uploadPartRequest.setBucketName(bucketName);
uploadPartRequest.setKey(key);
uploadPartRequest.setUploadId(uploadId);
uploadPartRequest.setInputStream(inputStream(data));
// 设置分块的长度
uploadPartRequest.setPartSize(data.length);
// 设置要上传的分块编号,从 1 开始
uploadPartRequest.setPartNumber(i);

try {
UploadPartResult uploadPartResult = cosClient.uploadPart(uploadPartRequest);
PartETag partETag = uploadPartResult.getPartETag();
partETags.add(partETag);
} catch (CosServiceException e) {
throw e;
} catch (CosClientException e) {
throw e;
}
}

System.out.println(partETags);

参数说明

参数名称
描述
类型
uploadPartRequest
请求
UploadPartRequest
Request 成员说明:
参数名称
设置方法
描述
类型
bucketName
set 方法
Bucket 的命名格式为 BucketName-APPID ,详情请参见 命名规范
String
key
set 方法
指定分块上传到 COS 上的路径,即 对象键。例如对象键为 folder/picture.jpg
String
uploadId
set 方法
标识指定分块上传的 uploadId
String
partNumber
set 方法
标识指定分块的编号,必须 >= 1
int
inputStream
set 方法
待上传分块的输入流
InputStream
trafficLimit
set 方法
用于对上传分块进行流量控制,单位:bit/s,默认不进行流量控制
Int

返回结果说明

成功:返回 UploadPartResult,包含上传分块的 eTag 信息。
失败:发生错误(如身份认证失败),抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理

返回参数说明

UploadPartResult 类用于返回结果信息,其主要成员说明如下:
成员名称
描述
类型
partNumber
标识指定分块的编号
String
eTag
返回上传分块的 MD5 值
String
crc64Ecma
服务端根据分块内容计算出来的 CRC64
String

查询已上传的分块

查询特定分块上传操作中的已上传的块(List Parts)。

方法原型

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

请求示例

// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例,如果没有则创建
// 详细代码参见本页:简单操作 -> 创建 COSClient
COSClient cosClient = createCOSClient();
// 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。
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 = createCOSClient();
// 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。
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 = createCOSClient();
// 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。
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。 详情请参见 异常处理