Completing a multipart upload

Content Platform Tenant Management
Version
9.7.x
File Size
4269 KB
Audience
anonymous
Part Number
MK-95HCPH002-19

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.

Status codes

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

Code Meaning Description
200 OK

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.
400 Bad 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.
403 Forbidden

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.
404 Not 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.
500 Internal Server Error

An internal error occurred. If this error persists, contact your tenant administrator.
503 Service 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>