帮你快速理解、总结文档立即下载
文档中心>对象存储>高性能存储>SDK 文档>Python SDK>分块上传操作>复制分块

复制分块

最近更新时间：2026-10-21 18:34:05
我的收藏

本页目录：

将已有对象（或其指定字节范围）作为一个分块复制到当前分块上传中（Upload Part - Copy），常用于大对象的分块复制、拼接场景。与 Python SDK 上传分块 类似，每个分块由 PartNumber 标识，复制成功后需记录返回的 ETag，供 Python SDK 完成分块上传 使用。对高性能桶发起请求时，SDK 自动完成会话鉴权。

注意事项

复制源必须为文件对象，源键末尾的 / 不做容错；以 / 结尾的源键返回 400 InvalidCopySource。不带 / 的源键若实际对应同名目录，返回 404 NoSuchKey。
Key 与 UploadId 必须对应同一次初始化分块上传；Key 表示不以 / 结尾的文件对象，不能改成目录对象键。
高性能桶仅支持同桶复制，复制源与目标必须位于同一个高性能桶，SDK 会在请求前本地校验。
高性能桶不支持对象版本，CopySource 中传入 VersionId 会本地报错。
通过 CopySourceRange 可只复制源对象的指定字节范围，实现大对象的分段复制拼接。
复制成功返回的 ETag 需连同 PartNumber 一起记录，Python SDK 完成分块上传 时需按此校验。
相同 UploadId 与 PartNumber 重复复制时，后复制的分块会覆盖先前的分块。
复制分块属于数据面接口，SDK 使用 session 临时凭证签名。

请求

方法原型

def upload_part_copy(self, Bucket, Key, PartNumber, UploadId, CopySource,
                     CopySourceRange='', **kwargs)

参数说明

参数名称
参数描述
类型
是否必选
Bucket
目标高性能桶完整名称，格式为 <BucketName>-x--<APPID>
string
是
Key
目标对象键（Object Key）
string
是
PartNumber
分块编号，从1开始
int
是
UploadId
初始化分块上传返回的 UploadId
string
是
CopySource
复制源信息，dict 类型，含 Bucket、Key、Region 等字段；须与目标为同一个桶
dict
是
CopySourceRange
复制源的字节范围，格式为 bytes=<start>-<end>，如 bytes=0-1048575
string
否
kwargs
可选请求参数，使用本文列出的参数
dict
否

响应

返回值为字典：
参数名称
参数描述
类型
ETag
复制生成分块的 ETag，需记录供完成分块上传使用
string
LastModified
分块的最后修改时间
string
响应头 dict
同时包含响应头部字段
dict

错误码

本接口遵循统一的错误响应和错误码，详情请参见 错误码文档。

实际案例

# -*- coding=utf-8 -*-
import os
from qcloud_cos import CosConfig, CosS3Client

# 高性能桶经 VPC 内网 HTTP 80 端口接入，SDK 的网关 DNS 负载均衡也仅对 HTTP 请求生效；SDK 默认 https，此处需显式指定 http。
config = CosConfig(
    Scheme='http',
    Region='ap-guangzhou',
    SecretId=os.environ['COS_SECRET_ID'],
    SecretKey=os.environ['COS_SECRET_KEY'],
    Token=os.environ.get('COS_SECURITY_TOKEN'),
    EnableRapidDomain=True)
client = CosS3Client(config)

bucket = 'examplebucket-x--1250000000'
key = 'exampleobject.txt'

# 初始化分块上传，取得 UploadId。
init_resp = client.create_multipart_upload(Bucket=bucket, Key=key)
upload_id = init_resp['UploadId']

# 复制源对象的前 1MB 作为第1个分块。
resp = client.upload_part_copy(
    Bucket=bucket,
    Key=key,
    PartNumber=1,
    UploadId=upload_id,
    CopySource={'Bucket': bucket, 'Key': 'srckey', 'Region': 'ap-guangzhou'},
    CopySourceRange='bytes=0-1048575')
print('part 1 copied, ETag: %s' % resp['ETag'])

中国站