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

以编程方式列出对象键

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

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

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

注意

HTTP 上的 SOAP 支持已弃用,但 SOAP 仍可在 HTTPS 上使用。SOAP 不支持新增的 Amazon S3 特征。我们建议您使用 REST API 或 Amazon SDK,而不是使用 SOAP。

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

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

REST API

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

列表执行效率

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

循环访问多页结果

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

示例

以下代码示例显示如何列出 S3 存储桶中的对象。

.NET
Amazon SDK for .NET
注意

在 GitHub 上查看更多内容。在 Amazon 代码示例存储库中查找完整示例,了解如何进行设置和运行。

/// <summary> /// Shows how to list the objects in an Amazon S3 bucket. /// </summary> /// <param name="client">An initialized Amazon S3 client object.</param> /// <param name="bucketName">The name of the bucket for which to list /// the contents.</param> /// <returns>A boolean value indicating the success or failure of the /// copy operation.</returns> public static async Task<bool> ListBucketContentsAsync(IAmazonS3 client, string bucketName) { try { var request = new ListObjectsV2Request { BucketName = bucketName, MaxKeys = 5, }; Console.WriteLine("--------------------------------------"); Console.WriteLine($"Listing the contents of {bucketName}:"); Console.WriteLine("--------------------------------------"); ListObjectsV2Response response; do { response = await client.ListObjectsV2Async(request); response.S3Objects .ForEach(obj => Console.WriteLine($"{obj.Key,-35}{obj.LastModified.ToShortDateString(),10}{obj.Size,10}")); // If the response is truncated, set the request ContinuationToken // from the NextContinuationToken property of the response. request.ContinuationToken = response.NextContinuationToken; } while (response.IsTruncated); return true; } catch (AmazonS3Exception ex) { Console.WriteLine($"Error encountered on server. Message:'{ex.Message}' getting list of objects."); return false; } }

使用分页工具列出对象。

using System; using System.Threading.Tasks; using Amazon.S3; using Amazon.S3.Model; /// <summary> /// The following example lists objects in an Amazon Simple Storage /// Service (Amazon S3) bucket. /// </summary> public class ListObjectsPaginator { private const string BucketName = "doc-example-bucket"; public static async Task Main() { IAmazonS3 s3Client = new AmazonS3Client(); Console.WriteLine($"Listing the objects contained in {BucketName}:\n"); await ListingObjectsAsync(s3Client, BucketName); } /// <summary> /// This method uses a paginator to retrieve the list of objects in an /// an Amazon S3 bucket. /// </summary> /// <param name="client">An Amazon S3 client object.</param> /// <param name="bucketName">The name of the S3 bucket whose objects /// you want to list.</param> public static async Task ListingObjectsAsync(IAmazonS3 client, string bucketName) { var listObjectsV2Paginator = client.Paginators.ListObjectsV2(new ListObjectsV2Request { BucketName = bucketName, }); await foreach (var response in listObjectsV2Paginator.Responses) { Console.WriteLine($"HttpStatusCode: {response.HttpStatusCode}"); Console.WriteLine($"Number of Keys: {response.KeyCount}"); foreach (var entry in response.S3Objects) { Console.WriteLine($"Key = {entry.Key} Size = {entry.Size}"); } } } }
  • 有关 API 详细信息,请参阅《Amazon SDK for .NET API 参考》中的 ListObjectsV2

Bash
Amazon CLI 及 Bash 脚本
注意

在 GitHub 上查看更多内容。在 Amazon 代码示例存储库中查找完整示例,了解如何进行设置和运行。

############################################################################### # function errecho # # This function outputs everything sent to it to STDERR (standard error output). ############################################################################### function errecho() { printf "%s\n" "$*" 1>&2 } ############################################################################### # function list_items_in_bucket # # This function displays a list of the files in the bucket with each file's # size. The function uses the --query parameter to retrieve only the key and # size fields from the Contents collection. # # Parameters: # $1 - The name of the bucket. # # Returns: # The list of files in text format. # And: # 0 - If successful. # 1 - If it fails. ############################################################################### function list_items_in_bucket() { local bucket_name=$1 local response response=$(aws s3api list-objects \ --bucket "$bucket_name" \ --output text \ --query 'Contents[].{Key: Key, Size: Size}') # shellcheck disable=SC2181 if [[ ${?} -eq 0 ]]; then echo "$response" else errecho "ERROR: AWS reports s3api list-objects operation failed.\n$response" return 1 fi }
  • 有关 API 详细信息,请参阅《Amazon CLI 命令参考》中的 ListObjectsV2

C++
SDK for C++
注意

查看 GitHub,了解更多信息。在 Amazon 代码示例存储库中查找完整示例,了解如何进行设置和运行。

bool AwsDoc::S3::ListObjects(const Aws::String &bucketName, const Aws::Client::ClientConfiguration &clientConfig) { Aws::S3::S3Client s3_client(clientConfig); Aws::S3::Model::ListObjectsRequest request; request.WithBucket(bucketName); auto outcome = s3_client.ListObjects(request); if (!outcome.IsSuccess()) { std::cerr << "Error: ListObjects: " << outcome.GetError().GetMessage() << std::endl; } else { Aws::Vector<Aws::S3::Model::Object> objects = outcome.GetResult().GetContents(); for (Aws::S3::Model::Object &object: objects) { std::cout << object.GetKey() << std::endl; } } return outcome.IsSuccess(); }
  • 有关 API 详细信息,请参阅 Amazon SDK for C++ API 参考中的 ListObjectsV2

CLI
Amazon CLI

以下示例使用 list-objects 命令显示指定存储桶中所有对象的名称:

aws s3api list-objects --bucket text-content --query 'Contents[].{Key: Key, Size: Size}'

该示例使用 --query 参数筛选 list-objects 的输出,使其范围缩小到每个对象的键值和大小

有关对象的更多信息,请参阅《Amazon S3 开发人员指南》中的“使用 Amazon S3 对象”。

  • 有关 API 详细信息,请参阅《Amazon CLI 命令参考》中的 ListObjectsV2

Go
适用于 Go V2 的 SDK
注意

查看 GitHub,了解更多信息。在 Amazon 代码示例存储库中查找完整示例,了解如何进行设置和运行。

// BucketBasics encapsulates the Amazon Simple Storage Service (Amazon S3) actions // used in the examples. // It contains S3Client, an Amazon S3 service client that is used to perform bucket // and object actions. type BucketBasics struct { S3Client *s3.Client } // ListObjects lists the objects in a bucket. func (basics BucketBasics) ListObjects(bucketName string) ([]types.Object, error) { result, err := basics.S3Client.ListObjectsV2(context.TODO(), &s3.ListObjectsV2Input{ Bucket: aws.String(bucketName), }) var contents []types.Object if err != nil { log.Printf("Couldn't list objects in bucket %v. Here's why: %v\n", bucketName, err) } else { contents = result.Contents } return contents, err }
  • 有关 API 详细信息,请参阅《Amazon SDK for Go API 参考》中的 ListObjectsV2

Java
SDK for Java 2.x
注意

查看 GitHub,了解更多信息。在 Amazon 代码示例存储库中查找完整示例,了解如何进行设置和运行。

import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.s3.S3Client; import software.amazon.awssdk.services.s3.model.ListObjectsRequest; import software.amazon.awssdk.services.s3.model.ListObjectsResponse; import software.amazon.awssdk.services.s3.model.S3Exception; import software.amazon.awssdk.services.s3.model.S3Object; import java.util.List; /** * Before running this Java V2 code example, set up your development * environment, including your credentials. * * For more information, see the following documentation topic: * * https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html */ public class ListObjects { public static void main(String[] args) { final String usage = """ Usage: <bucketName>\s Where: bucketName - The Amazon S3 bucket from which objects are read.\s """; if (args.length != 1) { System.out.println(usage); System.exit(1); } String bucketName = args[0]; Region region = Region.US_EAST_1; S3Client s3 = S3Client.builder() .region(region) .build(); listBucketObjects(s3, bucketName); s3.close(); } public static void listBucketObjects(S3Client s3, String bucketName) { try { ListObjectsRequest listObjects = ListObjectsRequest .builder() .bucket(bucketName) .build(); ListObjectsResponse res = s3.listObjects(listObjects); List<S3Object> objects = res.contents(); for (S3Object myValue : objects) { System.out.print("\n The name of the key is " + myValue.key()); System.out.print("\n The object is " + calKb(myValue.size()) + " KBs"); System.out.print("\n The owner is " + myValue.owner()); } } catch (S3Exception e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } } // convert bytes to kbs. private static long calKb(Long val) { return val / 1024; } }

使用分页列出对象。

import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.s3.S3Client; import software.amazon.awssdk.services.s3.model.ListObjectsV2Request; import software.amazon.awssdk.services.s3.model.S3Exception; import software.amazon.awssdk.services.s3.paginators.ListObjectsV2Iterable; public class ListObjectsPaginated { public static void main(String[] args) { final String usage = """ Usage: <bucketName>\s Where: bucketName - The Amazon S3 bucket from which objects are read.\s """; if (args.length != 1) { System.out.println(usage); System.exit(1); } String bucketName = args[0]; Region region = Region.US_EAST_1; S3Client s3 = S3Client.builder() .region(region) .build(); listBucketObjects(s3, bucketName); s3.close(); } public static void listBucketObjects(S3Client s3, String bucketName) { try { ListObjectsV2Request listReq = ListObjectsV2Request.builder() .bucket(bucketName) .maxKeys(1) .build(); ListObjectsV2Iterable listRes = s3.listObjectsV2Paginator(listReq); listRes.stream() .flatMap(r -> r.contents().stream()) .forEach(content -> System.out.println(" Key: " + content.key() + " size = " + content.size())); } catch (S3Exception e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } } }
  • 有关 API 详细信息,请参阅《Amazon SDK for Java 2.x API 参考》中的 ListObjectsV2

JavaScript
SDK for JavaScript (v3)
注意

在 GitHub 上查看更多内容。在 Amazon 代码示例存储库中查找完整示例,了解如何进行设置和运行。

列出存储桶中的所有对象。如果有多个对象,则将使用 IsTruncated 和 NextContinuationToken 来迭代完整列表。

import { S3Client, // This command supersedes the ListObjectsCommand and is the recommended way to list objects. ListObjectsV2Command, } from "@aws-sdk/client-s3"; const client = new S3Client({}); export const main = async () => { const command = new ListObjectsV2Command({ Bucket: "my-bucket", // The default and maximum number of keys returned is 1000. This limits it to // one for demonstration purposes. MaxKeys: 1, }); try { let isTruncated = true; console.log("Your bucket contains the following objects:\n"); let contents = ""; while (isTruncated) { const { Contents, IsTruncated, NextContinuationToken } = await client.send(command); const contentsList = Contents.map((c) => ` • ${c.Key}`).join("\n"); contents += contentsList + "\n"; isTruncated = IsTruncated; command.input.ContinuationToken = NextContinuationToken; } console.log(contents); } catch (err) { console.error(err); } };
  • 有关 API 详细信息,请参阅《Amazon SDK for JavaScript API 参考》中的 ListObjectsV2

Kotlin
适用于 Kotlin 的 SDK
注意

在 GitHub 上查看更多内容。在 Amazon 代码示例存储库中查找完整示例,了解如何进行设置和运行。

suspend fun listBucketObjects(bucketName: String) { val request = ListObjectsRequest { bucket = bucketName } S3Client { region = "us-east-1" }.use { s3 -> val response = s3.listObjects(request) response.contents?.forEach { myObject -> println("The name of the key is ${myObject.key}") println("The object is ${myObject.size?.let { calKb(it) }} KBs") println("The owner is ${myObject.owner}") } } } private fun calKb(intValue: Long): Long { return intValue / 1024 }
  • 有关 API 详细信息,请参阅《Amazon SDK for Kotlin API 参考》中的 ListObjectsV2

PHP
适用于 PHP 的 SDK
注意

在 GitHub 上查看更多内容。在 Amazon 代码示例存储库中查找完整示例,了解如何进行设置和运行。

列出存储桶中的对象。

$s3client = new Aws\S3\S3Client(['region' => 'us-west-2']); try { $contents = $this->s3client->listObjectsV2([ 'Bucket' => $this->bucketName, ]); echo "The contents of your bucket are: \n"; foreach ($contents['Contents'] as $content) { echo $content['Key'] . "\n"; } } catch (Exception $exception) { echo "Failed to list objects in $this->bucketName with error: " . $exception->getMessage(); exit("Please fix error with listing objects before continuing."); }
  • 有关 API 详细信息,请参阅《Amazon SDK for PHP API 参考》中的 ListObjectsV2

Python
SDK for Python (Boto3)
注意

查看 GitHub,了解更多信息。在 Amazon 代码示例存储库中查找完整示例,了解如何进行设置和运行。

class ObjectWrapper: """Encapsulates S3 object actions.""" def __init__(self, s3_object): """ :param s3_object: A Boto3 Object resource. This is a high-level resource in Boto3 that wraps object actions in a class-like structure. """ self.object = s3_object self.key = self.object.key @staticmethod def list(bucket, prefix=None): """ Lists the objects in a bucket, optionally filtered by a prefix. :param bucket: The bucket to query. This is a Boto3 Bucket resource. :param prefix: When specified, only objects that start with this prefix are listed. :return: The list of objects. """ try: if not prefix: objects = list(bucket.objects.all()) else: objects = list(bucket.objects.filter(Prefix=prefix)) logger.info( "Got objects %s from bucket '%s'", [o.key for o in objects], bucket.name ) except ClientError: logger.exception("Couldn't get objects for bucket '%s'.", bucket.name) raise else: return objects
  • 有关 API 详细信息,请参阅《Amazon SDK for Python(Boto3)API 参考》中的 ListObjectsV2

Ruby
适用于 Ruby 的 SDK
注意

查看 GitHub,了解更多信息。在 Amazon 代码示例存储库中查找完整示例,了解如何进行设置和运行。

require "aws-sdk-s3" # Wraps Amazon S3 bucket actions. class BucketListObjectsWrapper attr_reader :bucket # @param bucket [Aws::S3::Bucket] An existing Amazon S3 bucket. def initialize(bucket) @bucket = bucket end # Lists object in a bucket. # # @param max_objects [Integer] The maximum number of objects to list. # @return [Integer] The number of objects listed. def list_objects(max_objects) count = 0 puts "The objects in #{@bucket.name} are:" @bucket.objects.each do |obj| puts "\t#{obj.key}" count += 1 break if count == max_objects end count rescue Aws::Errors::ServiceError => e puts "Couldn't list objects in bucket #{bucket.name}. Here's why: #{e.message}" 0 end end # Example usage: def run_demo bucket_name = "doc-example-bucket" wrapper = BucketListObjectsWrapper.new(Aws::S3::Bucket.new(bucket_name)) count = wrapper.list_objects(25) puts "Listed #{count} objects." end run_demo if $PROGRAM_NAME == __FILE__
  • 有关 API 详细信息,请参阅《Amazon SDK for Ruby API 参考》中的 ListObjectsV2

Rust
适用于 Rust 的 SDK
注意

在 GitHub 上查看更多内容。在 Amazon 代码示例存储库中查找完整示例,了解如何进行设置和运行。

pub async fn list_objects(client: &Client, bucket: &str) -> Result<(), Error> { let mut response = client .list_objects_v2() .bucket(bucket.to_owned()) .max_keys(10) // In this example, go 10 at a time. .into_paginator() .send(); while let Some(result) = response.next().await { match result { Ok(output) => { for object in output.contents() { println!(" - {}", object.key().unwrap_or("Unknown")); } } Err(err) => { eprintln!("{err:?}") } } } Ok(()) }
  • 有关 API 详细信息,请参阅《Amazon SDK for Rust API 参考》中的 ListObjectsV2

SAP ABAP
SDK for SAP ABAP
注意

查看 GitHub,了解更多信息。在 Amazon 代码示例存储库中查找完整示例,了解如何进行设置和运行。

TRY. oo_result = lo_s3->listobjectsv2( " oo_result is returned for testing purposes. " iv_bucket = iv_bucket_name ). MESSAGE 'Retrieved list of objects in S3 bucket.' TYPE 'I'. CATCH /aws1/cx_s3_nosuchbucket. MESSAGE 'Bucket does not exist.' TYPE 'E'. ENDTRY.
  • 有关 API 详细信息,请参阅《Amazon SDK for SAP ABAP API 参考》中的 ListObjectsV2

Swift
SDK for Swift
注意

这是预览版 SDK 的预发布文档。本文档随时可能更改。

注意

查看 GitHub,了解更多信息。在 Amazon 代码示例存储库中查找完整示例,了解如何进行设置和运行。

public func listBucketFiles(bucket: String) async throws -> [String] { let input = ListObjectsV2Input( bucket: bucket ) let output = try await client.listObjectsV2(input: input) var names: [String] = [] guard let objList = output.contents else { return [] } for obj in objList { if let objName = obj.key { names.append(objName) } } return names }
  • 有关 API 详细信息,请参阅《Amazon SDK for Swift API 参考》中的 ListObjectsV2