List objects

To list the objects in a bucket you make a GET request that is scoped to a bucket. You can also use query string parameters to further scope the request. The request returns the list of objects in an XML document in the response body.

You must have bucket READ permission to get the list of objects that are in a bucket, and you must have bucket FULL_CONTROL permission to list a bucket's ACLs or CORS.

You can restrict and organize the list of objects that is returned in a GET Bucket request by using the delimiter, marker, max-keys, and prefix query string parameters. The marker query string parameter is a string of Unicode characters that specifies the object after which you want to start listing objects. Any objects whose names are lexicographically greater than the marker are returned in the list of objects. The max-keys query string parameter is an integer that specifies the maximum number of objects you want returned in the list of objects. If a request can return more objects than max-keys allows, the IsTruncated response element contains a True value and the NextMarker response element returns the name of the last object in the list. The returned NextMarker value can then be used as the new marker in another request.

The prefix query string parameter is a string of Unicode characters that restricts the listing to objects whose names begin with the string specified by the prefix. You can use the prefix query string parameter in conjunction with the delimiter query string parameter to create a smaller subset of objects.

The delimiter is a single character or multiple characters and is used to simplify a list of objects that use a directory-like naming scheme. For more information about using a delimiter, see delimiter.

The XML API does not return lists longer than 1000 objects.

Query string parameters

Parameter Description Required
delimiter A character or multiple characters that can be used to simplify a list of objects that use a directory-like naming scheme. Can be used in conjunction with a prefix. No
generation-marker The object generation after which you want to start listing objects. If you use generation-marker, you must also use marker. No
marker The object name after which you want to start listing objects. No
max-keys The maximum number of objects to return in a list object request. No
prefix A string that can be used to limit the number of objects that are returned in a GET Bucket request. Can be used in conjunction with a delimiter. No
versions If specified on a versioned bucket, returns the list of all object versions. If omitted, only lists current versions. No

Request headers

See common request headers.

Request body elements

This request does not include an XML document in the request body.

Request syntax

The following syntax applies to GET Bucket requests that use either no parameters, or one or more of the delimiter, generation- marker, marker, max-keys, prefix, and versions query string parameters.

GET /?prefix=a_prefix&marker=a_marker&max-keys=max_number_of_keys&delimiter=a_delimiter HTTP/1.1
Host: <bucket>.storage.googleapis.com
Date: <date>
Content-Length: <request body length>
Authorization: <authentication string>

Response headers

The request can return a variety of response headers depending on the request headers you use.

Response body elements

The following response body elements are applicable only if you use either no parameters, or one or more of the delimiter, generation-marker, marker, max-keys, prefix, or versions query string parameters to list objects in a bucket.

Element Description
ListBucketResult Container for the object information you are requesting.
Name The bucket name.
CommonPrefixes Container for prefixes that satisfy your prefix and delimiter constraints. This container is used only if you specify a delimiter and a prefix in the request.
Delimiter The delimiter that you specified in the request.
MaxKeys The max-keys that you specified in the request.
Prefix The prefix that you specified in the request.
GenerationMarker The generation-marker that you specified in the request.
NextGenerationMarker If the list of returned objects is incomplete and versions parameter was used, NextGenerationMarker provides the generation of the last object that was returned. If the list is already complete, NextGenerationMarker is not returned.
Marker The marker that you specified in the request.
NextMarker NextMarker provides the name of the last object that was returned. The value of NextMarker can be provided in the marker query string parameter in a future GET Bucket call to continue listing the Bucket after this set of results. If there are no more objects in the Bucket that follow the last object in the list, NextMarker is not returned.
IsTruncated Indicates whether or not all of the objects in a bucket appear on the list. If max-keys is less than the number of objects in a bucket, this element is True.
Contents Container for object information if versions query parameter is not used.
Version Container for object information if versions query parameter is used.
Key The name of an object.
Generation The generation of the object.
MetaGeneration Generation of the metadata of the object.
IsLatest If versions query parameter specified, this is set to true if the object is currently live. Live meaning that if this object is requested without generation, this object is returned.
LastModified The date and time that the object metadata was last modified.
DeletedTime If versions query parameter was specified, contains the date and time that an object was overwritten or deleted for non-current objects (if the bucket has versioning enabled).
ETag An HTTP 1.1 entity tag for the object.
Size Size of the object in bytes.
KmsKeyName The name of the KMS key used to encrypt the object. This element is only present if the object is encrypted with Customer-Managed Encryption Keys.

Examples

The following sample lists the objects in a bucket named travel-maps.

Request

GET / HTTP/1.1
Host: travel-maps.storage.googleapis.com
Date: Wed, 17 Feb 2010 15:31:56 GMT
Content-Length: 0
Content-Type: text/plain
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

Response

HTTP/1.1 200 OK
 Content-Length: 4061
 Content-Type: application/xml
 Date: Wed, 17 Feb 2010 23:31:57 GMT
 Expires: Wed, 17 Feb 2010 23:31:57 GMT

<?xml version='1.0' encoding='utf-8'?>
<ListBucketResult xmlns='http://doc.s3.amazonaws.com/2006-03-01'>
  <Name>travel-maps</Name>
  <Prefix></Prefix>
  <Marker></Marker>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>europe/france/cannes.pdf</Key>
    <Generation>1360887759327000</Generation>
    <MetaGeneration>1</MetaGeneration>
    <LastModified>2010-02-17T22:11:12.487Z</LastModified>
    <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag>
    <Size>5061631</Size>
  </Contents>
  <Contents>
    <Key>europe/france/paris.pdf</Key>
    <Generation>1360887759329000</Generation>
    <MetaGeneration>1</MetaGeneration>
    <LastModified>2010-02-17T22:09:57.457Z</LastModified>
    <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag>
    <Size>5061631</Size>
  </Contents>
</ListBucketResult>

The following sample lists the objects in travel-maps, but it restricts the list to 25 objects that begin with the letter "t" and come after "test".

Request

GET /?prefix=t&marker=test&max-keys=25 HTTP/1.1
Host: travel-maps.storage.googleapis.com
Date: Mon, 16 Feb 2010 22:58:38 GMT
Content-Length: 0
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

Response

HTTP/1.1 200 OK
Date: Mon, 15 Feb 2010 12:30:40 GMT
Content-Length: 2705
Content-Type: application/xml

<?xml version='1.0' encoding='utf-8'?>
<ListBucketResult xmlns='http://doc.s3.amazonaws.com/2006-03-01'>
  <Name>travel-maps</Name>
  <Prefix>t</Prefix>
  <Marker>test</Marker>
  <MaxKeys>25</MaxKeys>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>test_a.jpg</Key>
    <Generation>1360887659329000</Generation>
    <MetaGeneration>1</MetaGeneration>
    <LastModified>2010-02-17T03:12:55.561Z</LastModified>
    <ETag>"2281880ef78388266ecd7d4c1b472a0e"</ETag>
    <Size>328</Size>
  </Contents>
  <Contents>
    <Key>test_b.jpg</Key>
    <Generation>1360887659323000</Generation>
    <MetaGeneration>1</MetaGeneration>
    <LastModified>2010-02-17T03:12:54.606Z</LastModified>
    <ETag>"2281880ef78388266ecd7d4c1b472a0e"</ETag>
    <Size>328</Size>
  </Contents>
  <Contents>
    <Key>test_c.jpg</Key>
    <LastModified>2010-02-17T03:12:53.734Z</LastModified>
    <ETag>"2281880ef78388266ecd7d4c1b472a0e"</ETag>
    <Size>328</Size>
  </Contents>
</ListBucketResult>

The following example uses a prefix and a delimiter to return a list of objects that are named using a directory-like schema. The prefix and delimiter restrict the list of objects so that only those objects that are in the europe directory are returned. Objects that are in subdirectories of the europe directory are not listed.The sample assumes that the following objects are contained in a bucket named travel- maps:

  • africa/ghana.jpg
  • africa/egypt/cairo.jpg
  • europe/finland.jpg
  • europe/norway.jpg
  • europe/france/paris.jpg
  • europe/italy/rome.jpg
  • europe/sweden/stockholm.jpg
  • europe/sweden/stockholm/nordic_museum.jpg

The sample request returns an XML document that lists the following two objects in the Contents element:

  • europe/finland.jpg
  • europe/norway.jpg

The following europe subdirectories are listed in the CommonPrefixes element:

  • europe/france/
  • europe/italy/
  • europe/sweden/

Request

GET /travel-maps?delimiter=/&prefix=europe/ HTTP/1.1
Host: storage.googleapis.com
Date: Mon, 16 Feb 2010 22:58:38 GMT
Content-Length: 0
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

Response

HTTP/1.1 200 OK
Date: Mon, 15 Feb 2010 12:30:40 GMT
Content-Length: 1200
Content-Type: application/xml

<?xml version="1.0"?>
<ListBucketResult xmlns='http://doc.s3.amazonaws.com/2006-03-01'>
  <Name>mybucket</Name>
  <Prefix>europe/</Prefix>
  <Marker />
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>europe/finland.jpg</Key>
    <Generation>1360887659323000</Generation>
    <MetaGeneration>1</MetaGeneration>
    <LastModified>2010-02-17T03:12:55.561Z</LastModified>
    <ETag>"781e5e245d69b566979b86e28d23f2c7"</ETag>
    <Size>10</Size>
  </Contents>
  <Contents>
    <Key>europe/norway.jpg</Key>
    <Generation>1360887659323000</Generation>
    <MetaGeneration>1</MetaGeneration>
    <LastModified>2010-02-17T03:12:55.561Z</LastModified>
    <ETag>"781e5e245d69b566979b86e28d23f2c7"</ETag>
    <Size>10</Size>
  </Contents>
  <CommonPrefixes>
    <Prefix>europe/france/</Prefix>
  </CommonPrefixes>
  <CommonPrefixes>
    <Prefix>europe/italy/</Prefix>
  </CommonPrefixes>
  <CommonPrefixes>
    <Prefix>europe/sweden/</Prefix>
  </CommonPrefixes>
</ListBucketResult>
此页内容是否有用？请给出您的反馈和评价：

发送以下问题的反馈：

此网页
文档反馈
Cloud Storage
产品反馈
需要帮助？请访问我们的支持页面。