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
andtext/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 anx-amz-date
header. If a request includes both headers, HCP uses the date and time in thex-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
andfalse
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
orfalse
.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
orfalse
.
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
.- If objects are encrypted,
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>"etag"</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.
Code | Meaning | Description |
200 | OK |
Possible reasons include:
|
400 | Bad Request |
Possible reasons include:
|
403 | Forbidden |
Possible reasons include:
|
404 | Not Found |
One of these:
|
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>"e879d0c42d032f7b55d2be82825071d6-6"</ETag> </CompleteMultipartUploadResult>