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.
Requests
Syntax
GET / HTTP/1.1 Host:BucketName
.s3.amazonaws.com Date:date
Authorization: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 the prefix and the first
occurrence of the delimiter are grouped under a single result
element, Type: String Default: None | No |
key-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 only uses request headers common to all operations. For more information, see
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: Boolean Ancestor: ListBucketResult.Contents.Owner |
IsTruncated
|
Specifies whether ( Type: String Ancestor: boolean |
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 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 |
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
|
Always STANDARD. 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 15B4D3461F177624206A: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>8a6925ce4a7f21c32aa379004fef</ID> <DisplayName>[email protected]</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>8a69b1ddee97f21c32aa379004fef</ID> <DisplayName>[email protected]</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 15B4D3461F177624206A: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
This example lists rolls up all objects for each URI that starts with photos/2006/, has some path element, and ends with the first occurrence of the delimiter "/", for example, each of the following would become a CommonPrefixes entry: photos/2006/January/, photos/2006/February/, and photos/2006/March/
GET ?prefix=photos/2006/&delimiter=/ HTTP/1.1 Host: quotes.s3.amazonaws.com Date: Wed, 01 Mar 2009 12:00:00 GMT Authorization: AWS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=
Sample Response
<?xml version="1.0" encoding="UTF-8"?> <ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01"> <Name>johnsmith</Name> <Prefix>photos/2006/</Prefix> <Marker/> <MaxKeys>1000</MaxKeys> <Delimiter>/</Delimiter> <IsTruncated>false</IsTruncated> <Contents> <Key>photos/2006/index.html</Key> <LastModified>2009-01-01T12:00:00.000Z</LastModified> <ETag>"ce1acdafcc879d7eee54cf4e97334078"</ETag> <Size>1234</Size> <Owner> <ID>214153b66967d86f031c7487b4566cb1b</ID> <DisplayName>John Smith</DisplayName> </Owner> <StorageClass>STANDARD</StorageClass> </Contents> <CommonPrefixes> <Prefix>photos/2006/January/</Prefix> </CommonPrefixes> </ListBucketResult>