View a markdown version of this page

ListBucket（SOAP API） - Amazon Simple Storage Service
请求成功响应响应正文访问控制

ListBucket（SOAP API）

注意

Amazon S3 的 SOAP API 不适用于新客户，并将于 2025 年 8 月 31 日接近使用寿命终止（EOL）。我们建议您使用 REST API 或 AWS SDK。

ListBucket 操作返回有关存储桶中某些项目的信息。

有关列表操作的一般介绍，请参阅列出对象键。

请求

此示例列出了“quotes”存储桶中最多 1000 个带有前缀“notes”的键。

语法

<ListBucket xmlns="https://doc.s3.amazonaws.com/2006-03-01">
  <Bucket>quotes</Bucket>
  <Prefix>notes/</Prefix>
  <Delimiter>/</Delimiter>
  <MaxKeys>1000</MaxKeys>
  <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
  <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
  <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</ListBucket>

参数

名称 描述 必填
prefix

将响应限制为以指定的前缀开头的键。您可以使用前缀将存储桶分成不同的键集，其方式与文件系统使用文件夹的方式类似。

类型：字符串

默认值：无

 否
marker

指明要在存储桶中的哪个位置开始列出。该列表将仅包括按字典顺序出现在标记之后的键。这便于分页：要获取下一页的结果，请使用当前页面的最后一个键作为标记。

类型：字符串

默认值：无

 否
max-keys

您希望在响应正文中看到的最大键数。服务器返回的键数可能少于这个数量，但返回的键数不会多于此数量。

类型：字符串

默认值：无

 否
delimiter

导致在前缀和首次出现的分隔符之间包含相同字符串的键汇总到 CommonPrefixes 集合的单个结果元素中。这些汇总的键不会在响应中的其它地方返回。

类型：字符串

默认值：无

 否

成功响应

此响应假设存储桶包含以下键：

notes/todos.txt
notes/2005-05-23/customer_mtg_notes.txt
notes/2005-05-23/phone_notes.txt
notes/2005-05-28/sales_notes.txt

语法

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Name>backups</Name>
  <Prefix>notes/</Prefix>
  <MaxKeys>1000</MaxKeys>
  <Delimiter>/</Delimiter>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>notes/todos.txt</Key>
    <LastModified>2006-01-01T12:00:00.000Z</LastModified>
    <ETag>&quot;828ef3fdfa96f00ad9f27c383fc9ac7f&quot;</ETag>
    <Size>5126</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
      <DisplayName>webfile</DisplayName>
    </Owner>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
  <CommonPrefixes>
    <Prefix>notes/2005-05-23/</Prefix>
  </CommonPrefixes>
  <CommonPrefixes>
    <Prefix>notes/2005-05-28/</Prefix>
  </CommonPrefixes>
  </ListBucketResult>

如您所见，响应中的许多字段都与请求参数相呼应。IsTruncated、Contents 和 CommonPrefixes 是仅有的可以包含新信息的响应元素。

响应元素

名称 描述
Contents

有关返回的每个对象的元数据。

类型：XML 元数据

原级：ListBucketResult
CommonPrefixes

仅当您指定 delimiter 时，响应才会包含 CommonPrefixes。当您这样做时，CommonPrefixes 包含 Prefix 与由 delimiter 指定的字符串的下一次出现之间的所有（如果有的话）键。实际上，CommonPrefixes 会列出在 Prefix 指定的目录中充当子目录的键。例如，如果 prefix 是 notes/，delimiter 是斜杠（/），则在 notes/summer/july 中，常见前缀是 notes/summer/。

类型：字符串

原级：ListBucketResult
Delimiter

导致在前缀和首次出现的分隔符之间包含相同字符串的键汇总到 CommonPrefixes 集合的单个结果元素中。这些汇总的键不会在响应中的其它地方返回。

类型：字符串

原级：ListBucketResult
IsTruncated

指定是（true）否（false）返回了所有结果。如果结果数超过 MaxKeys 指定的数量，则可能无法返回所有结果。

类型：字符串

原级：布尔值
Marker

指明要在存储桶中的哪个位置开始列出。

类型：字符串

原级：ListBucketResult
MaxKeys

要在响应正文中返回的最大键数。

类型：字符串

原级：ListBucketResult
Name

存储桶的名称。

类型：字符串

原级：ListBucketResult
Prefix

以指定的前缀开头的键。

类型：字符串

原级：ListBucketResult

响应正文

有关列出响应的信息，请参阅列出键响应。

访问控制

要列出存储桶的键，您需要获得对该存储桶的 READ 访问权限。