# ListBucket（SOAP API）
<a name="SOAPListBucket"></a>

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

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

 有关列表操作的一般介绍，请参阅[列出对象键](https://docs.amazonaws.cn/AmazonS3/latest/userguide/ListingKeysUsingAPIs.html)。

## 请求
<a name="SOAPBucketGET_Request"></a>

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

### 语法
<a name="SOAPBucketGET_RequestSyntax"></a>

```
1. <ListBucket xmlns="https://doc.s3.amazonaws.com/2006-03-01">
2.   <Bucket>quotes</Bucket>
3.   <Prefix>notes/</Prefix>
4.   <Delimiter>/</Delimiter>
5.   <MaxKeys>1000</MaxKeys>
6.   <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
7.   <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
8.   <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
9. </ListBucket>
```

### 参数
<a name="SOAPBucketGET_RequestHeaders"></a>


|  名称  |  描述  |  必填  | 
| --- | --- | --- | 
|  prefix  | 将响应限制为以指定的前缀开头的键。您可以使用前缀将存储桶分成不同的键集，其方式与文件系统使用文件夹的方式类似。<br />类型：字符串<br />默认值：无 |  否  | 
|  marker  | 指明要在存储桶中的哪个位置开始列出。该列表将仅包括按字典顺序出现在标记之后的键。这便于分页：要获取下一页的结果，请使用当前页面的最后一个键作为标记。<br />类型：字符串<br />默认值：无 |  否  | 
|  max-keys  | 您希望在响应正文中看到的最大键数。服务器返回的键数可能少于这个数量，但返回的键数不会多于此数量。<br />类型：字符串<br />默认值：无 |  否  | 
|  delimiter  | 导致在前缀和首次出现的分隔符之间包含相同字符串的键汇总到 CommonPrefixes 集合的单个结果元素中。这些汇总的键不会在响应中的其它地方返回。<br />类型：字符串<br />默认值：无 |  否  | 

## 成功响应
<a name="SOAPBucketGET_ResponseSuccess"></a>

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

```
1. notes/todos.txt
2. notes/2005-05-23/customer_mtg_notes.txt
3. notes/2005-05-23/phone_notes.txt
4. notes/2005-05-28/sales_notes.txt
```

### 语法
<a name="SOAPBucketGET_ResponseSuccess-syntax"></a>

```
 1. <?xml version="1.0" encoding="UTF-8"?>
 2. <ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
 3.   <Name>backups</Name>
 4.   <Prefix>notes/</Prefix>
 5.   <MaxKeys>1000</MaxKeys>
 6.   <Delimiter>/</Delimiter>
 7.   <IsTruncated>false</IsTruncated>
 8.   <Contents>
 9.     <Key>notes/todos.txt</Key>
10.     <LastModified>2006-01-01T12:00:00.000Z</LastModified>
11.     <ETag>&quot;828ef3fdfa96f00ad9f27c383fc9ac7f&quot;</ETag>
12.     <Size>5126</Size>
13.     <StorageClass>STANDARD</StorageClass>
14.     <Owner>
15.       <ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
16.       <DisplayName>webfile</DisplayName>
17.     </Owner>
18.     <StorageClass>STANDARD</StorageClass>
19.   </Contents>
20.   <CommonPrefixes>
21.     <Prefix>notes/2005-05-23/</Prefix>
22.   </CommonPrefixes>
23.   <CommonPrefixes>
24.     <Prefix>notes/2005-05-28/</Prefix>
25.   </CommonPrefixes>
26.   </ListBucketResult>
```

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

### 响应元素
<a name="SOAPBucketGET_ResponseSuccess-response-elements"></a>


|  名称  |  描述  | 
| --- | --- | 
|  Contents  | 有关返回的每个对象的元数据。<br />类型：XML 元数据<br />原级：ListBucketResult | 
|  CommonPrefixes  |  仅当您指定 `delimiter` 时，响应才会包含 `CommonPrefixes`。当您这样做时，`CommonPrefixes` 包含 `Prefix` 与由 `delimiter` 指定的字符串的下一次出现之间的所有（如果有的话）键。实际上，`CommonPrefixes` 会列出在 `Prefix` 指定的目录中充当子目录的键。例如，如果 `prefix` 是 `notes/`，`delimiter` 是斜杠（/），则在 `notes/summer/july` 中，常见前缀是 `notes/summer/`。<br />类型：字符串<br />原级：ListBucketResult | 
|  Delimiter  | 导致在前缀和首次出现的分隔符之间包含相同字符串的键汇总到 CommonPrefixes 集合的单个结果元素中。这些汇总的键不会在响应中的其它地方返回。<br />类型：字符串<br />原级：ListBucketResult | 
|  IsTruncated  | 指定是（true）否（false）返回了所有结果。如果结果数超过 `MaxKeys` 指定的数量，则可能无法返回所有结果。<br />类型：字符串<br />原级：布尔值 | 
|  Marker  | 指明要在存储桶中的哪个位置开始列出。<br />类型：字符串<br />原级：ListBucketResult | 
|  MaxKeys  | 要在响应正文中返回的最大键数。<br />类型：字符串<br />原级：ListBucketResult | 
|  Name  | 存储桶的名称。<br />类型：字符串<br />原级：ListBucketResult | 
|  Prefix  | 以指定的前缀开头的键。<br />类型：字符串<br />原级：ListBucketResult | 

## 响应正文
<a name="SOAPListBucketResponseBody"></a>

 有关列出响应的信息，请参阅[列出键响应](https://docs.amazonaws.cn/AmazonS3/latest/userguide/ListingKeysUsingAPIs.html)。

## 访问控制
<a name="SOAPListBucketAccessControl"></a>

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