拷贝Object

更新时间：2026-09-23

BOS Python SDK 支持通过 copy_object 拷贝已有 Object；对于大文件，还提供了分块拷贝（Multipart Upload Copy）模式。

运行以下示例前，请先参考初始化完成 BOS Client 初始化，并将示例中的 bucket_name、key 替换为实际值。

简单拷贝

                Python
                
                bos_client.copy_object(source_bucket_name, source_key, target_bucket_name, target_key)

BOS 的 CopyObject 接口以同步方式实现，服务端会等待拷贝实际完成后才返回成功，便于用户准确判断拷贝状态。

注意：

单次同步拷贝的对象大小不能超过 5GB，超过时服务端返回 EntityTooLarge 错误，此时应改用分块拷贝。

若源 Object 为归档（ARCHIVE）类型，需先调用 restore_object 取回归档文件后才能拷贝。

拷贝时若传入 user_metadata 或 content_type，SDK 会自动将拷贝指令设为 replace（用新元信息覆盖）；否则为 copy。

拷贝时的条件判断

copy_object 可根据源 Object 的 ETag 或修改状态决定是否执行拷贝。其中 x-bce-copy-source-if-match 由独立的 etag 参数设置，其余三个条件 header 通过 copy_object_user_headers 传入：

名称	传入方式	说明
`x-bce-copy-source-if-match`	`etag` 参数	源 Object 的 ETag 与所给值一致时才拷贝，否则失败。
`x-bce-copy-source-if-none-match`	`copy_object_user_headers`	源 Object 的 ETag 与所给值不一致时才拷贝，否则失败。
`x-bce-copy-source-if-unmodified-since`	`copy_object_user_headers`	源 Object 在指定时间之后未被修改时才拷贝，否则失败。
`x-bce-copy-source-if-modified-since`	`copy_object_user_headers`	源 Object 在指定时间之后被修改过时才拷贝，否则失败。

注意： x-bce-copy-source-if-match 必须通过 etag 参数传入。SDK 仅将 x-bce-copy-source-if-none-match、x-bce-copy-source-if-unmodified-since、x-bce-copy-source-if-modified-since 三个 header 列入 copy_object_user_headers 的白名单，若把 x-bce-copy-source-if-match 放进 copy_object_user_headers，会被 SDK 静默丢弃而不生效。

                Python
                
            

                # 仅当源 Object 的 ETag 与所给值一致时才拷贝（if-match，通过 etag 参数）
bos_client.copy_object(
    source_bucket_name=bucket_name,
    source_key=source_key,
    target_bucket_name=bucket_name,
    target_key=target_key,
    etag="example-etag")

# 其余条件通过 copy_object_user_headers 传入
copy_object_user_headers = {
    "x-bce-copy-source-if-none-match": "another-etag",
    "x-bce-copy-source-if-unmodified-since": "Wed, 21 Jul 2020 07:23:48 GMT"
}
bos_client.copy_object(
    source_bucket_name=bucket_name,
    source_key=source_key,
    target_bucket_name=bucket_name,
    target_key=target_key,
    copy_object_user_headers=copy_object_user_headers)
            

分块拷贝

对于超过 5GB 的大文件，或需要断点拷贝、网络较差的场景，可使用分块拷贝。分块拷贝包含 init、拷贝分块、complete 三步，其中 init 和 complete 与分块上传一致，拷贝分块使用 upload_part_copy：

                Python
                
            

                import os

# 初始化分块上传，获取 upload_id
upload_id = bos_client.initiate_multipart_upload(target_bucket, target_key).upload_id

# 获取源 Object 大小
left_size = int(bos_client.get_object_meta_data(source_bucket, source_key).metadata.content_length)
offset = 0
part_number = 1
part_list = []

while left_size > 0:
    # 每块 5MB
    part_size = 5 * 1024 * 1024
    if left_size < part_size:
        part_size = left_size

    response = bos_client.upload_part_copy(
        source_bucket, source_key, target_bucket, target_key,
        upload_id, part_number, part_size, offset)

    left_size -= part_size
    offset += part_size
    part_list.append({
        "partNumber": part_number,
        "eTag": response.etag
    })
    part_number += 1

# 完成分块拷贝
bos_client.complete_multipart_upload(target_bucket, target_key, upload_id, part_list)
            

注意：

offset 以字节为单位，为分块的起始偏移位置；part_size 为每个分块的大小。

除最后一个分块外，其余每个分块的大小不得小于 100KB，否则完成分块拷贝时服务端返回 EntityTooSmall 错误。

若源 Object 为归档类型，需先取回归档文件。

恢复历史版本

对开启了版本控制的 Bucket，可将某个历史版本拷贝回同一 Bucket、同一 Key，从而生成一个内容等于该历史版本的新的当前版本：

                Python
                
            

                response = bos_client.copy_object(
    source_bucket_name=bucket_name,
    source_key=object_key,
    target_bucket_name=bucket_name,
    target_key=object_key,
    source_version_id=history_version_id)
            

方法说明

方法	返回值	说明
`bos_client.copy_object(source_bucket_name, source_key, target_bucket_name, target_key, ...)`	`BceResponse`	拷贝 Object，单次最大 5GB。
`bos_client.upload_part_copy(source_bucket, source_key, target_bucket, target_key, upload_id, part_number, part_size, offset, ...)`	`BceResponse`	分块拷贝中拷贝单个分块。

评价此篇文章

有帮助没帮助

获取及更新文件元信息

选取文件

百度智能云

BOS 对象存储