控制台指南

最佳实践

开发者指南

API 文档

SDK 文档

诚邀爱技术、爱分享的你,成为文档内容共建者> HOT

简介

本文档提供关于对象的下载操作相关的 API 概览以及 SDK 示例代码。

API 操作名 操作描述
GET Object 下载对象 下载一个对象至本地

高级接口(推荐)

高级接口指定暂停、恢复以及取消下载请求,同时支持断点下载功能。

说明:

高级接口的下载是直接把对象写进了指定的本地文件中,如果需要一个下载流,参考本页的简单操作。

创建 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);
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 断点续传下载时记录信息文件名 boolean file.cosresumabletask
multiThreadThreshold 断点续传下载使用多线程下载的最小文件大小 int 20 * 1024 * 1024
partSize 断点续传下载使用的分块大小 int 8 * 1024 * 1024

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 = "SECRETID";
    String secretKey = "SECRETKEY";
    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
目录