# 列出 Amazon S3 通用存储桶
<a name="list-buckets"></a>

要返回您拥有的通用存储桶的列表，可以使用 [ListBuckets](https://docs.amazonaws.cn/AmazonS3/latest/API/API_ListBuckets.htm)。您可以使用 Amazon S3 控制台、Amazon Command Line Interface 或 Amazon SDK 来列出存储桶。对于使用 Amazon CLI、Amazon SDK 和 Amazon S3 REST API 发出的 `ListBuckets` 请求，如果 Amazon Web Services 账户 采用存储桶的默认服务配额（10000 个存储桶），则将同时支持分页和非分页请求。无论您的账户中有多少存储桶，您都可以创建介于 1 到 10000 个存储桶之间的页面大小来列出所有存储桶。对于分页请求，`ListBuckets` 请求会返回存储桶名称，以及每个存储桶的相应 Amazon Web Services 区域。以下 Amazon Command Line Interface 和 Amazon SDK 示例向您展示了如何在 `ListBuckets` 请求中使用分页。请注意，有些 Amazon SDK 可以协助进行分页。

**权限**  
要列出所有通用存储桶，您必须拥有 `s3:ListAllMyBuckets` 权限。如果遇到 `HTTP Access Denied (403 Forbidden)` 错误，请参阅[排查 Amazon S3 中的拒绝访问（403 Forbidden）错误](troubleshoot-403-errors.md)。

**重要**  
我们强烈建议仅使用分页 `ListBuckets` 请求。只有设置为默认通用存储桶配额 10000 的 Amazon Web Services 账户，才支持未分页的 `ListBuckets` 请求。如果您批准的通用存储桶配额超过 10000，则必须发送分页 `ListBuckets` 请求以列出您账户的存储桶。对于通用存储桶配额大于 10000 的 Amazon Web Services 账户，所有未分页的 `ListBuckets` 请求都将遭拒绝。

## 使用 S3 控制台
<a name="access-bucket-example-console"></a>

1. 登录到 Amazon Web Services 管理控制台，然后通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.amazonaws.cn/s3/)。

1. 在左侧导航窗格中，选择**通用存储桶**。

1. 在**通用存储桶**选项卡上，您可以看到通用存储桶的列表。

1. 要按名称查找存储桶，请在**按名称查找存储桶**字段中输入存储桶名称。

## 使用 Amazon CLI
<a name="access-bucket-example-cli"></a>

要使用 Amazon CLI 生成通用存储桶的列表，可以使用 `ls` 或 `list-buckets` 命令。以下示例向您展示了如何创建分页 `list-buckets` 请求和未分页的 `ls` 请求。要使用这些示例，请替换*用户输入占位符*。

**Example – 使用 `ls`（未分页）列出您账户中的所有存储桶**  
以下示例命令将在单个非分页调用中列出您账户中的所有通用存储桶。此调用会返回您账户中所有存储桶的列表（最多 10000 个结果）：  

```
$ aws s3 ls
```
有关更多信息和示例，请参阅[列出存储桶和对象](https://docs.amazonaws.cn/cli/latest/userguide/cli-services-s3-commands.html#using-s3-commands-listing-buckets)。  


**Example – 使用 `ls`（分页）列出您账户中的所有存储桶**  
以下示例命令会进行一次或多次分页调用，列出您账户中的所有通用存储桶，每页返回 100 个存储桶：  

```
$ aws s3 ls --page-size 100
```
有关更多信息和示例，请参阅[列出存储桶和对象](https://docs.amazonaws.cn/cli/latest/userguide/cli-services-s3-commands.html#using-s3-commands-listing-buckets)。  


**Example – 列出您账户中的所有存储桶（分页）**  
以下示例提供了分页 `list-buckets` 命令，用于列出您账户中的所有通用存储桶。`--max-items` 和 `--page-size` 选项将列出的存储桶数量限制为每页 100 个。  

```
$ aws s3api list-buckets /
    --max-items 100 / 
    --page-size 100
```
如果项目输出的数量 (`--max-items`) 少于基础 API 调用所返回的项目总数，则输出将包含 `starting-token` 参数所指定的延续令牌，您可传递到后续命令以检索下一组项目。以下示例展示了如何使用上一示例返回的 `starting-token` 值。您可以指定 `starting-code` 检索接下来的 100 个存储桶。  

```
$ aws s3api list-buckets / 
    --max-items 100 / 
    --page-size 100 /
    --starting-token eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAxfQ==
```


**Example – 列出 Amazon Web Services 区域中的所有存储桶（分页）**  
以下示例命令使用 `--bucket-region` 参数来列出账户中位于 `us-east-2` 区域的最多 100 个存储桶。不支持向与 `--bucket-region` 参数中指定的值不同的区域端点发出请求。例如，如果您想将响应限制在 `us-east-2` 中的存储桶，则必须向 `us-east-2` 中的端点发出请求。  

```
$ aws s3api list-buckets /
    --region us-east-2 /
    --max-items 100 / 
    --page-size 100 /
    --bucket-region us-east-2
```


**Example – 列出所有以特定存储桶名称前缀开头的存储桶（分页）**  
以下示例命令列出了最多 100 个名称以 *amzn-s3-demo-bucket* 前缀开头的存储桶。  

```
$ aws s3api list-buckets /
    --max-items 100 /
    --page-size 100 /
    --prefix amzn-s3-demo-bucket
```

## 使用 Amazon SDK
<a name="access-bucket-example-sdk"></a>

以下示例向您展示如何使用 Amazon SDK 来列出通用存储桶。

------
#### [ SDK for Python ]

**Example – ListBuckets 请求（分页）**  

```
import boto3

s3 = boto3.client('s3')
response = s3.list_buckets(MaxBuckets=100)
```

**Example – ListBuckets 响应（分页）**  

```
import boto3

s3 = boto3.client('s3')
response = s3.list_buckets(MaxBuckets=1,ContinuationToken="eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAxfQ==EXAMPLE--")
```

------
#### [ SDK for Java ]

有关如何使用适用于 Java 的 Amazon SDK 列出存储桶的示例，请参阅《Amazon S3 API Reference》**中的 [List buckets](https://docs.amazonaws.cn/AmazonS3/latest/API/s3_example_s3_ListBuckets_section.html)。

------
#### [ SDK for Go ]

```
package main
import (
 "context"
 "fmt"
 "log"
 "github.com/aws/aws-sdk-go-v2/aws"
 "github.com/aws/aws-sdk-go-v2/config"
 "github.com/aws/aws-sdk-go-v2/service/s3"
)
func main() {
 cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRegion("us-east-2"))
 if err != nil {
  log.Fatal(err)
 }
 client := s3.NewFromConfig(cfg)
 maxBuckets := 1000
 resp, err := client.ListBuckets(context.TODO(), management portals3.ListBucketsInput{MaxBuckets: aws.Int32(int32(maxBuckets))})
 if err != nil {
  log.Fatal(err)
 }
 fmt.Println("S3 Buckets:")
 for _, bucket := range resp.Buckets {
     fmt.Println("- Name:", *bucket.Name)
     fmt.Println("-BucketRegion", *bucket.BucketRegion)
 }
 fmt.Println(resp.ContinuationToken == nil)
 fmt.Println(resp.Prefix == nil)
}
```

------