Prev

Next

Listing Keys

You can retrieve an ordered list of keys for objects contained in your bucket by executing an HTTP GET on the bucket. To help narrow the list, you can specify a key prefix that will ensure only keys matching the prefix are returned. For each key returned, the List operation will also return some basic information about the object represented by the key, including the size of the object, an ETag, a timestamp for the last modification on the object, and, if you are the owner of the target bucket, an identifier for the user that last modified the object.

The following sample code snippets demonstrate listing keys.

Java

To run the sample

Open the sample file.
Replace bucket-name with the name of your bucket.

Use the following sample to test different list operations.

// simple list
ListBucketResponse response =
    conn.listBucket("[bucket-name]", null, null, null, null);

List objects = response.entries;
for (Iterator it = objects.iterator(); it.hasNext(); ) {
    ListEntry entry = (ListEntry)it.next();
    System.out.println("key = " + entry.key + " size = " + entry.size);
}

// list only things starting with "foo"
response = conn.listBucket("[bucket-name]", "foo", null, null, null);

// list only things that come after "bar" alphabetically
response = conn.listBucket("[bucket-name]", null, "bar", null, null);

// only list 3 things
response = conn.listBucket("[bucket-name]", null, null, new Integer(3), null);

C#

To run the sample

Open the sample file.
Replace bucket-name with the name of your bucket.

Use the following sample to test different list operations.

// simple list
ListBucketResponse response =
    conn.listBucket("[bucket-name]", null, null, 0, null);

foreach( ListEntry entry in response.Entries ) {
    System.Console.WriteLine("key = " + entry.Key + " size = " + entry.Size);
}

// list only things starting with "foo"
response = conn.listBucket("[bucket-name]", "foo", null, 0, null);

// list only things that come after "bar" alphabetically
response = conn.listBucket("[bucket-name]", null, "bar", 0, null);

// only list 3 things
response = conn.listBucket("[bucket-name]", null, null, 3, null);

Perl

To run the sample

Open the sample file.
Replace bucket-name with the name of your bucket.

Use the following sample to test different list operations.

# simple list
my $response = $conn->list_bucket("[bucket-name]");

foreach my $entry (@{$response->entries}) {
    print "key = $entry->{Key} size = $entry->{Size}\n";
}

# list only things starting with "foo"
$response = $conn->list_bucket("[bucket-name]", {prefix => "foo"});

# list only things that come after "bar" alphabetically
$response = $conn->list_bucket("[bucket-name]", {marker => "bar"});

# only list 3 things
$response = $conn->list_bucket("[bucket-name]", {"max-keys" => 3});

PHP

To run the sample

Open the sample file.
Replace bucket-name with the name of your bucket.

Use the following sample to test different list operations.

$req =& new HTTP_Request("http://s3.amazonaws.com/[bucket-name]");
$req->setMethod("GET");
setAuthorizationHeader($req);
$req->sendRequest();

if ($req->getResponseCode() == 200) {
    $listXml = $req->getResponseBody();
} else {
    // something bad happened
}

// list only things starting with "foo"
$req =& new HTTP_Request("http://s3.amazonaws.com/[bucket-name]/?prefix=foo");
...

// list only things that come after "bar" alphabetically
$req =& new HTTP_Request("http://s3.amazonaws.com/[bucket-name]/?marker=bar");
...

# only list 3 things
$req =& new HTTP_Request("http://s3.amazonaws.com/[bucket-name]/?max-keys=3");
...

Ruby

To run the sample

Open the sample file.
Replace bucket-name with the name of your bucket.

Use the following sample to test different list operations.

response = conn.list_bucket("[bucket-name]");

response.entries.each do |entry|
    print "key = #{entry.key} size = #{entry.size}\n"
end

# list only things starting with "foo"
response = conn.list_bucket("[bucket-name]", {"prefix" => "foo"});

# list only things that come after "bar" alphabetically
response = conn.list_bucket("[bucket-name]", {"marker" => "bar"});

# only list 3 things
response = conn.list_bucket("[bucket-name]", {"max-keys" => "3"});

Python

To run the sample

Open the sample file.
Replace bucket-name with the name of your bucket.

Use the following sample to test different list operations.

# simple list
response = conn.list_bucket("[bucket-name]");

for entry in response.entries:
    print "key = %s size = %d" % (entry.key, entry.size)

# list only things starting with "foo"
response = conn.list_bucket("[bucket-name]", {"prefix": "foo"});

# list only things that come after "bar" alphabetically
response = conn.list_bucket("[bucket-name]", {"marker": "bar"});

# only list 3 things
response = conn.list_bucket("[bucket-name]", {"max-keys" => "3"});

HTTP

The following is an example of an HTTP request.

# list bucket request

GET /[test-bucket] HTTP/1.0
Date: Wed, 08 Mar 2006 04:06:17 GMT
Authorization: AWS [aws-access-key-id]:[header-signature]
Host: s3.amazonaws.com

# list bucket response (xml pretty formatted)

HTTP/1.1 200 OK
x-amz-id-2: 0rSP+1mPucqZ95lYmd53HsgDr6fi2KK8j1uNHz81AngfeOAIaVpNnOBLQ/B9pXJ/
x-amz-request-id: 317FD4EE0A1984DD
Date: Wed, 08 Mar 2006 04:06:17 GMT
Content-Type: application/xml
Connection: close
Server: AmazonS3
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://webservices.amazon.com/schema/request">
  <Name>[bucket-name]</Name>
  <Prefix/>
  <Marker/>
  <MaxKeys>1000</MaxKeys>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>>[key-name]</Key>
    <LastModified>2006-03-07T20:06:18.000-08:00</LastModified>
    <ETag>"54b0c58c7ce9f2a8b551351102ee0938"</ETag>
    <Size>14</Size>
    <Owner>
      <ID>AmazonCustomer|[amazon-id]</ID>
      <DisplayName>[display-name]</DisplayName>
    </Owner>
    <StorageClass>STANDARD<StorageClass>
  </Contents>
</ListBucketResult>

	Copyright Information