|« PreviousNext »|
|Did this page help you? Yes | No | Tell us about it...|
The prefix and delimiter parameters limit the kind of results returned by a list operation. Prefix limits results to only those keys that begin with the specified prefix, and delimiter causes list to roll up all keys that share a common prefix into a single summary list result.
The purpose of the prefix and delimiter parameters is to help you organize and then browse your keys hierarchically. To do this, first pick a delimiter for your bucket, such as slash (/), that doesn't occur in any of your anticipated key names. Next, construct your key names by concatenating all containing levels of the hierarchy, separating each level with the delimiter.
For example, if you were storing information about cities, you might naturally organize them by continent, then by country, then by province or state. Because these names don't usually contain punctuation, you might select slash (/) as the delimiter. The following examples use a slash (/) delimiter.
If you stored data for every city in the world in this manner, it would become
awkward to manage a flat key namespace. By using
Delimiter with the list operation, you can use the
hierarchy you've created to list your data. For example, to list all the states in
Prefix='North America/USA/'. To list all the provinces in Canada for
which you have data, set
A list request with a delimiter lets you browse your hierarchy at just one level, skipping
over and summarizing the (possibly millions of) keys nested at deeper levels. For
example, assume you have a bucket (
ExampleBucket) the following
The sample bucket has only the
sample.jpg object at the root level. To list only the root level
objects in the bucket you send a GET request on the bucket with "/" delimiter
character. In response, Amazon S3 returns the
sample.jpg object key because it does
not contain the "/" delimiter character. All other keys contain the
delimiter character. Amazon S3 groups these keys and return a single
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>ExampleBucket</Name> <Prefix></Prefix> <Marker></Marker> <MaxKeys>1000</MaxKeys> <Delimiter>/</Delimiter> <IsTruncated>false</IsTruncated> <Contents> <Key>sample.jpg</Key> <LastModified>2011-07-24T19:39:30.000Z</LastModified> <ETag>"d1a7fb5eab1c16cb4f7cf341cf188c3d"</ETag> <Size>6</Size> <Owner> <ID>75cc57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID> <DisplayName>displayname</DisplayName> </Owner> <StorageClass>STANDARD</StorageClass> </Contents> <CommonPrefixes> <Prefix>photos/</Prefix> </CommonPrefixes> </ListBucketResult>