You can call this operation to complete multipart upload of an object.

Versioning

You can call this operation to complete multipart upload of an object when versioning is enabled. In this case, OSS generates a unique version ID for the object, adds the version ID to x-oss-version-id, and returns x-oss-version-id in the response header.

When you perform this operation, you must provide a complete list of parts. Information of each part must contain a part number and an entity tag (ETag). After OSS receives the list of parts, OSS verifies the validity of each part one by one. After all these parts have been verified, OSS combines these parts into a complete object.

Note
  • When you perform this operation, OSS checks whether each part except the last part is larger than 100 KB in size and whether the part number and ETag are provided for each part in the list. When each part is uploaded, the client must record the part number and the ETag value returned from the server.
  • It may take a while for OSS to process the CompleteMultipartUpload request. If the client is disconnected from OSS during this period, OSS continues to process the request.
  • The part numbers listed in the request do not have to be consecutive. For example, the first part number can be 1 and the second part number can be 5.
  • After OSS processes the CompleteMultipartUpload request, the upload ID of this task is no longer valid.
  • An object may have different upload IDs that are independent of each other. When one upload task is complete, the corresponding upload ID becomes invalid and other upload IDs are not affected.
  • If the InitiateMultipartUpload operation is called and the x-oss-server-side-encryption request header is specified, the x-oss-server-side-encryption response header is returned in response to the CompleteMultipartUpload request. The x-oss-server-side-encryption response header indicates the server-side encryption method for the object.

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

The Encoding-type parameter can be specified in the CompleteMultipartUpload request. OSS uses the specified encoding type to encode the object name in the response.

Parameter Type Description
Encoding-type String Specifies the encoding type of the object name in the response. The object name can contain any characters encoded in UTF-8. However, the XML 1.0 standard cannot be used to parse certain control characters, such as characters with an ASCII value from 0 to 10. You can set the encoding-type parameter to encode the object name in the response. Set the value to url.

This parameter is empty by default.

Valid value: url

Request headers

Header Type Required Description
x-oss-forbid-overwrite String No Specifies whether the object with the same object name is overwritten when you perform the CompleteMultipartUpload operation.
  • By default, if x-oss-forbid-overwrite is not specified, the object with the same name is overwritten.
  • If x-oss-forbid-overwrite is set to true, the object with the same name cannot be overwritten. If x-oss-forbid-overwrite is set to false, the object with the same name can be overwritten.
Note
  • The x-oss-forbid-overwrite request header is invalid when the versioning state of the target bucket is Enabled or Suspended. In this case, the CompleteMultipartUpload operation overwrites the object with the same name.
  • Specifying the x-oss-forbid-overwrite request header may degrade the query per second (QPS) performance of OSS. If you want to use the x-oss-forbid-overwrite request header for a large number of operations (QPS > 1000), submit a ticket.
x-oss-complete-all:yes String No
  • If x-oss-complete-all:yes is specified, OSS lists all parts that have been uploaded in the task of the current upload ID, sorts the parts by their partNumber values, and then performs the CompleteMultipartUpload operation. OSS cannot detect parts that are not uploaded or being uploaded during the CompleteMultipartUpload operation. Therefore, you must ensure that all parts have been uploaded before you perform the CompleteMultipartUpload operation.
  • If x-oss-complete-all:yes is specified, the request body cannot be specified. Otherwise, an error occurs.
  • The format of the response remains unchanged after x-oss-complete-all:yes is specified.

Request elements

Element Type Description
CompleteMultipartUpload Container The container that stores the content of the CompleteMultipartUpload request.

Child node: Part

Parent node: none

ETag String The ETag value returned by OSS after the part is uploaded.

Parent node: Part

Part Container The container that stores information about the uploaded part.

Child node: ETag and PartNumber

Parent node: CompleteMultipartUpload

PartNumber Integer The number of the parts.

Parent node: Part

Response elements

Element Type Description
Bucket String The name of the bucket.

Parent node: CompleteMultipartUploadResult

CompleteMultipartUploadResult Container The container that stores the response to the CompleteMultipartUpload request.

Child node: Bucket, Key, ETag, and Location

Parent node: none

ETag String The ETag created to identify the content of the object when the object is created through the CompleteMultipartUpload request. The ETag value is the UUID of the object content. The ETag value of the object can be used to check whether the object content is modified.

Parent node: CompleteMultipartUploadResult

Location String The URL used to access the object.

Parent node: CompleteMultipartUploadResult

Key String The name of the object.

Parent node: CompleteMultipartUploadResult

EncodingType String The encoding type of the object name in the response. If the encoding-type parameter is specified in the request, the object name in the response is encoded.

Parent node: Container

Examples

  • Sample request
    POST /multipart.data? uploadId=0004B9B2D2F7815C432C9057C03134D4  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 qn6qrrqxo2oawuk53otfjbyc:8VwFhFUWmVecK6jQlHlXMK/z****
    <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>
    Sample response
    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">
        <Location>http://oss-example.oss-cn-hangzhou.aliyuncs.com /multipart.data</Location>
        <Bucket>oss-example</Bucket>
        <Key>multipart.data</Key>
        <ETag>"B864DB6A936D376F9F8D3ED3BBE540****"</ETag>
    </CompleteMultipartUploadResult>
  • Sample request for a versioning-enabled bucket
    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 6jftttm6x6san0e:XljBrYBYxDnxKdFMj9WYI6qu****
    <CompleteMultipartUpload> 
        <Part> 
            <PartNumber>1</PartNumber>  
            <ETag>"25A9F4ABFCC05743DF6E2C886C56****"</ETag> 
        </Part>  
        <Part> 
            <PartNumber>5</PartNumber>  
            <ETag>"25A9F4ABFCC05743DF6E2C886C56****"</ETag> 
        </Part>  
    </CompleteMultipartUpload>
    Sample response
    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>

SDKs

The SDKs of the CompleteMultipartUpload operation for various programming languages are as follows:

Error codes

Error code HTTP status code Description
InvalidDigest 400 The error message returned because the Content-MD5 value in the request is inconsistent with the MD5 value calculated by OSS. 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 value of the uploaded data and compares it with the Content-MD5 value in the request.
FileAlreadyExists 409 The error message returned because an object with the same name already exists when the request contains an x-oss-forbid-overwrite header and the value of this header is set to true.