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

UploadPart

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

本页目录：

UploadPart 接口请求实现将对象按照分块的方式上传到指定存储桶。需先调用 InitiateMultipartUpload 接口获取 UploadId，再使用相同的对象键、UploadId 以及递增的 PartNumber 调用本接口上传各分块；分块上传完成后，调用 CompleteMultipartUpload 完成对象合并。

注意事项

分块编号

partNumber 必须为1到10000之间的整数（包含1和10000）。超出范围将返回 InvalidArgument。各分块允许乱序上传，最终对象内容按分块编号升序拼接。

单分块大小限制

单个分块的大小不能超过 5 GiB，超出时返回 EntityTooLarge。除最后一个分块外，其余分块在调用 CompleteMultipartUpload 时还需满足最小分块大小限制，详见 CompleteMultipartUpload。

分块覆盖

若使用相同的 UploadId 和 PartNumber 重复上传，后到达的请求将覆盖之前已上传的同编号分块。

UploadId 有效性

UploadId 不存在、已被 AbortMultipartUpload 终止、或已被 CompleteMultipartUpload 完成时，本接口返回 NoSuchUpload。

请求

请求语法

PUT /<ObjectKey>?partNumber=<PartNumber>&uploadId=<UploadId> HTTP/1.1
Host: <BucketName-APPID>.cosrapid.<Region>.myqcloud.com
Date: <GMT Date>
Content-Length: <Content Length>
Content-MD5: <MD5>
Authorization: <Auth String>

[Object Part]
说明：
Authorization 字段的具体格式见 公共请求头部。

请求参数

参数名称
描述
类型
是否必选
partNumber
标识本次分块上传的编号，取值范围为 1 到 10000（包含两端）
integer
是
uploadId
调用 InitiateMultipartUpload 接口初始化分块上传时返回的 UploadId
string
是

请求头部

除 公共请求头部 外，本接口还支持以下请求头部：
Header 名称
描述
类型
是否必选
Content-Length
RFC 2616 中定义的 HTTP 请求内容长度（字节）。未指定 Transfer-Encoding: chunked 时必须携带
string
否
Content-MD5
RFC 2616 中定义的请求内容 MD5 摘要的 Base64 编码值。携带时服务端会校验，不一致返回 BadDigest
string
否
Transfer-Encoding
RFC 2616 中定义的传输编码格式。如果希望以分块方式传输请求体，则指定 Transfer-Encoding: chunked，并不再指定 Content-Length
string
否

请求体

该请求的请求体（Body）为本次上传分块的原始字节流。

响应

响应头部

除 公共响应头部 外，本接口还会返回以下响应头部：
Header 名称
描述
类型
是否必返
ETag
本分块的 MD5 校验值，使用双引号包裹。该值需要在调用 CompleteMultipartUpload 时作为对应分块的 ETag 一并提交
string
是
Last-Modified
本分块最近一次被上传的时间，格式为 RFC 1123 GMT，例如 Wed, 29 May 2019 04:10:12 GMT
string
是
x-cos-hash-crc64ecma
本分块的 CRC64-ECMA 校验值，十进制字符串
string
否

响应体

该接口的响应体为空。

错误码

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

实际案例

案例一：上传一个分块

请求

PUT /exampleobject?partNumber=1&uploadId=1585130821cbb7df1d11846c073ad648e8f33b087cec2381df437acdc833cf654b9ecc6361 HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Wed, 25 Mar 2020 10:07:14 GMT
Content-Type: application/octet-stream
Content-Length: 1048576
Content-MD5: OScKloo1fSQgfpkRFiUH6w==
Authorization: q-sign-algorithm=sha1&q-ak=AKIDXXXXXXXX&q-sign-time=1585130834;1585138034&q-key-time=1585130834;1585138034&q-header-list=content-length;content-md5;content-type;date;host&q-url-param-list=partnumber;uploadid&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

[Object Part]

响应

HTTP/1.1 200 OK
Content-Length: 0
Connection: keep-alive
Date: Wed, 25 Mar 2020 10:07:14 GMT
ETag: "39270a968a357d24207e9911162507eb"
Last-Modified: Wed, 25 Mar 2020 10:07:14 GMT
x-cos-hash-crc64ecma: 9973912126177188060
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAw

案例二：使用 chunked 传输编码上传分块

本案例请求中使用 Transfer-Encoding: chunked 编码，案例描述的是 HTTP 请求中的原始数据，在使用过程中根据不同语言和库将有不同的调用方法，请开发者查阅语言和库的相关文档。

请求

PUT /exampleobject?partNumber=2&uploadId=1585130821cbb7df1d11846c073ad648e8f33b087cec2381df437acdc833cf654b9ecc6361 HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Wed, 25 Mar 2020 10:08:01 GMT
Content-Type: application/octet-stream
Transfer-Encoding: chunked
Authorization: q-sign-algorithm=sha1&q-ak=AKIDXXXXXXXX&q-sign-time=1585130881;1585138081&q-key-time=1585130881;1585138081&q-header-list=content-type;date;host;transfer-encoding&q-url-param-list=partnumber;uploadid&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

100000
[Chunked Part Content]
0

响应

HTTP/1.1 200 OK
Content-Length: 0
Connection: keep-alive
Date: Wed, 25 Mar 2020 10:08:01 GMT
ETag: "aa488bb80185a6be87f4a7b936a80752"
Last-Modified: Wed, 25 Mar 2020 10:08:01 GMT
x-cos-hash-crc64ecma: 7188322482464764960
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAw

中国站