Complete Multipart Upload

Last updated: 2020-10-26 10:22:04

    Feature

    This API is used to complete a multipart upload after all parts are uploaded via the Upload Part API. When using this API, you must specify the PartNumber and ETag of each part in the request body to check if the parts are correct.

    It may take minutes for COS to merge uploaded parts upon a completed multipart upload. As a result, when the merging begins, COS immediately returns a 200 status code along with the Transfer-Encoding: chunked response header. COS then periodically returns chunked spaces to keep the connection active until the merging ends, and returns the information about the resulting entire object in the last chunk.

    • If any uploaded part is less than 1 MB in size, 400 EntityTooSmall will be returned when this API is called.
    • If the numbers of the uploaded parts are not continuous, 400 InvalidPart will be returned when this API is called.
    • If the part information entries in the request body are not sorted by number in ascending order, 400 InvalidPartOrder will be returned when this API is called.
    • If the uploadId does not exist, 404 NoSuchUpload will be returned when this API is called.

    We recommend you either complete or abort a multipart upload as early as possible, as the uploaded parts of an incomplete multipart upload will take up storage capacity and incur storage fees.

    Versioning

    • If versioning is enabled for the bucket, COS will automatically generate a unique version ID for the object to be uploaded and return this ID in the response using the x-cos-version-id response header.
    • If versioning is suspended for the bucket, COS will always use null as the version ID of any object in the bucket, and return the x-cos-version-id: null response header.

    Request

    Request samples

    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]

    Authorization: Auth String (see Request Signature for more information).

    Request parameters

    Name Description Type Required
    uploadId ID that identifies the multipart upload. It’s the same as the UploadId generated when using the Initiate Multipart Upload API. string Yes

    Request headers

    This API only uses common request headers. For more information, see Common Request Headers.

    Request body

    Submits application/xml request data, including all parts information.

    <CompleteMultipartUpload>
        <Part>
            <PartNumber>integer</PartNumber>
            <ETag>string</ETag>
        </Part>
        <Part>
            <PartNumber>integer</PartNumber>
            <ETag>string</ETag>
        </Part>
    </CompleteMultipartUpload>

    The nodes are described in details below:

    Node Name (Keyword) Parent Node Description Type Required
    CompleteMultipartUpload None Contains all information in the Complete Multipart Upload request Container No

    Content of the Container node CompleteMultipartUpload:

    Node Name (Keyword) Parent Node Description Type Required
    Part CompleteMultipartUpload Describes information on each part in this multipart upload Container Yes

    Content of the Container node Part:

    Node Name (Keyword) Parent Node Description Type Required
    PartNumber CompleteMultipartUpload.Part Part number integer Yes
    ETag CompleteMultipartUpload.Part The ETag header value returned when the Upload Part request succeeds string Yes

    Response

    Response headers

    In addition to common response headers, this API also returns the following response headers. For more information on common response headers, see Common Response Headers.

    Versioning-related headers

    If the object is uploaded to a versioning-enabled bucket, the following response headers will be returned:

    Name Description Type
    x-cos-version-id Object version ID string

    Headers related to server-side encryption (SSE)

    If you upload an object using SSE encryption, this API will return SSE headers. For more information, see Server-side encryption headers.

    Response body

    Returns application/xml data, including that on the resulting entire object, upon a successful request.

    <?xml version="1.0" encoding="UTF-8"?>
    <CompleteMultipartUploadResult xmlns="http://www.qcloud.com/document/product/436/7751">
        <Location>string</Location>
        <Bucket>string</Bucket>
        <Key>string</Key>
        <ETag>string</ETag>
    </CompleteMultipartUploadResult>

    The detailed nodes are described as follows:

    Node Name (Keyword) Parent Node Description Type
    CompleteMultipartUploadResult None Contains all the results of the Complete Multipart Upload action Container

    Content of the Container node CompleteMultipartUploadResult:

    Node Name (Keyword) Parent Node Description Type
    Location CompleteMultipartUploadResult Location of the object for which the multipart upload is completed. Format: http://<BucketName-APPID>.cos.<Region>.myqcloud.com/<ObjectKey>, e.g. http://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject string
    Bucket CompleteMultipartUploadResult The destination bucket for the multipart upload. Format: <BucketName-APPID>, e.g. examplebucket-1250000000 string
    Key CompleteMultipartUploadResult Object key string
    ETag CompleteMultipartUploadResult ETag of the object into which the parts are merged string

    Error codes

    This API uses standardized error responses and error codes. For more information, see Error Codes .

    Examples

    By default, this API uses “Transfer-Encoding: chunked” responses. However, developers should understand that, all the examples below use responses without Transfer-Encoding, which languages and libraries can automatically process. For more information, see the language- and library-specific documentation.

    Example 1. Simple example (versioning 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=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&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=45dae7b1a54930587f8123954664b1b5148b****
    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 xmlns="http://www.qcloud.com/document/product/436/7751">
        <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>