# 以编程方式列出对象键
在 Amazon S3 中，键可以按前缀列出。您可以为相关键的名称选择通用前缀，然后使用分隔层次结构的特殊字符标记这些键。然后，您可以使用列表操作按层次选择和浏览键。这类似于在文件系统的目录中存储文件的方式。
Amazon S3 公开了列表操作，允许您列出包含在存储桶中的键。将按存储桶和前缀选择用于列表的键。例如，假设一个存储桶的名称为“`dictionary`”，它为每个英语词汇包含了一个键值。您可能会创建一个调用来列出该存储桶中以字母“q”开头的存储桶。列表结果始终以 UTF-8 二进制顺序返回。
SOAP 和 REST 列表操作将返回一个 XML 文档，其中包含匹配键值的名称和有关由每个键值识别的对象的信息。
**注意**
Amazon S3 的 SOAP API 不适用于新客户，并将于 2025 年 8 月 31 日接近使用寿命终止（EOL）。我们建议您使用 REST API 或 AWS 软件开发工具包。
出于列表目的，可以根据通用前缀收拢那些共享一个前缀并且以特定分隔符终结的键组。这允许应用程序按层次结构组织和浏览键值，与您在文件系统的目录中组织文件的方式相同。
例如，要扩展字典存储桶以包含除英语单词外的更多内容，您可以使用语言和分隔符为每个单词添加前缀（例如，“`French/logical`”），从而构成键值。使用此命名方案和层级列表特征，您可以检索仅包含法语词汇的列表。您也可以浏览可用语言的顶级列表，而无需循环浏览所有按字典顺序排列的干预键。有关列表的此方面的更多信息，请参阅 [使用前缀组织对象](using-prefixes.md)。
**REST API**
如果您的应用程序需要它，则可以直接发送 REST 请求。您可以发送 GET 请求来返回存储桶中的某些或所有对象，或者您也可以使用选择条件来返回存储桶中对象的子集。有关更多信息，请参阅《Amazon Simple Storage Service API 参考》**中的 [GET Bucket (List Objects) 版本 2](https://docs.aws.amazon.com/AmazonS3/latest/API/v2-RESTBucketGET.html)。
**列表执行效率**
存储桶中的密钥总数不会对列表性能产生重大影响。它也不因是否存在 `prefix`、`marker`、`maxkeys` 或 `delimiter` 参数而受到影响。
**循环访问多页结果**
由于存储桶可以包含几乎无限数量的键，列表查询的完整结果可能会非常大。为了管理大型结果集，Amazon S3 API 支持分页，以将它们分割为多个响应。每个列出键响应将返回一个拥有多达 1000 个键的页面，同时使用指示器来指示响应是否存在截断。您可以发送一系列的列出键请求，直到您收到了所有的键。AWSSDK 包装库提供相同的分页。
## 示例
在列出存储桶中的所有对象时，请注意，您必须拥有 `s3:ListBucket` 权限。
------
#### [ CLI ]
**list-objects**
以下示例使用 `list-objects` 命令显示指定存储桶中所有对象的名称：
```
aws s3api list-objects --bucket text-content --query 'Contents[].{Key: Key, Size: Size}'
```
该示例使用 `--query` 参数筛选 `list-objects` 的输出，使其范围缩小到每个对象的键值和大小
有关对象的更多信息，请参阅 [使用 Amazon S3 中的对象](uploading-downloading-objects.md)。
+ 有关 API 详细信息，请参阅《AWS CLI 命令参考》**中的 [ListObjects](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/list-objects.html)。
**ls**
下面的示例通过使用 `ls` 命令列出了存储桶中的所有对象和前缀。
要使用此示例命令，请将 **amzn-s3-demo-bucket** 替换为您存储桶的名称。
```
$ aws s3 ls s3://amzn-s3-demo-bucket
```
+ 有关高级命令 `ls` 的更多信息，请参阅《AWS Command Line Interface 用户指南》**中的[列出存储桶和对象](https://docs.aws.amazon.com/cli/latest/userguide/cli-services-s3-commands.html#using-s3-commands-listing-buckets)。
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**示例 1：此命令检索有关存储桶“test-files”中所有项目的信息。**
```
Get-S3Object -BucketName amzn-s3-demo-bucket
```
**示例 2：此命令从存储桶“test-files”中检索有关项目“sample.txt”的信息。**
```
Get-S3Object -BucketName amzn-s3-demo-bucket -Key sample.txt
```
**示例 3：此命令从存储桶“test-files”中检索有关前缀为“sample”的所有项目的信息。**
```
Get-S3Object -BucketName amzn-s3-demo-bucket -KeyPrefix sample
```
+ 有关 API 详细信息，请参阅《AWS Tools for PowerShell Cmdlet Reference (V4)》**中的 [ListObjects](https://docs.aws.amazon.com/powershell/v4/reference)。
**适用于 PowerShell V5 的工具**
**示例 1：此命令检索有关存储桶“test-files”中所有项目的信息。**
```
Get-S3Object -BucketName amzn-s3-demo-bucket
```
**示例 2：此命令从存储桶“test-files”中检索有关项目“sample.txt”的信息。**
```
Get-S3Object -BucketName amzn-s3-demo-bucket -Key sample.txt
```
**示例 3：此命令从存储桶“test-files”中检索有关前缀为“sample”的所有项目的信息。**
```
Get-S3Object -BucketName amzn-s3-demo-bucket -KeyPrefix sample
```
+ 有关 API 详细信息，请参阅《AWS Tools for PowerShell Cmdlet Reference (V5)》**中的 [ListObjects](https://docs.aws.amazon.com/powershell/v5/reference)。
------