Listing the parts of a multipart upload

You use the HTTP GET method with the uploadId query parameter to list the parts that have been uploaded for an in-progress multipart upload. An in-progress multipart upload is one that has been initiated but not yet completed or aborted. You cannot list the parts of a completed or aborted multipart upload.

To list the parts of a multipart upload, you must be an authenticated user. You need to use either the same user account as the account used in the request to initiate the multipart upload or the user account for the owner of the bucket where the multipart upload was initiated. Additionally, you need read permission for the bucket.

You use the uploadId query parameter to specify the upload ID of the multipart upload for which you're requesting the part listing. 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 return a part listing.

A part listing is returned in an XML response body. The parts are listed in numeric order. For each part, the listing contains the part number, the date and time when the part was uploaded, the ETag for the part, and the size of the part.

A part listing does not include parts that are in the process of being uploaded or parts that have been replaced.

Request line

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

• With the bucket name included in the hostname:

  GET /object-name?uploadId=upload-id[&query-parameters]HTTP/1.1

• With the bucket name following the hostname:

  GET /bucket-name/object-name?uploadId=upload-id[&query-parameters]HTTP/1.1

The uploadId query parameter is case sensitive.

query-parameters can be none, one, or more of:

encoding-type

You use the encoding-type query parameter to request the S3 compatible API to encode the response. You can also use this query parameter to specify the encoding method to use.

The key for an object can contain any Unicode character. Some characters, such as those with an ASCII value from 0 to 10, cannot be parsed by XML 1.0 parsers. For these characters, you can add the encoding-type query parameter to request the S3 compatible API to encode the keys in the response.

The encoding-type parameter name is case sensitive.

max-parts

By default, a part listing for a multipart upload can include at most one thousand parts. However, you can use the max-parts query parameter to specify a smaller maximum number of parts to be included in the returned listing. If more than the maximum number of parts satisfy the criteria for a request, you can use query parameters to retrieve the parts in groups.

Valid values for the max-parts query parameter are integers in the range zero through one thousand. If you specify an integer greater than one thousand, HCP returns a 400 (Invalid Argument) status code and does not return a part listing.

The max-parts parameter name is case sensitive.

part-number-marker

By default, a part listing starts with the lowest-numbered part of the multipart upload. You can use the part-number-marker query parameter to request a listing that starts with a part with a higher number. When you include this query parameter in the request for a part listing, the returned listing starts with the part with the next higher number than the value you specified for the parameter.

Valid values for the part-number-marker query parameter are integers in the range 0 (zero) through 10,000.

The part-number-marker parameter name is case sensitive.

Required headers

The list below describes the headers you can use in a request to list the parts of a multipart upload.

Authorization

Specifies user credentials or requests anonymous access.

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

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.

Response headers

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

Content-Type

Specifies the Internet media type of the response body. For a request to list the parts of 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

Transfer-Encoding

Indicates that HCP could not determine the size of the response body before formulating the response. For a request to list the buckets you own, the value of this header is always chunked.

x-amz-abort-date

Specifies the date and time when the multipart upload will be automatically aborted if it has not already been completed. The date and time are expressed in this format:

DDD, ddMMMyyyyhh:mm:ss GMT

For example:

Sat, 25 Mar 2017 17:19:26 GMT

Response body

HCP returns the list of parts of a multipart upload in an XML response body.

The list below describes the XML elements in the response body returned in response to a request to list the parts of a multipart upload. The elements are listed in alphabetical order.

Bucket

Child of the ListPartsResult element.

The Bucket element specifies the name of the bucket where the multipart upload is being performed.

DisplayName

Child of the Initiator or Owner element.

If the multipart upload initiator or object owner is identified by an HCP user account, the value of the DisplayName element is the user name for that account. If the multipart upload initiator or object owner is identified by an AD user account, the value of the DisplayName element is the user name of that account followed by an at sign (@) and the AD domain name.

ETag

Child of the Part element.

The ETag element specifies the ETag of the applicable part.

ID

Child of the Initiator or Owner element.

If the multipart upload initiator or object owner is identified by an HCP user account, the value of the ID element is the user ID for that account. If the multipart upload initiator or object owner is identified by an AD user account, the value of the ID element is the SID for that account.

Initiator

Child of the ListPartsResult element and container for the DisplayName and ID elements.

The Initiator element identifies the user who initiated the multipart upload.

IsTruncated

Child of the ListPartsResult element.

The IsTruncated element indicates whether the returned part listing includes the last part that satisfies the request criteria. Possible values are:

true

The returned listing includes the last part that satisfies the request criteria.

false

The returned listing does not include the last part that satisfies the request criteria.

Key

Child of the ListPartsResult element.

The Key element specifies the name of the object being created by the multipart upload.

LastModified

Child of the Part element.

The LastModified element specifies the date and time when the applicable part was last modified, in Greenwich Mean Time (GMT).

The date and time are expressed in this format:

yyyy-MM-ddTHH:mm:ss.SSSZ

For example:

2020-02-18T19:46:03.856Z

ListPartsResult

Root element.

MaxParts

Child of the ListPartsResult element.

The MaxParts element specifies the value of the max-parts query parameter included in the request. If the request did not include the max-parts query parameter, the value of the MaxParts element is 1000.

NextPartNumberMarker

Child of the ListPartsResult element.

The NextPartNumberMarker element specifies the number of the last part included in the returned part listing. If the returned listing doesn't include any parts, the value of the NextPartNumberMarker element is 0 (zero).

If the returned listing is truncated, you can use the value of the NextPartNumberMarker element as the value of the part-number-marker query parameter in a new request to retrieve the next set of parts that satisfy the request criteria.

Owner

Child of the ListPartsResult element and container for the DisplayName and ID elements.

The Owner element identifies the user who will own the object created by the multipart upload.

Part

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

The response body contains one Part element for each 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.

PartNumberMarker

Child of the ListPartsResult element.

The PartNumberMarker element specifies the value of the part-number-marker query parameter included in the request. If the request did not include the part-number-marker query parameter, the value of the PartNumberMarker element is 0 (zero).

Size

Child of the ListPartsResult element.

The value of the StorageClass element is always STANDARD.

UploadId

Child of the ListPartsResult element.

The UploadId element specifies the upload ID of the multipart upload.

Status codes

The table below describes HTTP status codes that can be returned in response to a request to list the parts of a multipart upload.