全部产品
Search
文档中心

对象存储 OSS:Python断点续传下载

更新时间:Dec 20, 2023

当下载大文件时,如果网络不稳定或者程序异常退出,会导致下载失败,甚至重试多次仍无法完成下载。为此,OSS提供了断点续传下载功能。断点续传下载将需要下载的文件分成若干个分片分别下载,所有分片都下载完成后,将所有分片合并成完整的文件。

注意事项

  • 本文以华东1(杭州)外网Endpoint为例。如果您希望通过与OSS同地域的其他阿里云产品访问OSS,请使用内网Endpoint。关于OSS支持的Region与Endpoint的对应关系,请参见访问域名和数据中心

  • 本文以从环境变量读取访问凭证为例。如何配置访问凭证,请参见配置访问凭证

  • 本文以OSS域名新建OSSClient为例。如果您希望通过自定义域名、STS等方式新建OSSClient,请参见初始化

  • 要断点续传下载,您必须有oss:GetObject权限。具体操作,请参见为RAM用户授权自定义的权限策略

流程说明

断点续传下载的流程如下:

  1. 在本地创建一个临时文件,文件名由原文件名加上一个随机的后缀组成。

  2. 通过指定HTTP请求的Range头,按照范围读取OSS文件,并写入到临时文件里相应的位置。

  3. 下载完成之后,把临时文件重命名为目标文件。如目标文件已存在会覆盖,不存在则新建。

警告

因断点信息会在本地磁盘上互相覆盖,且临时文件名可能会冲突,需避免多个程序(线程)同时调用oss2.resumable_download方法下载同一个源文件到同一个目标文件。

示例代码

以下代码用于断点续传下载:

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
# 填写Bucket名称,例如examplebucket。
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')

# yourObjectName填写Object完整路径,完整路径中不能包含Bucket名称,例如exampledir/exampleobject.txt。
# yourLocalFile填写本地文件的完整路径,例如D:\\localpath\\examplefile.txt。
oss2.resumable_download(bucket, 'exampledir/exampleobject.txt', 'D:\\localpath\\examplefile.txt')
# 如未使用参数store指定目录,则会在HOME目录下建立.py-oss-upload目录来保存断点信息。

# Python SDK 2.1.0以上版本支持断点续传下载时设置以下可选参数。
# import sys
# # 当无法确定待下载的数据长度时,total_bytes的值为None。
# def percentage(consumed_bytes, total_bytes):
#     if total_bytes:
#         rate = int(100 * (float(consumed_bytes) / float(total_bytes)))
#         print('\r{0}% '.format(rate), end='')
#         sys.stdout.flush()
# # 如果使用store指定了目录,则断点信息将保存在指定目录中。如果使用num_threads设置并发下载线程数,请将oss2.defaults.connection_pool_size设置为大于或等于并发下载线程数。默认并发下载线程数为1。
# oss2.resumable_download(bucket,  'exampledir/exampleobject.txt', 'D:\\localpath\\examplefile.txt',
#                       store=oss2.ResumableDownloadStore(root='/tmp'),
#                       # 指定当文件长度大于或等于可选参数multipart_threshold(默认值为10 MB)时,则使用断点续传下载。
#                       multiget_threshold=100*1024,
#                       # 设置分片大小,单位为字节,取值范围为100 KB~5 GB。默认值为100 KB。
#                       part_size=100*1024,
#                       # 设置下载进度回调函数。
#                       progress_callback=percentage,
#                       # 如果使用num_threads设置并发下载线程数,请将oss2.defaults.connection_pool_size设置为大于或等于并发下载线程数。默认并发下载线程数为1。
#                       num_threads=4)

相关文档

  • 关于断点续传下载的完整示例代码,请参见GitHub示例

  • 关于断点续传下载的API接口说明,请参见GetObject