| « PreviousNext » | |
  | Did this page help you? Yes | No | Tell us about it... |
GET Bucket (List Objects)
Description
This implementation of the GET operation returns some or all (up to 1000)
of the objects in a bucket. You can use the request parameters as selection criteria to
return a subset of the objects in a bucket.
To use this implementation of the operation, you must have READ access to
the bucket.
Note
To get a list of your buckets, see GET Service.
Requests
Syntax
GET / HTTP/1.1 Host:BucketName.s3.amazonaws.com Date:dateAuthorization:signatureValue
Request Parameters
This implementation of GET uses the parameters in the
following table to return a subset of the objects in a bucket.
| Parameter | Description | Required |
|---|---|---|
delimiter | A delimiter is a character you use to group keys. All keys that contain the same string between theprefix, if
specified, and the first occurrence of the delimiter after the
prefix are grouped under a single result element,
CommonPrefixes. If you don't specify the
prefix parameter, then the substring
starts at the beginning of the key. The keys that are grouped under
CommonPrefixes result element are not
returned elsewhere in the response.Type: String Default: None | No |
marker |
Specifies the key to start with when listing objects in a bucket. Amazon S3 lists objects in alphabetical order. Type: String Default: None | No |
max-keys |
Sets the maximum number of keys returned in the response body. The response might
contain fewer keys but will never contain more. If there are
additional keys that satisfy the search criteria but were not
returned because Type: String Default: 1000 | No |
prefix |
Limits the response to keys that begin with the specified
prefix. You can use prefixes to separate a bucket into different
groupings of keys. (You can think of using Type: String Default: None | No |
Request Elements
This implementation of the operation does not use request elements.
Request Headers
This implementation of the operation uses only request headers that are common to all operations. For more information, see Common Request Headers.
Responses
Response Headers
This implementation of the operation uses only response headers that are common to most responses. For more information, see Common Response Headers.
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 Type: String Ancestor: ListBucketResult |
DisplayName
|
Object owner's name. Type: String Ancestor: ListBucketResult.Contents.Owner |
ETag
|
The entity tag is an MD5 hash of the object. The ETag only reflects changes to the contents of an object, not its metadata. Type: String Ancestor: ListBucketResult.Contents |
ID
|
Object owner's ID. Type: String Ancestor: ListBucketResult.Contents.Owner |
IsTruncated
|
Specifies whether ( Type: Boolean Ancestor: ListBucketResult |
Key
|
The object's key. Type: String Ancestor: ListBucketResult.Contents |
LastModified
|
Date and time the object was last modified. Type: Date Ancestor: ListBucketResult.Contents |
Marker
|
Indicates where in the bucket listing begins. 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 |
Owner
|
Bucket owner. Type: String Children: DisplayName, ID Ancestor: ListBucketResult.Contents | CommonPrefixes |
Prefix
|
Keys that begin with the indicated prefix. Type: String Ancestor: ListBucketResult |
Size
|
Size in bytes of the object. Type: String Ancestor: ListBucketResult.Contents |
StorageClass
|
STANDARD | REDUCED_REDUNDANCY | GLACIER Type: String Ancestor: ListBucketResult.Contents |
Special Errors
This implementation of the operation does not return special errors. For general information about Amazon S3 errors and a list of error codes, see Error Responses.
Examples
Sample Request
This requests returns the objects in BucketName.
GET / HTTP/1.1 Host: BucketName.s3.amazonaws.com Date: Wed, 12 Oct 2009 17:50:00 GMT Authorization: AWS AKIAIOSFODNN7EXAMPLE:xQE0diMbLRepdf3YB+FIEXAMPLE= Content-Type: text/plain
Sample Response
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>bucket</Name>
<Prefix/>
<Marker/>
<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>
<StorageClass>STANDARD</StorageClass>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>mtd@amazon.com</DisplayName>
</Owner>
</Contents>
<Contents>
<Key>my-third-image.jpg</Key>
<LastModified>2009-10-12T17:50:30.000Z</LastModified>
<ETag>"1b2cf535f27731c974343645a3985328"</ETag>
<Size>64994</Size>
<StorageClass>STANDARD</StorageClass>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>mtd@amazon.com</DisplayName>
</Owner>
</Contents>
</ListBucketResult>Sample Request Using Request Parameters
This example lists up to 40 keys in the "quotes" bucket that start with "N" and occur lexicographically after "Ned".
GET /?prefix=N&marker=Ned&max-keys=40 HTTP/1.1 Host: quotes.s3.amazonaws.com Date: Wed, 01 Mar 2009 12:00:00 GMT Authorization: AWS AKIAIOSFODNN7EXAMPLE:xQE0diMbLRepdf3YB+FIEXAMPLE=
Sample Response
HTTP/1.1 200 OK
x-amz-id-2: gyB+3jRPnrkN98ZajxHXr3u7EFM67bNgSAxexeEHndCX/7GRnfTXxReKUQF28IfP
x-amz-request-id: 3B3C7C725673C630
Date: Wed, 01 Mar 2009 12:00:00 GMT
Content-Type: application/xml
Content-Length: 302
Connection: close
Server: AmazonS3
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>quotes</Name>
<Prefix>N</Prefix>
<Marker>Ned</Marker>
<MaxKeys>40</MaxKeys>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>Nelson</Key>
<LastModified>2006-01-01T12:00:00.000Z</LastModified>
<ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
<Size>5</Size>
<StorageClass>STANDARD</StorageClass>
<Owner>
<ID>bcaf161ca5fb16fd081034f</ID>
<DisplayName>webfile</DisplayName>
</Owner>
</Contents>
<Contents>
<Key>Neo</Key>
<LastModified>2006-01-01T12:00:00.000Z</LastModified>
<ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
<Size>4</Size>
<StorageClass>STANDARD</StorageClass>
<Owner>
<ID>bcaf1ffd86a5fb16fd081034f</ID>
<DisplayName>webfile</DisplayName>
</Owner>
</Contents>
</ListBucketResult>Sample Request Using Prefix and Delimiter
Assume you have the following keys in your bucket.
sample.jpg
photos/2006/January/sample.jpg
photos/2006/February/sample2.jpg
photos/2006/February/sample3.jpg
photos/2006/February/sample4.jpg
The following GET request specifies the delimiter parameter with value "/".
GET /?delimiter=/ HTTP/1.1 Host: example-bucket.s3.amazonaws.com Date: Wed, 01 Mar 2009 12:00:00 GMT Authorization: AWS AKIAIOSFODNN7EXAMPLE:xQE0diMbLRepdf3YB+FIEXAMPLE=
The key sample.jpg does not contain the delimiter character, and
Amazon S3 returns it in the Contents element in the response.
However, all other keys contain the delimiter character. Amazon S3 groups these keys
and return a single CommonPrefixes element with prefix value
photos/ that is a substring from the beginning of these
keys to the first occurrence of the specified delimiter.
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>example-bucket</Name>
<Prefix></Prefix>
<Marker></Marker>
<MaxKeys>1000</MaxKeys>
<Delimiter>/</Delimiter>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>sample.html</Key>
<LastModified>2011-02-26T01:56:20.000Z</LastModified>
<ETag>"bf1d737a4d46a19f3bced6905cc8b902"</ETag>
<Size>142863</Size>
<Owner>
<ID>canonical-user-id</ID>
<DisplayName>display-name</DisplayName>
</Owner>
<StorageClass>STANDARD</StorageClass>
</Contents>
<CommonPrefixes>
<Prefix>photos/</Prefix>
</CommonPrefixes>
</ListBucketResult>The following GET request specifies the delimiter parameter with value
"/", and the prefix parameter with value
photos/2006/.
GET /?prefix=photos/2006/&delimiter=/ HTTP/1.1 Host: example-bucket.s3.amazonaws.com Date: Wed, 01 Mar 2009 12:00:00 GMT Authorization: AWS AKIAIOSFODNN7EXAMPLE:xQE0diMbLRepdf3YB+FIEXAMPLE=
In response, Amazon S3 returns only the keys that start with the specified prefix. Further,
it 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 Amazon S3 returns one <CommonPrefixes> element in the response.
The keys grouped under this CommonPrefixes element are not
returned elsewhere in the response. The value returned in the
CommonPrefixes element is a substring from the beginning of the key
to 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>
<Marker></Marker>
<MaxKeys>1000</MaxKeys>
<Delimiter>/</Delimiter>
<IsTruncated>false</IsTruncated>
<CommonPrefixes>
<Prefix>photos/2006/feb/</Prefix>
</CommonPrefixes>
<CommonPrefixes>
<Prefix>photos/2006/jan/</Prefix>
</CommonPrefixes>
</ListBucketResult>
