技術情報

技術情報

OpenStack: Swift 【API 編】

2013年5月27日

技術文書トップへ

第 4 章 オブジェクトストレージ操作

1. アカウントサービス

1-1. コンテナ一覧の取得

アカウント持つコンテナ一覧を取得します。コンテナ名は、辞書順に並び替えられます。また、format パラメータを指定した場合、コンテナ一覧に加えて、各コンテナが持つオブジェクト数およびオブジェクトサイズの合計の情報も返却されます。

【リクエスト】

【レスポンス】

【コンテナ一覧の出力フォーマット指定】

詳細な情報の取得が必要な時は、format パラメータを指定します。

  • format 省略時
    コンテナ名
    コンテナ名
        :
    コンテナ名
    
  • format=json
    [{"name":"コンテナ名",
      "count":オブジェクト数,
      "bytes":オブジェクト総容量},
      {...}, ...
    ]
    
  • format=xml
    <?xml version="1.0" encoding="UTF-8"?>
    <account name="アカウント名">
        <container>
            <name>コンテナ名</name>
            <count>オブジェクト数</count>
            <bytes>オブジェクト総容量</bytes>
        </container>
            :
    </account>
    
  • marker、limit パラメータ
    GET リクエスト時に、marker パラメータと limit パラメータを組み合わせて利用することで、コンテナ一覧取得処理を複数回に分割して実行することができます。これは、非常に多くのコンテナが存在する環境で役に立ちます。
    1 回の GET リクエストで取得できるコンテナ名は、最大 10,000 個です。1 回の GET でコンテナ名を取得しきれなかった場合には、続けて marker パラメータを指定した GET リクエストを送信する必要があります。marker パラメータに前回受信したレスポンスの最後のコンテナ名を指定することで、その続きからコンテナ名を取得することが可能です。
    limit パラメータ未指定の場合の取得数最大値は 10,000 です。limit パラメータにより、コンテナ名の取得数の最大値をより小さい値に変更することができます。
    GET リクエストにより取得したコンテナ名の数が、ちょうど取得数最大値に一致した場合、未取得のコンテナ名が残っている可能性があります。その場合、取得できたコンテナ名のうち最後のコンテナ名を marker パラメータに指定して、再度 GET リクエストを送る必要があります。ただし、コンテナ数がちょうど取得数最大値の倍数であった場合には、最後の GET リクエストに対して空のレスポンス (204 No Content) が返されることになるので、注意が必要です。

【実行例: marker、limit パラメータ】

まず、marker、limit パラメータを指定せずに全コンテナ名を取得します。

  • GET リクエスト
    GET /v1/AUTH_transporters HTTP/1.1
    User-Agent: curl/7.19.7 (i486-pc-linux-gnu) libcurl/7.19.7 OpenSSL/0.9.8k zlib/1.2.3.3 libidn/1.15
    Host: objstore.example.jp
    Accept: */*
    X-Auth-Token: AUTH_tk395fe09733df4789aae26f65b20f060e
    
  • レスポンス
    HTTP/1.1 200 OK
    X-Account-Object-Count: 0
    X-Account-Bytes-Used: 0
    X-Account-Container-Count: 13
    Content-Length: 82
    Content-Type: text/plain; charset=utf8
    Date: Sun, 24 Jul 2011 23:13:18 GMT
    
    airplane
    bicycle
    bike
    boat
    bus
    car
    coach
    horseback
    ship
    subway
    taxi
    train
    walking
    

次は、コンテナ名を 5 つずつ取得します。limit パラメータに 5 を指定して、GET リクエストを送ります。

  • GET リクエスト
    GET /v1/AUTH_transporters/?limit=5 HTTP/1.1
    User-Agent: curl/7.19.7 (i486-pc-linux-gnu) libcurl/7.19.7 OpenSSL/0.9.8k zlib/1.2.3.3 libidn/1.15
    Host: objstore.example.jp
    Accept: */*
    X-Auth-Token: AUTH_tk395fe09733df4789aae26f65b20f060e
    
  • レスポンス
    HTTP/1.1 200 OK
    X-Account-Object-Count: 0
    X-Account-Bytes-Used: 0
    X-Account-Container-Count: 13
    Content-Length: 31
    Content-Type: text/plain; charset=utf8
    Date: Sun, 24 Jul 2011 23:14:10 GMT
    
    airplane
    bicycle
    bike
    boat
    bus
    

コンテナ名を取得しきれていない (コンテナ数が limit の値と同じ 5 つ) ため、取得できたコンテナ名の最後のものである "bus" を marker に指定して、再度 GET を送ります。

  • GET リクエスト
    GET /v1/AUTH_transporters/?limit=5&marker=bus HTTP/1.1
    User-Agent: curl/7.19.7 (i486-pc-linux-gnu) libcurl/7.19.7 OpenSSL/0.9.8k zlib/1.2.3.3 libidn/1.15
    Host: objstore.example.jp
    Accept: */*
    X-Auth-Token: AUTH_tk395fe09733df4789aae26f65b20f060e
    
  • レスポンス
    HTTP/1.1 200 OK
    X-Account-Object-Count: 0
    X-Account-Bytes-Used: 0
    X-Account-Container-Count: 13
    Content-Length: 32
    Content-Type: text/plain; charset=utf8
    Date: Sun, 24 Jul 2011 23:15:33 GMT
    
    car
    coach
    horseback
    ship
    subway
    

同様に、取得できたコンテナ名の最後のもの "subway" を marker に指定して、再度 GET を送ります。取得できたコンテナ名は 3 つであり、limit の値の 5 つまで取得できていないため、これでコンテナ名を全て読み出したことになります。

  • GET リクエスト
    GET /v1/AUTH_transporters/?limit=5&marker=subway HTTP/1.1
    User-Agent: curl/7.19.7 (i486-pc-linux-gnu) libcurl/7.19.7 OpenSSL/0.9.8k zlib/1.2.3.3 libidn/1.15
    Host: objstore.example.jp
    Accept: */*
    X-Auth-Token: AUTH_tk395fe09733df4789aae26f65b20f060e
    
  • レスポンス
    HTTP/1.1 200 OK
    X-Account-Object-Count: 0
    X-Account-Bytes-Used: 0
    X-Account-Container-Count: 13
    Content-Length: 19
    Content-Type: text/plain; charset=utf8
    Date: Sun, 24 Jul 2011 23:15:50 GMT
    
    taxi
    train
    walking
    

試しに、最後のコンテナ名を marker に指定して GET を送ったときの動きをみておきましょう。取得したコンテナ名の最後のものである "walking" を marker に指定して、GET を送ると、単にレスポンスとして成功 (204) が返されてくることがわかります。

  • GETリクエスト
    GET /v1/AUTH_transporters/?limit=5&marker=walking HTTP/1.1
    User-Agent: curl/7.19.7 (i486-pc-linux-gnu) libcurl/7.19.7 OpenSSL/0.9.8k zlib/1.2.3.3 libidn/1.15
    Host: objstore.example.jp
    Accept: */*
    X-Auth-Token: AUTH_tk395fe09733df4789aae26f65b20f060e
    
  • レスポンス
    HTTP/1.1 204 No Content
    X-Account-Object-Count: 0
    X-Account-Bytes-Used: 0
    X-Account-Container-Count: 13
    Content-Length: 0
    Date: Sun, 24 Jul 2011 23:47:35 GMT
    

【実行例: format パラメータ】

各種 format 指定を行った時の実行例を説明します。
アカウント (ストレージ URL) に対して GET リクエストを送ります。レスポンスにより、このアカウントには 4 つのコンテナ (X-Account-Container-Count: 4) が存在し、それぞれ bin、doc、image、src という名前であることがわかります。
オブジェクトは、まだ 2 つしか登録されていません (X-Account-Object-Count: 2) が、容量はそこそこ使っているため (X-Account-Bytes-Used: 715653825)、大きめのオブジェクトが登録されていることがわかります。

  • GET リクエスト
    GET /v1/AUTH_orion-cabinet HTTP/1.1
    User-Agent: curl/7.21.0 (x86_64-pc-linux-gnu) libcurl/7.21.0 OpenSSL/0.9.8o zlib/1.2.3.4 libidn/1.18
    Host: objstore.example.jp
    Accept: */*
    X-Auth-Token: AUTH_tkcbd0b108401245a3acf1b550aa4862bb
    
  • レスポンス
    HTTP/1.1 200 OK
    X-Account-Object-Count: 2
    X-Account-Bytes-Used: 715653825
    X-Account-Container-Count: 4
    Content-Length: 18
    Content-Type: text/plain; charset=utf8
    Date: Thu, 07 Jul 2011 02:35:22 GMT
    
    bin
    doc
    image
    src
    

アカウント (ストレージURL) に対して GET リクエストを送る際に "format=json" を指定し、より詳細な情報を得てみましょう。
レスポンスによると、コンテナ bin とコンテナ image の下にそれぞれオブジェクトが 1 つずつ登録されており、コンテナ doc とコンテナ src の下にはまだ何もオブジェクトがないことがわかります。

  • GET リクエスト
    GET /v1/AUTH_orion-cabinet?format=json HTTP/1.1
    User-Agent: curl/7.21.0 (x86_64-pc-linux-gnu) libcurl/7.21.0 OpenSSL/0.9.8o zlib/1.2.3.4 libidn/1.18
    Host: objstore.example.jp
    Accept: */*
    X-Auth-Token: AUTH_tkcbd0b108401245a3acf1b550aa4862bb
    
  • レスポンス
    HTTP/1.1 200 OK
    X-Account-Object-Count: 2
    X-Account-Bytes-Used: 715653825
    X-Account-Container-Count: 4
    Content-Length: 154
    Content-Type: application/json; charset=utf8
    Date: Thu, 07 Jul 2011 02:35:56 GMT
    
    [{"name":"bin","count":1,"bytes":8897},{"name":"doc","count":0,"bytes":0},{"name":"image","count":1,"bytes":715644928},{"name":"src","count":0,"bytes":0}]
    

"format=xml" を指定した場合は、"format=json" 指定時と同等の情報を xml 形式で取得できます。

  • GET リクエスト
    GET /v1/AUTH_orion-cabinet?format=xml HTTP/1.1
    User-Agent: curl/7.21.0 (x86_64-pc-linux-gnu) libcurl/7.21.0 OpenSSL/0.9.8o zlib/1.2.3.4 libidn/1.18
    Host: objstore.example.jp
    Accept: */*
    X-Auth-Token: AUTH_tkcbd0b108401245a3acf1b550aa4862bb
    
  • レスポンス
    HTTP/1.1 200 OK
    X-Account-Object-Count: 2
    X-Account-Bytes-Used: 715653825
    X-Account-Container-Count: 4
    Content-Length: 409
    Content-Type: application/xml; charset=utf8
    Date: Thu, 07 Jul 2011 02:36:00 GMT
    
    <?xml version="1.0" encoding="UTF-8"?>
    <account name="AUTH_b90c1a33-33ea-48a1-8a30-fc91efa21e25">
    <container><name>bin</name><count>>1</count><bytes>8897</bytes></container>
    <container><name>doc</name><count>0</count><bytes>0</bytes></container>
    <container><name>image</name><count>1</count><bytes>715644928</bytes></container>
    <container><name>src</name><count>0</count><bytes>0</bytes></container>
    </account>
    

ページトップ

1-2. アカウントメタデータの設定

アカウントに対して POST リクエストを送信することにより、メタデータを登録することが可能です。
リクエストヘッダに、"X-Account-Meta-" から始まる名前の拡張ヘッダを付けることで、任意のメタデータをアカウントに与えることができます。このメタデータは、Swift の動作に影響しませんので、ユーザが自由に利用することができます。

【リクエスト】

【レスポンス】

【メタデータの削除】

リクエストヘッダに、"X-Remove-Account-Meta-" から始まる名前の拡張ヘッダを付けることで、任意のメタデータをアカウントから削除することができます。
拡張ヘッダ "X-Remove-Account-Meta-" には適当な値を指定しましょう。これは、値が空の拡張ヘッダを指定することができないためであり、値は無視されます (v1.4.8 Essex リリース以降で利用可能)。

【実行例】

アカウントに、メタデータを設定してみましょう。アカウントに、ヘッダ「X-Account-Meta-Team: fusion」を設定した POST リクエストを送ります。
設定したメタデータは GET または HEAD リクエストで読み出すことができます (第4章 1. アカウントサービス 1-3. アカウントメタデータの取得を参照)。

  • POST リクエスト
    POST /v1/AUTH_orion-cabinet HTTP/1.1
    User-Agent: curl/7.21.0 (x86_64-pc-linux-gnu) libcurl/7.21.0 OpenSSL/0.9.8o zlib/1.2.3.4 libidn/1.18
    Host: objstore.example.jp
    Accept: */*
    X-Auth-Token: AUTH_tkcbd0b108401245a3acf1b550aa4862bb
    X-Account-Meta-Team: fusion
    
  • レスポンス
    HTTP/1.1 204 No Content
    Content-Length: 0
    Content-Type: text/html; charset=UTF-8
    Date: Mon, 25 Jul 2011 00:32:16 GMT
    

次に、アカウントからメタデータを削除してみましょう。アカウントに、ヘッダ「X-Remove-Account-Meta-Team: x」を設定した POST リクエストを送ります。

  • POSTリクエスト
    POST /v1/AUTH_orion-cabinet HTTP/1.1
    User-Agent: curl/7.21.0 (x86_64-pc-linux-gnu) libcurl/7.21.0 OpenSSL/0.9.8o zlib/1.2.3.4 libidn/1.18
    Host: objstore.example.jp
    Accept: */*
    X-Auth-Token: AUTH_tkcbd0b108401245a3acf1b550aa4862bb
    X-Remove-Account-Meta-Team: x
    
  • レスポンス
    HTTP/1.1 204 No Content
    Content-Length: 0
    Content-Type: text/html; charset=UTF-8
    Date: Mon, 26 Nov 2012 10:23:47 GMT
    

ページトップ

1-3. アカウントメタデータの取得

アカウントが持つコンテナの数とオブジェクトの総数、オブジェクトサイズの合計を返します。また、ユーザが POST リクエストで設定したメタデータも読み出すことができ、これらの情報はレスポンスのヘッダで返されます。

【リクエスト】

【レスポンス】

【実行例】

アカウント (ストレージ URL) に対して HEAD を発行すると、そのレスポンスでコンテナ数が 4 つ (X-Account-Container-Count: 4)、オブジェクト数が 219 個 (X-Account-Object-Count: 219)、オブジェクトサイズの合計が 718041135 バイト (X-Account-Bytes-Used: 718041135) であることが分かりました。
アカウントへの POST リクエストで設定したメタデータ (X-Account-Meta-Team: fusion) も読み出すことができています。

  • HEAD リクエスト
    HEAD /v1/AUTH_orion-cabinet HTTP/1.1
    User-Agent: curl/7.21.0 (x86_64-pc-linux-gnu) libcurl/7.21.0 OpenSSL/0.9.8o zlib/1.2.3.4 libidn/1.18
    Host: objstore.example.jp
    Accept: */*
    X-Auth-Token: AUTH_tkcbd0b108401245a3acf1b550aa4862bb
    
  • レスポンス
    HTTP/1.1 204 No Content
    X-Account-Object-Count: 219
    X-Account-Meta-Team: fusion
    X-Account-Bytes-Used: 718041135
    X-Account-Container-Count: 4
    Content-Length: 0
    Date: Mon, 25 Jul 2011 00:32:52 GMT
    
ページトップ