GET Bucket (List Objects)

指定したバケットの一部又は全てのオブジェクトをリストで返します。

この操作はページング機能をサポートしています。一度に最大1000個のオブジェクトの一覧を取得し、markerパラメータを指定して次のリストを取得します。また、一度に取得するオブジェクトの数はmax-keysパラメータで変更することができます。

この操作を行うユーザは、対象バケットに対するREAD権限が必要です。

一覧を取得したいバケットがあるリージョンに対してリクエストを行う必要があります。

リクエスト情報

シンタックス

GET / HTTP/1.1
Host: {bucket name}.storage-dag.iijgio.com
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に指定した値です。オブジェクトのキーが(アルファベット順で)これより後のオブジェクトのみリストに含めます。

型:String
親: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
次のリストの取得に使用するマーカー文字列

結果のリストが部分的(IsTrancatedtrue)である場合は、次の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直下の実体オブジェクトと仮想的なサブディレクトリのリスト」となります。

Note

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

エラー情報

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

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

サンプル

BucketName という名のバケット内のオブジェクトの一覧を取得するサンプル
リクエスト
GET / HTTP/1.1
Host: BucketName.storage-dag.iijgio.com
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 ?prefix=N&marker=Ned&max-keys=40 HTTP/1.1
Host: quotes.storage-dag.iijgio.com
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: storage-dag.iijgio.com
<?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 ?prefix=photos/2006/&delimiter=/ HTTP/1.1
Host: quotes.storage-dag.iijgio.com
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>

HEAD Bucket

HEAD Bucketは指定したバケットが存在するかどうか、およびバケットに対してアクセス可能かどうかを返します。

バケットが存在しなければ404 Not Foundを返し、バケットが存在しアクセスするための権限を保持している場合は200 OKを、権限を保持していなければ403 Forbiddenを返します。

対象のバケットが存在するリージョンに対してリクエストを行う必要があります。

リクエスト情報

シンタックス

HEAD / HTTP/1.1
Host: {bucket name}.storage-dag.iijgio.com
Date: {date}
Authorization: {authorization string}

リクエストパラメータ

この操作ではリクエストパラメータは使用しません。

リクエストヘッダー

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

リクエストエレメント

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

レスポンス情報

レスポンスヘッダー

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

レスポンスエレメント

この操作はレスポンスエレメントを返しません。

サンプル

mybucketという名のバケットが存在し、アクセス可能な場合のサンプル

リクエスト
HEAD / HTTP/1.1
Date: Wed, 1 Oct 2014 00:00:00 GMT
Authorization: IIJGIO 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=
Host: mybucket.storage-dag.iijgio.com
Connection: Keep-Alive
レスポンス
HTTP/1.1 200 OK
x-iijgio-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo
x-iijgio-request-id: 236A8905248E5A01
Date: Wed, 1 Oct 2014 00:00:00 GMT
Server: storage-dag.iijgio.com

PUT Bucket

新しいバケットを作成します。

匿名は本APIを利用できません。本APIを利用するためには、有効なAccessKeyIdで認証されたリクエストである必要があります。匿名状態、つまりAuthorizationヘッダの指定がない状態ではエラーを返します。

バケットには所有者の概念があり、認証の際に利用したAccessKeyId(アカウント)がバケットの所有者になります。

バケットの命名規則はバケット(Bucket)を参照ください。

バケットはリクエストをしたリージョンに作成されます。リクエストエレメントLocationConstraintでリージョンを指定する場合、この値はリクエスト先のリージョン(エンドポイント)と一致する必要があります。リクエストエレメントLocationConstraintでのリージョンの指定は省略が可能です。

バケットのアクセス制御の設定を行うには、リクエストヘッダーのx-iijgio-aclを用います。

Note

バケット登録の際に100ms以内の遅延が発生する場合があります。同一バケットに対して連続した操作を行った時に 404 Not Found が返された場合は操作のリトライをお願い致します。

リクエスト情報

シンタックス

PUT / HTTP/1.1
Host: {bucket name}.storage-dag.iijgio.com
Content-Length: {length}
Date: {date}
Authorization: {authorization string}

リクエストパラメータ

この操作ではリクエストパラメータは使用しません。

リクエストヘッダー

この操作は、バケットの作成と同時に本サービスのアカウントやグループ(匿名ユーザなど)に対して Access Control List (ACL) として権限を付与することができます。
ACLを設定する方法として以下の2つが用意されています。ただし、両方を同時に指定することはできません。

Canned ACL で指定する場合

表. PUT Bucket リクエストヘッダー(Canned ACL)
HTTPヘッダー 説明 必須
x-iijgio-acl
バケットのACLを設定する
型:String
有効な値:private | public-read | public-read-write
デフォルト値:private
×

詳細に指定する場合

より詳細に ACL を設定する場合は以下のリクエストヘッダーを指定してください。

表. PUT Bucket リクエストヘッダー(ACL詳細指定)
HTTPヘッダー 説明 必須
x-iijgio-grant-read
このバケットにおけるオブジェクト一覧の閲覧を許可するアカウントまたはグループのリスト
型:String
デフォルト値:なし
×
x-iijgio-grant-write
このバケットに対してオブジェクトの作成、上書き、削除を許可するアカウントまたはグループのリスト
型:String
デフォルト値:なし
×
x-iijgio-grant-read-acp
バケットACLの参照を許可するアカウントまたはグループのリスト
型:String
デフォルト値:なし
×
x-iijgio-grant-write-acp
バケットACLの設定を許可するアカウントまたはグループのリスト
型:String
デフォルト値:なし
×
x-iijgio-grant-full-control
このバケットに対して全ての権限を付加するアカウントまたはグループのリスト
型:String
デフォルト値:なし
×

設定するアカウントまたはグループはそれぞれtype=value形式で指定します。typeには以下のいずれかを指定できます。

  • emailAddress: アカウントのメールアドレス

  • id: アカウントの Show ID

  • url: グループを示す以下のURL

x-iijgio-grant-readヘッダーを指定する例:

x-iijgio-grant-read: emailAddress="taro@dag.iijgio.com", emailAddress="jiro@dag.iijgio.com"

リクエストエレメント

この操作では以下のリクエストエレメントを使用します。

表. PUT Bucket リクエストエレメント一覧
名前 説明 必須
CreateBucketConfiguration
LocationConstraintを含むコンテナ
型:Container
親:なし
×
LocationConstraint
バケットが属するリージョン
型:String
有効な値:エンドポイントの表にあるリージョンの識別子もしくは、リージョンの別名を指定してください。
デフォルト値:なし
親:CreateBucketConfiguration
×

レスポンス情報

レスポンスヘッダー

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

レスポンスエレメント

この操作はレスポンスエレメントを返しません。

エラー情報

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

表. PUT Bucket エラーコード一覧
コード ステータス 内容
InvalidAccessKeyId 403 Forbidden 指定のアクセスキーIDを持つユーザが存在しません。
SignatureDoesNotMatch 403 Forbidden 指定されたリクエストのシグネチャが一致しません。
InvalidBucketName 400 Bad Request バケット名が不正です。
InvalidLocationConstraint 400 Bad Request LocationConstraintに無効な値が設定されています。
BucketAlreadyExists 409 Conflict バケット名が既に使用されています。
BucketAlreadyOwnedByYou 409 Conflict 既に同名のバケット所有者です。

サンプル

colorpictures という名のバケットを作成するサンプル
リクエスト
PUT / HTTP/1.1
Host: colorpictures.storage-dag.iijgio.com
Content-Length: 0
Date: Wed, 01 Mar 2009 12:00:00 GMT
Authorization: IIJGIO 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=
レスポンス
HTTP/1.1 200 OK
x-iijgio-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo
x-iijgio-request-id: 236A8905248E5A01
Date: Wed, 01 Mar 2009 12:00:00 GMT
Location: /colorpictures
Content-Length: 0
Server: storage-dag.iijgio.com
バケット作成時に属するリージョンをJP-WEST1に指定するサンプル
リクエスト
PUT / HTTP/1.1
Host: bucketName.storage-dag.iijgio.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: IIJGIO 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=
Content-Type: text/plain
Content-Length: 124

<CreateBucketConfiguration xmlns="http://acs.dag.iijgio.com/doc/2006-03-01/">
  <LocationConstraint>JP-WEST1</LocationConstraint>
</CreateBucketConfiguration >
レスポンス
HTTP/1.1 200 OK
x-iijgio-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo
x-iijgio-request-id: 236A8905248E5A01
Date: Wed, 01 Mar 2009 12:00:00 GMT
Location: /bucketName
Content-Length: 0
Server: storage-dag.iijgio.com
バケットを作成時にACL(private)を設定するサンプル
リクエスト
PUT / HTTP/1.1
Host: colorpictures.storage-dag.iijgio.com
Content-Length: 0
x-iijgio-acl: private
Date: Wed, 01 Mar 2009 12:00:00 GMT
Authorization: IIJGIO 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=
レスポンス
HTTP/1.1 200 OK
x-iijgio-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo
x-iijgio-request-id: 236A8905248E5A01
Date: Wed, 01 Mar 2009 12:00:00 GMT
Location: /colorpictures
Content-Length: 0
Server: storage-dag.iijgio.com

DELETE Bucket

自身が所有者であるバケットを削除します。

削除対象とするバケットは空(1つもオブジェクトが配置されていない状態)でなければなりません。従って、対象バケットが1つ以上のオブジェクトを保持している場合、それらのオブジェクトはバケットの削除前に全て削除する必要があります。

バケットはACLの設定内容にかかわらず、バケット所有者のみが削除することができます。

このリクエストではAccessKeyIdが必須であり、特定ユーザ(本サービスに有効なアカウントを持つ者)のみが利用できます。匿名ユーザは本リクエストを利用できません。

削除対象のバケットが存在するリージョンに対してリクエストを行う必要があります。

リクエスト情報

シンタックス

DELETE / HTTP/1.1
Host: {bucket name}.storage-dag.iijgio.com
Date: {date}
Authorization: {authorization string}

リクエストパラメータ

この操作ではリクエストパラメータは使用しません。

リクエストヘッダー

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

リクエストエレメント

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

レスポンス情報

レスポンスヘッダー

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

レスポンスエレメント

この操作はレスポンスエレメントを返しません。

エラー情報

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

表. DELETE Bucket エラーコード一覧
コード ステータス 内容
InvalidAccessKeyId 403 Forbidden 指定のアクセスキーIDを持つユーザが存在しません。
SignatureDoesNotMatch 403 Forbidden 指定されたリクエストのシグネチャが一致しません。
NoSuchBucket 404 Not Found 指定のバケットが存在しません。
AccessDenied 403 Forbidden アクセス権限がありません。
BucketNotEmpty 409 Conflict バケットが空ではありません。

サンプル

quotes という名のバケットを削除するサンプル
リクエスト
DELETE / HTTP/1.1
Host: quotes.storage-dag.iijgio.com
Date: Wed, 01 Mar 2009 12:00:00 GMT
Authorization: IIJGIO 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=
レスポンス
HTTP/1.1 204 No Content
x-iijgio-id-2: JuKZqmXuiwFeDQxhD7M8KtsKobSzWA1QEjLbTMTagkKdBX2z7Il/jGhDeJ3j6s80
x-iijgio-request-id: 32FE2CEB32F5EE25
Date: Wed, 01 Mar 2009 12:00:00 GMT
Server: storage-dag.iijgio.com

ページ先頭へ