本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# ListBucket (SOAP API)
<a name="SOAPListBucket"></a>

**注意**  
 Amazon S3 的 SOAP API 不適用於新客戶，並且將於 2025 年 8 月 31 日接近生命週期結束 (EOL)。我們建議您使用 REST API 或 AWS SDKs。

 `ListBucket` 操作會傳回儲存貯體中某些項目的相關資訊。

 如需清單操作的一般簡介，請參閱[列出物件金鑰](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ListingKeysUsingAPIs.html)。

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

此範例列出「引號」儲存貯體中字首為「備註」的最多 1000 個金鑰。

### 語法
<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 />Ancestor：ListBucketResult | 
|  CommonPrefixes  |  `CommonPrefixes` 只有在您指定 時，回應才能包含 `delimiter`。當您這樣做時， 會`CommonPrefixes`包含介於 `Prefix`和 之間的所有 （如果有的話） 金鑰，以及 所指定字串的下一次出現`delimiter`。實際上， `CommonPrefixes`會列出 指定目錄中作用類似子目錄的索引鍵`Prefix`。例如，如果 `prefix` 是 `notes/`且 `delimiter` 是斜線 (/)`notes/summer/july`，則在 中，通用字首為 `notes/summer/`。<br />類型：字串<br />Ancestor：ListBucketResult | 
|  Delimiter  | 導致在字首與第一個出現的分隔符號之間包含相同字串的索引鍵彙總為 CommonPrefixes 集合中的單一結果元素。這些彙總金鑰不會在回應的其他地方傳回。<br />類型：字串<br />Ancestor：ListBucketResult | 
|  IsTruncated  | 指定是否傳回 (true) 所有結果 (false)。如果結果數量超過 指定的數量，則可能不會傳回所有結果`MaxKeys`。<br />類型：字串<br />Ancestor：布林值 | 
|  Marker  | 指出儲存貯體中要開始列出的位置。<br />類型：字串<br />Ancestor：ListBucketResult | 
|  MaxKeys  | 回應內文中傳回的金鑰數目上限。<br />類型：字串<br />Ancestor：ListBucketResult | 
|  Name  | 儲存貯體的名稱。<br />類型：字串<br />Ancestor：ListBucketResult | 
|  Prefix  | 以指定字首開頭的金鑰。<br />類型：字串<br />Ancestor：ListBucketResult | 

## 回應內文
<a name="SOAPListBucketResponseBody"></a>

 如需清單回應的資訊，請參閱[列出金鑰回應](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ListingKeysUsingAPIs.html)。

## 存取控制
<a name="SOAPListBucketAccessControl"></a>

若要列出儲存貯體的金鑰，您需要獲得儲存貯體的`READ`存取權。