断点续传下载
当下载大对象到本地时,经常出现因网络不稳定或程序崩溃导致下载失败的情况。失败后再次重新下载不仅浪费资源,而且当网络不稳定时仍然有下载失败的风险。断点续传下载接口能有效地解决此类问题引起的下载失败,其原理是将待下载的对象分成若干个分段分别下载,并实时地将每段下载结果统一记录在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) 关闭自动解码。