Limiting the multipart upload listing

You can use the prefix, max-uploads, key-marker, upload-id-marker, encoding-type, and delimiter query parameters to limit the multipart uploads included in a listing of in-progress multipart uploads.

prefix query parameter

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

prefix parameter rules

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.

max-uploads query parameter

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.

max-uploads parameter rules

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.

key-marker query parameter

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

For information about using the key-marker query parameter with the upload-id-marker query parameter, see upload-id-marker query parameter.

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. For information about this element, see upload-id-marker query parameter.

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.

key-marker parameter rules

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.

upload-id-marker query parameter

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.

For example, suppose the finance bucket contains three in-progress multipart uploads for acctg/RulesAndRegulations.pdf with upload IDs 1, 2, and 3. To page through all the multipart uploads in the finance bucket four at a time, you would use a sequence of requests like this:

1.Request line:

GET  /?uploads&max-uploads=4  HTTP/1.1

The response body lists these multipart uploads:

acctg/AcctgAtExampleCorp-Advanced.mov
acctg/AcctgAtExampleCorp-Introduction.mov
acctg/RulesAndRegulations.pdf (upload ID 1)
acctg/RulesAndRegulations.pdf (upload ID 2)

The response body also includes these elements:

<IsTruncated>true</IsTruncated>
<NextKeyMarker>acctg/RulesAndRegulations.pdf</NextKeyMarker>
<NextUploadIdMarker>2</NextUploadIdMarker>

2.Request line:

GET  /?uploads&max-uploads=4&key-marker=acctg/RulesAndRegulations.pdf
    &upload-id-marker=2  HTTP/1.1

The response body lists these multipart uploads:

acctg/RulesAndRegulations.pdf (upload ID 3)
sales/RulesAndRegulations.pdf

The response body also includes this element:

<IsTruncated>false</IsTruncated>

upload-id-marker parameter rules

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.

encoding-type parameter

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.

encoding-type parameter rules

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.

delimiter query parameter

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.

For example, the multipart upload listing returned in response to a GET bucket list multipart uploads request with the delimiter=RulesAndRegulations query parameter contains these multipart uploads and common prefixes:

Multipart uploads:

acctg/AcctgAtExampleCorp-Advanced.mov
acctg/AcctgAtExampleCorp-Introduction.mov

Common prefixes:

acctg/RulesAndRegulations
sales/RulesAndRegulations

The listed multipart uploads do not have the string RulesAndRegulations in their object names. The acctg/RulesAndRegulations common prefix represents the multipart uploads with object names that start with the string acctgRulesAndRegulations. The salesRulesAndRegulations common prefix represents the multipart uploads with object names that start with the string salesRulesAndRegulations.

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.

delimiter parameter rules

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.

© 2015, 2020 Hitachi Vantara LLC. All rights reserved.