バケット内のオブジェクトを一覧表示するには、バケットを範囲とする GET リクエストを作成します。また、クエリ文字列パラメータを使用してリクエストの範囲をさらに絞り込むこともできます。 リクエストは、レスポンスの本文に含まれる XML ドキュメントにオブジェクトのリストを返します。リスト内のオブジェクトは名前順に辞書順に表示されます。
バケット内にあるオブジェクトの一覧を取得するには、バケットの READ
権限が必要です。バケットの ACL や CORS を一覧表示するには、バケットの FULL_CONTROL
権限が必要です。
GET Bucket リクエストで返されるオブジェクトの一覧を制限したり整理したりするには、delimiter
、marker
、max-keys
、prefix
クエリ文字列パラメータを使用します。
XML API では、1,000 を超えるオブジェクトは返されません。
クエリ文字列パラメータ
パラメータ | 説明 | 必須 |
---|---|---|
delimiter |
ディレクトリのような命名スキームを使用するオブジェクトの一覧を見やすくするために使用できる 1 つまたは複数の文字。prefix と組み合わせて使用できます。 |
× |
encoding-type |
url に設定すると、レスポンス内でオブジェクト名は URL エンコードされます。 |
× |
generation-marker |
このオブジェクト世代より後のオブジェクトから一覧表示を開始します。generation-marker を使用する場合は、必ずマーカーを使用する必要があります。 | × |
marker |
このオブジェクトの一覧より後ろにあるオブジェクトの名前。marker より辞書順で後ろにあるオブジェクトがオブジェクトの一覧に返されます。 |
× |
max-keys |
オブジェクト一覧表示リクエストで返すオブジェクトの最大数。 | × |
prefix |
GET Bucket リクエストで返されるオブジェクトの数を、指定された値で始まる名前に制限するために使用される文字列。delimiter と組み合わせて使用できます。 |
× |
versions |
バージョニングされているバケットで指定すると、すべてのオブジェクト バージョンの一覧が返されます。省略した場合は、現在のバージョンのみ一覧表示されます。 | × |
署名付き URL を作成して使用するときに指定するパラメータについては、署名付き URL クエリ文字列パラメータをご覧ください。
リクエスト ヘッダー
一般的なリクエスト ヘッダーをご覧ください。
リクエストの本文の要素
このリクエストの本文に XML ドキュメントは含まれません。
リクエストの構文
次の構文は、パラメータを使用しないか、delimiter
、generation-marker
、marker
、max-keys
、prefix
のいずれかを使用する GET Bucket リクエストに適用されます。 、および versions
クエリ文字列パラメータです。
GET /?prefix=a_prefix&marker=a_marker&max-keys=max_number_of_keys&delimiter=a_delimiter HTTP/1.1 Host: BUCKET_NAME.storage.googleapis.com Date: DATE Content-Length: 0 Authorization: AUTHENTICATION_STRING
レスポンス ヘッダー
使用するリクエスト ヘッダーに応じて、リクエストから返されるレスポンス ヘッダーは異なります。
レスポンスの本文の要素
次のレスポンスの本文の要素は、パラメータを使用しないか、delimiter
、generation-marker
、marker
、max-keys
、prefix
、versions
クエリ文字列パラメータを使用してバケット内のオブジェクトを一覧表示します。
要素 | 説明 |
---|---|
ListBucketResult |
リクエスト対象のオブジェクト情報のコンテナ。 |
Name |
バケットの名前。 |
CommonPrefixes |
prefix 制約と delimiter 制約を満たす接頭辞のコンテナ。このコンテナは、リクエストで delimiter を指定した場合のみ使用され、重複するエントリは省略されます。 |
Delimiter |
リクエストで指定した delimiter 。 |
MaxKeys |
リクエストで指定した max-keys 。 |
Prefix |
リクエストで指定した prefix 。 |
GenerationMarker |
リクエストで指定した generation-marker 。 |
NextGenerationMarker |
返されたオブジェクトの一覧が不完全で、versions パラメータが使用されている場合、返された最後のオブジェクトの世代が NextGenerationMarker から提供されます。リストがすでに完全な場合、NextGenerationMarker は返されません。 |
Marker |
リクエストで指定した marker 。 |
NextMarker |
NextMarker は、返された最後のオブジェクト名を提供します。NextMarker の値は、今後 GET Bucket 呼び出しで marker クエリ文字列パラメータを指定して、この結果セットの後にバケットの一覧表示を続けることができます。一覧の最終オブジェクトの後ろにバケット内のオブジェクトが存在しない場合、NextMarker は返されません。 |
IsTruncated |
バケット内のオブジェクトがすべて一覧に含まれているかどうかを示します。max-keys がバケット内のオブジェクトの数より小さい場合、この要素は True になります。 |
Contents |
versions クエリ パラメータを使用しない場合のオブジェクト情報のコンテナ。 |
Version |
versions クエリ パラメータを使用する場合のオブジェクト情報のコンテナ。 |
Key |
オブジェクトの名前。 |
Generation |
オブジェクトの世代。 |
MetaGeneration |
オブジェクトのメタデータの世代。 |
IsLatest |
versions クエリ パラメータを指定した場合、オブジェクトが現在ライブの場合は true に設定されます。ライブとは、世代を指定せずにこのオブジェクトをリクエストすると、このオブジェクトが返されることを意味します。 |
LastModified |
オブジェクトが最後に変更された日時。 |
DeletedTime |
versions クエリ パラメータを指定した場合、現在のオブジェクトでオブジェクトの置換や削除が行われた日時が含まれます(バケットでバージョニングが有効になっている場合)。 |
ETag |
オブジェクトの HTTP 1.1 エンティティ タグ。 |
Size |
オブジェクトのサイズ(バイト単位)。 |
KmsKeyName |
オブジェクトの暗号化に使用される KMS 鍵の名前。この要素は、オブジェクトが顧客管理の暗号鍵で暗号化されている場合にのみ存在します。 |
例
次の例では、travel-maps という名前のバケット内のオブジェクトを一覧表示します。
リクエスト
GET / HTTP/1.1 Host: travel-maps.storage.googleapis.com Date: Wed, 17 Feb 2010 15:31:56 GMT Content-Length: 0 Content-Type: text/plain Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
レスポンス
HTTP/1.1 200 OK Content-Length: 4061 Content-Type: application/xml Date: Wed, 17 Feb 2010 23:31:57 GMT Expires: Wed, 17 Feb 2010 23:31:57 GMT <?xml version='1.0' encoding='utf-8'?> <ListBucketResult xmlns='http://doc.s3.amazonaws.com/2006-03-01'> <Name>travel-maps</Name> <Prefix></Prefix> <Marker></Marker> <IsTruncated>false</IsTruncated> <Contents> <Key>europe/france/cannes.pdf</Key> <Generation>1360887759327000</Generation> <MetaGeneration>1</MetaGeneration> <LastModified>2010-02-17T22:11:12.487Z</LastModified> <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag> <Size>5061631</Size> </Contents> <Contents> <Key>europe/france/paris.pdf</Key> <Generation>1360887759329000</Generation> <MetaGeneration>1</MetaGeneration> <LastModified>2010-02-17T22:09:57.457Z</LastModified> <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag> <Size>5061631</Size> </Contents> </ListBucketResult>
次の例では、travel-maps 内のオブジェクトを一覧表示していますが、「t」から始まる「test」の次からのオブジェクトを 25 個に絞って表示しています。
リクエスト
GET /?prefix=t&marker=test&max-keys=25 HTTP/1.1 Host: travel-maps.storage.googleapis.com Date: Mon, 16 Feb 2010 22:58:38 GMT Content-Length: 0 Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
レスポンス
HTTP/1.1 200 OK Date: Mon, 15 Feb 2010 12:30:40 GMT Content-Length: 2705 Content-Type: application/xml <?xml version='1.0' encoding='utf-8'?> <ListBucketResult xmlns='http://doc.s3.amazonaws.com/2006-03-01'> <Name>travel-maps</Name> <Prefix>t</Prefix> <Marker>test</Marker> <MaxKeys>25</MaxKeys> <IsTruncated>false</IsTruncated> <Contents> <Key>test_a.jpg</Key> <Generation>1360887659329000</Generation> <MetaGeneration>1</MetaGeneration> <LastModified>2010-02-17T03:12:55.561Z</LastModified> <ETag>"2281880ef78388266ecd7d4c1b472a0e"</ETag> <Size>328</Size> </Contents> <Contents> <Key>test_b.jpg</Key> <Generation>1360887659323000</Generation> <MetaGeneration>1</MetaGeneration> <LastModified>2010-02-17T03:12:54.606Z</LastModified> <ETag>"2281880ef78388266ecd7d4c1b472a0e"</ETag> <Size>328</Size> </Contents> <Contents> <Key>test_c.jpg</Key> <LastModified>2010-02-17T03:12:53.734Z</LastModified> <ETag>"2281880ef78388266ecd7d4c1b472a0e"</ETag> <Size>328</Size> </Contents> </ListBucketResult>
接頭辞と区切り文字の使用例
次の例では、prefix
と delimiter
を使用して、ディレクトリに似たスキーマを使用して名前が指定されたオブジェクトの一覧を返します。prefix=europe/
と delimiter=/
を使用すると、europe/
の「ディレクトリ」にあるオブジェクトのみが返されます。europe ディレクトリのサブディレクトリのオブジェクトは一覧表示されず、代わりにレスポンスの CommonPrefixes
要素に名前の先頭部分が含まれています。この例では、次のオブジェクトが travel-maps
という名前のバケットにあることを前提としています。
- africa/ghana.jpg
- africa/egypt/cairo.jpg
- europe/finland.jpg
- europe/norway.jpg
- europe/france/paris.jpg
- europe/italy/rome.jpg
- europe/sweden/stockholm.jpg
- europe/sweden/stockholm/nordic_museum.jpg
このリクエストの例では、Contents
要素内にある次の 2 つのオブジェクトを一覧表示する XML ドキュメントが返されます。
- europe/finland.jpg
- europe/norway.jpg
次の europe サブディレクトリが CommonPrefixes
要素にリストされています。
- europe/france/
- europe/italy/
- europe/sweden/
リクエスト
GET /travel-maps?delimiter=/&prefix=europe/ HTTP/1.1 Host: storage.googleapis.com Date: Mon, 16 Feb 2010 22:58:38 GMT Content-Length: 0 Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
レスポンス
HTTP/1.1 200 OK Date: Mon, 15 Feb 2010 12:30:40 GMT Content-Length: 1200 Content-Type: application/xml <?xml version="1.0"?> <ListBucketResult xmlns='http://doc.s3.amazonaws.com/2006-03-01'> <Name>mybucket</Name> <Prefix>europe/</Prefix> <Marker /> <IsTruncated>false</IsTruncated> <Contents> <Key>europe/finland.jpg</Key> <Generation>1360887659323000</Generation> <MetaGeneration>1</MetaGeneration> <LastModified>2010-02-17T03:12:55.561Z</LastModified> <ETag>"781e5e245d69b566979b86e28d23f2c7"</ETag> <Size>10</Size> </Contents> <Contents> <Key>europe/norway.jpg</Key> <Generation>1360887659323000</Generation> <MetaGeneration>1</MetaGeneration> <LastModified>2010-02-17T03:12:55.561Z</LastModified> <ETag>"781e5e245d69b566979b86e28d23f2c7"</ETag> <Size>10</Size> </Contents> <CommonPrefixes> <Prefix>europe/france/</Prefix> </CommonPrefixes> <CommonPrefixes> <Prefix>europe/italy/</Prefix> </CommonPrefixes> <CommonPrefixes> <Prefix>europe/sweden/</Prefix> </CommonPrefixes> </ListBucketResult>