オブジェクトのリスト

バケット内のオブジェクトを一覧表示するには、バケットを範囲とする 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>