Completing a multipart upload

You use the HTTP POST method with the uploadId query parameter to complete a multipart upload. You must use the same user account as the account used in the request to initiate the multipart upload. Additionally, you need write permission for the bucket where the multipart upload was initiated.

You use the uploadId query parameter to specify the upload ID of the multipart upload you are completing. If the upload ID you specify does not match the upload ID of an in-progress multipart upload or is not associated with the object specified in the request, the upload does not complete and HCP returns a 404 (Not Found) status code.

To specify the list of parts to use when completing a multipart upload, you use an XML request body. You identify each part by its part number and the ETag returned when the part was uploaded. The list of parts must be in ascending order by part number.

Only the parts listed in the request to complete a multipart upload are used as data for the resulting object. Parts that were uploaded for the multipart upload but that are not listed in the request are automatically deleted after the request is processed.

A multipart upload must have at least one part to complete.

When you complete a multipart upload, you become the owner of the resulting object.

If a request to complete a multipart upload includes any custom metadata x-amz-meta- headers, HCP returns a 400 (Bad Request) status code and does not complete the multipart upload.

HCP ignores ACL headers in requests to complete a multipart upload.

Request line

Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to complete a multipart upload has either of these formats:

  • With the bucket name included in the hostname:
    POST /object-name?uploadId=upload-id HTTP/1.1
  • With the bucket name following the hostname:
    POST /bucket-name/object-name?uploadId=upload-id HTTP/1.1

The uploadId query parameter is case sensitive.

Required headers

The following list describes the required headers to use in a request to complete a multipart upload.

  • Authorization

    Specifies user credentials or requests anonymous access.

  • Content-Length

    Specifies the size, in bytes, of the request body.

  • Content-Type

    Specifies the Internet media type of the request body. The only valid values are application/xml and text/xml.

  • Date

    Specifies the date and time when the request is being made according to the requester. Normally, this is the current date and time.

    The date and time must always be specified using Greenwich Mean Time (GMT).

    To specify the date and time, use this format:

    DDD, dd MMM yyyy HH:mm:ss (+0000|GMT)

    In this format:

    • DDD

      The three-letter abbreviation for the day of the week, with an uppercase first letter (for example, Mon).

    • dd

      The two-digit day of the month.

    • MMM

      The three-letter abbreviation for the month, with an uppercase first letter (for example, Feb).

    • yyyy

      The four-digit year.

    • HH

      The hour on a 24-hour clock.

    • mm

      The number of minutes.

    • ss

      The number of seconds.

    For example:

    Thu, 23 Mar 2017 14:27:05 +0000

    All S3 compatible requests must include either a Date header or an x-amz-date header. If a request includes both headers, HCP uses the date and time in the x-amz-date header.

  • Host

    Specifies the hostname for the request. The host name identifies either a tenant or a bucket.

    For a tenant, use this format:

    tenant-name.hcp-domain-name

    For a bucket, use this format:

    bucket-name.tenant-name.hcp-domain-name

  • x-amz-date

    Specifies the date and time at which the request is being made according to the requester. Normally, this is the current date and time.

    For the valid values for this header, see the description of the Date header above.

Optional headers

  • If-Match

    Specifies a value for comparison with the ETag of the most recent version of the object specified in the request. If the specified value matches the Etag, HCP continues processing the request. If the specified value doesn't match the Etag or the specified object doesn't exist, HCP returns an error response body and does not complete the multipart upload.

    The value of this header can be any string of one or more characters.

  • x-hcp-pretty-print

    Optionally, requests that the XML response body be formatted for readability. Valid values are:

    • true

      Format the XML response body for readability.

    • false

      Do not apply any special formatting to the XML response body.

    The default is false.

    The values true and false are not case sensitive.

  • x-hcp-labelretentionhold

    Specifies whether to place one or more labeled holds on the object and the associated labeled hold IDs. The values passed with this header are in a JSON format string containing one or more id and hold value pairs.

    • id

      Unique label name. The maximum label size is 64 characters.

    • hold

      Either true or false.

    • Example

      Place two labeled holds on the object.

      x-hcp-labelretentionhold [{"id":"UniqueLabelHold-1","hold":true}, 
      {"id":"UniqueLabelHold-2","hold":true}]

  • x-hcp-retention

    Specifies the retention value for the object being stored. This value can be a fixed date, an offset, a retention class, or a special value.

  • x-hcp-retentionhold

    Specifies whether the object is on hold. This value can be either true or false.

Request body

The next list describes the XML elements in a complete multipart upload request body. The elements are listed in alphabetical order.

  • CompleteMultipartUpload

    Root element. This must be the first element in the complete multipart upload request body.

    The CompleteMultipartUpload element can optionally include this XML namespace specification:

    xmlns="http://s3.amazonaws.com/doc/2006-03-01/"

  • ETag

    Child of the Part element.

    The ETag element specifies the ETag of the applicable part.

  • Part

    Child of the CompleteMultipartUpload element and container for the elements that describe a part.

    The Part element identifies a part that has been uploaded for the multipart upload.

  • PartNumber

    Child of the Part element.

    The PartNumber element specifies the part number of the applicable part.

Response headers

The list below describes the headers returned in response to a successful request to complete a multipart upload.

  • Content-Type

    Specifies the Internet media type of the response body. For a request to complete a multipart upload, the value of this header is always application/xml;charset=UTF-8.

  • Date

    The date and time when HCP responded to the request, in Greenwich Mean Time (GMT). The date and time are returned in this format:

    DDD dd MMM yyyy HH:mm:ss GMT

    For example:

    Fri, 18 Sep 2020 14:27:05 GMT

  • x-amz-server-side-encryption

    Specifies whether objects stored in HCP are encrypted. Possible values are:

    • If objects are encrypted, AES256
    • If objects are not encrypted, None

    This header is returned only if the request headers include x-amz-server-side-encryption.

  • x-amz-version-id

    Specifies the version ID of the object. This header is returned only while versioning is enabled for the bucket.

Response body

HCP returns information about the object that results from a successful complete multipart upload request in an XML response body.

The information is returned in the following format:

<?xml version='1.0' encoding='UTF-8'?>
<CompleteMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2020-09-01/">
    <Location>object-url</Location>
    <Bucket>bucket-name</Bucket>
    <Key>object-name</Key>
    <ETag>&quot;etag&quot;</ETag>
</CompleteMultipartUploadResult>

The following list describes the XML elements returned in the response body. The elements are listed in alphabetical order.

  • Bucket

    Child of the CompleteMultipartUploadResult element.

    The Bucket element specifies the bucket where the object was created.

  • CompleteMultipartUploadResult

    Root element.

  • ETag

    Child of the CompleteMultipartUploadResult element.

    The ETag element specifies the ETag for the object.

    The ETag in the multipart upload complete operation is not an MD5 hash of the object data and therefore is not useful for verifying the data integrity.

  • Key

    Child of the CompleteMultipartUploadResult element.

    The Key element specifies the name of the object.

  • Location

    Child of the CompleteMultipartUploadResult element.

    The Location element specifies the complete URL for the object.

Return codes

The table below describes HTTP status codes that can be returned in response to a request to complete a multipart upload.

CodeMeaningDescription
200OK

Possible reasons include:

  • HCP successfully started processing the request.

    To determine whether the multipart upload successfully completed, check whether HCP returned a response body that identifies the resulting multipart object or an error response body.

    The following errors can cause a request to complete a multipart upload to fail after HCP returns the 200 (OK) status code:

    • The list of parts in the request body includes a part, other than the last part, that is smaller than one megabyte.
    • The list of parts in the request body includes one or more part numbers that are not the number of an uploaded part.
    • The ETag associated with one or more part numbers listed in the request body is not the ETag returned for the part with the specified part number.
    • The parts in the request body are not listed in ascending order.
    • The request includes the If-Match request header and either the value specified by the header does not match the ETag of the most recent version of the specified object, or the specified object does not already exist.
  • The application attempts to set a labeled hold on an object with an HCP version earlier than 9.1.
400Bad Request

Possible reasons include:

  • The request does not include a Content-Type header.
  • The XML in the request body is malformed or contains an invalid value.
  • The request includes a custom metadata x-amz-meta- header.
  • The labeled hold ID length exceeds 64 characters.
  • A label hold ID must have at least one character.
  • The request contains over 100 labeled holds.
  • The active labeled hold limit exceeds 100 labels.
  • A request cannot specify the same labeled hold ID as both active and inactive.
  • The request must specify the labeled hold id and hold values.
  • To use the labeled hold feature, an online upgrade is required to HCP 9.1 or later.
403Forbidden

Possible reasons include:

  • The request specifies anonymous access. Only an authenticated user can complete a multipart upload.
  • The credentials provided with the request are invalid.
  • The credentials provided with the request do not match the credentials used to initiate the multipart upload.
  • You do not have permission to complete multipart uploads in the specified bucket.
  • The S3 compatible API is currently disabled for the specified bucket.
404Not Found

One of these:

  • The specified multipart upload does not exist. Either the upload ID is invalid, or the multipart upload was aborted or already completed.
  • The specified bucket does not exist.
500Internal Server Error

An internal error occurred. If this error persists, contact your tenant administrator.

503Service Unavailable

HCP is temporarily unable to handle the request, probably due to system overload, maintenance, or upgrade. Try the request again, gradually increasing the delay between each successive attempt.

If this error persists, contact your tenant administrator.

Example: Completing a multipart upload

Here is a sample POST request that completes a multipart upload for an object named acctg/RulesAndRegulations.pdf in the finance bucket. The request body is in a file named Acctg-RulesAndRegulations.xml.

In this example, the retention value of the object is set to five days past the time when the object was stored. Additionally, a labeled retention hold is placed on the object. The user has write and data access permissions on the bucket.

The request is being made while versioning is enabled for the bucket.

Request body

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CompleteMultipartUpload>
     <Part>
          <PartNumber>1</PartNumber>
          <ETag>4a01f8acf3353b0a7e1c03a0e34f63e4</ETag>
     </Part>
     <Part>
          <PartNumber>2</PartNumber>
          <ETag>97ede335e69d08bb3cfbbd974bae68e4</ETag>
     </Part>
     <Part>
          <PartNumber>3</PartNumber>
          <ETag>a39ebe49948a821cab2c4d7d04f9b1c3</ETag>
     </Part>
     <Part>
          <PartNumber>4</PartNumber>
          <ETag>a7b8192c98da2c13a034980376b6c809</ETag>
     </Part>
     <Part>
          <PartNumber>5</PartNumber>
          <ETag>bbe438b2a0376f08dc37867a82ea87e6</ETag>
     </Part>
     <Part>
          <PartNumber>6</PartNumber>
          <ETag>f79eac0151d6b62226986e721c89a2f1</ETag>
     </Part>
</CompleteMultipartUpload>

Request with s3curl command line

./s3curl.pl --id=lgreen --post=Acctg-RulesAndRegulations.xml -- -k
     "https://finance.europe.hcp.example.com/acctg/RulesAndRegulations.pdf
             ?uploadId=94837746087105" -H "x-hcp-retention: A+5d"
            .-H 'x-hcp-labelretentionhold: [{"id":"UniqueLabelHold-1","hold":true}]'
             -H "x-hcp-pretty-print: true"

Request headers

POST /acctg/RulesAndRegulations.pdf?uploadId=94837746087105 HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Fri, 26 June 2020 17:19:26 +0000
Authorization:  AWS bGdyZWVu:y4wahRZz+oLpASXkNeBy9LQAJsE=
X-HCP-Retention:  A+5d
X-HCP-LabelRetentionHold: '[{"id":"UniqueLabelHold-1","hold":true}]'

Response headers

HTTP/1.1 200 OK
Date: Fri, 26 June 2020 17:19:26 GMT
x-amz-server-side-encryption: None
x-amz-version-id: 94874564091777
Content-Type: application/xml;charset=ISO-8859-1
ETag: "e879d0c42d032f7b55d2be82825071d6-6"
Content-Length: 401

Response body

<?xml version='1.0' encoding='UTF-8'?>
<CompleteMultipartUploadResult
             xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
     <Location>https://finance.europe.hcp.example.com/hs3/acctg
             /RulesAndRegulations.pdf</Location>
     <Bucket>finance</Bucket>
     <Key>acctg/RulesAndRegulations.pdf</Key>
     <ETag>&quot;e879d0c42d032f7b55d2be82825071d6-6&quot;</ETag>
</CompleteMultipartUploadResult>