Listing the parts of a multipart upload

Content Platform Tenant Management Help

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

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.

Code Meaning Description
200 OK HCP successfully listed the parts of the multipart upload.
400 Bad Request Possible reasons include that a query parameter has an invalid value.
403 Forbidden

Possible reasons include:

  • The request specifies anonymous access. Only an authenticated user can list the parts of 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 or the credentials for the owner of the bucket where the multipart upload is being performed.
  • You do not have permission to list the parts of a multipart upload 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 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: Listing the parts of a multipart upload

Here's a sample GET request for a listing of the parts of an in-progress multipart upload for an object named acctg/RulesAndRegulations.pdf in the finance bucket. The request uses these query parameters in addition to uploadId:

part-number-marker=1
Starts the list with the first part with a part number greater than one
max-parts=3
Lists a maximum of three parts

The example assumes that parts one, two, three, five, and six have already been uploaded.

Request with s3curl command line

./s3curl.pl --id=lgreen -- -k
     "https://finance.europe.hcp.example.com/acctg/RulesAndRegulations.pdf
             ?uploadId=94837746087105&part-number-marker=1&max-parts=3"
     -H "x-hcp-pretty-print: true"

Request headers

GET /acctg/RulesAndRegulations.pdf?uploadId=94837746087105
     &part-number-marker=1&max-parts=3 HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:Ey256+39Nz19jRw7chPIOJwD8m4=
x-hcp-pretty-print: true

Response headers

HTTP/1.1 200 OK
Date: Fri, 07 February 2020 17:19:26 GMT
x-amz-abort-date: Sat, 25 Feb 2017 17:19:26 GMT
Content-Type: application/xml;charset=UTF-8
Transfer-Encoding: chunked

Response body

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ListPartsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
     <Bucket>finance</Bucket>
     <Key>acctg/RulesAndRegulations.pdf</Key>
     <UploadId>94837746087105</UploadId>
     <Initiator>
          <ID>835be4b1-8f84-407b-8084-b9329beadf9b</ID>
          <DisplayName>lgreen</DisplayName>
     </Initiator>
     <Owner>
          <ID>835be4b1-8f84-407b-8084-b9329beadf9b</ID>
          <DisplayName>lgreen</DisplayName>
     </Owner>
     <StorageClass>STANDARD</StorageClass>
     <PartNumberMarker>1</PartNumberMarker>
     <NextPartNumberMarker>5</NextPartNumberMarker>
     <MaxParts>3</MaxParts>
     <IsTruncated>true</IsTruncated>
     <Part>
          <PartNumber>2</PartNumber>
          <LastModified>2017-02-23T17:19:26.000Z</LastModified>
          <ETag>"97ede335e69d08bb3cfbbd974bae68e4"</ETag>
          <Size>6800000</Size>
     </Part>
     <Part>
          <PartNumber>3</PartNumber>
          <LastModified>2017-02-23T17:19:26.000Z</LastModified>
          <ETag>"a39ebe49948a821cab2c4d7d04f9b1c3"</ETag>
          <Size>6800000</Size>
     </Part>
     <Part>
          <PartNumber>5</PartNumber>
          <LastModified>2017-02-23T17:19:26.000Z</LastModified>
          <ETag>"bbe438b2a0376f08dc37867a82ea87e6"</ETag>
          <Size>6700000</Size>
     </Part>
</ListPartsResult>