当下载大对象时，可能出现网络波动等情况导致下载对象失败，TOS Python SDK 提供了重试机制保障下载对象的稳定性，但可能出现多次重试后仍无法完成下载的情况。针对上述情况，TOS Python SDK 提供了断点续传下载的功能，在下载大对象失败后可实现重入。断点续传下载将待下载的对象分割为多个分片，并支持并发下载，待所有分片下载完成后，合并成完整的文件。通过断点续传下载的方式将对象下载到本地文件前，您可以设置分片大小、下载分片的线程数、下载时客户端限速、事件回调函数等。同时也能在断点续传下载任务执行过程中，取消该任务。
tos:GetObject 权限，具体操作，请参见权限配置指南。tos:GetObjectVersion 权限，具体操作，请参见权限配置指南。以下代码用于断点续传下载桶 bucket-test 中对象 object-test 到本地文件中，若在下载过程中抛出 TosClientError 异常并且错误为网络超时则可以相同参数调用 download_file，实现断点续传下载重入。
import os
import tos
# 从环境变量获取 AK 和 SK 信息。
ak = os.getenv('TOS_ACCESS_KEY')
sk = os.getenv('TOS_SECRET_KEY')
# your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例，your endpoint 填写 tos-cn-beijing.volces.com，your region 填写 cn-beijing。
endpoint = "your endpoint"
region = "your region"
bucket_name = "bucket-test"
# 对象名称，例如 example_dir 下的 example_object.txt 文件，则填写为 example_dir/example_object.txt
object_key = "object-test"
# 本地文件完整路径，例如usr/local/testfile.txt
file_path = "/usr/local/testfile.txt"
try:
# 创建 TosClientV2 对象，对桶和对象的操作都通过 TosClientV2 实现
client = tos.TosClientV2(ak, sk, endpoint, region)
client.download_file(bucket_name, object_key, file_path,
# 通过可选参数part_size配置下载时分片大小，默认为20mb
part_size=1024 * 1024 * 20,
# 通过可选参数task_num配置下载分片的线程数，默认为1
task_num=3)
except tos.exceptions.TosClientError as e:
# 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常
print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause))
except tos.exceptions.TosServerError as e:
# 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息
print('fail with server error, code: {}'.format(e.code))
# request id 可定位具体问题，强烈建议日志中保存
print('error with request id: {}'.format(e.request_id))
print('error with message: {}'.format(e.message))
print('error with http code: {}'.format(e.status_code))
print('error with ec: {}'.format(e.ec))
print('error with request url: {}'.format(e.request_url))
except Exception as e:
print('fail with unknown error: {}'.format(e))
以下代码用于配置断点续传下载进度条功能。
import os
import tos
from tos import DataTransferType
# 从环境变量获取 AK 和 SK 信息。
ak = os.getenv('TOS_ACCESS_KEY')
sk = os.getenv('TOS_SECRET_KEY')
# your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例，your endpoint 填写 tos-cn-beijing.volces.com，your region 填写 cn-beijing。
endpoint = "your endpoint"
region = "your region"
bucket_name = "bucket-test"
# 对象名称，例如 example_dir 下的 example_object.txt 文件，则填写为 example_dir/example_object.txt
object_key = "object-test"
# 本地文件完整路径，例如usr/local/testfile.txt
file_path = "/usr/local/testfile.txt"
try:
# 创建 TosClientV2 对象，对桶和对象的操作都通过 TosClientV2 实现
client = tos.TosClientV2(ak, sk, endpoint, region)
def percentage(consumed_bytes, total_bytes, rw_once_bytes, type: DataTransferType):
if total_bytes:
rate = int(100 * float(consumed_bytes) / float(total_bytes))
print("rate:{}, consumed_bytes:{},total_bytes{}, rw_once_bytes:{}, type:{}".format(rate, consumed_bytes,
total_bytes,
rw_once_bytes, type))
client.download_file(bucket_name, object_key, file_path,
# 通过可选参数part_size配置下载时分片大小，默认为20mb
part_size=1024 * 1024 * 20,
# 通过可选参数task_num配置下载分片的线程数，默认为1
task_num=3,
# 通过可选参数data_transfer_listener配置进度条
data_transfer_listener=percentage)
except tos.exceptions.TosClientError as e:
# 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常
print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause))
except tos.exceptions.TosServerError as e:
# 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息
print('fail with server error, code: {}'.format(e.code))
# request id 可定位具体问题，强烈建议日志中保存
print('error with request id: {}'.format(e.request_id))
print('error with message: {}'.format(e.message))
print('error with http code: {}'.format(e.status_code))
print('error with ec: {}'.format(e.ec))
print('error with request url: {}'.format(e.request_url))
except Exception as e:
print('fail with unknown error: {}'.format(e))
以下代码用于自定义断点续传下载回调函数。
import os
import tos
from tos import DownloadEventType
# 从环境变量获取 AK 和 SK 信息。
ak = os.getenv('TOS_ACCESS_KEY')
sk = os.getenv('TOS_SECRET_KEY')
# your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例，your endpoint 填写 tos-cn-beijing.volces.com，your region 填写 cn-beijing。
endpoint = "your endpoint"
region = "your region"
bucket_name = "bucket-test"
# 对象名称，例如 example_dir 下的 example_object.txt 文件，则填写为 example_dir/example_object.txt
object_key = "object-test"
# 本地文件完整路径，例如usr/local/testfile.txt
file_path = "/usr/local/testfile.txt"
try:
# 创建 TosClientV2 对象，对桶和对象的操作都通过 TosClientV2 实现
client = tos.TosClientV2(ak, sk, endpoint, region)
# 用户自定义事件回调函数
def download_event(type: DownloadEventType, err, bucket, key, version_id, file_path, checkpint_file, tmp_file,
download_part):
print(type, err, bucket, key, version_id, file_path, checkpint_file, tmp_file, download_part)
client.download_file(bucket_name, object_key, file_path,
# 通过可选参数part_size配置下载时分片大小，默认为20mb
part_size=1024 * 1024 * 20,
# 通过可选参数task_num配置下载分片的线程数，默认为1
task_num=3,
# 通过可选参数data_transfer_listener配置进度条
download_event_listener=download_event)
except tos.exceptions.TosClientError as e:
# 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常
print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause))
except tos.exceptions.TosServerError as e:
# 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息
print('fail with server error, code: {}'.format(e.code))
# request id 可定位具体问题，强烈建议日志中保存
print('error with request id: {}'.format(e.request_id))
print('error with message: {}'.format(e.message))
print('error with http code: {}'.format(e.status_code))
print('error with ec: {}'.format(e.ec))
print('error with request url: {}'.format(e.request_url))
except Exception as e:
print('fail with unknown error: {}'.format(e))
以下代码用于设置断点续传下载客户端限速。
import os
import tos
from tos import DownloadEventType
# 从环境变量获取 AK 和 SK 信息。
ak = os.getenv('TOS_ACCESS_KEY')
sk = os.getenv('TOS_SECRET_KEY')
# your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例，your endpoint 填写 tos-cn-beijing.volces.com，your region 填写 cn-beijing。
endpoint = "your endpoint"
region = "your region"
bucket_name = "bucket-test"
# 对象名称，例如 example_dir 下的 example_object.txt 文件，则填写为 example_dir/example_object.txt
object_key = "object-test"
# 本地文件完整路径，例如usr/local/testfile.txt
file_path = "/usr/local/testfile.txt"
try:
# 创建 TosClientV2 对象，对桶和对象的操作都通过 TosClientV2 实现
client = tos.TosClientV2(ak, sk, endpoint, region)
# 通过可选参数rate_limiter配下载下载对象客户端限制速
# TOS Python SDK 通过最基本的令牌桶算法实现了客户端限速，其中rate为发送令牌的速率，capacity为总容量
# 以下配置的意义为5 MB/s的平均上传速率，最高支持 10 + 5 MB/s的下载速率
rate_limiter = tos.RateLimiter(rate=5 * 1024 * 1024, capacity=10 * 1024 * 1024)
client.download_file(bucket_name, object_key, file_path,
# 通过可选参数part_size配置下载时分片大小，默认为20mb
part_size=1024 * 1024 * 20,
# 通过可选参数task_num配置下载分片的线程数，默认为1
task_num=3,
# 通过可选参数rate_limiter配置客户端限速
rate_limiter=rate_limiter)
except tos.exceptions.TosClientError as e:
# 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常
print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause))
except tos.exceptions.TosServerError as e:
# 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息
print('fail with server error, code: {}'.format(e.code))
# request id 可定位具体问题，强烈建议日志中保存
print('error with request id: {}'.format(e.request_id))
print('error with message: {}'.format(e.message))
print('error with http code: {}'.format(e.status_code))
print('error with ec: {}'.format(e.ec))
print('error with request url: {}'.format(e.request_url))
except Exception as e:
print('fail with unknown error: {}'.format(e))
以下代码用于在运行时取消正在执行的断点续传上传任务。
import time
from threading import Thread
import os
import tos
from tos.checkpoint import CancelHook
from tos.exceptions import TosClientError
# 从环境变量获取 AK 和 SK 信息。
ak = os.getenv('TOS_ACCESS_KEY')
sk = os.getenv('TOS_SECRET_KEY')
endpoint = "your endpoint"
region = "your region"
bucket_name = "bucket-test"
# 对象名称，例如 example_dir 下的 example_object.txt 文件，则填写为 example_dir/example_object.txt
object_key = "object-test"
# 本地文件完整路径，例如usr/local/testfile.txt
file_path = "/usr/local/testfile.txt"
# 创建 TosClientV2 对象，对桶和对象的操作都通过 TosClientV2 实现
client = tos.TosClientV2(ak, sk, endpoint, region)
# 继承 CancelHook 类实现断点续传下载任务取消功能
class MyCancel(CancelHook):
def cancel(self, is_abort: bool):
# is_abort 为 true 时删除上下文信息并 abort 分段上传任务，为 false 时只是中断当前执行
# 重写 cancel 方法时必须调用 父类的 cancel 方法
# 模拟 10 秒后取消任务
time.sleep(10)
super(MyCancel, self).cancel(is_abort=is_abort)
print('some user define')
cancel = MyCancel()
t1 = Thread(target=cancel.cancel, args=(False,))
t1.start()
try:
client.download_file(bucket_name, object_key, file_path,
# 通过可选参数part_size配置下载时分片大小，默认为20mb
part_size=1024 * 1024 * 20,
# 通过可选参数task_num配置下载分片的线程数，默认为1
task_num=3,
# 通过可选参数cancel_hook实现取消机制
cancel_hook=cancel)
except TosClientError as e:
# 若取消断点续传下载任务，将抛出TosClientError，同时message='the task is canceled'
if e.message == 'the task is canceled':
print('the task is canceled')
except Exception as e:
print(e)