Uploading a part of a multipart upload
You use the HTTP PUT method with the uploadId and partNumber query parameters to upload a part of a multipart upload. The bucket where you upload the part must be the same bucket as the one where the multipart upload was initiated.
To upload a part, you must be an authenticated user. You need to 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 you're uploading the part.
For a request to upload a part, the request body consists of the data in a specified file.
You use the uploadId query parameter to specify the upload ID of the multipart upload for which you're uploading the part. If the upload ID you specify doesn't match the upload ID of an in-progress multipart upload or isn't associated with the object specified in the request, HCP returns a 404 (Not Found) status code and does not upload the part.
When you upload a part, you use the partNumber query parameter to specify the part number of the data you're uploading. The part number must be an integer in the range 1 (one) through 10,000.
The parts of the data for an object are ordered, but the part numbers do not need to start at one and do not need to be consecutive numbers. For example, if you're uploading the data for an object in three parts, you could number the parts 1, 2, and 3, but you could also number them 2, 7, and 19.
You can upload the parts of a multipart upload in any order. However, in the request to complete the multipart upload, you need to list the parts in ascending numeric order.
You can upload multiple parts of a multipart upload concurrently.
If a request to upload a part includes any custom metadata (x-amz-meta-) headers, HCP returns a 400 (Bad Request) status code and does not upload the part.
HCP ignores ACL headers in requests to upload a part.
Request line
Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to upload a part of a multipart upload has either of these formats:
- With the bucket name included in the hostname:
PUT /object-name?uploadId=upload-id&partNumber=part-number HTTP/1.1
- With the bucket name following the hostname:
PUT /bucket-name/object-name?uploadId=upload-id&partNumber=part-number HTTP/1.1
The uploadId and partNumber query parameters are not case sensitive.
Required headers
The list below describes the headers you can use in a request to upload a part of a multipart upload.
Authorization
Specifies user credentials or requests anonymous access.
Content-Length
Specifies the size, in bytes, of the data being uploaded.
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
Content-MD5
Directs HCP to check the integrity of the data it receives by comparing a Base64-encoded MD5 hash of that data to the value specified by this header. The valid value for this header is the Base64-encoded MD5 hash of the data in the request body.
Content-Type
Specifies the Internet media type of the data being uploaded. Valid values are Internet media types (for example,
text/plain
,application/xml
, orimage/jpeg
).Expect
Tells the application not to send the request body if the request headers are rejected. The only valid value is
100-continue
. This value is not case sensitive.
Response headers
The list below describes the headers returned in response to a successful request to upload a part of a multipart upload.
Content-length
Specifies the size, in bytes, of the response body. In response to a successful request to upload a part of a multipart upload, the value of this header is always
0
(zero).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
ETag
Specifies the ETag for the object.
ETags are useful for making object-level operations conditional based on the object content. Operations that can be made conditional are checking the existence of an object, copying an object, and retrieving an object.
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.
Return codes
The table below describes HTTP status codes that can be returned in response to a request to upload a part of a multipart upload.
Code | Meaning | Description |
200 | OK | HCP successfully uploaded the part. |
400 | Bad Request |
Possible reasons include:
|
403 | Forbidden |
Possible reasons include:
|
404 | Not Found |
One of these:
|
411 | Length Required | Either the request does not include a Content-Length header, or the request includes a Content-Length header with no value. |
413 | Request Entity Too Large | The part you are trying to upload is too big for the amount of space left in the bucket. |
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: Uploading a part
Here’s a sample PUT request that uploads a part of the multipart upload for an object named acctg/RulesAndRegulations.pdf in the finance bucket. The data for the part is in a file named /file-parts-temp/RulesAndRegs-Acctg-1.
The example shows the response headers HCP returns while versioning is enabled for the bucket and while versioning is disabled for the bucket.
Request with s3curl command line
./s3curl.pl --id=lgreen --put=/file-parts-temp/RulesAndRegs-Acctg-1 -- -k "https://finance.europe.hcp.example.com/acctg/RulesAndRegulations.pdf ?uploadId=94837746087105&partNumber=1"
Request headers
PUT /acctg/RulesAndRegulations.pdf?uploadId=94837746087105&partNumber=1 HTTP/1.1 Host: finance.europe.hcp.example.com Date: Fri, 07 February 2020 17:19:26 +0000 Authorization: AWS bGdyZWVu:oVRZgtbngViycDs+I2p2NP5Y3zY=
Response headers with versioning enabled
HTTP/1.1 200 OK Date: Fri, 16 Dec 2016 15:29:28 GMT ETag: "4a01f8acf3353b0a7e1c03a0e34f63e4" x-amz-version-id: 94841738807809 x-amz-server-side-encryption: None Content-Length: 0
Response headers with versioning disabled
HTTP/1.1 200 OK Date: Fri, 07 February 2020 17:19:26 GMT ETag: "4a01f8acf3353b0a7e1c03a0e34f63e4" x-amz-server-side-encryption: None Content-Length: 0