有奖捉虫:办公协同&微信生态&物联网文档专题 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 方法
输入流。<