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

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

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

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

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

注記

SOAP のサポートは HTTP 経由では廃止されましたが、HTTPS 経由では引き続き利用可能です。SOAP では、Amazon S3 の新機能がサポートされなくなります。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 ラッパーライブラリでも行うことができます。

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

この例では、バージョン 3 の AWS SDK for PHP のクラスを使用して、Amazon S3 バケットに含まれるオブジェクトキーを一覧表示する手順を示します。

この例では、AWS SDK for PHP の使用と PHP サンプルの実行 の手順を既に実行しており、AWS SDK for PHP が正しくインストールされていることを前提としています。

AWS SDK for PHP を使用してバケットに含まれるオブジェクトキーをリストするには、まずバケットに含まれるオブジェクトをリストし、次にリストされた各オブジェクトからキーを抽出します。バケットのオブジェクトキーをリストする際、下位の Aws\S3\S3Client::listObjects() メソッドを使用するか、または上位の Aws\ResultPaginator クラスを使用するかを選択できます。

下位の listObjects() メソッドは、基盤となる Amazon S3 REST API にマッピングします。1 つの listObjects() リクエストは、最大 1,000 オブジェクトからなるページを返します。バケットに 1,000 を超えるオブジェクトがある場合、レスポンスは切り捨てられるため、次の 1,000 個のオブジェクトのセットを取得するにはもう 1 つの listObjects() リクエストを送信する必要があります。

高レベルの ListObjects ページネーターを使用すると、バケットに含まれるオブジェクトを簡単に一覧表示できます。ListObjects ページネーターを使用してオブジェクトのリストを作成するには、Aws/AwsClientInterface クラスから継承された、Amazon S3 クライアントの getPaginator() メソッドを実行します。このとき、1 番目の引数として ListObjects コマンドを指定し、2 番目の引数として、指定したバケットから返されるオブジェクトを格納する配列を指定します。

ListObjects メソッドを getPaginator() ページネーターとして使用すると、指定したバケットに含まれるすべてのオブジェクトが返されます。1,000 個までのオブジェクトには制限がないため、レスポンスが切り捨てられるかどうかを心配する必要はありません。

以下のタスクは、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; }