当下载大对象时，可能出现网络波动等情况导致下载对象失败，TOS Python SDK 提供了重试机制保障下载对象的稳定性，但可能出现多次重试后仍无法完成下载的情况。针对上述情况，TOS Python SDK 提供了断点续传下载的功能，在下载大对象失败后可实现重入。断点续传下载将待下载的对象分割为多个分片，并支持并发下载，待所有分片下载完成后，合并成完整的文件。通过断点续传下载的方式将对象下载到本地文件前，您可以设置分片大小、下载分片的线程数、下载时客户端限速、事件回调函数等。同时也能在断点续传下载任务执行过程中，取消该任务。

注意事项 #

• 下载对象前，您必须具有 tos:GetObject 权限，具体操作，请参见权限配置指南。
• 对于开启多版本的桶，下载指定版本对象时，您必须具有 tos:GetObjectVersion 权限，具体操作，请参见权限配置指南。
• 如果应用程序会在同一时刻大量下载同一个对象，您的访问速度会受到 TOS 带宽及地域的限制。建议您使用 CDN 产品，提升性能的同时也能降低您的成本。通过 CDN 访问 TOS 的详细信息，请参见使用 CDN 加速访问 TOS 资源。

示例代码 #

失败后重入 #

以下代码用于断点续传下载桶 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)