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

CompleteMultipartUpload

最近更新时间：2026-10-21 18:34:04
本文档已由 AI 辅助审校
我的收藏

本页目录：

CompleteMultipartUpload 接口请求实现完成整个分块上传。当使用 UploadPart 和 UploadPartCopy 上传所有分块完成后，必须调用本接口来完成最终对象的合并。在请求体中需提供每一个分块的 PartNumber 和 ETag，用于校验分块的完整性与顺序。

注意事项

分块顺序与完整性

请求体中的 <Part> 列表必须满足以下约束：
每个 <Part> 的 PartNumber 必须对应一个本次分块上传中实际已上传的分块；任一 PartNumber 不存在、或 ETag 与服务端已记录的不一致，将返回 InvalidPart。
列表必须按 PartNumber 升序排列且不允许重复，否则返回 InvalidPartOrder。
列表不能为空，否则返回 InvalidArgument。
PartNumber 不要求连续，可以跳号（例如只提交编号为1、3、5的分块）。未在列表中出现的已上传分块在合并时将被丢弃。

最小分块大小

除请求体中 PartNumber 最大的分块（即合并后对象的最后一块）以外，其余每个分块的大小不得小于1MiB，否则返回 EntityTooSmall。最后一块不受此限制，可以小于1MiB。

目标对象键

本接口要求 URL 路径中的 <ObjectKey> 与 InitiateMultipartUpload 调用时使用的对象键完全一致（包括大小写、路径层级与末尾 /），不一致时本接口返回 NoSuchUpload。

防覆盖与同名冲突

合并阶段会按文件对象语义写入目标对象键，与 PutObject 一致：
携带 x-cos-forbid-overwrite: true 且目标文件对象已存在时，返回 409 FileAlreadyExists。
目标对象键的同名目录对象已存在时，返回 409 DirAlreadyExists。
目标对象键中的中间路径组件已是文件对象（例如目标键为 a/b/c 且 a/b 已是文件对象）时，返回 409 FileAlreadyExists。

UploadId 有效性

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

请求

请求语法

POST /<ObjectKey>?uploadId=<UploadId> HTTP/1.1
Host: <BucketName-APPID>.cosrapid.<Region>.myqcloud.com
Date: <GMT Date>
Content-Type: application/xml
Content-Length: <Content Length>
Authorization: <Auth String>

<CompleteMultipartUpload>
    <Part>
        <PartNumber>integer</PartNumber>
        <ETag>string</ETag>
    </Part>
    ...
</CompleteMultipartUpload>
说明：
Authorization 字段的具体格式见 公共请求头部。

请求参数

参数名称
描述
类型
是否必选
uploadId
调用 InitiateMultipartUpload 接口初始化分块上传时返回的 UploadId
string
是

请求头部

除 公共请求头部 外，本接口还支持以下请求头部：
Header 名称
描述
类型
是否必选
x-cos-forbid-overwrite
是否禁止覆盖同名对象，取值为 true 时启用。行为契约详见「防覆盖与同名冲突」
string
否

请求体

提交 application/xml 请求数据，包含所有分块信息：
<CompleteMultipartUpload>
    <Part>
        <PartNumber>integer</PartNumber>
        <ETag>string</ETag>
    </Part>
    <Part>
        <PartNumber>integer</PartNumber>
        <ETag>string</ETag>
    </Part>
</CompleteMultipartUpload>
具体节点说明：
节点名称
父节点
描述
类型
是否必选
CompleteMultipartUpload
无
包含本次合并请求中所有分块的信息
Container
是
Part
CompleteMultipartUpload
单个分块的信息条目
Container
是
PartNumber
CompleteMultipartUpload.Part
分块编号，与上传该分块时使用的 partNumber 一致
integer
是
ETag
CompleteMultipartUpload.Part
分块的 ETag，取值为 UploadPart 或 UploadPartCopy 响应中返回的 ETag，使用双引号包裹
string
是

响应

响应头部

除 公共响应头部 外，本接口还会返回以下响应头部：
Header 名称
描述
类型
是否必返
ETag
合并后对象的 ETag，使用双引号包裹
string
是
Last-Modified
合并后对象的最后修改时间，格式为 RFC 1123 GMT，例如 Wed, 29 May 2019 04:10:12 GMT
string
是
x-cos-hash-crc64ecma
合并后对象的 CRC64-ECMA 校验值，十进制字符串
string
是
x-cos-storage-class
合并后对象的存储类型，固定为 RAPID
string
是

响应体

响应体为 application/xml 格式：
<?xml version="1.0" encoding="UTF-8"?>
<CompleteMultipartUploadResult>
    <Bucket>string</Bucket>
    <Key>string</Key>
    <ETag>string</ETag>
</CompleteMultipartUploadResult>
具体节点说明：
节点名称
父节点
描述
类型
CompleteMultipartUploadResult
无
保存 CompleteMultipartUpload 结果的所有信息
Container
Bucket
CompleteMultipartUploadResult
目标存储桶名称，形式为 <BucketName-APPID>
string
Key
CompleteMultipartUploadResult
目标对象键
string
ETag
CompleteMultipartUploadResult
合并后对象的 ETag，使用双引号包裹（XML 实体编码形式）
string

错误码

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

实际案例

案例一：完成一次分块上传

请求

POST /exampleobject?uploadId=1585130821cbb7df1d11846c073ad648e8f33b087cec2381df437acdc833cf654b9ecc6361 HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Wed, 29 May 2019 04:10:12 GMT
Content-Type: application/xml
Content-Length: 353
Authorization: q-sign-algorithm=sha1&q-ak=AKIDXXXXXXXX&q-sign-time=1559074212;1559077812&q-key-time=1559074212;1559077812&q-header-list=content-length;content-type;date;host&q-url-param-list=uploadid&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

<CompleteMultipartUpload>
    <Part>
        <PartNumber>1</PartNumber>
        <ETag>"39270a968a357d24207e9911162507eb"</ETag>
    </Part>
    <Part>
        <PartNumber>2</PartNumber>
        <ETag>"d899fbd1e06109ea2e4550f5751c88d6"</ETag>
    </Part>
    <Part>
        <PartNumber>3</PartNumber>
        <ETag>"762890d6c9a871b7bd136037cb2260cd"</ETag>
    </Part>
</CompleteMultipartUpload>

响应

HTTP/1.1 200 OK
Content-Type: application/xml
Connection: keep-alive
Date: Wed, 29 May 2019 04:10:12 GMT
ETag: "aa259a62513358f69e98e72e59856d88"
Last-Modified: Wed, 29 May 2019 04:10:12 GMT
x-cos-hash-crc64ecma: 2290339086971918696
x-cos-storage-class: RAPID
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAw

<?xml version="1.0" encoding="UTF-8"?>
<CompleteMultipartUploadResult>
<Bucket>examplebucket-x--1250000000</Bucket>
    <Key>exampleobject</Key>
    <ETag>&quot;aa259a62513358f69e98e72e59856d88&quot;</ETag>
</CompleteMultipartUploadResult>

案例二：使用 x-cos-forbid-overwrite 防覆盖

本案例在请求中携带 x-cos-forbid-overwrite: true，要求目标对象已存在时拒绝合并。

请求

POST /exampleobject?uploadId=1585130821cbb7df1d11846c073ad648e8f33b087cec2381df437acdc833cf654b9ecc6361 HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Wed, 29 May 2019 04:10:12 GMT
Content-Type: application/xml
Content-Length: 153
x-cos-forbid-overwrite: true
Authorization: q-sign-algorithm=sha1&q-ak=AKIDXXXXXXXX&q-sign-time=1559074212;1559077812&q-key-time=1559074212;1559077812&q-header-list=content-length;content-type;date;host;x-cos-forbid-overwrite&q-url-param-list=uploadid&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

<CompleteMultipartUpload>
    <Part>
        <PartNumber>1</PartNumber>
        <ETag>"108f528eb63b65e734f27ae331f5ffaa"</ETag>
    </Part>
</CompleteMultipartUpload>

响应

HTTP/1.1 409 Conflict
Content-Type: application/xml
Connection: keep-alive
Date: Wed, 29 May 2019 04:10:12 GMT
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAw

<?xml version='1.0' encoding='utf-8'?>
<Error>
    <Code>FileAlreadyExists</Code>
    <Message>File already exists.</Message>
<Resource>examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com/exampleobject</Resource>
    <RequestId>NjUwMDAwMDAwMDAwMDAwMDAw</RequestId>
    <TraceId></TraceId>
</Error>

中国站