简介

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

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

SDK API 参考

SDK 所有接口的具体参数与方法说明，请参考 SDK API 参考。

高级接口（推荐）

下载对象

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

示例代码一: 下载对象

// 高级下载接口支持断点续传，所以会在下载前先发起 HEAD 请求获取文件信息。
// 如果您使用的是临时密钥或者使用子账号访问，请确保权限列表中包含 HeadObject 的权限。
// 初始化 TransferConfig，这里使用默认配置，如果需要定制，请参考 SDK 接口文档
TransferConfig transferConfig = new TransferConfig.Builder().build();
//初始化 TransferManager
TransferManager transferManager = new TransferManager(cosXmlService,
       transferConfig);
// 存储桶名称，由bucketname-appid 组成，appid必须填入，可以在COS控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucket
String bucket = "examplebucket-1250000000";
String cosPath = "exampleobject"; //对象在存储桶中的位置标识符，即称对象键
//本地目录路径
String savePathDir = context.getExternalCacheDir().toString();
//本地保存的文件名，若不填（null），则与 COS 上的文件名一样
String savedFileName = "exampleobject";
Context applicationContext = context.getApplicationContext(); // application
// context
COSXMLDownloadTask cosxmlDownloadTask =
       transferManager.download(applicationContext,
               bucket, cosPath, savePathDir, savedFileName);
//设置下载进度回调
cosxmlDownloadTask.setCosXmlProgressListener(new CosXmlProgressListener() {
   @Override
   public void onProgress(long complete, long target) {
       // todo Do something to update progress...
   }
});
//设置返回结果回调
cosxmlDownloadTask.setCosXmlResultListener(new CosXmlResultListener() {
   @Override
   public void onSuccess(CosXmlRequest request, CosXmlResult result) {
       COSXMLDownloadTask.COSXMLDownloadTaskResult downloadTaskResult =
               (COSXMLDownloadTask.COSXMLDownloadTaskResult) result;
   }
    // 如果您使用 kotlin 语言来调用，请注意回调方法中的异常是可空的，否则不会回调 onFail 方法，即：
   // clientException 的类型为 CosXmlClientException?，serviceException 的类型为 CosXmlServiceException?
   @Override
   public void onFail(CosXmlRequest request,
                      @Nullable CosXmlClientException clientException,
                      @Nullable CosXmlServiceException serviceException) {
       if (clientException != null) {
           clientException.printStackTrace();
       } else {
           serviceException.printStackTrace();
       }
   }
});
//设置任务状态回调，可以查看任务过程
cosxmlDownloadTask.setTransferStateListener(new TransferStateListener() {
   @Override
   public void onStateChanged(TransferState state) {
       // todo notify transfer state
   }
});

说明：

更多完整示例，请前往 GitHub 查看。

示例代码二: 下载暂停、继续与取消

对于下载任务，可以通过以下方式暂停：

cosxmlDownloadTask.pause();

暂停之后，可以通过以下方式续传：

cosxmlDownloadTask.resume();

也通过以下方式取消下载：

cosxmlDownloadTask.cancel();

说明：

更多完整示例，请前往 GitHub 查看。

示例代码三: 设置下载支持断点续传

// 初始化 TransferConfig，这里使用默认配置，如果需要定制，请参考 SDK 接口文档
// TransferManager 支持断点下载，您只需要保证 bucket、cosPath、savePathDir、savedFileName
// 参数一致，SDK 便会从上次已经下载的位置继续下载。
TransferConfig transferConfig = new TransferConfig.Builder().build();
//初始化 TransferManager
TransferManager transferManager = new TransferManager(cosXmlService,
       transferConfig);
// 存储桶名称，由bucketname-appid 组成，appid必须填入，可以在COS控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucket
String bucket = "examplebucket-1250000000";
String cosPath = "exampleobject"; //对象在存储桶中的位置标识符，即称对象键
//本地目录路径
String savePathDir = context.getExternalCacheDir().toString();
//本地保存的文件名，若不填（null），则与 COS 上的文件名一样
String savedFileName = "exampleobject";
GetObjectRequest getObjectRequest = new GetObjectRequest(bucket, cosPath, savePathDir, savedFileName);
Context applicationContext = context.getApplicationContext(); // application
// context
COSXMLDownloadTask cosxmlDownloadTask =
       transferManager.download(applicationContext, getObjectRequest);

说明：

更多完整示例，请前往 GitHub 查看。

示例代码四: 批量下载

// 对象在存储桶中的位置标识符，即称对象键
String[] cosPaths = new String[] {
       "exampleobject1",
       "exampleobject2",
       "exampleobject3",
};
for (String cosPath : cosPaths) {
    COSXMLDownloadTask cosxmlDownloadTask =
           transferManager.download(applicationContext,
                   bucket, cosPath, savePathDir, savedFileName);
   // 设置返回结果回调
   cosxmlDownloadTask.setCosXmlResultListener(new CosXmlResultListener() {
       @Override
       public void onSuccess(CosXmlRequest request, CosXmlResult result) {
           COSXMLDownloadTask.COSXMLDownloadTaskResult downloadResult =
                   (COSXMLDownloadTask.COSXMLDownloadTaskResult) result;
       }
    // 如果您使用 kotlin 语言来调用，请注意回调方法中的异常是可空的，否则不会回调 onFail 方法，即：
   // clientException 的类型为 CosXmlClientException?，serviceException 的类型为 CosXmlServiceException?
   @Override
   public void onFail(CosXmlRequest request,
                      @Nullable CosXmlClientException clientException,
                      @Nullable CosXmlServiceException serviceException) {
           if (clientException != null) {
               clientException.printStackTrace();
           } else {
               serviceException.printStackTrace();
           }
       }
   });
}

说明：

更多完整示例，请前往 GitHub 查看。

示例代码五: 下载目录

boolean isTruncated = true;
String marker = null;
try {
   while (isTruncated) {
       GetBucketRequest getBucketRequest = new GetBucketRequest(region, bucket, directoryPath);
       // 设置分页信息
       getBucketRequest.setMarker(marker);
       // 设置不查询子目录
       getBucketRequest.setDelimiter("/");
       GetBucketResult getBucketResult = cosXmlService.getBucket(getBucketRequest);
       // 批量下载
       for (ListBucket.Contents content : getBucketResult.listBucket.contentsList) {
           GetObjectRequest getObjectRequest = new GetObjectRequest(bucket, content.key, savePathDir);
           transferManager.download(context,getObjectRequest);
       }
       isTruncated = getBucketResult.listBucket.isTruncated;
       marker = getBucketResult.listBucket.nextMarker;
   }
} catch (CosXmlServiceException serviceException) {
   serviceException.printStackTrace();
} catch (CosXmlClientException clientException) {
   clientException.printStackTrace();
}

说明：

更多完整示例，请前往 GitHub 查看。

简单操作

下载对象

功能说明

下载一个 Object（文件/对象）至本地（GET Object）。

示例代码

String bucket = "examplebucket-1250000000"; //存储桶名称，格式：BucketName-APPID
String cosPath = "exampleobject"; //对象位于存储桶中的位置标识符，即对象键
String savePath = context.getExternalCacheDir().toString(); //本地路径
GetObjectRequest getObjectRequest = new GetObjectRequest(bucket, cosPath,
       savePath);
getObjectRequest.setProgressListener(new CosXmlProgressListener() {
   @Override
   public void onProgress(long progress, long max) {
       // todo Do something to update progress...
   }
});
cosXmlService.getObjectAsync(getObjectRequest, new CosXmlResultListener() {
   @Override
   public void onSuccess(CosXmlRequest cosXmlRequest,
                         CosXmlResult cosXmlResult) {
       GetObjectResult getObjectResult = (GetObjectResult) cosXmlResult;
   }
    // 如果您使用 kotlin 语言来调用，请注意回调方法中的异常是可空的，否则不会回调 onFail 方法，即：
   // clientException 的类型为 CosXmlClientException?，serviceException 的类型为 CosXmlServiceException?
   @Override
   public void onFail(CosXmlRequest cosXmlRequest,
                      @Nullable CosXmlClientException clientException,
                      @Nullable CosXmlServiceException serviceException) {
       if (clientException != null) {
           clientException.printStackTrace();
       } else {
           serviceException.printStackTrace();
       }
   }
});

说明：

更多完整示例，请前往 GitHub 查看。