此页面由 Cloud Translation API 翻译。
Switch to English

列出对象

要列出存储分区中的对象,您可以发出 范围限定为存储分区的 GET 请求。您还可以使用查询字符串参数来进一步限定请求范围。 该请求会在响应正文的 XML 文档中返回对象列表,而列表中的对象按名称按名称排序。

您必须具有存储分区 READ 权限才能获取存储分区中的对象列表,并且必须具有存储分区 FULL_CONTROL 权限才能列出存储分区的 ACL 或 CORS。

您可以使用 delimitermarkermax-keysprefix 查询字符串参数来限制和整理 GET Bucket 请求中返回的对象列表。

XML API 返回的列表数不超过 1000 个。

查询字符串参数

参数 说明 必需
delimiter 一个字符或多个字符,可用于简化使用类目录命名方案的对象列表。可与 prefix 结合使用。
encoding-type 设置为 url 时,系统会在响应中对对象名称进行网址编码。
generation-marker 开始生成对象后,用于生成对象的对象。如果您使用世代标记,则还必须使用标记。
marker 指定后要用于开始列出对象的对象名称。对象名称按字典顺序大于 marker 的对象将在对象列表中返回。
max-keys 列表对象请求中可返回的对象数上限。
prefix 一个字符串,可用于将 GET Bucket 请求中返回的对象数量限制为名称以指定值开头的对象。可与 delimiter 结合使用。
versions 如果在启用了版本控制的存储分区中指定,则返回所有对象版本的列表。如果省略,则仅列出当前版本。

如需了解您在创建和使用签名网址时包含的参数,请参阅签名网址查询字符串参数

请求标头

请参阅常见请求标头

请求正文元素

此请求不包含 XML 文档。

请求语法

以下语法适用于不使用任何或一个或多个 delimitergeneration-markermarkermax-keysprefix 的 GET Bucket 请求,以及 versions 查询字符串参数。

GET /?prefix=a_prefix&marker=a_marker&max-keys=max_number_of_keys&delimiter=a_delimiter HTTP/1.1
Host: BUCKET_NAME.storage.googleapis.com
Date: DATE
Content-Length: 0
Authorization: AUTHENTICATION_STRING

响应标头

请求可以返回各种响应标头,具体取决于您使用的请求标头。

响应正文元素

以下响应正文元素仅适用于未使用任何参数或一个或多个参数delimitergeneration-markermarkermax-keysprefixversions查询字符串参数以列出存储分区中的对象。

元素 说明
ListBucketResult 您所请求的对象信息的容器。
Name 存储分区名称。
CommonPrefixes 用于满足 prefixdelimiter 约束的前缀的容器。只有当您在请求中指定 delimiter 并省略重复条目时,才会使用此容器。
Delimiter 您在请求中指定的 delimiter
MaxKeys 您在请求中指定的 max-keys
Prefix 您在请求中指定的 prefix
GenerationMarker 您在请求中指定的 generation-marker
NextGenerationMarker 如果返回对象的列表不完整且使用了 versions 参数,则 NextGenerationMarker 会提供所返回的最后一个对象。如果此列表已存在,则返回 NextGenerationMarker
Marker 您在请求中指定的 marker
NextMarker NextMarker 返回返回的最后一个对象的名称。可以在未来的 GET Bucket 调用的 marker 查询字符串参数中提供 NextMarker 的值,以继续在此结果集之后列出存储分区。如果存储分区中再没有出现在列表中的最后一个对象之后,则不会返回 NextMarker
IsTruncated 表示存储分区中的所有对象是否出现在列表中。如果 max-keys 小于存储分区中的对象数量,则此元素为 True。
Contents 如果未使用 versions 查询参数,则用于存储对象信息的容器。
Version 如果使用 versions 查询参数,则提供对象信息的容器。
Key 对象的名称。
Generation 对象的生成。
MetaGeneration 生成对象的元数据。
IsLatest 如果指定了 versions 查询参数,且对象当前处于活动状态,则将此设为 true。实时表示,如果在未生成的情况下请求此对象,则会返回此对象。
LastModified 对象元数据的最后修改日期和时间。
DeletedTime 如果指定了 versions 查询参数,则对象包含当前对象或为非当前对象替换或删除的日期和时间(如果存储分区启用了版本控制)。
ETag 对象的 HTTP 1.1 实体标记
Size 此对象的大小(以字节为单位)。
KmsKeyName 用于加密对象的 KMS 密钥的名称。只有使用 客户管理的加密密钥加密对象时,此元素才会显示。

示例

以下示例会列出名为 travel-maps 的存储分区中的对象。

请求

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

响应

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>

以下示例列出了 travel-map 中的对象,但它将列表限制为 25 个以字母“t”开头并出现在“test”之后的对象。

请求

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

响应

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>

使用前缀和分隔符的示例

以下示例使用 prefixdelimiter 返回使用类似目录架构命名的对象列表。使用 prefix=europe/delimiter=/,则仅返回 europe/“目录”中的对象。欧洲目录的“子目录”中不会列出对象,而其名称包含在响应的 CommonPrefixes 元素中。该示例假定以下对象包含在名为 travel-maps 的存储分区中:

  • afria/ghana.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

示例请求会返回一个 XML 文档,其中列出了 Contents 元素中的以下两个对象:

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

CommonPrefixes 元素列出了以下欧洲子目录:

  • 欧洲/法国/
  • 欧洲/italy/
  • 欧洲/斯温登/

请求

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

响应

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>