帮你快速理解、总结文档立即下载

上传分块

最近更新时间:2026-10-21 18:34:05
我的收藏
在初始化分块上传后上传单个分块(Upload Part)。每个分块由 PartNumber 标识(从 1 开始,支持乱序上传),上传成功后需从响应头读取该块的 ETag,并将 PartNumber 与 ETag 记录下来,供后续 Python SDK 完成分块上传 使用。对高性能桶发起请求时,SDK 自动完成会话鉴权。

注意事项

Key 与 UploadId 必须对应同一次初始化分块上传;Key 表示不以 / 结尾的文件对象,不能改成目录对象键。
上传成功后必须读取响应头中的 ETag,并连同 PartNumber 一起记录,Python SDK 完成分块上传 时需按此校验。
除最后一块外,每个分块建议不小于 1MB;分块过小在完成上传时可能返回 EntityTooSmall。
单个分块大小不得超过 5GB。
相同 UploadId 与 PartNumber 重复上传时,后上传的分块会覆盖先前的分块。
上传分块属于数据面接口,SDK 使用 session 临时凭证签名。

请求

方法原型

def upload_part(self, Bucket, Key, Body, PartNumber, UploadId, EnableMD5=False, **kwargs)

参数说明

参数名称
参数描述
类型
是否必选
Bucket
高性能桶完整名称,格式为 <BucketName>-x--<APPID>
string
是
Key
对象键(Object Key)
string
是
Body
待上传分块的内容,可为文件流或字节流
file / bytes
是
PartNumber
分块编号,从 1 开始,支持乱序上传
int
是
UploadId
初始化分块上传返回的 UploadId
string
是
EnableMD5
是否需要 SDK 计算 Content-MD5,打开会增加上传耗时
bool
否
kwargs
可选请求参数,使用本文列出的参数
dict
否

响应

返回值为响应头部字典:
参数名称
参数描述
类型
响应头 dict
成功时返回响应头部字典,可通过 ETag 键读取该分块的 ETag
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']

# 上传第1个分块,并记录 PartNumber 与 ETag。
part_number = 1
resp = client.upload_part(
Bucket=bucket,
Key=key,
Body=b'this is the content of part 1',
PartNumber=part_number,
UploadId=upload_id)
print('part %d uploaded, ETag: %s' % (part_number, resp['ETag']))