You use query parameters to limit the items included in a bucket listing. You can use prefix, max-keys, delimiter, encoding-type, list-type, continuation-token, fetch-owner, and start-after 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.
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.
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.
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.
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.
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.
list-type parameter
You use the list-type query parameter in order to use version 2 of the S3 compatible API. The value for this query parameter must always be set to 2 if you want to use version 2 of S3 compatible API requests.
list-type parameter rules
If any value other than 2 is specified for this query parameter, version 1 of the S3 compatible API is used by default.
The list-type parameter name is case sensitive.
continuation-token parameter
By default, a bucket listing can include at most one thousand items. If your request exceeds this or exceeds the value set for the max-keys query parameter, the response is truncated and you can use the continuation-token query parameter to list the next set of objects. Also, when the IsTruncated response element value is set to true, the response includes the NextContinuationToken element. The value of this element can be used in your next request as the continuation token to list the next set of objects.
continuation-token parameter rules
The continuation-token is a value that only the S3 compatible API understands, and objects are listed in UTF-8 character encoding in lexicographical order. If you specify an invalid continuation-token query parameter in a request, a 400 (Bad Request) error is returned, including a message that specifies the invalid continuation-token query parameter.
The continuation-token parameter name is case sensitive.
fetch-owner parameter
You use the fetch-owner query parameter to retrieve owner information. When you specify the fetch-owner query parameter to true, the S3 compatible API returns the owner information in the response.
fetch-owner parameter rules
The S3 compatible API no longer returns owner information by default in the response. To include owner information in the response, you need to set the fetch-owner query parameter to true.
The fetch-owner parameter name is case sensitive.
start-after parameter
You use the start-after query parameter to specify that you want the S3 compatible API to return key names after a specific object key. The start-after query parameter that you specify is always returned in the response, regardless of whether the specified value is valid.
start-after parameter rules
The start-after query parameter is valid only in the first request. If the response is truncated, you can use the continuation-token query parameter to list the next set of objects. The S3 compatible API lists objects in UTF-8 character encoding in lexicographical order.
The start-after parameter name and the character string you specify are both case sensitive.
© 2015, 2020 Hitachi Vantara LLC. All rights reserved.