Listing the in-progress multipart uploads in a bucket

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 uploads query parameter to list the multipart uploads that are in progress in a bucket. An in-progress multipart upload is one that has been initiated but not yet completed or aborted. While a multipart upload is in the process of being completed, it is still considered to be in progress.

To list the in-progress multipart uploads in a bucket, you must be an authenticated user. Additionally, you need browse permission for the bucket.

A multipart upload listing is returned in an XML response body. The multipart uploads are listed in ascending alphanumeric order by object name. If the listing includes multiple multipart uploads for the same object, those multipart uploads are listed in ascending chronological order by the time they were initiated.

Request line

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

  • With the bucket name included in the hostname:
    GET/?uploads[&query-parameters] HTTP/1.1
  • With the bucket name following the hostname:
    GET/bucket-name?uploads[&query-parameters] HTTP/1.1

The uploads query parameter is case sensitive.

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

delimiter
You use the delimiter query parameter to request a multipart upload listing that includes a list of common prefixes for multipart upload object names. A common prefix is the name of an object up through the first occurrence of the character string specified by the delimiter parameter.
Each common prefix is listed only once regardless of the number of multipart uploads with matching object names. The multipart uploads with object names that begin with the common prefix are not included elsewhere in the listing.
The returned listing also contains multipart uploads with object names that do not include the character string specified by the delimiter parameter. In the listing, all these multipart uploads are listed first, followed by all the common prefixes.
The multipart uploads and common prefixes included in a listing are subject to any other criteria specified in the request.
Both the multipart uploads and the common prefixes count toward the maximum number of multipart uploads that can be included in the listing.
The character string you specify for the delimiter query parameter can contain any valid UTF-8 characters. including white space. Percent-encode non-ASCII characters and reserved special characters such as ampersands (&), commas (,) and equal signs (=). If the character string contains spaces, enclose the entire string in quotation marks.
The delimiter parameter name and the character string you specify are both case sensitive.
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.
key-marker
You use the key-marker query parameter without the upload-id-marker query parameter to specify a starting point for the returned multipart upload listing. That point is the first multipart upload with an object name that's alphanumerically greater than the character string specified by the key-marker parameter.
For example, the multipart upload listing returned in response to a GET multipart upload listing request with the key-marker=sales/ query parameter contains this multipart upload:
sales/RulesAndRegulations.pdf
When more than the requested number of multipart uploads satisfy the criteria in a request for a multipart upload listing, HCP returns a partial listing. In this case, the response body includes:
  • The IsTruncated element with a value of true.
  • The NextKeyMarker element. The value of this element is either the object name for the last multipart upload included in the returned listing or the last common prefix in the returned listing, whichever is alphanumerically greater.
  • Conditionally, the NextUploadIdMarker element.
To return the next part of the multipart upload listing, you include the key-marker query parameter in another request for the listing. As the parameter value, you specify the value of the NextKeyMarker element returned with the previous partial listing.
When the returned listing includes the last multipart upload that satisfies the request criteria, the response body includes the IsTruncated element with a value of false and does not include the NextKeyMarker and NextUploadIdMarker elements.
The character string you specify for the key-marker query parameter can contain any valid UTF-8 characters. including white space. Percent-encode non-ASCII characters and reserved special characters such as ampersands (&), commas (,) and equal signs (=). If the character string contains spaces, enclose the entire string in quotation marks.
The key-marker parameter name and the character string you specify are both case sensitive.
max-uploads
By default, a multipart upload listing can include at most one thousand multipart uploads. However, you can use the max-uploads query parameter in a multipart upload listing request to specify a smaller maximum number of multipart uploads.
For example, the bucket listing returned in response to a GET bucket list multipart uploads request with the max-uploads=2 query parameter contains these multipart uploads:
acctg/AcctgAtExampleCorp-Advanced.mov
acctg/AcctgAtExampleCorp-Introduction.mov
If more than the maximum number of multipart uploads satisfy the criteria for a request, you can use the the key-marker and, optionally, upload-id-marker query parameters in conjunction with max-uploads to retrieve the parts in groups.
Valid values for the max-uploads query parameter are integers in the range 0 (zero) through 1,000. If you specify an integer greater than one thousand, HCP returns a 400 (Invalid Argument) status code and does not return a multipart upload listing.
The max-uploads parameter name is case sensitive.
prefix
You use the prefix query parameter to request a multipart upload listing that contains only multipart uploads with object names that begin with a specified character string (the prefix).
For example, the multipart upload listing returned in response to a GET bucket list multipart uploads request with the prefix=acctg query parameter contains only these items:
acctg/AcctgAtExampleCorp-Advanced.mov
acctg/AcctgAtExampleCorp-Introduction.mov
acctg/RulesAndRegulations.pdf
The character string you specify for the prefix query parameter can contain any valid UTF-8 characters, including white space. Percent-encode non-ASCII characters and reserved special characters such as ampersands (&), commas (,) and equal signs (=). If the character string contains spaces, enclose the entire string in quotation marks.
The prefix parameter name and the character string you specify are both case sensitive.
upload-id-marker
By default, if a bucket contains multiple multipart uploads for a given object, a multipart upload listing for the bucket includes all the multipart uploads for that object, where those multipart uploads satisfy the request criteria.
You use the upload-id-marker query parameter in conjunction with the key-marker parameter to start a multipart upload listing with a multipart upload for which:
  • The object name is the same as the character string specified by the key-marker parameter.
  • The upload ID is the first upload ID for the named object that's alphanumerically greater than the character string specified by the upload-id-marker parameter.
If no multipart upload satisfies the above criteria, the returned listing starts with the first multipart upload with an object name that's alphanumerically greater than the character string specified by the key-marker parameter.
If the multipart upload listing request includes the upload-id-marker parameter without the key-marker parameter, the upload-id-marker parameter is ignored.
When the response body for a multipart upload listing request includes the IsTruncated element with a value of true, the response body also includes the NextUploadIdMarker element, except when both of these are true:
  • The response body lists one or more common prefixes.
  • The last multipart upload that satisfies the request criteria does not appear in the response body because the object name for that multipart upload starts with the last listed common prefix.
The value of the NextUploadIdMarker element, when present, is the upload ID of the last multipart upload included in the returned listing. This is the value to use for the upload-id-marker query parameter in a request to retrieve the next group of multipart uploads that satisfy the request criteria.
The character string you specify for the upload-id-marker query parameter can contain any valid UTF-8 characters. including white space. Percent-encode non-ASCII characters and reserved special characters such as ampersands (&), commas (,) and equal signs (=). If the character string contains spaces, enclose the entire string in quotation marks.
The upload-id-marker parameter name and the character string you specify are both case sensitive.

Required headers

The list below describes the headers you can use in a request to list in-progress multipart uploads.

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 in-progress multipart uploads.

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.

Response body

The list below describes the XML elements in the response body returned in response to a request to list the multipart uploads that are in progress in a bucket. The elements are listed in alphabetical order.

Bucket
Child of the ListMultipartUploadsResult element.
The Bucket element specifies the name of the bucket targeted by the request.
CommonPrefixes
Child of the ListMultipartUploadsResult and container for the Prefix element.
The response body contains one CommonPrefixes element for each common prefix in the multipart upload listing.
Delimiter
Child of the ListMultipartUploadsResult element.
The Delimiter element specifies the value of the delimiter query parameter included in the request. If the request did not include the delimiter query parameter, the response body does not include the Delimiter element.
DisplayName
Child of the Initiator or Owner element.
If the initiator or owner is identified by an HCP user account, the value of the DisplayName element is the username for that account. If the initiator or owner is identified by an AD user account, the value of the DisplayName element is the username of that account followed by an at sign (@) and the AD domain name.
ID
Child of the Initiator or Owner element.
If the initiator or owner is identified by an HCP user account, the value of the ID element is the user ID for that account. If the initiator or owner is identified by an AD user account, the value of the ID element is the SID for that account.
Initiated
Child of the Upload element.
The Initiated element specifies the date and time when the applicable multipart upload was initiated, 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
Initiator
Child of the Upload element and container for the DisplayName and ID elements.
The Initiator element identifies the user who initiated the applicable multipart upload.
IsTruncated
Child of the ListMultipartUploadsResult element.
The IsTruncated element indicates whether the returned listing includes the last multipart upload that satisfies the request criteria. Possible values are:
true
The returned listing includes the last multipart upload that satisfies the request criteria.
false
The returned listing does not include the last multipart upload that satisfies the request criteria.
Key
Child of the Upload element.
The Key element specifies the name of the object to be created by the applicable multipart upload.
KeyMarker
Child of the ListMultipartUploadsResult element.
The KeyMarker element specifies the value of the key-marker query parameter included in the request. If the request did not include the key-marker query parameter, the response body includes KeyMarker as an empty element.
ListMultipartUploadsResult
Root element.
MaxUploads
Child of the ListMultipartUploadsResult element.
The MaxUploads element specifies the value of the max-uploads query parameter included in the request. If the request did not include the max-uploads query parameter, the value of the MaxUploads element is 1000.
NextKeyMarker
Child of the ListMultipartUploadsResult element.
The NextKeyMarker element specifies the object name for the last multipart upload included in the returned listing. This element is included in the response body only when the value of the IsTruncated element is true.
If the returned listing is truncated, you can use the value of the NextKeyMarker element as the value of the key-marker query parameter in a new request to retrieve the next set of multipart uploads that satisfy the request criteria.
NextUploadIdMarker
Child of the ListMultipartUploadsResult element.
The NextUploadIdMarker element specifies the upload ID of the last multipart upload included in the returned listing. This element is included in the response body only when the value of the IsTruncated element is true.
If the returned listing is truncated, you can use the value of the NextUploadIdMarker element as the value of the upload-id-marker query parameter in a new request to retrieve the next set of multipart uploads that satisfy the request criteria.
Owner
Child of the Upload element and container for the DisplayName and ID elements.
The Owner element identifies the user who will own the object created by the applicable multipart upload.
Prefix
One of these:
  • Child of the ListMultipartUploadsResult.

    In this case, the Prefix element specifies the value of the prefix query parameter included in the request. If the request did not include the prefix query parameter, the response body includes Prefix as an empty element.

  • Child of the CommonPrefixes element.

    In this case, the Prefix element specifies a common prefix.

StorageClass
Child of the Upload element.
The value of the StorageClass element is always STANDARD.
Upload
Child of the ListMultipartUploadsResult and container for the elements that describe a multipart upload.
The response body contains one Upload element for each multipart upload in the returned listing.
UploadId
Child of the Upload element.
The UploadId element specifies the upload ID of the applicable multipart upload.
UploadIdMarker
Child of the ListMultipartUploadsResult element.
The UploadIdMarker element specifies the value of the upload-id-marker query parameter included in the request. If the request did not include the upload-id-marker query parameter, the response body does not include the KeyMarker element.

Status codes

The table below describes HTTP status codes that can be returned in response to a request to list the in-progress multipart uploads in a bucket.

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

Possible reasons include:

  • The credentials provided with the request are invalid.
  • You do not have permission to list the in-progress multipart uploads in the specified bucket.
  • The S3 compatible API is currently disabled for the specified bucket.
404 Not Found 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 multipart uploads for an object

Here's a sample GET request for a listing of the in-progress multipart uploads in the finance bucket for an object named acctg/RulesAndRegulations.pdf. The request uses the prefix query parameter to specify the object name.

Request with s3curl command line

./s3curl.pl --id=lgreen -- -k "https://finance.europe.hcp.example.com?uploads
             &prefix=acctg/RulesAndRegulations"
     -H "x-hcp-pretty-print: true"

Request headers

GET /?uploads&prefix=acctg/RulesAndRegulations.pdf HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:IUzJmUIE9YYu9S6f7l9iYUqzZRE=
x-hcp-pretty-print: true

Response headers

HTTP/1.1 200 OK
Date: Fri, 07 February 2020 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"?>
<ListMultipartUploadsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
     <Bucket>finance</Bucket>
     <Prefix>acctg/RulesAndRegulations.pdf</Prefix>
     <MaxUploads>1000</MaxUploads>
     <IsTruncated>false</IsTruncated>
     <Upload>
          <Key>acctg/RulesAndRegulations.pdf</Key>
          <UploadId>94874755807297</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>
          <Initiated>2017-02-22T14:47:39.527Z</Initiated>
     </Upload>
     <Upload>
          <Key>acctg/RulesAndRegulations.pdf</Key>
          <UploadId>94874826378433</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>
          <Initiated>2017-02-22T15:06:02.223Z</Initiated>
     </Upload>
</ListMultipartUploadsResult>

Example: Listing multipart uploads a few at a time

Here's a sample GET request for a limited listing of the in-progress multipart uploads in the finance bucket. The request uses these query parameters in addition to uploads:

key-marker=acctg/AcctgAtExampleCorp-Introduction.mov
Starts the listing with a multipart upload for the first object with a name that's alphanumerically greater than acctg/AcctgAtExampleCorp-Introduction.mov
max-uploads=3
Lists at most three multipart uploads

Request with s3curl command line

./s3curl.pl --id=lgreen -- -k
     "https://finance.europe.hcp.example.com?uploads
          &key-marker=acctg/AcctgAtExampleCorp-Introduction.mov&max-uploads=3"
     -H "x-hcp-pretty-print: true"

Request headers

GET /?uploads&key-marker=acctg/AcctgAtExampleCorp-Introduction.mov
     &max-uploads=3 HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:+fE2/Hy6h+ntZ9Q3fuhCnH3SLQM=
x-hcp-pretty-print: true

Response headers

HTTP/1.1 200 OK
Date: Fri, 07 February 2020 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"?>
<ListMultipartUploadsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
     <Bucket>finance</Bucket>
     <KeyMarker>acctg/AcctgAtExampleCorp-Introduction.mov</KeyMarker>
     <MaxUploads>3</MaxUploads>
     <IsTruncated>false</IsTruncated>
     <Upload>
          <Key>acctg/RulesAndRegulations.pdf</Key>
          <UploadId>94874755807297</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>
          <Initiated>2017-02-22T14:47:39.527Z</Initiated>
     </Upload>
     <Upload>
          <Key>acctg/RulesAndRegulations.pdf</Key>
          <UploadId>94874826378433</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>
          <Initiated>2017-02-22T15:06:02.223Z</Initiated>
     </Upload>
     <Upload>
          <Key>sales/RulesAndRegulations.pdf</Key>
          <UploadId>94874757710913</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>
          <Initiated>2017-02-21T09:48:22.289Z</Initiated>
     </Upload>
</ListMultipartUploadsResult>