ListObjectsV2
Returns some or all (up to 1,000) of the objects in a bucket with each request. You can use the request parameters as selection criteria to return a subset of the objects in a bucket. A 200 OK response can contain valid or invalid XML. Make sure to design your application to parse the contents of the response and handle it appropriately. For more information about listing objects, see Listing object keys programmatically in the Amazon S3 User Guide. To get a list of your buckets, see ListBuckets.
ListObjectsV2 doesn't return prefixes that are related only to in-progress multipart uploads.
Permissions
| Action | Description | Resource |
|---|---|---|
| ListBucket | Grants permission to list some or all of the objects in an Astran S3 bucket (up to 1000) | bucket |
Sorting order of returned objects
ListObjectsV2 returns objects in lexicographical order based on their key names.
The following operations are related to ListObjectsV2:
Request Syntax
GET /Bucket?list-type=2&delimiter=Delimiter&max-keys=MaxKeys&prefix=Prefix&start-after=StartAfter HTTP/1.1
Host: <partition>.s3.astran.io
URI Request Parameters
The request uses the following URI parameters.
Required: Yes
A delimiter is a character that you use to group keys.
Valid Values: url
Sets the maximum number of keys returned in the response. By default, the action returns up to 1,000 key names. The response might contain fewer keys but will never contain more.
Limits the response to keys that begin with the specified prefix.
StartAfter is where you want Astran S3 to start listing from. Astran S3 starts listing after this specified key. StartAfter can be any key in the bucket.
Request Body
The request does not have a request body.
Response Syntax
HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult>
<IsTruncated>boolean</IsTruncated>
<Contents>
...
<ETag>string</ETag>
<Key>string</Key>
<LastModified>timestamp</LastModified>
<Size>long</Size>
</Contents>
...
<Name>string</Name>
<Prefix>string</Prefix>
<Delimiter>string</Delimiter>
<MaxKeys>integer</MaxKeys>
<CommonPrefixes>
<Prefix>string</Prefix>
</CommonPrefixes>
...
<KeyCount>integer</KeyCount>
<StartAfter>string</StartAfter>
</ListBucketResult>
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in XML format by the service.
Root level tag for the ListBucketResult parameters.
Required: Yes
All of the keys (up to 1,000) that share the same prefix are grouped together. When counting the total numbers of returns by this API operation, this group of keys is considered as one item.
A response can contain CommonPrefixes only if you specify a delimiter.
CommonPrefixes contains all (if there are any) keys between Prefix and the next occurrence of the string specified by a delimiter.
CommonPrefixes lists keys that act like subdirectories in the directory specified by Prefix.
For example, if the prefix is notes/ and the delimiter is a slash (/) as in notes/summer/july, the common prefix is notes/summer/. All of the keys that roll up into a common prefix count as a single return when calculating the number of returns.
Type: Array of CommonPrefix data types
Metadata about each object returned.
Type: Array of Object data types
Causes keys that contain the same string between the prefix and the first occurrence of the delimiter to be rolled up into a single result element in the CommonPrefixes collection. These rolled-up keys are not returned elsewhere in the response. Each rolled-up result counts as only one return against the MaxKeys value.
Type: String
Set to false if all of the results were returned. Set to trueif more keys are available to return. If the number of results exceeds that specified by MaxKeys, all of the results might not be returned.
Type: Boolean
KeyCount is the number of keys returned with this request. KeyCount will always be less than or equal to the MaxKeysfield. For example, if you ask for 50 keys, your result will include 50 keys or fewer.
Type: Integer
Sets the maximum number of keys returned in the response. By default, the action returns up to 1,000 key names. The response might contain fewer keys but will never contain more.
Type: Integer
The bucket name.
Type: String
Keys that begin with the indicated prefix.
Type: String
If StartAfter was sent with the request, it is included in the response.
Type: String
Errors
NoSuchBucket
The specified bucket does not exist.
HTTP Status Code: 404
Examples
Sample Request for general purpose buckets: Listing keys
This request returns the objects in bucket. The request specifies the list-type parameter, which indicates version 2 of the API operation.
GET /bucket?list-type=2 HTTP/1.1
Host: <partition>.s3.astran.io
x-amz-date: 20160430T233541Z
Authorization: authorization string
Sample Response for general purpose buckets
This example illustrates one usage of ListObjectsV2.
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>bucket</Name>
<Prefix/>
<KeyCount>205</KeyCount>
<MaxKeys>1000</MaxKeys>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>my-image.jpg</Key>
<LastModified>2009-10-12T17:50:30.000Z</LastModified>
<ETag>"fba9dede5f27731c9771645a39863328"</ETag>
<Size>434234</Size>
</Contents>
<Contents>
...
</Contents>
...
</ListBucketResult>
Sample Request for general purpose buckets: Listing keys using the max-keys, prefix, and start-after parameters
In addition to the list-type parameter that indicates version 2 of the API operation, the request also specifies additional parameters to retrieve up to three keys in the quotes bucket that start with E and occur lexicographically after ExampleGuide.pdf.
GET /?list-type=2&max-keys=3&prefix=E&start-after=ExampleGuide.pdf HTTP/1.1
Host: <partition>.s3.astran.io
x-amz-date: 20160430T232933Z
Authorization: authorization string
Sample Response for general purpose buckets
This example illustrates one usage of ListObjectsV2.
HTTP/1.1 200 OK
x-request-id: 3B3C7C725673C630
Date: Sat, 30 Apr 2016 23:29:37 GMT
Content-Type: application/xml
Content-Length: length
Connection: close
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>quotes</Name>
<Prefix>E</Prefix>
<StartAfter>ExampleGuide.pdf</StartAfter>
<KeyCount>1</KeyCount>
<MaxKeys>3</MaxKeys>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>ExampleObject.txt</Key>
<LastModified>2013-09-17T18:07:53.000Z</LastModified>
<ETag>"599bab3ed2c697f1d26842727561fd94"</ETag>
<Size>857</Size>
</Contents>
</ListBucketResult>
Sample Request for general purpose buckets: Listing keys by using the prefix and delimiter parameters
This example illustrates the use of the prefix and the delimiter parameters in the request. For this example, we assume that you have the following keys in your bucket:
sample.jpgphotos/2006/January/sample.jpgphotos/2006/February/sample2.jpgphotos/2006/February/sample3.jpgphotos/2006/February/sample4.jpg
The following GET request specifies the delimiterparameter with a value of /.
GET /?list-type=2&delimiter=/ HTTP/1.1
Host: <partition>.s3.astran.io
x-amz-date: 20160430T235931Z
Authorization: authorization string
Sample Response for general purpose buckets
The key sample.jpg does not contain the delimiter character, and Astran S3 returns it in the Contents element in the response. However, all of the other keys contain the delimiter character. Astran S3 groups these keys and returns a single CommonPrefixes element with the Prefix value photos/. The Prefix element is a substring that starts at the beginning of these keys and ends at the first occurrence of the specified delimiter.
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>example-bucket</Name>
<Prefix></Prefix>
<KeyCount>2</KeyCount>
<MaxKeys>1000</MaxKeys>
<Delimiter>/</Delimiter>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>sample.jpg</Key>
<LastModified>2011-02-26T01:56:20.000Z</LastModified>
<ETag>"bf1d737a4d46a19f3bced6905cc8b902"</ETag>
<Size>142863</Size>
</Contents>
<CommonPrefixes>
<Prefix>photos/</Prefix>
</CommonPrefixes>
</ListBucketResult>
Sample Request for general purpose buckets
The following request specifies the delimiter parameter with the value /, and the prefix parameter with the value photos/2006/.
GET /?list-type=2&prefix=photos/2006/&delimiter=/ HTTP/1.1
Host: <partition>.s3.astran.io
x-amz-date: 20160501T000433Z
Authorization: authorization string
Sample Response for general purpose buckets
In response, Astran S3 returns only the keys that start with the specified prefix. Further, Astran S3 uses the delimiter character to group keys that contain the same substring until the first occurrence of the delimiter character after the specified prefix. For each such key group, Astran S3 returns one CommonPrefixes element in the response. The keys grouped under this CommonPrefixes element are not returned elsewhere in the response. The Prefix value returned in the CommonPrefixes element is a substring that starts at the beginning of the key and ends at the first occurrence of the specified delimiter after the prefix.
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>example-bucket</Name>
<Prefix>photos/2006/</Prefix>
<KeyCount>2</KeyCount>
<MaxKeys>1000</MaxKeys>
<Delimiter>/</Delimiter>
<IsTruncated>false</IsTruncated>
<CommonPrefixes>
<Prefix>photos/2006/February/</Prefix>
</CommonPrefixes>
<CommonPrefixes>
<Prefix>photos/2006/January/</Prefix>
</CommonPrefixes>
</ListBucketResult>
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: