Limiting a listing of current items

You can use prefix, max-keys, marker, encoding-type, and delimiter query parameters, alone or in combination with each other, to limit the list of the current items in a bucket.

prefix query parameter

You use the prefix query parameter to request a bucket listing that contains only items with names that begin with a specified character string (the prefix) and, if applicable, common prefixes that begin that prefix.

For example, the bucket listing returned in response to a GET request with the prefix=sales query parameter contains only these items:

sales/
sales/budget_proposals/
sales/budget_proposals/BudgProp-2020
sales_quotas_2020.pdf

The list of items does not include in-progress multipart uploads or common prefixes that are exclusively for multipart uploads. For more information about multipart uploads, see Working with multipart uploads.

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-keys query parameter

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

For example, the bucket listing returned in response to a GET request with the max-keys=6 query parameter contains these items:

AcctgBestPractices.doc (current version)
acctg/
acctg/AcctgRR-Summary
acctg/budget_proposals/
acctg/budget_proposals/BudgProp-2020
hum_res/

max-keys parameter rules

Valid values for the max-keys query parameter are integers in the range 0 (zero) through 2,147,483,647. If you specify an integer greater than one thousand, the returned bucket listing includes only the first one thousand items that satisfy the request criteria (or fewer if fewer than one thousand items satisfy the criteria).

The max-keys parameter name is case sensitive.

marker query parameter

You use the marker query parameter to start the returned bucket listing with the first item with a name that comes alphanumerically after the character string specified by the marker parameter.

For example, the bucket listing returned in response to a GET request with the marker=quarterly_rpts/ query parameter contains these items:

quarterly_rpts/Q2_2019.ppt
quarterly_rpts/Q3_2019.ppt
quarterly_rpts/Q4_2019.ppt
sales/
sales/budget_proposals/
sales/budget_proposals/BudgProp-2020
sales_quotas_2020.pdf

When more than the requested number of items satisfy the criteria in a request for a bucket listing, HCP returns a partial listing. In this case, the response body includes the IsTruncated element with a value of true. You can request the next part of the listing by including the marker query parameter in a new request. As the parameter value, you specify either the name of the last item in the returned listing or the last common prefix in the returned listing, whichever is alphanumerically greater.

If the string you specify as the value of the marker query parameter is the name of a folder and does not end with a forward slash (/), items that begin with that string followed by a forward slash are omitted from the listing.

marker parameter rules

The character string you specify for the 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 marker parameter name and the character string you specify are both case sensitive.

The marker parameter is ignored if specified in a GET request that includes the versions parameter.

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 bucket listing that includes a list of common prefixes, where a prefix is the name of an item 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 items with matching names. The items with matching names are not included elsewhere in the listing.

The returned listing also contains items with names that do not include the character string specified by the delimiter parameter. In the listing, all the named items are listed first, followed by all the common prefixes.

For example, the bucket listing returned in response to a GET request with the delimiter=budget_proposals query parameter contains these items and common prefixes:

Items:

AcctgBestPractices.doc (current version)
acctg/
acctg/AcctgRR-Summary
hum_res/
mktg/
mktg/campaign_GoGetEm_expenses.xls (current version)
mktg/campaign_LiveIt_expenses.xls
quarterly_rpts/
quarterly_rpts/Q2_2019.ppt
quarterly_rpts/Q3_2019.ppt
quarterly_rpts/Q4_2019.ppt
sales/
sales_quotas_2020.pdf

Common prefixes:

acctg/budget_proposals
hum_res/budget_proposals
mktg/budget_proposals
sales/budget_proposals

The items and common prefixes included in a listing are subject to any other criteria specified in the request.

Both the items and the common prefixes count toward the maximum number of items that can be included in the bucket listing.

The list of items does not include in-progress multipart uploads. The list of common prefixes does not include common prefixes that are exclusively for multipart uploads. For more information about multipart uploads, see Working with multipart uploads.

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.