技術情報

技術情報

OpenStack: Swift 【API 編】

2013年5月27日

技術文書トップへ

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

2. コンテナサービス

2-1. オブジェクト一覧の取得

指定されたコンテナ内のオブジェクト一覧を取得します。パラメータ指定がなかった場合、コンテナ内のオブジェクト名を最大 10,000 個返します。パラメータを指定することで、オブジェクト一覧の取得条件を変更することが可能です。

【リクエスト】

【レスポンス】

【オブジェクト一覧の出力フォーマット】

  • format 省略時
    オブジェクト名
    オブジェクト名
        :
    オブジェクト名
    
  • format=json
    [{"name":"オブジェクト名",
      "hash":"ハッシュ値",
      "bytes":オブジェクトサイズ,
      "content_type":"メディアタイプ",
      "last_modified":"最終更新時刻"},
      {...}, ...
    ]
    
  • format=xml
    <?xml version="1.0" encoding="UTF-8"?>
    <container name="コンテナ名">
        <object>
            <name>オブジェクト名/name>
            <hash>ハッシュ値</hash>
            <bytes>オブジェクトサイズ</bytes>
            <content_type>メディアタイプ</content_type>
            <last_modified>最終更新時刻</last_modified>
        </object>
    :
    </container>
    
  • marker、limit の使い方
    GET リクエスト時に、marker パラメータと limit パラメータを組み合わせて利用することで、オブジェクト一覧取得処理を複数回に分割して実行することができます。これは、非常に多くのオブジェクトが存在する環境で役に立ちます。
    アカウントに対するコンテナ一覧と同様に、コンテナに対するオブジェクト一覧取得処理も、1 回のリクエストで取得できるオブジェクト名は最大 10,000 個です。1 回の GET でコンテナ名を取得しきれなかった場合には、続けて marker パラメータを指定した GET リクエストを送信する必要があります。marker パラメータに前回受信したレスポンスの最後のオブジェクト名を指定することで、その続きからオブジェクト名を取得することができます。

【実施例】

コンテナ src に対する GET リクエストによるオブジェクト一覧取得を、パラメータ marker、limit を使って制御します。一度に取得するオブジェクト数を 5 と指定して、GET を発行します。レスポンスでは、オブジェクト名が 5 つ取得できます。

  • GET リクエスト
    GET /v1/AUTH_orion-cabinet/src?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_tk734c83ab579a4f938a1b82e5841d8d22
    
  • レスポンス
    HTTP/1.1 200 OK
    X-Container-Object-Count: 217
    X-Container-Bytes-Used: 2387310
    Content-Length: 47
    Content-Type: text/plain; charset=utf8
    Date: Wed, 13 Jul 2011 08:27:12 GMT
    
    .functests
    .probetests
    .unittests
    AUTHORS
    ChangeLog
    

続けて、ChangeLog に続くオブジェクト名を 5 つ取得します。marker に "ChangeLog" を指定することにより、辞書的に "ChangeLog" より後に出現する名前をもつオブジェクトのみが取得対象となります。

  • GET リクエスト
    GET/v1/AUTH_orion-cabinet/src?limit=5&marker=ChangeLog 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_tk734c83ab579a4f938a1b82e5841d8d22
    
  • レスポンス
    HTTP/1.1 200 OK
    X-Container-Object-Count: 217
    X-Container-Bytes-Used: 2387310
    Content-Length: 35
    Content-Type: text/plain; charset=utf8
    Date: Wed, 13 Jul 2011 08:27:23 GMT
    
    LICENSE
    MANIFEST.in
    PKG-INFO
    README
    bin
    

続けて、同様に "bin" 以降のオブジェクト名を 5 つ取得します。

  • GET リクエスト
    GET /v1/AUTH_orion-cabinet/src?limit=5&marker=bin 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_tk734c83ab579a4f938a1b82e5841d8d22
    
  • レスポンス
    HTTP/1.1 200 OK
    X-Container-Object-Count: 217
    X-Container-Bytes-Used: 2387310
    Content-Length: 37
    Content-Type: text/plain; charset=utf8
    Date: Wed, 13 Jul 2011 08:27:28 GMT
    
    doc
    etc
    setup.cfg
    setup.py
    swift.egg-info
    

続けて、同様に "swift.egg-info" 以降のオブジェクト名を 5 つ取得します。実際に取得できたのは、オブジェクト名を 2 つのみでした。これは、これ以上、取得必要なオブジェクトはないことを意味しています。

  • GET リクエスト
    GET /v1/AUTH_orion-cabinet/src?limit=5&marker=swift.egg-info 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_tk734c83ab579a4f938a1b82e5841d8d22
    
  • レスポンス
    HTTP/1.1 200 OK
    X-Container-Object-Count: 217
    X-Container-Bytes-Used: 2387310
    Content-Length: 9
    Content-Type: text/plain; charset=utf8
    Date: Wed, 13 Jul 2011 08:27:36 GMT
    
    swift
    test
    

一番最後のオブジェクト名 "test" を marker に指定した場合の動きを確認しておきます。レスポンスとして、正常終了 (204 No Content) が戻ってきます。これは、これ以上取得が必要なオブジェクトがないことを意味しています。

  • GET リクエスト
    GET /v1/AUTH_orion-cabinet/src?limit=5&marker=test 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_tk734c83ab579a4f938a1b82e5841d8d22
    
  • レスポンス
    HTTP/1.1 204 No Content
    X-Container-Object-Count: 217
    X-Container-Bytes-Used: 2387310
    Content-Length: 0
    Date: Wed, 13 Jul 2011 08:27:43 GMT
    

【擬似ディレクトリ】

Swift にはコンテナ以外にディレクトリに相当するものはありませんが、Amazon S3 と同様に擬似的なディレクトリ表現を用いることができます。
Swift には、擬似ディレクトリを表現する方法が 2 種類あります。

  1. ディレクトリマーカーオブジェクトを使う
    ディレクトリ名を示す特別なオブジェクトを作成することでディレクトリを表現します。オブジェクト一覧を取得する際には、path パラメータを使用します。なお、パスの区切り文字はスラッシュ ('/') であり、変更することはできません。

  2. パラメータ prefix と delimiter を使う
    パスの区切り文字として扱う文字をオブジェクト名に埋め込み、区切り文字より前をディレクトリ名として扱います。オブジェクト一覧を取得する際には、prefix パラメータと delimiter パラメータを使用します。

    それぞれの方法について、実行例を用いて説明します。前提として、コンテナ src に、以下のオブジェクトが保存されているものとします。
  • swift-1.3.0/ChangeLog
  • swift-1.3.0/LICENSE
  • swift-1.3.0/README
  • swift-1.3.0/swift/container/__init__.py
  • swift-1.3.0/swift/container/auditor.py
  • swift-1.3.0/swift/container/replicator.py
  • swift-1.3.0/swift/container/server.py
  • swift-1.3.0/swift/container/updater.py
  • swift-1.3.0/swift/obj/__init__.py
  • swift-1.3.0/swift/obj/auditor.py
  • swift-1.3.0/swift/obj/replicator.py
  • swift-1.3.0/swift/obj/server.py
  • swift-1.3.0/swift/obj/updater.py

【実施例:ディレクトリマーカーオブジェクトを使う】

ディレクトリパスを表現するオブジェクトを作成します。Content-Length に 0 (または 1) バイト、Content-Type に "application/directory" を指定します。このオブジェクトは、ディレクトリマーカーオブジェクトと呼ばれています。
今回の例では、次の 4 つをディレクトリマーカーオブジェクトとして作成する必要があります。

  • swift-1.3.0/
  • swift-1.3.0/swift/
  • swift-1.3.0/swift/container/
  • swift-1.3.0/swift/obj/

ディレクトリマーカーとして動作するオブジェクト "swift-1.3.0/" を作成します。コンテナ "src" 配下のオブジェクト "swift-1.3.0/" を指定して、PUT リクエストを送ります。ディレクトリマーカー属性を表す「Content-Length: 0」と「Content-Type: application/directory」の設定を忘れずに行いましょう。

  • PUT リクエスト
    PUT /v1/AUTH_orion-cabinet/src/swift-1.3.0/ 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_tk734c83ab579a4f938a1b82e5841d8d22
    Content-Length: 0
    Content-Type: application/directory
    
  • レスポンス
    HTTP/1.1 201 Created
    Content-Length: 118
    Content-Type: text/html; charset=UTF-8
    Etag: d41d8cd98f00b204e9800998ecf8427e
    Last-Modified: Wed, 13 Jul 2011 06:26:43 GMT
    Date: Wed, 13 Jul 2011 06:26:43 GMT
     
    <html>
     <head>
      <title>201 Created</title>
     </head>
     <body>
      <h1>201 Created</h1>
      <br /><br />
    
     </body>
    </html>
    

オブジェクト一覧を取得するとき、path パラメータに擬似ディレクトリ名を指定します。これにより、擬似ディレクトリ内のオブジェクト一覧を取得することができます。
まず、擬似ディレクトリ "swift-1.3.0" 直下のオブジェクト一覧を取得し、GET リクエスト発行時、path パラメータに "swift-1.3.0" を指定します。

  • GET リクエスト
    GET /v1/AUTH_orion-cabinet/src?path=swift-1.3.0 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_tk734c83ab579a4f938a1b82e5841d8d22
    
  • レスポンス
        (略)
    swift-1.3.0/ChangeLog
    swift-1.3.0/LICENSE
    swift-1.3.0/README
    swift-1.3.0/swift/
    

続けて、擬似ディレクトリ "swift-1.3.0/swift" 下のオブジェクト一覧を取得します。GET リクエスト時、path パラメータに "swift-1.3.0/swift" を指定します。

  • GET リクエスト
    GET /v1/AUTH_orion-cabinet/src?path=swift-1.3.0/swift 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_tk734c83ab579a4f938a1b82e5841d8d22
    
  • レスポンス
        (略)
    swift-1.3.0/swift/container/
    swift-1.3.0/swift/obj/
    

同様に、擬似ディレクトリ "swift-1.3.0/swift/obj" 下のオブジェクト一覧を取得します。

  • GET リクエスト
    GET /v1/AUTH_orion-cabinet/src?path=swift-1.3.0/swift/obj 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_tk734c83ab579a4f938a1b82e5841d8d22
    
  • レスポンス
        (略)
    swift-1.3.0/swift/obj/__init__.py
    swift-1.3.0/swift/obj/auditor.py
    swift-1.3.0/swift/obj/replicator.py
    swift-1.3.0/swift/obj/server.py
    swift-1.3.0/swift/obj/updater.py
    

実施例:パラメータ prefix と delimiter を使う

この方法では特に事前準備は必要ありません。
prefix パラメータにディレクトリ相当のパス、delimiter パラメータにスラッシュ ('/') を指定してオブジェクト一覧を取得します。prefix は、末尾にスラッシュを付けないと期待した結果が得られないため注意が必要です。

  • GET リクエスト
    GET /v1/AUTH_orion-cabinet/src?prefix=swift-1.3.0/&delimiter=/ 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_tk734c83ab579a4f938a1b82e5841d8d22
    
  • レスポンス
         (略)
    swift-1.3.0/ChangeLog
    swift-1.3.0/LICENSE
    swift-1.3.0/README
    swift-1.3.0/swift/
    

次に、擬似ディレクトリ swift-1.3.0/swift/ 以下のオブジェクトを一覧を取得します。

  • GET リクエスト
    GET /v1/AUTH_orion-cabinet/src?prefix=swift-1.3.0/swift/&delimiter=/ 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_tk734c83ab579a4f938a1b82e5841d8d22
    
  • レスポンス
         (略)
    swift-1.3.0/swift/container/
    swift-1.3.0/swift/obj/
    

次に、擬似ディレクトリ swift-1.3.0/swift/obj/ 以下のオブジェクトを一覧を取得します。

  • GET リクエスト
    GET /v1/AUTH_orion-cabinet/src?prefix=swift-1.3.0/swift/obj/&delimiter=/ 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_tk734c83ab579a4f938a1b82e5841d8d22
    
  • レスポンス
         (略)
    swift-1.3.0/swift/obj/__init__.py
    swift-1.3.0/swift/obj/auditor.py
    swift-1.3.0/swift/obj/replicator.py
    swift-1.3.0/swift/obj/server.py
    swift-1.3.0/swift/obj/updater.py
    
ページトップ