Call CompleteMultipartUpload to complete multipart upload - Object Storage Service

After uploading all data parts, you must invoke the CompleteMultipartUpload operation to finalize the multipart upload process for the file.

Notes

To invoke the CompleteMultipartUpload operation, you must provide a list of all valid parts, including their PartNumber and ETag. OSS verifies each part's validity sequentially upon receiving your submitted list. Once all parts are verified, OSS merges them into a single complete object.

Verify the size of each part

During the CompleteMultipartUpload call, OSS checks that each part, except the last, is at least 100 KB. It also verifies the PartNumber and ETag for each part in your submitted list. Therefore, you should record the part number and the ETag value returned by the server after each successful upload.
Manage requests

Processing a CompleteMultipartUpload request by OSS may take some time. If the client-OSS connection is interrupted during this period, OSS will continue to process the request.
PartNumber

The server checks the PartNumber during the CompleteMultipartUpload operation.

PartNumber values range from 1 to 10,000. The part numbers in your request should be in ascending order, though they need not be consecutive. For instance, the first part could be numbered 1 and the second part 5.
UploadId

An object can be uploaded in multiple tasks, each with a unique upload ID. When a task is completed, its upload ID is invalidated, but this does not affect the upload IDs of other tasks.
x-oss-server-side-encryption request header

If you specify the x-oss-server-side-encryption header in an InitiateMultipartUpload request, OSS returns this header in the CompleteMultipartUpload response. The header's value in the response indicates the encryption method used on the OSS server.

Version control

If versioning is enabled, invoking the CompleteMultipartUpload operation assigns a unique version ID to the file, which OSS returns in the response header as x-oss-version-id.

Request syntax

POST /ObjectName?uploadId=UploadId HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Content-Length: Size
Authorization: Signature
<CompleteMultipartUpload>
<Part>
<PartNumber>PartNumber</PartNumber>
<ETag>ETag</ETag>
</Part>
...
</CompleteMultipartUpload>

Request parameters

When invoking the CompleteMultipartUpload operation, you can encode the key in the result using the Encoding-type parameter.

Name

Type

Description

encoding-type

String

Specifies the encoding type of the returned key. Only URL encoding is supported.

The key can contain characters that are encoded in UTF-8. However, the XML 1.0 standard cannot be used to parse control characters, such as characters with an ASCII value from 0 to 10. If the key contains control characters that are not supported by the XML 1.0 standard, you can specify Encoding-type to encode the returned key.

Default value: none

Valid value: url

Request headers

Name	Type	Required	Description
x-oss-forbid-overwrite	String	No	Specifies whether to overwrite an existing object with the same name when you call the CompleteMultipartUpload operation. If you do not specify x-oss-forbid-overwrite or specify x-oss-forbid-overwrite as false, the object with the same name is overwritten. If you specify x-oss-forbid-overwrite as true, the object with the same name is not overwritten. Note If versioning is enabled or suspended for the destination bucket, the x-oss-forbid-overwrite request header is invalid. In this case, the object with the same name is overwritten. If you specify the x-oss-forbid-overwrite request header, the queries per second (QPS) performance of OSS may degrade. If you want to configure the x-oss-forbid-overwrite header in many requests (more than 1,000 QPS), submit a ticket to contact us to confirm the configuration to avoid affecting your business.
x-oss-complete-all	String	No	Specifies whether to list all parts that are uploaded by using the current upload ID. Valid value: yes If you specify x-oss-complete-all and set its value to yes, OSS lists all parts that are uploaded by using the current upload ID, sorts the parts by part number, and then performs the CompleteMultipartUpload operation. During the CompleteMultipartUpload operation, OSS cannot detect parts that are being uploaded or missing. Therefore, you must ensure the integrity of the parts. If you specify x-oss-complete-all, you cannot specify the request body. Otherwise, an error occurs. If you specify x-oss-complete-all, the format of the response remains unchanged.
x-oss-object-acl	String	No	Specifies the access control list (ACL) of the object when OSS creates the object. Valid values: default (default): The object inherits the ACL of the bucket to which the object belongs. private: The object is private. Only the owner of the object and authorized users have read and write permissions on the object. Other users do not have permissions on the object. public-read: The object is public read. Only the owner of the object and authorized users have read and write permissions on the object. Other users can only read the object. Exercise caution when you use this permission. public-read-write: The object is public read/write. All users have read and write permissions on the object. Exercise caution when you use this permission. For more information about access permissions, see Set Object ACL.

This operation also requires common request headers, such as Host and Date. For detailed information about common request headers, see Common HTTP headers.

Request elements

Name	Type	Description
CompleteMultipartUpload	Container	The container that stores the content of the CompleteMultipartUpload request. Child nodes: one or more Part elements Parent nodes: none
ETag	String	The ETag value that is returned by OSS after the part is uploaded. Parent nodes: Part
Part	Container	The container that stores the uploaded parts. Child nodes: ETag, PartNumber Parent nodes: CompleteMultipartUpload
PartNumber	Integer	The part模型无法生成答案，请稍后重试~```html number. Parent nodes: Part

Response elements

Name	Type	Description
Bucket	String	The name of the bucket. Parent nodes: CompleteMultipartUploadResult
CompleteMultipartUploadResult	Container	The container that stores the results of the CompleteMultipartUpload request. Child nodes: Bucket, Key, ETag, Location Parent nodes: None
ETag	String	The ETag that is generated when the object is created. ETags are used to identify the content of objects. If an object is created by calling the CompleteMultipartUpload operation, the ETag value is not the MD5 hash of the object content but a unique value calculated based on a specific rule. Note The ETag value can be used to check whether the object content is modified. We recommend that you use the MD5 hash of an object rather than the ETag value to verify data integrity. Parent nodes: CompleteMultipartUploadResult
Location	String	The URL that is used to access the uploaded object. Parent nodes: CompleteMultipartUploadResult
Key	String	The name of the uploaded object. Parent nodes: CompleteMultipartUploadResult
EncodingType	String	The encoding type of the object name in the response. If this parameter is specified in the request, the object name is encoded in the response. Parent nodes: CompleteMultipartUploadResult

Examples

Versioning Not Enabled

Request Example

POST /multipart.data?uploadId=0004B9B2D2F7815C432C9057C031****&encoding-type=url HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Length: 1056
Date: Fri, 24 Feb 2012 10:19:18 GMT
Authorization: OSS qn6q**************:77Dv****************
<CompleteMultipartUpload> 
    <Part> 
        <PartNumber>1</PartNumber>  
        <ETag>"3349DC700140D7F86A0784842780****"</ETag> 
    </Part>  
    <Part> 
        <PartNumber>5</PartNumber>  
        <ETag>"8EFDA8BE206636A695359836FE0A****"</ETag> 
    </Part>  
    <Part> 
        <PartNumber>8</PartNumber>  
        <ETag>"8C315065167132444177411FDA14****"</ETag> 
    </Part> 
</CompleteMultipartUpload>

Response Example

HTTP/1.1 200 OK
Server: AliyunOSS
Content-Length: 329
Content-Type: Application/xml
Connection: keep-alive
x-oss-request-id: 594f0751-3b1e-168f-4501-4ac71d21****
Date: Fri, 24 Feb 2012 10:19:18 GMT
<?xml version="1.0" encoding="UTF-8"?>
<CompleteMultipartUploadResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
    <EncodingType>url</EncodingType>
    <Location>http://oss-example.oss-cn-hangzhou.aliyuncs.com/multipart.data</Location>
    <Bucket>oss-example</Bucket>
    <Key>multipart.data</Key>
    <ETag>"B864DB6A936D376F9F8D3ED3BBE540****"</ETag>
</CompleteMultipartUploadResult>

Versioning Enabled

Request Example

POST /multipart.data?uploadId=63C06A5CFF6F4AE4A6BB3AD7F01C**** HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Length: 223
Date: Tue, 09 Apr 2019 07:01:56 GMT
Authorization: OSS qn6q**************:77Dv****************
<CompleteMultipartUpload> 
    <Part> 
        <PartNumber>1</PartNumber>  
        <ETag>"25A9F4ABFCC05743DF6E2C886C56****"</ETag> 
    </Part>  
    <Part> 
        <PartNumber>5</PartNumber>  
        <ETag>"25A9F4ABFCC05743DF6E2C886C56****"</ETag> 
    </Part>  
</CompleteMultipartUpload>

Response Example

HTTP/1.1 200 OK
Server: AliyunOSS
Content-Length: 314
Content-Type: Application/xml
Connection: keep-alive
x-oss-version-id: CAEQMxiBgID6v86D0BYiIDc3ZDI0YTBjZGQzYjQ2Mjk4OWVjYWNiMDljYzhlN****
x-oss-request-id: 5CAC4364B7AEADE017000662
Date: Tue, 09 Apr 2019 07:01:56 GMT
<?xml version="1.0" encoding="UTF-8"?>
<CompleteMultipartUploadResult>
  <Location>http://oss-example.oss-cn-hangzhou.aliyuncs.com/multipart.data</Location>
  <Bucket>oss-example</Bucket>
  <Key>multipart.data</Key>
  <ETag>"097DE458AD02B5F89F9D0530231876****"</ETag>
</CompleteMultipartUploadResult>

SDK

The following SDKs correspond to this operation:

Command line tool ossutil

For the ossutil command corresponding to the CompleteMultipartUpload operation, see complete-multipart-upload.

Error codes

Error code

HTTP status code

Description

InvalidDigest

400

To ensure that no errors occur during data transmission over the network, you can include the Content-MD5 value in the request. OSS calculates the MD5 hash of the uploaded data and compares it with the Content-MD5 value in the request. If the two values are inconsistent, an error occurs during data transmission.

FileAlreadyExists

409

Possible causes of this error are as follows:

The request header contains x-oss-forbid-overwrite=true to prevent overwriting an object with the same name, but an object with the same name already exists in the bucket.
If the hierarchical namespace feature is enabled for the bucket, the object is a directory when you complete the multipart upload of a file in the bucket.