You can upload a part of a multipart upload by copying all or part of the data for an existing object. To do this, you use the HTTP PUT method with the uploadId and partNumber query parameters and the x-amz-copy-source header. The bucket where you upload the part must be the same bucket as the one where the multipart upload was initiated.
You use the x-amz-copy-source header to specify the object you're copying (the source object) and the bucket that contains that object (the source bucket). The source bucket can be the same bucket as the one to which you're uploading the part. Alternatively, the source bucket can be a different bucket that's owned by the same tenant.
To upload a part by copying, 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 and read permission for the source bucket or for the source object itself.
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 by copying, 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 by copying 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 by copying.
Source object version
By default, when you upload a part by copying, HCP copies data from the current version of the source object. However, while versioning is enabled for the source bucket, you can use the versionId query parameter with the source object specification to copy data from a specific version of the object. If the version identified by the versionId parameter does not exist or is a delete marker, HCP returns a 404 (Not Found) status code.
Copying part of the data for an object
To upload a part by copying only part of the data for the source object, you use the x-amz-copy-source-range request header. The value of the x-amz-copy-source-range header is the range of bytes you want to copy. The first byte of the data for an object is in position 0 (zero), so a range of one to five specifies the second through sixth bytes, not the first through fifth.
To specify a byte range in an x-amz-copy-source-range header, use this format:
bytes=start-position-end-position
For example, to copy 6,000,000 bytes, starting from the 1,000,001st byte, you would use this x-amz-copy-source-range header:
x-amz-copy-source-range: bytes=1000000-6999999
These considerations apply to x-amz-copy-source-range header values:
•If you specify a valid range in which the start position is less than the size of the source object data, HCP uploads the part and returns a 200 (OK) status code.
•If you specify a valid range in which the start position is greater than or equal to the size of the source object data, HCP returns a 400 (Bad Request) status code and does not upload a part.
•If you specify an invalid range (for example, a range in which the start position is greater than the end position, HCP returns a 400 (Bad Request) status code and does not upload a part.
A request to upload a part by copying a range of bytes in a multipart object is most efficient when the start and end bytes for the requested range are aligned with the start and end bytes for one or more of the parts uploaded to create the object.
Part size
The parts you upload for a multipart upload can be any size up to and including five gigabytes. However, the minimum size for the parts you include in a complete multipart upload request, except the last part, is one megabyte. The last part can be smaller than one megabyte.
The maximum size for the object resulting from a multipart upload is five terabytes.
Replacing parts of a multipart upload
When you upload a part of a multipart upload by copying, if you use a part number that was already used for a part in the same multipart upload, the new part replaces the part that was previously uploaded. The part that was replaced is automatically deleted.
You can replace a part multiple times. The part for which the upload finished last is the one that is used for the object created by the multipart upload.
ETags
When you upload a part of a multipart upload by copying, HCP returns the ETag for the part in the ETag response header. The ETag is an identifier for the part data. In a request to complete a multipart upload, you need to specify the ETag along with the part number for each part you want to include in the resulting object.
Conditionally uploading a part by copying
You can choose to upload a part by copying only if the ETag or last modification date and time of the source object meet certain criteria. To specify these criteria, you use request headers:
•The x-amz-copy-source-if-match and x-amz-copy-source-if-none-match request headers compare the ETag for the source object or object version to one or more values that you specify. Typically, each value is the ETag for an object or object version of interest.
•The x-amz-copy-source-if-modified-since and x-amz-copy-source-if-unmodified-since request headers compare the date and time the source object or object version was last modified to a date and time that you specify.
If the source object or object version meets all the conditions specified by the conditional headers included in the request, HCP uploads the part by copying the object data. If the source object or object version does not meet the condition specified by:
•An x-amz-copy-source-if-match or x-amz-copy-source-if-unmodified-since header, HCP returns a 412 (Precondition Failed) status code and does not upload the part
•An x-amz-copy-source-if-none-match or x-amz-copy-source-if-modified-since header, HCP returns a 304 (Not Modified) status code and does not upload the part
If a request includes multiple different conditional headers, HCP processes any x-amz-copy-source-if-match and x-amz-copy-source-if-none-match headers before any x-amz-copy-source-if-modified-since or x-amz-copy-source-if-unmodified-since headers. If a request includes more than one of any given header, HCP processes only the first one of those headers and ignores the rest.
![]() |
Note: The x-amz-copy-source-if-modified-since and x-amz-copy-source-if-unmodified-since request headers are not compatible with s3curl. |
Client timeouts
Uploading a part of a multipart upload by copying a large amount of data from another object can take some time. If a client times out because an upload part copy operation is taking too long, HCP continues the operation in the background.
Because the connection to the client is broken, HCP cannot report the completion of the upload part copy operation to the client. To see whether the operation has finished successfully, use a GET request with the multipart upload ID to list the parts of the multipart upload. If the operation finished successfully, the part appears in the list. If the operation is still in progress or has failed, the part does not appear in the list.
If upload part copy operations are causing a client to time out, consider increasing the client timeout interval.
© 2015, 2020 Hitachi Vantara LLC. All rights reserved.