对象存储下载对象-SDK 文档-文档中心-腾讯云

简介
本文介绍对象存储 COS 通过 Java  SDK 实现下载对象功能的示例代码和描述。包括高级接口、简单接口两个部分。
注意事项
若您想要下载对象，需要具有目标对象的读权限：在您进行 授权策略 时，action 需要设置为cos:GetObject ，更多授权请参见 支持CAM的业务接口。
相关示例
功能名称
描述
示例代码
高级接口
高级接口封装了简单下载接口，支持断点下载，下载目录，但不支持流式下载。
﻿GitHub完整示例﻿
简单接口
GET Object 接口可以实现流式下载和下载对象到本地文件，不支持断点下载功能。
﻿GitHub完整示例﻿
简单接口
前期准备
创建 COSClient
调用 COS 的接口之前，必须先创建一个 COSClient 的实例。
说明：
COSClient 实例是并发安全的，这里推荐一个进程只创建一个 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"));
         
    // 以下的设置，是可选的：
    
    // 设置 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() {
    // 这里需要已经获取到临时密钥的结果。
    // 临时密钥的生成参见 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"));
﻿
    // 以下的设置，是可选的：
﻿
    // 设置 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 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);
InputStream cosObjectInput = null;
﻿
try {
    COSObject cosObject = cosClient.getObject(getObjectRequest);
    cosObjectInput = cosObject.getObjectContent();
} catch (CosServiceException e) {
    e.printStackTrace();
} catch (CosClientException 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
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
返回值
成功：返回 COSObject 类，包含输入流以及对象属性。
失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。
下载到本地文件
方法原型
public COSObject getObject(final GetObjectRequest getObjectRequest, File destinationFile)
            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);
﻿
try {
    File localFile = new File("my_test.json");
    ObjectMetadata objectMetadata = cosClient.getObject(getObjectRequest, localFile);
} catch (CosServiceException e) {
    e.printStackTrace();
} catch (CosClientException e) {
    e.printStackTrace();
}
// 确认本进程不再使用 cosClient 实例之后，关闭即可
cosClient.shutdown();
参数说明
参数名称
描述
类型
getObjectRequest
下载对象请求
GetObjectRequest
destinationFile
要下载到的本地文件
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
返回值
成功：返回 ObjectMetadata 类，包含对象属性。
失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。
高级接口（推荐）
说明：
高级接口的下载是直接把对象写进了指定的本地文件中，如果需要一个下载流，参考本页的简单接口。
前期准备
创建 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;
}
关闭 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。若要使用此功能，请先将 sdk 版本升级至5.6.168或更高版本。
方法原型
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。详情请参见 异常处理。
下载目录
下载目录可以下载 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
存储桶的命名格式为 BucketName-APPID，详情请参见 命名规范﻿
String
keyPrefix
cos 上 object 的前缀
String
destinationDirectory
本地的文件夹的绝对路径
File
返回值
成功：返回 MultipleFileDownload，可以查询下载是否结束，也可同步的等待下载结束。
失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。
API 操作
关于下载对象接口涉及的 API 接口说明，请参见 GET Object 查看。
功能名称	描述	示例代码
高级接口	高级接口封装了简单下载接口，支持断点下载，下载目录，但不支持流式下载。	GitHub完整示例
简单接口	GET Object 接口可以实现流式下载和下载对象到本地文件，不支持断点下载功能。	GitHub完整示例
参数名称	描述	类型
getObjectRequest	下载对象请求	GetObjectRequest
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
方法名称	描述	类型
getBytesTransferred	获取已下载的字节数	long
getTotalBytesToTransfer	获取总文件的字节数	long
getPercentTransferred	获取已下载的字节百分比	double
下载对象

本页目录：

简介

注意事项

相关示例

简单接口

前期准备

创建 COSClient

使用临时密钥创建 COSClient

关闭 COSClient

使用案例

流式下载

方法原型

请求示例

参数说明

返回值

下载到本地文件

方法原型

请求示例

参数说明

返回值

高级接口（推荐）

前期准备

创建 TransferManager

关闭 TransferManager

使用案例

下载对象到本地文件

方法原型

请求示例

参数说明

返回值

断点下载对象

方法原型

请求示例

参数说明

返回值

显示下载进度

方法原型

请求示例

获取进度说明

参数说明

返回值

下载目录

方法原型

请求示例

参数说明

返回值

API 操作
