如何使用OSS Python SDK V2进行文件下载_对象存储(OSS)-阿里云帮助中心

本文针对文件的传输场景，介绍如何使用Python SDK V2新增的下载管理器Downloader模块进行文件下载。

注意事项

本文示例代码以华东1（杭州）的地域IDcn-hangzhou为例，默认使用外网Endpoint，如果您希望通过与OSS同地域的其他阿里云产品访问OSS，请使用内网Endpoint。关于OSS支持的Region与Endpoint的对应关系，请参见OSS地域和访问域名。
要进行文件下载，您必须有oss:GetObject权限。具体操作，请参见为RAM用户授权自定义的权限策略。

方法定义

下载管理器功能简介

Python SDK V2新增下载管理器Downloader提供了通用的下载方法，隐藏了底层方法的实现细节，提供便捷的文件下载能力。

下载管理器Downloader底层利用范围下载，把文件自动分成多个较小的分片进行并发下载，提升下载的性能。
下载管理器Downloader同时提供了断点续传的能力，即在下载过程中，记录已完成的分片状态，如果出现网络中断、程序异常退出等问题导致文件下载失败，甚至重试多次仍无法完成下载，再次下载时，可以通过断点记录文件恢复下载。

下载管理器Downloader的常用方法如下：

# 用于下载文件到本地
download_file(request: GetObjectRequest, filepath: str, **kwargs: Any) → DownloadResult

请求参数列表

参数名	类型	说明

参数名	类型	说明
request	GetObjectRequest	下载对象的请求参数，和GetObject 方法的请求参数一致，具体请参见GetObjectRequest
filepath	str	本地文件路径

返回参数列表

类型	说明

类型	说明
DownloadResult	下载对象的返回参数，具体请参见DownloadResult

当您使用client.downloader初始化下载管理器实例时，您可以指定多个配置选项来自定义下载行为，例如指定分片大小如下所示。

downloader = client.downloader(part_size=1024 * 1024)

常用的配置选项说明列举如下：

参数名	类型	说明

参数名	类型	说明
part_size	int	指定分片大小，默认值为 6MiB
parallel_num	int	指定下载任务的并发数，默认值为 3。针对的是单次调用的并发限制，而不是全局的并发限制
enable_checkpoint	bool	是否开启断点下载功能，默认不开启
checkpoint_dir	str	指定记录文件的保存路径，例如 /local/dir/, 当enable_checkpoint 为True时有效
verify_data	bool	恢复下载时，是否要校验已下载数据的CRC64值，默认不校验, 当enable_checkpoint 为True时有效
use_temp_file	bool	下载文件时，是否使用临时文件，默认使用。先下载到临时文件上，当成功后，再重命名为目标文件

关于文件下载管理器方法的完整定义，请参见Downloader。

示例代码

您可以使用以下代码将存储空间中的文件下载到本地。

import argparse
import alibabacloud_oss_v2 as oss

# 创建一个命令行参数解析器，并描述脚本用途：下载文件示例
parser = argparse.ArgumentParser(description="download file sample")

# 添加命令行参数 --region，表示存储空间所在的区域，必需参数
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# 添加命令行参数 --bucket，表示要下载文件的存储空间名称，必需参数
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
# 添加命令行参数 --endpoint，表示其他服务可用来访问OSS的域名，非必需参数
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
# 添加命令行参数 --key，表示对象（文件）在OSS中的键名，必需参数
parser.add_argument('--key', help='The name of the object.', required=True)
# 添加命令行参数 --file_path，表示下载文件保存的本地路径，必需参数，例如“/Users/yourLocalPath/yourFileName”
parser.add_argument('--file_path', help='The path to save the downloaded file.', required=True)

def main():
    # 解析命令行提供的参数，获取用户输入的值
    args = parser.parse_args()

    # 从环境变量中加载访问OSS所需的认证信息，用于身份验证
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # 使用SDK的默认配置创建配置对象，并设置认证提供者
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    
    # 设置配置对象的区域属性，根据用户提供的命令行参数
    cfg.region = args.region

    # 如果提供了自定义endpoint，则更新配置对象中的endpoint属性
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # 使用上述配置初始化OSS客户端，准备与OSS交互
    client = oss.Client(cfg)

    # 创建一个用于下载文件的对象
    downloader = client.downloader()

    # 调用方法执行文件下载操作
    result = downloader.download_file(
        oss.GetObjectRequest(
            bucket=args.bucket,  # 指定目标存储空间
            key=args.key,        # 指定文件在OSS中的名称
        ),
        filepath=args.file_path  # 指定下载文件保存的本地路径
    )

    # 打印下载结果的相关信息，包括已写入的字节数
    print(f'written: {result.written}')

# 当此脚本被直接执行时，调用main函数开始处理逻辑
if __name__ == "__main__":
    main()  # 脚本入口点，控制程序流程从这里开始

常见使用场景

使用下载管理器设置分片大小和并发数

您可以使用以下代码配置下载管理器，设置分片大小和并发数。

import argparse
import alibabacloud_oss_v2 as oss

# 创建一个命令行参数解析器，并描述脚本用途：下载文件示例
parser = argparse.ArgumentParser(description="download file sample")

# 添加命令行参数 --region，表示存储空间所在的区域，必需参数
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# 添加命令行参数 --bucket，表示要下载文件的存储空间名称，必需参数
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
# 添加命令行参数 --endpoint，表示其他服务可用来访问OSS的域名，非必需参数
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
# 添加命令行参数 --key，表示对象（文件）在OSS中的键名，必需参数
parser.add_argument('--key', help='The name of the object.', required=True)
# 添加命令行参数 --file_path，表示下载文件保存的本地路径，必需参数，例如“/Users/yourLocalPath/yourFileName”
parser.add_argument('--file_path', help='The path to save the downloaded file.', required=True)

def main():
    # 解析命令行提供的参数，获取用户输入的值
    args = parser.parse_args()

    # 从环境变量中加载访问OSS所需的认证信息，用于身份验证
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # 使用SDK的默认配置创建配置对象，并设置认证提供者
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    
    # 设置配置对象的区域属性，根据用户提供的命令行参数
    cfg.region = args.region

    # 如果提供了自定义endpoint，则更新配置对象中的endpoint属性
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # 使用上述配置初始化OSS客户端，准备与OSS交互
    client = oss.Client(cfg)

    # 创建一个用于下载文件的对象，并设置高级选项
    downloader = client.downloader(
        part_size=1024 * 1024,  # 设置每个分片的大小为1MB
        parallel_num=5,         # 设置并行下载的线程数为5
        block_size=1024 * 1024  # 设置每次读取的数据块大小为1MB
    )

    # 调用方法执行文件下载操作
    result = downloader.download_file(
        oss.GetObjectRequest(
            bucket=args.bucket,  # 指定目标存储空间
            key=args.key,        # 指定文件在OSS中的名称
        ),
        filepath=args.file_path  # 指定下载文件保存的本地路径
    )

    # 打印下载结果的相关信息，包括已写入的字节数
    print(f'written: {result.written}')

# 当此脚本被直接执行时，调用main函数开始处理逻辑
if __name__ == "__main__":
    main()  # 脚本入口点，控制程序流程从这里开始

使用下载管理器启动断点续传功能

您可以使用以下代码配置下载管理器，启动断点续传功能。

import argparse
import alibabacloud_oss_v2 as oss

# 创建一个命令行参数解析器，并描述脚本用途：下载文件示例
parser = argparse.ArgumentParser(description="download file sample")

# 添加命令行参数 --region，表示存储空间所在的区域，必需参数
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# 添加命令行参数 --bucket，表示要下载文件的存储空间名称，必需参数
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
# 添加命令行参数 --endpoint，表示其他服务可用来访问OSS的域名，非必需参数
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
# 添加命令行参数 --key，表示对象（文件）在OSS中的键名，必需参数
parser.add_argument('--key', help='The name of the object.', required=True)
# 添加命令行参数 --file_path，表示下载文件保存的本地路径，必需参数，例如“/Users/yourLocalPath/yourFileName”
parser.add_argument('--file_path', help='The path to save the downloaded file.', required=True)

def main():
    # 解析命令行提供的参数，获取用户输入的值
    args = parser.parse_args()

    # 从环境变量中加载访问OSS所需的认证信息，用于身份验证
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # 使用SDK的默认配置创建配置对象，并设置认证提供者
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    
    # 设置配置对象的区域属性，根据用户提供的命令行参数
    cfg.region = args.region

    # 如果提供了自定义endpoint，则更新配置对象中的endpoint属性
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # 使用上述配置初始化OSS客户端，准备与OSS交互
    client = oss.Client(cfg)

    # 创建一个用于下载文件的对象，并设置高级选项
    downloader = client.downloader(
        use_temp_file=True,            # 使用临时文件
        enable_checkpoint=True,        # 启用断点续传
        checkpoint_dir=args.file_path, # 保存断点续传记录文件的目录
        verify_data=True               # 是否校验数据
    )

    # 调用方法执行文件下载操作
    result = downloader.download_file(
        oss.GetObjectRequest(
            bucket=args.bucket,  # 指定目标存储空间
            key=args.key,        # 指定文件在OSS中的名称
        ),
        filepath=args.file_path  # 指定下载文件保存的本地路径
    )

    # 打印下载结果的相关信息，包括已写入的字节数
    print(f'written: {result.written}')

# 当此脚本被直接执行时，调用main函数开始处理逻辑
if __name__ == "__main__":
    main()  # 脚本入口点，控制程序流程从这里开始

Python文件下载管理器