公開
マニュアル一覧へ

ご契約者向け
マニュアル一覧へ

IIJ IoTサービス オンラインマニュアル

GET Bucket (List Objects)

指定したバケットの一部又は全てのオブジェクトをリストで返します。
この操作はページング機能をサポートしています。 一度に最大1000個のオブジェクトの一覧を取得し、 marker パラメータを指定して次のリストを取得します。 また、一度に取得するオブジェクトの数は max-keys パラメータで変更することができます。
この操作を行うユーザは、対象バケットに対するREAD権限が必要です。

 

リクエスト情報

シンタックス
GET /{bucket name} HTTP/1.1
Host: s3api.iot.iij.jp
Date: {date}
Authorization: {authorization string}

 

リクエストパラメータ

以下のHTTPリクエストパラメータを使用します。

 

表. GET Bucket リクエストパラメータ一覧

パラメータ名説明必須
delimiter

オブジェクト階層の区切り文字

このパラメータで指定された文字を「階層の区切り文字」として、リクエストで指定したURIに存在するオブジェクトのキーのリストを返します。この時、返されるキーは「階層の区切り文字」で切り捨てられます。具体的な内容については、delimiter パラメータについて をご覧ください。

  • 型:String
  • デフォルト値:なし
×
marker

リストの取得開始位置を指定する文字列

リストされたキーのうち、キーをアルファベット順で並べた際に、ここで指定されたオブジェクトキーより後のもののみをリストに含めます(指定文字列と同名のキーは含まれません)。

  • 型:String
  • デフォルト値:なし
×
max-keys

レスポンスに含めるキーの最大件数

結果が指定された値より少ない件数だった場合には、その件数がそのまま返ります。結果が指定された値より多くの件数を含んでいた場合、実際のレスポンスには指定された値と同じ件数の結果だけが含まれ、かつレスポンスに isTruncated 要素に true がセットされます。

  • 型:String
  • デフォルト値:1000
×
prefix

レスポンスに含めるキーを前方一致でフィルタする為の文字列

URI（バケット名指定がURI形式の場合、バケット名より後ろ）の文字列に対して前方一致のフィルタを行います。

  • 型:String
  • デフォルト値:なし
×

 

リクエストヘッダー

この操作では基本リクエストヘッダーのみ使用します。

リクエストエレメント

この操作ではリクエストエレメントは使用しません。

 

レスポンス情報

レスポンスヘッダー

この操作では基本レスポンスヘッダーのみ返します。

レスポンスエレメント

この操作では以下のレスポンスエレメントを返します。

 

表. GET Bucket レスポンスレメント一覧

名前説明
Contents

各オブジェクトのメタ情報を含むコンテナ

  • 型:Container
  • 子:Etag, Key, LastModified, Owner, Size, StorageClass
  • 親:ListBucketResult
CommonPrefixes

Prefix 直下の仮想的なサブディレクトリのリストを持つコンテナ

リクエストで Prefix および delimiter を指定した場合にのみ含まれます。

  • 型:Container
  • 子:Prefix
  • 親:ListBucketResult
Delimiter

リクエストでデリミタに指定した値

  • 型:String
  • 親:ListBucketResult
DisplayName

バケット所有者の表示名

  • 型:String
  • 親:ListBucketResult.Contents.Owner
ETag

オブジェクトから生成されたMD5ハッシュ値

ETagはメタデータの変更を反映せず、オブジェクトの変更のみ反映します。

  • 型:String
  • 親:ListBucketResult.Contents
ID

オブジェクト所有者のID

  • 型:String
  • 親:ListBucketResult.Contents.Owner
IsTruncated

結果のオブジェクトの件数がMaxKeysによって指定された数を超えているかどうか。

  • 型:Boolean
  • 親:ListBucketResult
Key

オブジェクトのキー（ファイル名）

  • 型:String
  • 親:ListBucketResult.Contents
LastModified

オブジェクトの最終更新日時

  • 型:Date
  • 親:ListBucketResult.Contents
Marker

リストの開始を指定する文字列

リクエストで key-marker に指定した値です。オブジェクトのキーが（アルファベット順で）これより後のオブジェクトのみリストに含めます。

  • 型:Strin
  • g親:ListBucketResult
MaxKeys

レスポンスに含まれるオブジェクトのリストの最大件数

リクエストで max-keys に指定した値です。

  • 型:String
  • 親:ListBucketResult
Name

バケット名

  • 型:String
  • 親:ListBucketResult
Owner

バケット所有者の情報を含むコンテナ

  • 型:Container
  • 子:DisplayName, ID
  • 親:ListBucketResult
Prefix

オブジェクトのキーを前方一致でフィルタリングする文字列

リクエストで prefix, delimiter を指定した場合にのみ含まれます。前方一致文字列直下の仮想的なサブディレクトリです。

  • 型:String
  • 親:ListBucketResult または ListBucketResult.CommonPrefixes
Size

オブジェクトのサイズ（Byte）

  • 型:String
  • 親:ListBucketResult.Contents
StorageClass

常にSTANDARDを返します。

  • 型:String
  • 親:ListBucketResult.Contents
NextMarker

次のリストの取得に使用するマーカー文字列結果のリストが部分的（ IsTrancated が true ）である場合は、次の GET Bucket (List Objects) リクエストの marker パラメータに設定してください。

  • 型:String
  • 親:ListBucketResult

 

delimiter パラメータについて

GET Bucketリクエストにおける delimiter パラメータ指定は「結果として得られた各キーを、指定の文字の箇所で切り落とす」動作を行います。

delimiterの例:

以下のオブジェクトが存在したとします。

  • /foo/photo/2009/index.html
  • /foo/photo/2009/12/xmas.jpg
  • /foo/photo/2010/index.html
  • /foo/photo/2010/01/index.html
  • /foo/photo/2010/01/friends.jpg
  • /foo/photo/2010/01/trip-20100115_01.jpg
  • /foo/photo/2010/02/index.html
  • /foo/photo/2010/02/seminar.jpg

以下のリクエストパラメータでバケット内のオブジェクトリストを要求したとします。

prefix=/foo/photo/2010
delimiter=/

すると、以下の結果が返ってきます。

  • /foo/photo/2010/index.html
  • /foo/photo/2010/01
  • /foo/photo/2010/02

prefixが ”/foo/photo/2010” なので、全てのキーの中でprefixに前方一致するキーのみが候補となります。
候補の各要素について、prefix直下の値（URI文字列の中でprefix部を除いた部分）を調べ、delimiterで指定された文字までを結果として残します。
この結果、得られるリストは「prefix直下の実体オブジェクトと仮想的なサブディレクトリのリスト」となります。

「仮想的なサブディレクトリ」と表現されている部分は、オブジェクトキーをディレクトリ構造で表現したときにサブディレクトリに該当するものを表わしています。そのサブディレクトリは実際には存在しないという点に注意してください。

 

エラー情報

この操作では以下のエラーを返します。

 

表. GET Bucketエラーコード一覧
コードステータス内容
InvalidAccessKeyId403 Forbidden指定のアクセスキーIDを持つユーザが存在しません。
SignatureDoesNotMatch403 Forbidden指定されたリクエストのシグネチャが一致しません。
AccessDenied403 Forbiddenバケットに対するREAD権限がありません。
NoSuchBucket404 Not Found指定のバケットが存在しません。

 

サンプル

BucketName という名のバケット内のオブジェクトの一覧を取得するサンプル

リクエスト
GET /BucketName HTTP/1.1
Host: s3api.iot.iij.jp
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: IIJGIO 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=
Content-Type: text/plain
レスポンス
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult>
  <Name>bucket</Name>
  <Prefix/>
  <Marker/>
  <MaxKeys>1000</MaxKeys>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>my-image.jpg</Key>
    <LastModified>2009-10-12T17:50:30.000Z</LastModified>
    <ETag>&quot;fba9dede5f27731c9771645a39863328&quot;</ETag>
    <Size>434234</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>8a6925ce4a7f21c32aa379004fef</ID>
      <DisplayName>mtd@dag.iijgio.com</DisplayName>
    </Owner>
  </Contents>
  <Contents>
    <Key>my-third-image.jpg</Key>
    <LastModified>2009-10-12T17:50:30.000Z</LastModified>
    <ETag>&quot;1b2cf535f27731c974343645a3985328&quot;</ETag>
    <Size>64994</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>8a69b1ddee97f21c32aa379004fef</ID>
      <DisplayName>mtd@dag.iijgio.com</DisplayName>
    </Owner>
  </Contents>
</ListBucketResult>

 

キー名が”N”と前方一致していて、かつアルファベット順で”Ned”より後になるオブジェクトを40件取得するサンプル(prefix=N, marker=Ned, max-keys=40)

リクエスト
GET /quotes?prefix=N&marker=Ned&max-keys=40 HTTP/1.1
Host: s3api.iot.iij.jp
Date: Wed, 01 Mar 2009 12:00:00 GMT
Authorization: IIJGIO 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=
レスポンス
HTTP/1.1 200 OK
x-iijgio-id-2: gyB+3jRPnrkN98ZajxHXr3u7EFM67bNgSAxexeEHndCX/7GRnfTXxReKUQF28IfP
x-iijgio-request-id: 3B3C7C725673C630
Date: Wed, 01 Mar 2009 12:00:00 GMT
Content-Type: application/xml
Content-Length: 302
Server: s3api.iot.iij.jp
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult>
  <Name>quotes</Name>
  <Prefix>N</Prefix>
  <Marker>Ned</Marker>
  <MaxKeys>40</MaxKeys>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>Nelson</Key>
    <LastModified>2006-01-01T12:00:00.000Z</LastModified>
    <ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
    <Size>5</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>bcaf161ca5fb16fd081034f</ID>
      <DisplayName>webfile</DisplayName>
    </Owner>
  </Contents>
  <Contents>
    <Key>Neo</Key>
    <LastModified>2006-01-01T12:00:00.000Z</LastModified>
    <ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
    <Size>4</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>bcaf1ffd86a5fb16fd081034f</ID>
      <DisplayName>webfile</DisplayName>
    </Owner>
  </Contents>
</ListBucketResult>

 

“photos/2006/”直下のオブジェクトを取得するサンプル

“photos/2006/”に前方一致するキーを抽出し、”/”を区切り文字として指定します。
(prefix=photos/2006/, delimiter=/)

リクエスト
GET /quotes?prefix=photos/2006/&delimiter=/ HTTP/1.1
Host: s3api.iot.iij.jp
Date: Wed, 01 Mar 2009 12:00:00 GMT
Authorization: IIJGIO 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=
レスポンス
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult>
  <Name>johnsmith</Name>
  <Prefix>photos/2006/</Prefix>
  <Marker/>
  <MaxKeys>1000</MaxKeys>
  <Delimiter>/</Delimiter>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>photos/2006/index.html</Key>
    <LastModified>2009-01-01T12:00:00.000Z</LastModified>
    <ETag>"ce1acdafcc879d7eee54cf4e97334078"</ETag>
    <Size>1234</Size>
    <Owner>
      <ID>214153b66967d86f031c7487b4566cb1b</ID>
      <DisplayName>John Smith</DisplayName>
    </Owner>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
  <CommonPrefixes>
    <Prefix>photos/2006/January/</Prefix>
  </CommonPrefixes>
</ListBucketResult>