以编程方式列出对象键 - Amazon Simple Storage Service
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

欢迎使用新的 Amazon S3 用户指南! Amazon S3 用户指南结合了以下三个已停用的指南中的信息和说明:Amazon S3 开发人员指南Amazon S3 控制台用户指南Amazon S3 入门指南

以编程方式列出对象键

在 Amazon S3 中,键可以按前缀列出。您可以为相关键的名称选择通用前缀,然后使用分隔层次结构的特殊字符标记这些键。然后,您可以使用列表操作按层次选择和浏览键。这类似于在文件系统的目录中存储文件的方式。

Amazon S3 公开了列表操作,允许您列出包含在存储桶中的键。将按存储桶和前缀选择用于列表的键。例如,假设一个存储桶的名称为“dictionary”,它为每个英语词汇包含了一个键值。您可能会创建一个调用来列出该存储桶中以字母“q”开头的存储桶。列表结果始终以 UTF-8 二进制顺序返回。

SOAP 和 REST 列表操作将返回一个 XML 文档,其中包含匹配键值的名称和有关由每个键值识别的对象的信息。

注意

HTTP 上的 SOAP 支持已弃用,但是仍可在 HTTPS 上使用。不支持将新 Amazon S3 功能用于 SOAP。我们建议您使用 REST API 或 AWS 开发工具包。

出于列表目的,可以根据通用前缀收拢那些共享一个前缀并且以特定分隔符终结的键组。这允许应用程序按层次结构组织和浏览键值,与您在文件系统的目录中组织文件的方式相同。

例如,要扩展字典存储桶以包含除英语单词外的更多内容,您可以使用语言和分隔符为每个单词添加前缀(例如,“French/logical”),从而构成键值。使用此命名方案和层级列表功能,您可以检索仅包含法语词汇的列表。您也可以浏览可用语言的顶级列表,而无需循环浏览所有按字典顺序排列的干预键。有关列表的此方面的更多信息,请参阅使用前缀组织对象

REST API

如果您的应用程序需要它,则可以直接发送 REST 请求。您可以发送 GET 请求来返回存储桶中的某些或所有对象,或者您也可以使用选择条件来返回存储桶中对象的子集。有关更多信息,请参阅 Amazon Simple Storage Service API 参考中的 GET Bucket (List Objects) 版本 2

列表执行效率

存储桶中的密钥总数不会对列表性能产生重大影响。它也不因是否存在 prefixmarkermaxkeysdelimiter 参数而受到影响。

循环访问多页结果

由于存储桶可以包含几乎无限数量的键,列表查询的完整结果可能会非常大。为了管理大型结果集,Amazon S3 API 支持分页,以将它们分割为多个响应。每个列出键响应将返回一个拥有多达 1000 个键的页面,同时使用指示器来指示响应是否存在截断。您可以发送一系列的列出键请求,直到您收到了所有的键。AWS 开发工具包包装库提供相同的分页。

Java

下面的示例将列出存储桶中的对象键。该示例使用分页来检索一组对象键。如果有多个键要在第一页后要返回,Amazon S3 将在响应中包含一个延续令牌。该示例在后续请求中使用延续令牌来提取下一组对象键。

有关创建和测试有效示例的说明,请参阅测试 Amazon S3 Java 代码示例

import com.amazonaws.AmazonServiceException; import com.amazonaws.SdkClientException; import com.amazonaws.auth.profile.ProfileCredentialsProvider; import com.amazonaws.regions.Regions; import com.amazonaws.services.s3.AmazonS3; import com.amazonaws.services.s3.AmazonS3ClientBuilder; import com.amazonaws.services.s3.model.ListObjectsV2Request; import com.amazonaws.services.s3.model.ListObjectsV2Result; import com.amazonaws.services.s3.model.S3ObjectSummary; import java.io.IOException; public class ListKeys { public static void main(String[] args) throws IOException { Regions clientRegion = Regions.DEFAULT_REGION; String bucketName = "*** Bucket name ***"; try { AmazonS3 s3Client = AmazonS3ClientBuilder.standard() .withCredentials(new ProfileCredentialsProvider()) .withRegion(clientRegion) .build(); System.out.println("Listing objects"); // maxKeys is set to 2 to demonstrate the use of // ListObjectsV2Result.getNextContinuationToken() ListObjectsV2Request req = new ListObjectsV2Request().withBucketName(bucketName).withMaxKeys(2); ListObjectsV2Result result; do { result = s3Client.listObjectsV2(req); for (S3ObjectSummary objectSummary : result.getObjectSummaries()) { System.out.printf(" - %s (size: %d)\n", objectSummary.getKey(), objectSummary.getSize()); } // If there are more than maxKeys keys in the bucket, get a continuation token // and list the next objects. String token = result.getNextContinuationToken(); System.out.println("Next Continuation Token: " + token); req.setContinuationToken(token); } while (result.isTruncated()); } catch (AmazonServiceException e) { // The call was transmitted successfully, but Amazon S3 couldn't process // it, so it returned an error response. e.printStackTrace(); } catch (SdkClientException e) { // Amazon S3 couldn't be contacted for a response, or the client // couldn't parse the response from Amazon S3. e.printStackTrace(); } } }
.NET

下面的 C# 示例将列出存储桶的对象键。在该示例中,我们使用分页来检索一组对象键。如果有多个键要返回,Amazon S3 将在响应中包含一个延续令牌。该代码在后续请求中使用延续令牌来提取下一组对象键。

有关如何创建和测试有效示例的说明,请参阅 运行 Amazon S3 .NET 代码示例

using Amazon; using Amazon.S3; using Amazon.S3.Model; using System; using System.Threading.Tasks; namespace Amazon.DocSamples.S3 { class ListObjectsTest { private const string bucketName = "*** bucket name ***"; // Specify your bucket region (an example region is shown). private static readonly RegionEndpoint bucketRegion = RegionEndpoint.USWest2; private static IAmazonS3 client; public static void Main() { client = new AmazonS3Client(bucketRegion); ListingObjectsAsync().Wait(); } static async Task ListingObjectsAsync() { try { ListObjectsV2Request request = new ListObjectsV2Request { BucketName = bucketName, MaxKeys = 10 }; ListObjectsV2Response response; do { response = await client.ListObjectsV2Async(request); // Process the response. foreach (S3Object entry in response.S3Objects) { Console.WriteLine("key = {0} size = {1}", entry.Key, entry.Size); } Console.WriteLine("Next Continuation Token: {0}", response.NextContinuationToken); request.ContinuationToken = response.NextContinuationToken; } while (response.IsTruncated); } catch (AmazonS3Exception amazonS3Exception) { Console.WriteLine("S3 error occurred. Exception: " + amazonS3Exception.ToString()); Console.ReadKey(); } catch (Exception e) { Console.WriteLine("Exception: " + e.ToString()); Console.ReadKey(); } } } }
PHP

此示例将指导您使用适用于 PHP 的 AWS 开发工具包(版本 3)中的类列出 Amazon S3 存储桶中包含的对象键。

此示例假定您已按照使用适用于 PHP 的 AWS 开发工具包和运行 PHP 示例中的说明执行操作,并正确安装了适用于 PHP 的 AWS 开发工具包。

要使用适用于 PHP 的 AWS 开发工具包列出存储桶中包含的对象键,首先必须列出该存储桶中包含的对象,然后从列出的每个对象中提取键。在列出存储桶中的对象时,可选择使用低级别 Aws\S3\S3Client::listObjects() 方法或高级别 Aws\ResultPaginator 类。

低级别的 listObjects() 方法将映射到底层 Amazon S3 REST API。每个 listObjects() 请求均返回最多有 1000 个对象的页面。如果您的存储桶中有超过 1000 个对象,则将截断您的响应,并且您必须发送其他 listObjects() 请求,以检索下一组 1000 个对象。

您可以使用高级别 ListObjects 分页工具来更轻松地列出存储桶中包含的对象。要使用 ListObjects 分页工具创建对象列表,请运行从 Aws/AwsClientInterface 类继承的 Amazon S3 客户端 getPaginator() 方法,同时将 ListObjects 命令作为第一个参数,将包含从指定存储桶返回的对象的数组作为第二个参数。

当作为 ListObjects 分页工具使用时,getPaginator() 方法将返回指定存储桶中包含的所有对象。不存在 1000 个对象的限制,因此,您无需担心响应是否被截断。

以下任务将引导您使用 PHP Amazon S3 客户端方法列出您能够从中列出对象键的存储桶中包含的对象。

例 列出对象键

以下 PHP 示例演示如何列出指定存储桶中的键。它演示如何使用高级别 getIterator() 方法列出存储桶中的对象,然后如何从该列表的每个对象中提取键。它还演示如何使用低级别 listObjects() 方法列出存储桶中的对象,然后如何从返回的列表的每个对象中提取键。有关运行本指南中的 PHP 示例的信息,请参阅运行 PHP 示例

require 'vendor/autoload.php'; use Aws\S3\S3Client; use Aws\S3\Exception\S3Exception; $bucket = '*** Your Bucket Name ***'; // Instantiate the client. $s3 = new S3Client([ 'version' => 'latest', 'region' => 'us-east-1' ]); // Use the high-level iterators (returns ALL of your objects). try { $results = $s3->getPaginator('ListObjects', [ 'Bucket' => $bucket ]); foreach ($results as $result) { foreach ($result['Contents'] as $object) { echo $object['Key'] . PHP_EOL; } } } catch (S3Exception $e) { echo $e->getMessage() . PHP_EOL; } // Use the plain API (returns ONLY up to 1000 of your objects). try { $objects = $s3->listObjects([ 'Bucket' => $bucket ]); foreach ($objects['Contents'] as $object) { echo $object['Key'] . PHP_EOL; } } catch (S3Exception $e) { echo $e->getMessage() . PHP_EOL; }