更新时间:2024-06-21 GMT+08:00

断点续传下载

开发过程中,您有任何问题可以在github上提交issue接口参考文档详细介绍了每个接口的参数和使用方法。

当下载大对象到本地时,经常出现因网络不稳定或程序崩溃导致下载失败的情况。失败后再次重新下载不仅浪费资源,而且当网络不稳定时仍然有下载失败的风险。断点续传下载接口能有效地解决此类问题引起的下载失败,其原理是将待下载的对象分成若干个分段分别下载,并实时地将每段下载结果统一记录在checkpoint文件中,仅当所有分段都下载成功时返回下载成功的结果,否则抛出异常提醒用户再次调用接口进行重新下载(重新下载时因为有checkpoint文件记录当前的下载进度,避免重新下载所有分段,从而节省资源提高效率)。

您可以通过ObsClient.downloadFile进行断点续传下载。该接口可设置的参数如下:

参数

作用

OBS Android SDK对应方法

bucketName

桶名,必选参数。

DownloadFileRequest.setBucketName

objectKey

对象名,必选参数。

DownloadFileRequest.setObjectKey

downloadFile

下载对象的本地文件全路径。当该值为空时,默认为当前程序的运行目录。

DownloadFileRequest.setDownloadFile

partSize

分段大小,单位字节,取值范围是100KB~5GB,默认为5MB。

DownloadFileRequest.setPartSize

taskNum

分段下载时的最大并发数,默认为1。

DownloadFileRequest.setTaskNum

isEncodeHeaders

是否自动解码响应头

DownloadFileRequest.setIsEncodeHeaders

enableCheckpoint

是否开启断点续传模式,默认为false,表示不开启。

DownloadFileRequest.setEnableCheckpoint

checkpointFile

记录下载进度的文件,只在断点续传模式下有效。当该值为空时,默认与下载对象的本地文件路径同目录。

DownloadFileRequest.setCheckpointFile

versionId

对象的版本号。

DownloadFileRequest.setVersionId

ifModifiedSince

如果对象在指定的时间后有修改,则返回对象内容,否则返回错误。

DownloadFileRequest.setIfModifiedSince

ifUnmodifiedSince

如果对象在指定的时间后没有修改,则返回对象内容,否则返回错误。

DownloadFileRequest.setIfUnmodifiedSince

ifMatchTag

如果对象的ETag值与该参数值相同,则返回对象内容,否则抛出异常。

DownloadFileRequest.setIfMatchTag

ifNoneMatchTag

如果对象的ETag值与该参数值不相同,则返回对象内容,否则抛出异常。

DownloadFileRequest.setIfNoneMatchTag

progressListener

设置数据传输监听器,用于获取下载进度。

DownloadFileRequest.setProgressListener

以下代码展示了如何使用断点续传下载接口下载对象到本地文件:

// 认证用的ak和sk硬编码到代码中或者明文存储都有很大的安全风险,建议在配置文件或者环境变量中密文存放,使用时解密,确保安全;本示例以ak和sk保存在环境变量中为例,运行本示例前请先在本地环境中设置环境变量ACCESS_KEY_ID和SECRET_ACCESS_KEY_ID。
// 您可以登录访问管理控制台获取访问密钥AK/SK,获取方式请参见https://support.huaweicloud.com/intl/zh-cn/usermanual-ca/ca_01_0003.html
String ak = System.getenv("ACCESS_KEY_ID");
String sk = System.getenv("SECRET_ACCESS_KEY_ID");
String endPoint = "https://your-endpoint";
// 创建ObsClient实例
ObsClient obsClient = new ObsClient(ak, sk, endPoint);
DownloadFileRequest request = new DownloadFileRequest("bucketname", "objectname");
// 设置下载对象的本地文件路径
request.setDownloadFile("localfile");
// 设置分段下载时的最大并发数
request.setTaskNum(5);
// 设置分段大小为10MB
request.setPartSize(10 * 1024 * 1024);
// 开启断点续传模式
request.setEnableCheckpoint(true);
try{
    // 进行断点续传下载
    DownloadFileResult result = obsClient.downloadFile(request);
}catch (ObsException e) {
    // 发生异常时可再次调用断点续传下载接口进行重新下载
}
  • 断点续传下载接口是利用范围下载特性实现的,是对范围下载的封装和加强。
  • 断点续传下载接口不仅能在失败重下时节省资源提高效率,还因其对分段进行并发下载的机制能加快下载速度,帮助用户快速完成下载业务;且其对用户透明,用户不用关心checkpoint文件的创建和删除、分段任务的切分、并发下载的实现等内部细节。
  • enableCheckpoint参数默认是false,代表不启用断点续传模式,此时断点续传下载接口退化成对范围下载的简单封装,不会产生checkpoint文件。
  • checkpointFile参数仅在enableCheckpoint参数为true时有效。
  • 由于 HTTP 编码规范限制,无法发送非 ASCII 码字符,SDK 会在接收响应时使用 url 解码规则解码响应头头中的信息,。如您的元数据存储的 content-disposition 为 ”attachment; filename="%E4%B8%AD%E6%96%87.txt"”,则 SDK 获取结果为”attachment; filename="中文.txt"”。
  • 如果不需要 SDK 帮您解码,可以调用 DownloadFileRequest.setIsEncodeHeaders(false) 关闭自动解码。