Call CompleteMultipartUpload to complete a multipart upload-Object Storage Service(OSS)-阿里云帮助中心

After uploading all data parts, call the CompleteMultipartUpload operation to complete the multipart upload.

Usage notes

When you call the CompleteMultipartUpload operation, you must provide a list of all valid parts, including their part numbers and ETags. OSS receives the part list, verifies each part, and then combines them into a complete object.

Part size
When you call CompleteMultipartUpload, OSS checks that each part, except for the last one, is at least 100 KB. OSS also checks the part number and ETag of each part in the list you provide. Therefore, when you upload a part, your client must record the part number and the ETag value that the server returns.
Request processing
Processing a CompleteMultipartUpload request may take some time. If the connection between the client and OSS is interrupted during this process, OSS continues to process the request.
PartNumber
The server validates the part number when you call the CompleteMultipartUpload operation.
The value for PartNumber ranges from 1 to 10,000. The part numbers do not need to be consecutive, but they must be in ascending order. For example, the first part can have a PartNumber of 1, and the second part can have a PartNumber of 5.
UploadId
An object can have multiple UploadIds at the same time. When you complete a multipart upload for a specific UploadId, that UploadId becomes invalid. Other UploadIds for the object are not affected.
x-oss-server-side-encryption request header
If you specify the x-oss-server-side-encryption request header when you call the InitiateMultipartUpload operation, the x-oss-server-side-encryption header is also returned in the response from CompleteMultipartUpload. The value of this header indicates the server-side encryption algorithm used for the object.

Versioning

If versioning is enabled, when you call the CompleteMultipartUpload operation, OSS generates a unique version ID for the object. This ID is returned in the x-oss-version-id response header.

Permissions

By default, an Alibaba Cloud account has full permissions. RAM users or RAM roles under an Alibaba Cloud account do not have any permissions by default. The Alibaba Cloud account or account administrator must grant operation permissions through RAM policies or Bucket Policy.

API	Action	Description
CompleteMultipartUpload	`oss:PutObject`	Merges parts into an object.
CompleteMultipartUpload	`oss:PutObjectTagging`	When merging parts into an object, if you specify object tags through x-oss-tagging, this permission is required.

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>

When youOSS ONWhen you call this API operation in CloudBox, you must setHostreplace withCloudBoxEndpoint.For more information, seeCloudBoxEndpoint.

Request parameters

When you call the CompleteMultipartUpload operation, you can use `encoding-type` to encode the `Key` value in the response.

Name

Type

Description

encoding-type

String

Specifies the encoding for the returned Key. Only URL encoding is supported.

The Key uses UTF-8 characters. However, the XML 1.0 standard does not support parsing some control characters, such as characters with ASCII values 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 Key in the response.

Default: none

Valid value: url

Request headers

Name	Type	Required	Description
x-oss-forbid-overwrite	String	No	Specifies whether to overwrite an object that has the same name when you call the CompleteMultipartUpload operation. If you do not specify `x-oss-forbid-overwrite` or set it to false, an object with the same name is overwritten. If you set `x-oss-forbid-overwrite` to true, an 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. This means an object with the same name is overwritten. Setting the `x-oss-forbid-overwrite` request header reduces queries per second (QPS) performance. To use this header for many operations (QPS > 1,000), submit a ticket to us for confirmation to avoid affecting your services.
x-oss-complete-all	String	No	Specifies whether to list all parts that have been uploaded for the current UploadId. Value: yes If you specify `x-oss-complete-all` and set it to yes, OSS lists all parts that have been uploaded for the current UploadId, sorts them by part number, and then runs the CompleteMultipartUpload operation. During the CompleteMultipartUpload operation, OSS cannot detect parts that are being uploaded or have failed to upload. You must ensure the integrity of the parts. If you specify `x-oss-complete-all`, you cannot specify a body. Otherwise, an error is returned. 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 it. Values: default (default): The object inherits the ACL of the bucket. private: The object is a private resource. Only the object owner and authorized users have read and write permissions on the object. Other users cannot access the object. public-read: The object is a public-read resource. Only the object owner and authorized users have read and write permissions on the object. Other users have only read permissions. Use this permission with caution. public-read-write: The object is a public-read-write resource. All users have read and write permissions on the object. Use this permission with caution. For more information about ACLs, see Object ACL.

This operation also includes common request headers, such as Host and Date. For more information about common request headers, see Common request headers.

Request elements

Name	Type	Description
CompleteMultipartUpload	Container	The container for the content of a CompleteMultipartUpload request. Child nodes: one or more Part elements Parent node: none
ETag	String	The ETag value that OSS returns after a part is successfully uploaded. Parent node: Part
Part	Container	The container for information about uploaded parts. Child nodes: ETag, PartNumber Parent node: CompleteMultipartUpload
PartNumber	Integer	The part number. Parent node: Part

Response elements

Name	Type	Description
Bucket	String	The name of the bucket. Parent node: CompleteMultipartUploadResult
CompleteMultipartUploadResult	Container	The container for the result of the Complete Multipart Upload request. Child nodes: Bucket, Key, ETag, Location Parent node: None
ETag	String	When an object is created, a corresponding ETag is also created. The ETag identifies the content of an object. For an object created by a CompleteMultipartUpload request, the ETag is a unique value generated based on a specific calculation rule, but it is not the MD5 hash of the object's content. Note The ETag value can be used to check whether the object content has changed. We do not recommend using the ETag as the MD5 hash of the object content to verify data integrity. Parent node: CompleteMultipartUploadResult
Location	String	The URL of the newly created object. Parent node: CompleteMultipartUploadResult
Key	String	The name of the newly created object. Parent node: CompleteMultipartUploadResult
EncodingType	String	The encoding type used in the response. If you specify `encoding-type` in the request, the Key in the response is encoded. Parent node: CompleteMultipartUploadResult

Examples

Versioning disabled

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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<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

You can call this operation using the SDKs for the following languages:

ossutil command line interface

For more information about the ossutil command that corresponds 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 network transmission, you can include Content-MD5 in the request. OSS calculates the MD5 hash of the uploaded data and compares it with the Content-MD5 value you provided. If the values do not match, a data transmission error has occurred.
FileAlreadyExists	409	When the request header contains `x-oss-forbid-overwrite=true`, overwriting a file with the same name is forbidden. If a file with the same name already exists, this fault is returned.