文档中心

对象存储

分片上传

CompleteMultipartUpload

CompleteMultipartUpload

功能描述

该接口用于合并已经上传的分片数据。在调用该接口时，必须提供有效的分片列表（包含PartNumber和ETag），TOS 服务端收到请求后，会根据提供的分片列表来合并分片为一个对象。

使用说明

同一个对象可以初始化多次，拥有多个UploadId，当一个UploadId合并成功之后会被删除，其他未合并的UploadId不受影响。

PartNumber的取值有效范围 [1,10000]，合并时会进行校验，所有的上传分片都必须参与合并。

合并完成之后的分片数据会对应到一个对象，此对象与普通对象一样，可以调用删除对象接口删除，删除之后不可恢复。

请求消息样式

请求参数和消息头

该请求使用公共请求消息头，请参见公共参数。

名称	位置	参数类型	是否必选	示例值	说明
uploadId	Query	String	是	f93f6fc9da94371f321e****	指定分片上传任务，可通过 InitiateMultipartUpload 接口获取。
x-tos-forbid-overwrite	Header	String	否	false	是否允许覆盖同名 Object，取值说明如下：不指定或者指定为 false ：表示允许覆盖同名 Object。指定为 true 时：表示禁止覆盖同名 Object。警告当目标 Bucket 处于已开启或已暂停的版本控制状态时，x-tos-forbid-overwrite 参数设置无效，即允许覆盖同名 Object。
if-match	Header	String	否	d41d8cd98f00b204e9800998ecf8427e	控制上传行为的 ETag 条件，只有当指定的 ETag 与存储桶中已有对象的 ETag 匹配时，才会上传对象。若指定的 ETag 不存在或不匹配，则上传对象会失败，并返回 412 状态码。如果不传此参数，则默认不进行 ETag 校验。
if-none-match	Header	String	否	d41d8cd98f00b204e9800998ecf8427e	控制上传行为的 ETag 条件，只有当指定的 ETag 与存储桶中已有对象的 ETag 不匹配时，才会上传对象。若存储桶中已有对象的 ETag 匹配指定的 ETag，则上传对象会失败，并返回 412 状态码。如果不传此参数，则默认不进行 ETag 校验。说明 if-none-match 支持设置为 *，表示只要目标存储桶中存在同名对象（无论其 ETag 是什么），上传就会失败，并返回 412 状态码。

请求元素

该请求中的请求元素，携带了合并时需要的分片列表。

名称	参数类型	示例值	说明
Parts	Array	/-	已上传的分片信息。
PartNumber	Integer	1	已上传的分片号。父节点为 Parts。
ETag	String	00b8d61d63ca2bbc2b535917e40ef478-1	分片上传成功返回的 ETag 值。父节点为 Parts。

响应消息头

该请求返回的公共响应消息头，请参见公共参数。

名称	参数类型	示例值	说明
x-tos-server-side-encryption	String	AES256	对象是 SSE-TOS 加密或 SSE-KMS 时返回该头域，该头域表示对象的服务端加密方式，取值如下： AES256：使用 SSE-TOS 加密方式，并采用 AES256 加密算法。 SM4：使用 SSE-TOS 加密方式，并采用 SM4 加密算法。 kms: 使用 SSE-KMS 加密方式。关于 SSE-TOS、 SSE-KMS 加密方式详细说明，请参见服务端加密概述。
x-tos-server-side-encryption-kms-key-id	String	trn:kms:cn-beijing:20000111:keyrings/ring-test/keys/key-test	对象采用 SSE-KMS 加密方式时返回该头域，该头域表示 SSE-KMS 加密使用的 KMS 主密钥 ID。
x-tos-version-id	String	57AF1A32CECB56721267	合并后返回对象的版本号。如果不存在版本号，则该消息头不会出现在响应消息中。
x-tos-hash-crc64ecma	Integer	6186290338114851376	表示该对象的 64 位 CRC 值。该 64 位 CRC 根据 ECMA-182 标准计算得出。说明当上传对象使用服务端加密时，该值为对象明文内容的 CRC64 校验值。

响应元素

名称	参数类型	示例值	说明
Location	String	http://bucketName.tos-cn-beijing.volces.com/objectName	新创建对象的带域名的 URL。
Bucket	String	bucketName	桶名。
Key	String	objectName	合并得到的对象名。
ETag	String	00b8d61d63ca2bbc2b535917e40ef478	对象生成时创建的 ETag，用于唯一标识对象内容。

请求示例

响应示例

最近更新时间：2026.10.21 16:29:33

这个页面对您有帮助吗？

有用

有用

无用

无用