プログラムによるオブジェクトキーのリスト化 - Amazon Simple Storage Service

プログラムによるオブジェクトキーのリスト化

Amazon S3 では、キーはプレフィックス別に一覧表示できます。関連するキーの名前に共通のプレフィックスを選択し、階層を区切る特殊文字でこれらのキーをマークすることができます。その後、リストオペレーションを使用して、キーを階層的に選択および参照できます。これは、ファイルシステムにおいてディレクトリ内にファイルを格納するしくみに似ています。

Amazon S3 では、バケット内のキーを列挙するためのリストオペレーションを公開します。キーはバケット別またはプレフィックス別にリストされます。例えば、すべての英単語のキーを含む「dictionary」という名前のバケットがあるとします。そして、そのバケット内の文字「q」で始まるキーをすべてリストするための呼び出しを行うとします。リストの結果は常に UTF−8 バイナリ順で返されます。

SOAP および REST のリストオペレーションではいずれも、条件に一致するキーの名前と、各キーによって識別されるオブジェクトに関する情報を含む XML ドキュメントが返されます。

注記

SOAP のサポートは HTTP 経由では廃止されましたが、HTTPS 経由では引き続き利用可能です。Amazon S3 の新機能は SOAP でサポートされていません。SOAP の代わりに、REST API か AWS SDK を使用することをお勧めします。

特殊な区切り記号で終わるプレフィックスを共有するキーのグループは、リストの目的で、その共通のプレフィックスによってロールアップできます。このような機能によりアプリケーションでは、キーを階層的に構成および参照できるようになります。ファイルシステムにおいてファイルをディレクトリに分けて整理するのに似ています。

例えば、英語以外の単語も含まれるように dictionary バケットを拡張するには、各単語にその言語と区切り記号のプレフィックスを付けることでキーを形成できます (「French/logical」など)。この命名スキームと階層リスト機能を使用すれば、フランス語の単語のリストだけを取得することもできます。また、対応している言語の最上位レベルのリストを参照することで、それより下の階層間に介在するすべてのキーを反復処理する必要もなくなります。リスト化における階層の役割については、プレフィックスを使用してオブジェクトを整理する を参照してください。

REST API

アプリケーションで必要な場合は、REST リクエストを直接送信できます。GET リクエストを送信して、バケット内の一部またはすべてのオブジェクトを返すことができます。または選択条件を使用して、バケット内のオブジェクトのサブセットを返すことができます。詳細については、Amazon Simple Storage Service API リファレンスGET バケット (オブジェクトのリスト化) バージョン 2 を参照してください。

リスト実装の効率性

リスト化のパフォーマンスは、バケット内のキーの総数によって大きく影響されることはありません。prefixmarkermaxkeys または delimiter 引数の有無によって影響されることもありません。

複数ページの結果に対する反復処理

バケットに入れることのできるキーの数は実質的に無制限であるため、リストのクエリによっては結果が膨大な量になる可能性があります。大規模な結果セットを管理するため、Amazon S3 API ではページ分割をサポートして結果セットを複数のレスポンスに分割します。キーリストのレスポンスごとに最大 1,000 個のキーを含むページと、レスポンスが切り捨てられているかどうかを示すインジケータが返されます。すべてのキーを受信するまで、一連のキーリストリクエストを送信します。AWSこのページ分割は、SDK ラッパーライブラリでも行うことができます。

次のコード例は、S3 バケット内のオブジェクトを一覧表示する方法を示しています。

.NET
AWS SDK for .NET
ヒント

この例を設定および実行する方法については、「GitHub」を参照してください。

/// <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("--------------------------------------"); var response = new ListObjectsV2Response(); 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; } }
  • API の詳細については、「AWS SDK for .NET API リファレンス」の「ListObjects」を参照してください。

C++
SDK for C++
ヒント

この例を設定および実行する方法については、「GitHub」を参照してください。

bool AwsDoc::S3::ListObjects(const Aws::String& bucketName, const Aws::String& region) { Aws::Client::ClientConfiguration config; if (!region.empty()) { config.region = region; } Aws::S3::S3Client s3_client(config); Aws::S3::Model::ListObjectsRequest request; request.WithBucket(bucketName); auto outcome = s3_client.ListObjects(request); if (outcome.IsSuccess()) { std::cout << "Objects in bucket '" << bucketName << "':" << std::endl << std::endl; Aws::Vector<Aws::S3::Model::Object> objects = outcome.GetResult().GetContents(); for (Aws::S3::Model::Object& object : objects) { std::cout << object.GetKey() << std::endl; } return true; } else { std::cout << "Error: ListObjects: " << outcome.GetError().GetMessage() << std::endl; return false; } } int main() { Aws::SDKOptions options; Aws::InitAPI(options); { //TODO: Name of a bucket in your account. //The bucket must have at least one object in it. One way to achieve //this is to configure and run put_object.cpp's executable first. const Aws::String bucket_name = "DOC-EXAMPLE-BUCKET"; //TODO: Set to the AWS Region in which the bucket was created. Aws::String region = "us-east-1"; if (!AwsDoc::S3::ListObjects(bucket_name, region)) { return 1; } } Aws::ShutdownAPI(options); return 0; }
  • API の詳細については、「AWS SDK for C++ API リファレンス」の「ListObjects」を参照してください。

Go
SDK for Go V2
ヒント

この例を設定および実行する方法については、「GitHub」を参照してください。

// List objects in the bucket. // n.b. object keys in Amazon S3 do not begin with '/'. You do not need to lead your // prefix with it. fmt.Println("Listing the objects in the bucket:") listObjsResponse, err := client.ListObjectsV2(context.TODO(), &s3.ListObjectsV2Input{ Bucket: aws.String(name), Prefix: aws.String(""), }) if err != nil { panic("Couldn't list bucket contents") } for _, object := range listObjsResponse.Contents { fmt.Printf("%s (%d bytes, class %v) \n", *object.Key, object.Size, object.StorageClass) }
  • API の詳細については、「AWS SDK for Go API リファレンス」の「ListObjects」を参照してください。

Java
SDK for Java 2.x
ヒント

この例を設定および実行する方法については、「GitHub」を参照してください。

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; }
  • API の詳細については、「AWS SDK for Java 2.x API リファレンス」の「ListObjects」を参照してください。

JavaScript
SDK for JavaScript V3
ヒント

この例を設定および実行する方法については、「GitHub」を参照してください。

クライアントを作成します。

// Create service client module using ES6 syntax. import { S3Client } from "@aws-sdk/client-s3"; // Set the AWS Region. const REGION = "us-east-1"; // Create an Amazon S3 service client object. const s3Client = new S3Client({ region: REGION }); export { s3Client };

オブジェクトを一覧表示します。

// Import required AWS SDK clients and commands for Node.js. import { ListObjectsCommand } from "@aws-sdk/client-s3"; import { s3Client } from "./libs/s3Client.js"; // Helper function that creates an Amazon S3 service client module. // Create the parameters for the bucket export const bucketParams = { Bucket: "BUCKET_NAME" }; export const run = async () => { try { const data = await s3Client.send(new ListObjectsCommand(bucketParams)); console.log("Success", data); return data; // For unit tests. } catch (err) { console.log("Error", err); } }; run();

1000 以上のオブジェクトを一覧表示します。

// Import required AWS SDK clients and commands for Node.js. import { ListObjectsCommand } from "@aws-sdk/client-s3"; import { s3Client } from "./libs/s3Client.js"; // Helper function that creates an Amazon S3 service client module. // Create the parameters for the bucket export const bucketParams = { Bucket: "BUCKET_NAME" }; export async function run() { // Declare truncated as a flag that the while loop is based on. let truncated = true; // Declare a variable to which the key of the last element is assigned to in the response. let pageMarker; // while loop that runs until 'response.truncated' is false. while (truncated) { try { const response = await s3Client.send(new ListObjectsCommand(bucketParams)); // return response; //For unit tests response.Contents.forEach((item) => { console.log(item.Key); }); // Log the key of every item in the response to standard output. truncated = response.IsTruncated; // If truncated is true, assign the key of the last element in the response to the pageMarker variable. if (truncated) { pageMarker = response.Contents.slice(-1)[0].Key; // Assign the pageMarker value to bucketParams so that the next iteration starts from the new pageMarker. bucketParams.Marker = pageMarker; } // At end of the list, response.truncated is false, and the function exits the while loop. } catch (err) { console.log("Error", err); truncated = false; } } } run();
  • API の詳細については、「AWS SDK for JavaScript API リファレンス」の「ListObjects」を参照してください。

Kotlin
SDK for Kotlin
注記

これはプレビューリリースの機能に関するプレリリースドキュメントです。このドキュメントは変更される可能性があります。

ヒント

この例を設定および実行する方法については、「GitHub」を参照してください。

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 ${calKb(myObject.size)} KBs") println("The owner is ${myObject.owner}") } } } private fun calKb(intValue: Long): Long { return intValue / 1024 }
  • API の詳細については、「AWS SDK for Kotlin API リファレンス」の「ListObjects」を参照してください。

PHP
SDK for PHP
ヒント

この例を設定および実行する方法については、「GitHub」を参照してください。

バケット内のオブジェクトを一覧表示します。

$s3client = new Aws\S3\S3Client(['region' => 'us-west-2', 'version' => 'latest']); try { $contents = $s3client->listObjects([ 'Bucket' => $bucket_name, ]); 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 $bucket_name with error: " . $exception->getMessage(); exit("Please fix error with listing objects before continuing."); }
  • API の詳細については、「AWS SDK for PHP API リファレンス」の「ListObjects」を参照してください。

Python
SDK for Python (Boto3)
ヒント

この例を設定および実行する方法については、「GitHub」を参照してください。

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 の詳細については、「AWS SDK for Python (Boto3) API リファレンス」の「ListObjects」を参照してください。

Ruby
SDK for Ruby
ヒント

この例を設定および実行する方法については、「GitHub」を参照してください。

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 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 の詳細については、「AWS SDK for Ruby API リファレンス」の「ListObjects」を参照してください。

Rust
SDK for Rust
注記

これはプレビューリリースの SDK に関するドキュメントです。SDK は変更される場合があり、本稼働環境では使用しないでください。

ヒント

この例を設定および実行する方法については、「GitHub」を参照してください。

pub async fn list_objects(client: &Client, bucket_name: &str) -> Result<(), Error> { let objects = client.list_objects_v2().bucket(bucket_name).send().await?; println!("Objects in bucket:"); for obj in objects.contents().unwrap_or_default() { println!("{:?}", obj.key().unwrap()); } Ok(()) }
  • API の詳細については、「AWS SDK for Rust API リファレンス」の「ListObjects」を参照してください。

Swift
SDK for Swift
注記

これはプレビューリリースの SDK に関するプレリリースドキュメントです。このドキュメントは変更される可能性があります。

ヒント

この例を設定および実行する方法については、「GitHub」を参照してください。

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 の詳細については、「AWS SDK for Swift API リファレンス」の「ListObjects」を参照してください。