GET Bucket (List Objects) Version 1
Description
Important
This API has been revised. We recommend that you use the newer version, GET Bucket (List Objects) version 2, when developing applications. For more information, see GET Bucket (List Objects) Version 2. For backward compatibility, Amazon S3 continues to support GET Bucket (List Objects) version 1.
This implementation of the GET
operation returns some or all (up to 1,000) 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. A 200 OK
response can contain
valid or invalid XML. Be sure to design your application to parse the contents
of the
response and handle it
appropriately.
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:date
Authorization:authorization string
(see Authenticating Requests (AWS Signature Version 4))
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. If you specify a Type: String Default: None |
No |
encodingtype |
Requests Amazon S3 to encode the response and specifies the encoding method to use. An object key can contain any Unicode character. However, XML 1.0 parsers cannot parse some characters, such as characters with an ASCII value from 0 to 10. For characters that are not supported in XML 1.0, you can add this parameter to request that Amazon S3 encode the keys in the response. Type: String Default: None Valid value: |
No |
marker |
Specifies the key to start with when listing objects in a bucket. Amazon S3 returns object keys in UTF-8 binary order, starting with key after the marker in order. Type: String Default: None |
No |
max-keys |
Sets the maximum number of keys returned in the response body. If you want to retrieve fewer than the default 1,000 keys, you can add this to your request. The response might contain fewer keys, but it never contains more. If there are
additional keys that satisfy the search criteria, but these keys
were not returned because Type: String Default: 1,000 |
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: |
CommonPrefixes
|
All of the keys rolled up in a common prefix count as a
single return when calculating the number of returns. See
For example, if the prefix is Type: String Ancestor: |
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: |
DisplayName
|
Object owner's name. Important This value is only included in the response in the US East (N. Virginia), US West (N. California), US West (Oregon), Asia Pacific (Singapore), Asia Pacific (Sydney), Asia Pacific (Tokyo), EU (Ireland), and South America (São Paulo) regions. For a list of all the Amazon S3 supported regions and endpoints, see Regions and Endpoints in the AWS General Reference. Type: String Ancestor: |
Encoding-Type
|
Encoding type used by Amazon S3 to encode object key names in the XML response. If you specify the
Type: String Ancestor: |
ETag
|
The entity tag is an MD5 hash of the object. The Type: String Ancestor: |
ID
|
Object owner's ID. Type: String Ancestor: |
IsTruncated
|
Specifies whether ( Type: Boolean Ancestor: |
Key
|
The object's key. Type: String Ancestor: |
LastModified
|
Date and time the object was last modified. Type: Date Ancestor: |
Marker
|
Indicates where in the bucket listing begins. Type: String Ancestor: |
MaxKeys
|
The maximum number of keys returned in the response body. Type: String Ancestor: |
Name
|
Name of the bucket. Type: String Ancestor: |
NextMarker
|
When the response is truncated (that is, the Note This element is returned only if you specify a
Type: String Ancestor: |
Owner
|
Bucket owner. Type: String Children: DisplayName, ID Ancestor: |
Prefix
|
Keys that begin with the indicated prefix. Type: String Ancestor: |
Size
|
Size in bytes of the object. Type: String Ancestor: |
StorageClass
|
Type: String Ancestor: |
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 request returns the objects in BucketName
.
GET / HTTP/1.1 Host: BucketName.s3.amazonaws.com Date: Wed, 12 Oct 2009 17:50:00 GMT Authorization:
authorization string
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_IA</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 2006 12:00:00 GMT Authorization:
authorization string
Sample Response
HTTP/1.1 200 OK x-amz-id-2: gyB+3jRPnrkN98ZajxHXr3u7EFM67bNgSAxexeEHndCX/7GRnfTXxReKUQF28IfP x-amz-request-id: 3B3C7C725673C630 Date: Wed, 01 Mar 2006 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 a Prefix and Delimiter
For this example, we assume that 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 2006 12:00:00 GMT Authorization:
authorization string
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 returns 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.jpg</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
the value /
, and the prefix
parameter with the value
photos/2006/
.
GET /?prefix=photos/2006/&delimiter=/ HTTP/1.1 Host: example-bucket.s3.amazonaws.com Date: Wed, 01 Mar 2006 12:00:00 GMT Authorization:
authorization string
In response, Amazon S3 returns only the keys that start with the specified prefix.
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 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> <Marker></Marker> <MaxKeys>1000</MaxKeys> <Delimiter>/</Delimiter> <IsTruncated>false</IsTruncated> <CommonPrefixes> <Prefix>photos/2006/February/</Prefix> </CommonPrefixes> <CommonPrefixes> <Prefix>photos/2006/January/</Prefix> </CommonPrefixes> </ListBucketResult>