ListBucket
The ListBucket
operation returns information about some of the items in the
bucket.
For a general introduction to the list operation, see the Listing Keys.
Requests
This example lists up to 1000 keys in the "quotes" bucket that have the prefix "notes."
Syntax
<ListBucket xmlns="http://doc.s3.amazonaws.com/2006-03-01"> <Bucket>quotes</Bucket> <Prefix>notes/</Prefix> <Delimiter>/</Delimiter> <MaxKeys>1000</MaxKeys> <AWSAccessKeyId>1D9FVRAYCP1VJEXAMPLE=</AWSAccessKeyId> <Timestamp>2006-03-01T12:00:00.183Z</Timestamp> <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature> </ListBucket>
Parameters
Name | Description | Required |
---|---|---|
prefix
|
Limits the response to keys which begin with the indicated prefix. You can use prefixes to separate a bucket into different sets of keys in a way similar to how a file system uses folders. Type: String Default: None |
No |
marker
|
Indicates where in the bucket to begin listing. The list will only include keys that occur lexicographically after marker. This is convenient for pagination: To get the next page of results use the last key of the current page as the marker. Type: String Default: None |
No |
max-keys
|
The maximum number of keys you'd like to see in the response body. The server might return fewer than this many keys, but will not return more. Type: String Default: None |
No |
delimiter
|
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. Type: String Default: None |
No |
Success Response
This response assumes the bucket contains the following keys:
notes/todos.txt notes/2005-05-23/customer_mtg_notes.txt notes/2005-05-23/phone_notes.txt notes/2005-05-28/sales_notes.txt
Syntax
<?xml version="1.0" encoding="UTF-8"?> <ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Name>backups</Name> <Prefix>notes/</Prefix> <MaxKeys>1000</MaxKeys> <Delimiter>/</Delimiter> <IsTruncated>false</IsTruncated> <Contents> <Key>notes/todos.txt</Key> <LastModified>2006-01-01T12:00:00.000Z</LastModified> <ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag> <Size>5126</Size> <StorageClass>STANDARD</StorageClass> <Owner> <ID>bcaf1ffd86f41ce161ca5fb16fd081034f</ID> <DisplayName>webfile</DisplayName> </Owner> <StorageClass>STANDARD</StorageClass> </Contents> <CommonPrefixes> <Prefix>notes/2005-05-23/</Prefix> </CommonPrefixes> <CommonPrefixes> <Prefix>notes/2005-05-28/</Prefix> </CommonPrefixes> </ListBucketResult>
As you can see, many of the fields in the response echo the request parameters.
IsTruncated
, Contents
, and
CommonPrefixes
are the only response elements that can
contain new information.
Response Elements
Name | Description |
---|---|
Contents
|
Metadata about each object returned. Type: XML metadata Ancestor: ListBucketResult |
CommonPrefixes
|
A response can contain Type: String Ancestor: ListBucketResult |
Delimiter
|
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. Type: String Ancestor: ListBucketResult |
IsTruncated
|
Specifies whether (true) or not (false) all of the results
were returned. All of the results may not be returned if the
number of results exceeds that specified by Type: String Ancestor: boolean |
Marker
|
Indicates where in the bucket to begin listing. Type: String Ancestor: ListBucketResult |
MaxKeys
|
The maximum number of keys returned in the response body. Type: String Ancestor: ListBucketResult |
Name
|
Name of the bucket. Type: String Ancestor: ListBucketResult |
Prefix
|
Keys that begin with the indicated prefix. Type: String Ancestor: ListBucketResult |
Response Body
For information about the list response, see Listing Keys Response.
Access Control
To list the keys of a bucket you need to have been granted READ
access on
the bucket.