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

本文针对大文件的传输场景，介绍如何使用Python SDK V2新增的Copier模块进行文件拷贝。

注意事项

本文示例代码以华东1（杭州）的地域IDcn-hangzhou为例，默认使用外网Endpoint，如果您希望通过与OSS同地域的其他阿里云产品访问OSS，请使用内网Endpoint。关于OSS支持的Region与Endpoint的对应关系，请参见OSS地域和访问域名。
要进行拷贝文件，您必须拥有源文件的读权限及目标Bucket的读写权限。
不支持跨地域拷贝。例如不能将华东1（杭州）地域存储空间中的文件拷贝到华北1（青岛）地域。
拷贝文件时，您需要确保源Bucket和目标Bucket均未设置合规保留策略，否则报错The object you specified is immutable.。

方法定义

拷贝管理器介绍

当需要将对象从存储空间复制到另外一个存储空间，或者修改对象的属性时，您可以通过拷贝接口或者分片拷贝接口来完成这个操作。这两个接口有其适用的场景，例如：

拷贝接口（CopyObject）只适合拷贝 5GiB 以下的对象；
分片拷贝接口（UploadPartCopy）支持拷贝大于5GiB 的对象，但不支持元数据指令（x-oss-metadata-directive）和标签指令（x-oss-tagging-directive）参数，拷贝时需要主动设置需要复制的元数据和标签。

Python SDK V2新增拷贝管理器Copier提供了通用的拷贝接口，隐藏了接口的差异和实现细节，可根据拷贝的请求参数自动选择合适的接口复制对象。Copier的常用方法定义如下：

copy(request: CopyObjectRequest, **kwargs: Any) → CopyResult

请求参数列表

参数名	类型	说明

参数名	类型	说明
request	CopyObjectRequest	设置具体接口的请求参数，具体请参见CopyObjectRequest

其中，CopyObjectRequest的常用参数列举如下：

参数名	类型	说明

参数名	类型	说明
bucket	str	指定目标存储空间名称
key	str	指定目标对象名称
source_bucket	str	指定源存储空间名称
source_key	str	指定源对象名称
forbid_overwrite	str	指定CopyObject操作时是否覆盖同名目标Object
tagging	str	指定Object的对象标签，可同时设置多个标签，例如TagA=A&TagB=B。
tagging_directive	str	指定如何设置目标Object的对象标签。取值如下： Copy（默认值）：复制源Object的对象标签到目标 Object。 Replace：忽略源Object的对象标签，直接采用请求中指定的对象标签。

Copy方法的常用参数列举如下：

参数名	类型	说明

参数名	类型	说明
part_size	int	指定分片大小，默认值为 64MiB
parallel_num	int	指定拷贝任务的并发数，默认值为 3。针对的是单次调用的并发限制，而不是全局的并发限制
multipart_copy_threshold	int64	使用分片拷贝的阈值，默认值为 200MiB
leave_parts_on_error	bool	当拷贝失败时，是否保留已拷贝的分片，默认不保留
disable_shallow_copy	bool	不使用浅拷贝行为，默认使用

返回值列表

返回值名	类型	说明

返回值名	类型	说明
result	CopyResult	接口返回值，当 err 为nil 时有效，具体请参见CopyResult

示例代码

您可以使用以下代码将对象从源存储空间拷贝到目标存储空间。

import argparse
import alibabacloud_oss_v2 as oss

# 创建命令行参数解析器
parser = argparse.ArgumentParser(description="copier sample")

# 添加命令行参数：region（必填），指定Bucket所在的地域
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)

# 添加命令行参数：bucket（必填），指定目标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（必填），指定目标对象的名称
parser.add_argument('--key', help='The name of the object.', required=True)

# 添加命令行参数：source_key（必填），指定源对象的名称
parser.add_argument('--source_key', help='The name of the source address for object.', required=True)

# 添加命令行参数：source_bucket（必填），指定源Bucket的名称
parser.add_argument('--source_bucket', help='The name of the source address for bucket.', required=True)


def main():
    # 解析命令行参数
    args = parser.parse_args()

    # 从环境变量中加载凭证信息
    # 使用EnvironmentVariableCredentialsProvider从环境变量中读取Access Key ID和Access Key Secret
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # 使用SDK的默认配置
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider  # 设置凭证提供者
    cfg.region = args.region  # 设置Bucket所在的地域
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint  # 如果提供了endpoint，则设置自定义访问域名

    # 创建OSS客户端实例
    client = oss.Client(cfg)

    # 创建Copier实例并执行对象复制操作
    copier = client.copier()

    # 执行对象复制操作
    result = copier.copy(
        oss.CopyObjectRequest(
            bucket=args.bucket,          # 目标Bucket名称
            key=args.key,                # 目标对象名称
            source_bucket=args.source_bucket,  # 源Bucket名称
            source_key=args.source_key   # 源对象名称
        )
    )

    # 打印复制结果
    # 使用vars(result)将结果对象转换为字典格式并打印
    print(vars(result))


if __name__ == "__main__":
    main()

常见使用场景

使用拷贝管理器设置分片大小和并发数

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

import argparse
import alibabacloud_oss_v2 as oss

# 创建命令行参数解析器
parser = argparse.ArgumentParser(description="copier sample")

# 添加命令行参数：region（必填），指定Bucket所在的地域
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)

# 添加命令行参数：bucket（必填），指定目标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（必填），指定目标对象的名称
parser.add_argument('--key', help='The name of the object.', required=True)

# 添加命令行参数：source_key（必填），指定源对象的名称
parser.add_argument('--source_key', help='The name of the source address for object.', required=True)

# 添加命令行参数：source_bucket（必填），指定源Bucket的名称
parser.add_argument('--source_bucket', help='The name of the source address for bucket.', required=True)


def main():
    # 解析命令行参数
    args = parser.parse_args()

    # 从环境变量中加载凭证信息
    # 使用EnvironmentVariableCredentialsProvider从环境变量中读取Access Key ID和Access Key Secret
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # 使用SDK的默认配置
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider  # 设置凭证提供者
    cfg.region = args.region  # 设置Bucket所在的地域
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint  # 如果提供了endpoint，则设置自定义访问域名

    # 创建OSS客户端实例
    client = oss.Client(cfg)

    # 创建Copier实例并执行对象复制操作
    copier = client.copier()

    # 执行对象复制操作
    result = copier.copy(
        oss.CopyObjectRequest(
            bucket=args.bucket,          # 目标Bucket名称
            key=args.key,                # 目标对象名称
            source_bucket=args.source_bucket,  # 源Bucket名称
            source_key=args.source_key   # 源对象名称
        ),
        part_size= 1 * 1024 * 1024,          # 分片大小，单位为字节（此处设置为1MiB）
        parallel_num=5,                 # 并发数，控制同时拷贝的分片数量
        leave_parts_on_error=True,      # 如果复制失败，保留已拷贝的分片
    )

    # 打印复制结果
    # 使用vars(result)将结果对象转换为字典格式并打印
    print(vars(result))


if __name__ == "__main__":
    main()

Python文件拷贝管理器