tencent cloud

APIs

DocumentaçãoAPIsCloud Object StorageObject APIsMultipart UploadComplete Multipart Upload

Complete Multipart Upload

Baixar
Modo Foco
Tamanho da Fonte
Última atualização: 2026-06-05 17:28:40

Feature Description

The Complete Multipart Upload API request is used to finalize the entire multipart upload. After uploading all parts using the Upload Part API, you must call this API to complete the multipart upload of the entire file. When using this API, you must provide the PartNumber and ETag for each part in the request body to verify the accuracy of the parts.
Because multipart uploads require merging after completion, and the merge process takes several minutes, COS immediately returns a 200 status code and specifies the Transfer-Encoding: chunked response header when the merge begins. During the merge, COS periodically returns whitespace information using the chunked method to keep the connection alive. Once the merge is complete, COS returns the information of the entire object after merging in the final chunk.
When the uploaded part numbers are not consecutive, calling this API will return 400 InvalidPart.
When the part information in the request body is not arranged in ascending order by sequence number, calling this API will return 400 InvalidPartOrder.
When the UploadId does not exist, calling this API will return 404 NoSuchUpload.
Note:
Only the root account or a sub-account that has been granted permission for the Complete Multipart Upload API can call this API.
It is recommended to complete multipart uploads promptly or abort multipart uploads because being uploaded but unterminated parts will occupy storage space and incur storage fees.


Authorization Description

Set the action in the authorization policy to cos:CompleteMultipartUpload. View all actions.

Versioning

If versioning is enabled for a bucket, COS automatically generates a unique version ID for the object to be added. COS returns this identifier in the response using the x-cos-version-id response header.
If versioning for a bucket is suspended, COS always uses null as the version ID for objects stored in the bucket and returns the x-cos-version-id: null response header.

Request

Request Example

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

[Request Body]
Note:
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com. Here, <BucketName-APPID> is the bucket name with the APPID suffix, for example, examplebucket-1250000000. For details, see Bucket Overview > Basic Information and Bucket Overview > Bucket Naming Conventions. <Region> is the available region of COS. For details, see Regions and Access Domains.
Authorization: Auth String (For details, see Request Signature).

Request Parameter

Name
Description
Type
Required
uploadId
Identifies the ID for this multipart upload. It is the UploadId obtained when the multipart upload is initialized using the Initiate Multipart Upload API.
string
Yes

Request Header

In addition to using common request headers, this API also supports the following request headers. For details about common request headers, see Common Request Headers.
Name
Description
Type
Required
x-cos-forbid-overwrite
For buckets with versioning disabled, specifies whether to forbid overwriting objects with the same name during upload operations.
When the x-cos-forbid-overwrite header is not carried or is specified as false, the Object with the same name is overwritten by default.
When x-cos-forbid-overwrite is specified as true, it indicates that overwriting the Object with the same name is forbidden.
Note:
When versioning for a bucket is enabled, the x-cos-forbid-overwrite setting is ineffective, meaning overwriting objects with the same name is allowed.
String
No
x-cos-pnum-max
Limits the maximum number of upload parts. If the number of parts exceeds the limit, the request is rejected.
Note:
Used together with the Upload Part API's x-cos-psize-max header (which limits the maximum value of a part size), it can restrict the maximum size of a file for multipart upload.
Integer
No
x-cos-pnum-min
Limits the minimum number of upload parts. If the number of parts is less than this value, the request is rejected.
Note:
Used together with the Upload Part API's x-cos-psize-min header (which limits the minimum value of a part size), it can restrict the minimum size of a file for multipart upload.
Integer
No

Request Body

Submit application/xml request data that contains all part information.
<CompleteMultipartUpload>
    <Part>
        <PartNumber>integer</PartNumber>
        <ETag>string</ETag>
    </Part>
    <Part>
        <PartNumber>integer</PartNumber>
        <ETag>string</ETag>
    </Part>
</CompleteMultipartUpload>
The detailed node descriptions are as follows:
Node Name (Keyword)
Parent Node
Description
Type
Required
CompleteMultipartUpload
None
Contains all request information for the Complete Multipart Upload operation.
Container
Yes
Container node CompleteMultipartUpload:
Node Name (Keyword)
Parent Node
Description
Type
Required
Part
CompleteMultipartUpload
Describes the information of each part in this multipart upload.
Container
Yes
Container node Part:
Node Name (Keyword)
Parent Node
Description
Type
Required
PartNumber
CompleteMultipartUpload.Part
Part number. You can call the List Parts API to query the part numbers of uploaded parts.
integer
Yes
ETag
CompleteMultipartUpload.Part
The value of the ETag response header returned by COS after a successful Upload Part request. You can call the List Parts API to query the ETag value of uploaded parts.
string
Yes

Response

Response Headers

In addition to common response headers, this API returns the following response headers. For details about common response headers, see Common Response Headers.
Versioning-related headers
The following table describes the response headers returned when objects are uploaded to a versioning-enabled bucket.
Name
Description
Type
x-cos-version-id
Version ID of an object.
string
SSE-related headers
If SSE is used during object upload, this API returns headers used specifically for SSE. For details, see Server-Side Encryption Custom Header.

Response Body

Upon a successful request, application/xml data is returned, which contains the complete information of the merged object.
<?xml version="1.0" encoding="UTF-8"?>
<CompleteMultipartUploadResult>
    <Location>string</Location>
    <Bucket>string</Bucket>
    <Key>string</Key>
    <ETag>string</ETag>
</CompleteMultipartUploadResult>
The detailed node descriptions are as follows:
Node Name (Keyword)
Parent Node
Description
Type
CompleteMultipartUploadResult
None
Saves all information of the Complete Multipart Upload result.
Container
Container node CompleteMultipartUploadResult:
Node Name (Keyword)
Parent Node
Description
Type
Location
CompleteMultipartUploadResult
The location of the object after a multipart upload is in the format http://<BucketName-APPID>.cos.<Region>.myqcloud.com/<ObjectKey>, for example, http://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject.
string
Bucket
CompleteMultipartUploadResult
The target bucket for a multipart upload is in the format <BucketName-APPID>, for example, examplebucket-1250000000.
string
Key
CompleteMultipartUploadResult
Object Key
string
ETag
CompleteMultipartUploadResult
ETag of the object after multipart merge
string

Error Codes

This API follows unified error responses and error codes. For details, see Error Codes.

Practical Case

By default, responses from this API use the Transfer-Encoding: chunked encoding. For readability, the examples in this documentation are presented without Transfer-Encoding. During usage, different languages and libraries can automatically handle this encoding format. Developers should be aware of this and handle it accordingly. For more information, refer to the relevant documentation for your language and library.

Case 1: Simple Case (Version Control Not Enabled)

Request

POST /exampleobject?uploadId=1585130821cbb7df1d11846c073ad648e8f33b087cec2381df437acdc833cf654b9ecc6361 HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Wed, 25 Mar 2020 10:07:26 GMT
Content-Type: application/xml
Content-Length: 353
Content-MD5: Me/0Gvtc2x4VPIOhoIRllw==
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1585130846;1585138046&q-key-time=1585130846;1585138046&q-header-list=content-length;content-md5;content-type;date;host&q-url-param-list=uploadid&q-signature=************************************
Connection: close

<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>

Response

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 378
Connection: close
Date: Wed, 25 Mar 2020 10:07:26 GMT
Server: tencent-cos
x-cos-hash-crc64ecma: 2290339086971918696
x-cos-request-id: NWU3YjJkNWVfZDFjODJhMDlfMTk2ODJfMmEyNTA0****

<?xml version="1.0" encoding="UTF-8"?>
<CompleteMultipartUploadResult>
    <Location>http://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject</Location>
    <Bucket>examplebucket-1250000000</Bucket>
    <Key>exampleobject</Key>
    <ETag>&quot;aa259a62513358f69e98e72e59856d88-3&quot;</ETag>
</CompleteMultipartUploadResult>

Example Two: Using Server-Side Encryption (SSE-COS)

Request

POST /exampleobject?uploadId=1590862540251355295a5c736513d70d42b92bbde4f0fafb5e0ecb314b55aa0018cc9fa76f HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Sat, 30 May 2020 18:16:08 GMT
Content-Type: application/xml
Content-Length: 153
Content-MD5: wmpyfdr9s/A+VCBwDdC1bA==
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1590862568;1590869768&q-key-time=1590862568;1590869768&q-header-list=content-length;content-md5;content-type;date;host&q-url-param-list=uploadid&q-signature=****************************************
Connection: close

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

Response

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 378
Connection: close
Date: Sat, 30 May 2020 18:16:08 GMT
Server: tencent-cos
x-cos-hash-crc64ecma: 4510578591875220731
x-cos-request-id: NWVkMmEyZThfYTJjMjJhMDlfMmQzOV8zYTM5****
x-cos-server-side-encryption: AES256

<?xml version="1.0" encoding="UTF-8"?>
<CompleteMultipartUploadResult>
    <Location>http://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject</Location>
    <Bucket>examplebucket-1250000000</Bucket>
    <Key>exampleobject</Key>
    <ETag>&quot;915fca1c3b2737c262458b3a1a43c683-1&quot;</ETag>
</CompleteMultipartUploadResult>

Example Three: Using Server-Side Encryption (SSE-KMS)

Request

POST /exampleobject?uploadId=15908625793957d71176fa878282d266a95b79dc2aec159b4a73d1d79c80d4f931cda6ad65 HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Sat, 30 May 2020 18:16:40 GMT
Content-Type: application/xml
Content-Length: 153
Content-MD5: jUFgTSZThmPT3qseea0mRQ==
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1590862600;1590869800&q-key-time=1590862600;1590869800&q-header-list=content-length;content-md5;content-type;date;host&q-url-param-list=uploadid&q-signature=****************************************
Connection: close

<CompleteMultipartUpload>
    <Part>
        <PartNumber>1</PartNumber>
        <ETag>"1d3e8ae9da423b440341b09f1616f074"</ETag>
    </Part>
</CompleteMultipartUpload>

Response

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 378
Connection: close
Date: Sat, 30 May 2020 18:16:40 GMT
Server: tencent-cos
x-cos-hash-crc64ecma: 4510578591875220731
x-cos-request-id: NWVkMmEzMDhfYzhjODJhMDlfMjNhYTBfMjdmNjNl****
x-cos-server-side-encryption: cos/kms
x-cos-server-side-encryption-cos-kms-key-id: 48ba38aa-26c5-11ea-855c-52540085****

<?xml version="1.0" encoding="UTF-8"?>
<CompleteMultipartUploadResult>
    <Location>http://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject</Location>
    <Bucket>examplebucket-1250000000</Bucket>
    <Key>exampleobject</Key>
    <ETag>&quot;8093dc3e18f7070444e6ca21789eb8d4-1&quot;</ETag>
</CompleteMultipartUploadResult>


Example Four: Using Server-Side Encryption (SSE-C)

Request

POST /exampleobject?uploadId=1590862610acd643927bad05cd3947bf98b56b04b0b0b2a45a49969f87cc95b7fd5fcc065a HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Sat, 30 May 2020 18:17:11 GMT
Content-Type: application/xml
Content-Length: 153
Content-MD5: MnXmb3yvrbwMfBlUwUE1Hg==
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1590862631;1590869831&q-key-time=1590862631;1590869831&q-header-list=content-length;content-md5;content-type;date;host&q-url-param-list=uploadid&q-signature=****************************************
Connection: close

<CompleteMultipartUpload>
    <Part>
        <PartNumber>1</PartNumber>
        <ETag>"ff14981a35a58eb97bca838b055c573b"</ETag>
    </Part>
</CompleteMultipartUpload>

Response

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 378
Connection: close
Date: Sat, 30 May 2020 18:17:11 GMT
Server: tencent-cos
x-cos-hash-crc64ecma: 4510578591875220731
x-cos-request-id: NWVkMmEzMjdfODljOTJhMDlfMzQ2ZDNfMWMwZWYy****
x-cos-server-side-encryption-customer-algorithm: AES256
x-cos-server-side-encryption-customer-key-MD5: U5L61r7jcwdNvT7frmUG8g==

<?xml version="1.0" encoding="UTF-8"?>
<CompleteMultipartUploadResult>
    <Location>http://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject</Location>
    <Bucket>examplebucket-1250000000</Bucket>
    <Key>exampleobject</Key>
    <ETag>&quot;55973f71e8e892273053617e6b83d1c7-1&quot;</ETag>
</CompleteMultipartUploadResult>

Example Five: Enabling Versioning

Request

POST /exampleobject?uploadId=15908626631e1995018f81a5e563837d6d7f1b51d7c97dff09989296403e32366e52f2877b HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Sat, 30 May 2020 18:18:04 GMT
Content-Type: application/xml
Content-Length: 153
Content-MD5: wmpyfdr9s/A+VCBwDdC1bA==
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1590862684;1590869884&q-key-time=1590862684;1590869884&q-header-list=content-length;content-md5;content-type;date;host&q-url-param-list=uploadid&q-signature=****************************************
Connection: close

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

Response

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 378
Connection: close
Date: Sat, 30 May 2020 18:18:04 GMT
Server: tencent-cos
x-cos-hash-crc64ecma: 4510578591875220731
x-cos-request-id: NWVkMmEzNWNfOGNjOTJhMDlfMWQ4NjJfMWM0NGUw****
x-cos-version-id: MTg0NDUxNTMyMTEwNDU1NDc3OTc

<?xml version="1.0" encoding="UTF-8"?>
<CompleteMultipartUploadResult>
    <Location>http://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject</Location>
    <Bucket>examplebucket-1250000000</Bucket>
    <Key>exampleobject</Key>
    <ETag>&quot;42318fc0ec58952b0d9ab4d7a006f595-1&quot;</ETag>
</CompleteMultipartUploadResult>

Example Six: Suspending Versioning

Request

POST /exampleobject?uploadId=1590862705b4349d597c0db1281e1c666bc431eb468b3a64076be7093c91a963bc5ead2ea4 HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Sat, 30 May 2020 18:18:45 GMT
Content-Type: application/xml
Content-Length: 153
Content-MD5: wmpyfdr9s/A+VCBwDdC1bA==
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1590862725;1590869925&q-key-time=1590862725;1590869925&q-header-list=content-length;content-md5;content-type;date;host&q-url-param-list=uploadid&q-signature=****************************************
Connection: close

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

Response

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 378
Connection: close
Date: Sat, 30 May 2020 18:18:45 GMT
Server: tencent-cos
x-cos-hash-crc64ecma: 4510578591875220731
x-cos-request-id: NWVkMmEzODVfZjZjMjBiMDlfNGYzZV8zODc4****
x-cos-version-id: null

<?xml version="1.0" encoding="UTF-8"?>
<CompleteMultipartUploadResult>
    <Location>http://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject</Location>
    <Bucket>examplebucket-1250000000</Bucket>
    <Key>exampleobject</Key>
    <ETag>&quot;491509b1fdf8e13d1f51d323c4a6d0e8-1&quot;</ETag>
</CompleteMultipartUploadResult>
Anterior: Upload Part - CopyPróximo: Abort Multipart Upload

Ajuda e Suporte

Esta página foi útil?

comentários