有奖征文:轻量对象存储LighthouseCOS用户实践> HOT

简介

本文档提供关于对象的下载操作相关的 API 概览以及 SDK 示例代码。
API
操作名
操作描述
下载对象
下载一个对象至本地

高级接口(推荐)

高级接口指定暂停、恢复以及取消下载请求,同时支持断点下载功能。
说明
高级接口的下载是直接把对象写进了指定的本地文件中,如果需要一个下载流,参考本页的简单操作。

创建 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);

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);
}

下载对象

下载对象将 COS 上的对象下载存储到本地的一个文件中。

方法原型

public Download download(final GetObjectRequest getObjectRequest, final File file);

请求示例

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

// 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。详情请参见 [对象键](https://cloud.tencent.com/document/product/436/13324)
String key = "exampleobject";
// 本地文件路径
String localFilePath = "/path/to/localFile";
File downloadFile = new File(localFilePath);

GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, key);
try {
// 返回一个异步结果 Download, 可同步的调用 waitForCompletion 等待下载结束, 成功返回 void, 失败抛出异常
Download download = transferManager.download(getObjectRequest, downloadFile);
download.waitForCompletion();
} catch (CosServiceException e) {
e.printStackTrace();
} catch (CosClientException e) {
e.printStackTrace();
} catch (InterruptedException e) {
e.printStackTrace();
}

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

参数说明

参数名称
描述
类型
默认值
getObjectRequest
下载对象请求
GetObjectRequest
file
要下载到的本地文件
File
Request 成员说明:
Request 成员
设置方法
描述
类型
bucketName
构造函数或 set 方法
存储桶的命名格式为 BucketName-APPID,详情请参见 命名规范
String
key
构造函数或 set 方法
对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中,对象键为 doc/picture.jpg,详情请参见 对象键
String
range
set 方法
下载的 range 范围
Long[]
trafficLimit
set 方法
用于对下载对象进行流量控制,单位:bit/s,默认不进行流量控制
int

返回值

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

断点下载对象

断点下载对象利用了分 range 多线程同时下载的方式下载对象,并在完成之后做完整性校验。如果下载过程中出现异常中断,重新下载时不会下载已经下载过的 range (源文件如果在重启前被修改,则会从头下载)。 适合大文件下载。

方法原型

public Download download(final GetObjectRequest getObjectRequest, final File file,
boolean resumableDownload);

public Download download(final GetObjectRequest getObjectRequest, final File file,
boolean resumableDownload, String resumableTaskFile,
int multiThreadThreshold, int partSize);

请求示例

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

// 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。详情请参见 [对象键](https://cloud.tencent.com/document/product/436/13324)
String key = "exampleobject";
// 本地文件路径
String localFilePath = "/path/to/localFile";
File downloadFile = new File(localFilePath);

GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, key);
getObjectRequest.setDownloadPartsThreads(4); // 设置分 range 多线程同时下载的并发数,不设置默认为1(此参数在5.6.168及以上版本支持)
try {
// 返回一个异步结果 Download, 可同步的调用 waitForCompletion 等待下载结束, 成功返回 void, 失败抛出异常
Download download = transferManager.download(getObjectRequest, downloadFile, true);
download.waitForCompletion();
} catch (CosServiceException e) {
e.printStackTrace();
} catch (CosClientException e) {
e.printStackTrace();
} catch (InterruptedException e) {
e.printStackTrace();
}

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

参数说明

参数名称
描述
类型
默认值
getObjectRequest
下载对象请求
GetObjectRequest
file
要下载到的本地文件
File
resumableDownload
是否启用分块断点续传下载
boolean
false
resumableTaskFile
断点续传下载时记录信息文件名
String
file.cosresumabletask
multiThreadThreshold
断点续传下载使用多线程下载的最小文件大小
int
20 * 1024 * 1024
partSize
断点续传下载使用的分块大小
int
8 * 1024 * 1024
downloadPartsThreads
分 range 多线程同时下载的并发数(5.6.168及以上版本支持)
int
1
Request 成员说明:
Request 成员
设置方法
描述
类型
bucketName
构造函数或 set 方法
存储桶的命名格式为 BucketName-APPID,详情请参见 命名规范
String
key
构造函数或 set 方法
对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中,对象键为 doc/picture.jpg,详情请参见 对象键
String
range
set 方法
下载的 range 范围
Long[]
trafficLimit
set 方法
用于对下载对象进行流量控制,单位:bit/s,默认不进行流量控制
int

返回值

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

显示下载进度

要显示下载进度首先需要一个自己的打印下载进度的函数,在这个函数里通过调用接口来获取已经成功下载的大小从而计算出当前进度。

方法原型

public Download download(final GetObjectRequest getObjectRequest, final File file);

请求示例

// 可以参考下面的例子,结合实际情况做调整
void showTransferProgress(Transfer transfer) {
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)是对象在存储桶中的唯一标识。详情请参见 [对象键](https://cloud.tencent.com/document/product/436/13324)
String key = "exampleobject";
// 本地文件路径
String localFilePath = "/path/to/localFile";
File downloadFile = new File(localFilePath);

GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, key);
try {
// 返回一个异步结果 Download, 可同步的调用 waitForCompletion 等待下载结束, 成功返回 void, 失败抛出异常
Download download = transferManager.download(getObjectRequest, downloadFile);
// 打印下载进度,直到下载结束
showTransferProgress(download);
// 这里可以捕获可能出现的异常
download.waitForCompletion();
} catch (CosServiceException e) {
e.printStackTrace();
} catch (CosClientException e) {
e.printStackTrace();
} catch (InterruptedException e) {
e.printStackTrace();
}

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

获取进度说明

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

参数说明

参数名称
描述
类型
默认值
getObjectRequest
下载对象请求
GetObjectRequest
file
要下载到的本地文件
File
Request 成员说明:
Request 成员
设置方法
描述
类型
bucketName
构造函数或 set 方法
存储桶的命名格式为 BucketName-APPID,详情请参见 命名规范
String
key
构造函数或 set 方法
对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中,对象键为 doc/picture.jpg,详情请参见 对象键
String
range
set 方法
下载的 range 范围
Long[]
trafficLimit
set 方法
用于对下载对象进行流量控制,单位:bit/s,默认不进行流量控制
int

返回值

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

下载时暂停、继续与取消

使用高级接口可以暂停下载任务、随后继续下载,或者直接取消一个下载任务。

方法原型

public Download download(final GetObjectRequest getObjectRequest, final File file);

请求示例

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

// 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。详情请参见 [对象键](https://cloud.tencent.com/document/product/436/13324)
String key = "exampleobject";
// 本地文件路径
String localFilePath = "/path/to/localFile";
File downloadFile = new File(localFilePath);
GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, key);

try {
// 返回一个异步结果 copy, 可同步的调用 waitForCompletion 等待 download 结束, 成功返回 void, 失败抛出异常.
Download download = transferManager.download(getObjectRequest, downloadFile);
// 等待 3 秒,下载一部分
Thread.sleep(3000L);
// 暂停下载,获取一个 PersistableUpload 实例,用来随后的恢复
PersistableDownload persistableDownload = download.pause();
// 复杂的暂停与继续用法:
// PersistableDownload 实例也可以通过 serialize 序列化后存储起来,之后再通过 deserialize 反序列化来恢复继续下载
// persistableDownload.serialize(out);
// 继续下载
download = transferManager.resumeDownload(persistableDownload);
// 捕获可能出现的异常
download.waitForCompletion();

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

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

参数说明

参数名称
描述
类型
默认值
getObjectRequest
下载对象请求
GetObjectRequest
file
要下载到的本地文件
File
Request 成员说明:
Request 成员
设置方法
描述
类型
bucketName
构造函数或 set 方法
存储桶的命名格式为 BucketName-APPID,详情请参见 命名规范
String
key
构造函数或 set 方法
对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中,对象键为 doc/picture.jpg,详情请参见 对象键
String
range
set 方法
下载的 range 范围
Long[]
trafficLimit
set 方法
用于对下载对象进行流量控制,单位:bit/s,默认不进行流量控制
int

返回值

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

下载目录

下载目录可以下载 COS 上有相同前缀的一批对象(一个虚拟目录),到指定的本地目录中。下载到本地的文件,保持和在 COS 相同的目录结构。

方法原型

public MultipleFileDownload downloadDirectory(String bucketName, String keyPrefix,
File destinationDirectory) {

请求示例

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

// 设置要下载的对象的前缀(相当于 cos 上的一个目录),如果设置成 "",则下载整个 bucket。
String cos_path = "/prefix";
// 要保存下载的文件的文件夹的绝对路径
String dir_path = "/to/mydir";

try {
// 返回一个异步结果 download, 可同步的调用 waitForUploadResult 等待 download 结束.
MultipleFileDownload download = transferManager.downloadDirectory(bucketName, cos_path, new File(dir_path));

// 可以选择查看下载进度
showTransferProgress(download);

// 或者阻塞等待完成
download.waitForCompletion();

System.out.println("download directory done.");
} catch (CosServiceException e) {
e.printStackTrace();
} catch (CosClientException e) {
e.printStackTrace();
} catch (InterruptedException e) {
e.printStackTrace();
}

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

参数说明

参数名称
描述
类型
bucketName
cos 上的 bucket
GetObjectRequest
keyPrefix
cos 上 object 的前缀
String
destinationDirectory
本地的文件夹的绝对路径
File

返回值

成功:返回 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);
}

下载对象

下载一个 Object 到本地(GET Object)。
说明
以下只有下载并使用流的示例,如果需要下载到文件中,直接使用本页的高级接口。

方法原型

public COSObject getObject(GetObjectRequest getObjectRequest)
throws CosClientException, CosServiceException;

请求示例

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

// 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 对象键(Key)是对象在存储桶中的唯一标识。详情请参见 [对象键](https://cloud.tencent.com/document/product/436/13324)
String key = "exampleobject";

GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, key);
COSObjectInputStream cosObjectInput = null;

try {
COSObject cosObject = cosClient.getObject(getObjectRequest);
cosObjectInput = cosObject.getObjectContent();
} catch (CosServiceException e) {
e.printStackTrace();
} catch (CosClientException e) {
e.printStackTrace();
} catch (InterruptedException e) {
e.printStackTrace();
}

// 处理下载到的流
// 这里是直接读取,按实际情况来处理
byte[] bytes = null;
try {
bytes = IOUtils.toByteArray(cosObjectInput);
} catch (IOException e) {
e.printStackTrace();
} finally {
// 用完流之后一定要调用 close()
cosObjectInput.close();
}

// 在流没有处理完之前,不能关闭 cosClient
// 确认本进程不再使用 cosClient 实例之后,关闭即可
cosClient.shutdown();

参数说明

参数名称
描述
类型
getObjectRequest
下载文件请求
GetObjectRequest
destinationFile
本地的保存文件
File
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
range
set 方法
下载的 range 范围
Long[]
trafficLimit
set 方法
用于对下载对象进行流量控制,单位:bit/s,默认不进行流量控制
Int

返回结果说明

成功:返回 COSObject 类,包含输入流以及对象属性。
失败:发生错误(如身份认证失败),抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理

返回参数说明

COSObject 类用于返回结果信息,其主要成员说明如下:
成员名称
描述
类型
bucketName
Bucket 的命名格式为 BucketName-APPID ,详情请参见 命名规范
String
key
对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中,对象键为 doc/picture.jpg,详情请参见 对象键
String
metadata
对象的元数据
ObjectMetadata
objectContent
包含 COS 对象内容的数据流
COSObjectInputStream