技術情報

技術情報

OpenStack: Swift 【API 編】

2013年7月19日

技術文書トップへ

第 5 章 マルチパートオブジェクト

オブジェクトは 1 つあたりのサイズに 5GB までという制限があり、5GB を超える場合は複数のオブジェクトに分割して保存する必要があります。Swift は、このように複数に分割して保存されたオブジェクト群を、あたかも一つのオブジェクトであるように扱うための機能を備えています。
この機能を利用するための手順と条件は以下の通りです。

  1. これら分割後のオブジェクトは、共通プレフィクスから始まる名前を持っていなければならない。
  2. 分割後のオブジェクト群を、オブジェクト名で辞書順に並べたものが、分割順序に一致しなければならない。
  3. 分割後のオブジェクト群を代表するメタオブジェクトを作成する。このオブジェクトは、マニフェストファイルと呼ばれる。

マニフェストファイルは、通常のオブジェクトと同じく、マニフェストファイルとなるオブジェクトを指定して、PUT リクエストを送ることにより作成します。通常のオブジェクト作成時の PUT リクエストと異なるのは、次の拡張ヘッダを指定するという点です。

X-Object-Manifest: コンテナ名/プレフィクス

"コンテナ名" は分割後のオブジェクト群が置かれているコンテナの名前であり、"プレフィクス" は、その分割後のオブジェクトに付けられた名前の共通部分です。また、マニフェストファイルは空のオブジェクトで構いません。分割後のオブジェクト群が置かれているコンテナとは別のコンテナに、マニフェストファイルを置いても問題ありません。

このマニフェストファイルを指定してGETリクエストを送ると、分割後のオブジェクト群を結合した、ひとつの大きなオブジェクトとして取得できます。
この機能は、オブジェクトを分割し、それぞれを同時にアップロードすることで、オブジェクトのアップロード時間を短縮する目的でも利用することができます。

【実行例】

コンテナshelfの下に、毎日のシステム運用ログをオブジェクトとしてアップロードしているものと仮定します。
コンテナshelfの下に、syslog-0728, syslog-0729, syslog-0730, syslog-0731, syslog-0801, syslog-0802 が置かれていた場合、この中から 7 月分のログだけを集めたオブジェクトを定義します。

7 月の運用ログのオブジェクトの名前は、全て同じプレフィクス "syslog-07" を持っているため、それらを辞書順に並べると結合したい日付順になります。
コンテナ shelf に GET リクエスト (format 指定あり) を送り、shelf 配下にあるオブジェクトとそれぞれのオブジェクトサイズを確認します。

  • GETリクエスト
    GET /v1/AUTH_orion-cabinet/shelf?format=json 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_tk55dbfd33f2d44ccb9f254555f0975142
    
  • レスポンス
    HTTP/1.1 200 OK
    X-Container-Object-Count: 4
    X-Container-Bytes-Used: 362904
    Content-Length: 1066
    Content-Type: application/json; charset=utf8
    Date: Mon, 03 Aug 2011 01:57:57 GMT
    
    [{"name":"syslog-0728","hash":"fc7510d59dc06ba4da9f6d72e467b88d","bytes":7347,
      "content_type":"application/x-www-form-urlencoded",
      "last_modified":"2011-07-29T01:38:24.155270"},
    {"name":"syslog-0729","hash":"f49162bc09df5a6db81bf9cf7c105c8f","bytes":919,
      "content_type":"application/x-www-form-urlencoded",
      "last_modified":"2011-07-30T01:38:34.630770"},
    {"name":"syslog-0730","hash":"c7e330322b421b480ba79fcab4ef0111","bytes":24024,
      "content_type":"application/x-www-form-urlencoded",
      "last_modified":"2011-07-31T01:56:42.285210"},
    {"name":"syslog-0731","hash":"992606b8f66af9012b750e76067972ff","bytes":292292,
      "content_type":"application/x-www-form-urlencoded",
      "last_modified":"2011-08-01T01:57:10.127310"},
    {"name":"syslog-0801","hash":"fa56c06de7135cdde8d4f701df73aefa","bytes":1028,
      "content_type":"application/x-www-form-urlencoded",
      "last_modified":"2011-08-02T01:57:16.137920"},
    {"name":"syslog-0802","hash":"4808deba36e11d131efa810a2ae9b1ce","bytes":37294,
      "content_type":"application/x-www-form-urlencoded",
      "last_modified":"2011-08-03T01:57:37.227280"}]
    

7 月の運用ログのオブジェクト群をまとめるマニフェストファイルを作成します。

  • これから作成するマニフェストファイル "systemlog-July" を指定して、PUT リクエストを送ります。
  • 拡張ヘッダとして "X-Object-Manifest: shelf/syslog-07"を設定します。
  • 7 月の運用ログのオブジェクトの共通プレフィクス "syslog-07" を指定します。

上記の例では、システムログのオブジェクトが置かれたコンテナ shelf とは別のコンテナ record の下に、マニフェストファイル systemlog-July を作成します。

  • PUTリクエスト
    PUT /v1/AUTH_orion-cabinet/record/systemlog-July 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_tk55dbfd33f2d44ccb9f254555f0975142
    X-Object-Manifest: shelf/syslog-07
    Content-Length: 0
    Content-Type: application/x-www-form-urlencoded
    
  • レスポンス
    HTTP/1.1 201 Created
    Content-Length: 118
    Content-Type: text/html; charset=UTF-8
    Etag: d41d8cd98f00b204e9800998ecf8427e
    Last-Modified: Mon, 25 Jul 2011 04:02:28 GMT
    Date: Mon, 03 Aug 2011 04:02:28 GMT
    
    <html>
     <head>
      <title>201 Created</title>
     </head>
     <body>
      <h1>201 Created</h1>
      <br /><br />
    
     </body>
    </html>
    

作成したマニュフェストファイルを指定して GET リクエストを送ると、7 月の運用ログを納めたオブジェクトが結合されたものを読み出すことができます。
読み出せたデータの大きさ 324582 バイト (Content-Length: 324582) が、syslog-0728 (7347バイト), syslog-0729 (919バイト), syslog-0730 (24024バイト), syslog-0731 (292292バイト) の合計に一致することも確認できます。

  • GETリクエスト
    GET /v1/AUTH_orion-cabinet/record/systemlog-July 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_tk55dbfd33f2d44ccb9f254555f0975142
    
  • レスポンス
    HTTP/1.1 200 OK
    X-Object-Manifest: shelf/syslog-07
    Content-Type: application/x-www-form-urlencoded
    Etag: 320366cada15207c5b977966ad30f2dc
    Content-Length: 324582
    Last-Modified: Mon, 25 Jul 2011 01:57:10 GMT
    Date: Aug, 03 Jul 2011 04:49:07 GMT
      (以下実際のデータ)
          :
          :
    

ページトップ

第 6 章 アクセス制御

1. デフォルトのアクセス権限

明示的なアクセス権限の設定を行っていない場合、あるアカウント配下のコンテナおよびオブジェクトへのアクセスは、admin 権限を持ったユーザのみに許されます。

2. コンテナのACL設定

Swift では、コンテナ単位でアクセス制御を行うことが可能です。各コンテナは ACL (アクセスコントロールリスト) を持っており、コンテナ配下のオブジェクトの読み出し権限と、オブジェクトへの書き込み権限を各々設定できます。ACL には、Swift のユーザに基づく指定と、referer ヘッダによる指定方法があり、それぞれ複数の設定を登録することができます。

コンテナへの ACL 設定は、コンテナに対する PUT リクエスト、または POST リクエストにて行います。X-Container-Read ヘッダには読み出しアクセス用の ACL 情報を載せ、X-Container-Write ヘッダには書き込みアクセスに関する ACL 情報を載せます。コンテナの新規作成時に ACL を設定することも、コンテナ作成後に後から ACL を設定変更することも可能です。
コンテナの ACL 設定は、コンテナに対する HEAD または GET にて読み出すことができます。

3. ユーザベースのアクセス制御

ACL として、コンテナへのアクセスを許可するアカウントの名前、もしくはユーザの名前をカンマ "," を挟んで列挙します。ユーザは「アカウント名:ユーザ名」の書式で指定します。「アカウント名」のみを指定した場合、そのアカウント配下の全てのユーザにアクセス権が与えられます。

アカウント orion が持つコンテナ foo に、ACL を設定する例を紹介します。この例では、「アカウント orion 配下の全てのユーザ」および「アカウント pleiades 内のユーザ beth と joe 」に対して、オブジェクトを読み出す権限が与えられます。
書き込み権限は、「アカウント orion 配下のユーザ mary と cris」に与えています。アカウント orion に属するユーザでも、ユーザ bob と tony はコンテナ foo 配下にオブジェクトを書き込むことができません。

アカウントの admin 権限を持っているユーザは、コンテナの ACL 設定の状態に関わらず、常にコンテナ配下のオブジェクトの読み書き、およびコンテナの設定変更が可能です。この例の場合、アカウント orion のユーザ joe はコンテナ foo の ACL に登録されていませんが、admin 権限を持っているためコンテナ foo 配下のオブジェクトに書き込むことができます。

  • POSTリクエスト
    POST /v1/AUTH_orion-cabinet/foo 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_tk4967d312608749e39c49956dd889589d
    X-Container-Read: orion,pleiades:beth,pleiades:joe
    X-Container-Write: orion:mary,orion:cris
    
  • レスポンス
    HTTP/1.1 204 No Content
    Content-Length: 0
    Content-Type: text/html; charset=UTF-8
    Date: Fri, 22 Jul 2011 12:56:52 GMT
    

コンテナ foo に対して HEAD リクエストを送信することにより、指定した ACL が期待とおりに登録されていることを確認できます。

  • HEADリクエスト
    HEAD /v1/AUTH_orion-cabinet/foo HTTP/1.1
    User-Agent: curl/7.19.7 (i486-pc-linux-gnu) libcurl/7.19.7 OpenSSL/0.9.8k zlib/.2.3.3 libidn/1.15
    Host: objstore.example.jp
    Accept: */*
    X-Auth-Token: AUTH_tk4967d312608749e39c49956dd889589d
    
  • レスポンス
    HTTP/1.1 204 No Content
    X-Container-Object-Count: 1
    X-Container-Write: orion:joe,orion:cris
    X-Container-Read: orion,pleiades:beth,pleiades:joe
    X-Container-Bytes-Used: 4
    Content-Length: 0
    Date: Fri, 22 Jul 2011 12:56:52 GMT
    

4. リファラに基づくアクセス制御

リファラ (HTTP referer) ヘッダを利用し、アクセス元ごとに読み出しアクセスの許可・禁止を設定できます。ただし、書き込みアクセスを許可することはできません。
読み出しアクセス用の ACL に、以下の形式でアクセスを許可するホストとドメインをカンマ","を挟んで複数列挙します。

  • ホストは、".r:ホスト名 (FQDN表記)" と指定する。
  • ドメインは、".r:.ドメイン名" もしくは ".r:*.ドメイン名" という表記で指定する。
  • ".r:*" という指定を行った場合は、すべてのアクセスの許可を意味する。
  • ".r:-ホスト名(FQDN表記)"、".r:-.ドメイン名"、".r:-*.ドメイン名" という表記は、その指定されたホストやドメインからのアクセスを禁止することを意味する。

この例では、アカウント orion のコンテナ baz 配下のオブジェクトを、サイト example.com と valinux.co.jp に対して公開するように設定しています。この時、アカウント orion 内の全ユーザもコンテナ配下のオブジェクトを参照できるよう、アカウント名 orion を ACL の設定に加えることにします。

  • POSTリクエスト
    POST /v1/AUTH_orion-cabinet/baz 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_tk52b871ea91cc4fe9a78c130029545bcd
    X-Container-Read: .r:.example.com,r:.valinux.co.jp,orion
    

このリファラによる ACL 設定により、上記 2 つのサイト (example.com、valinux.co.jp) から、baz コンテナ配下のオブジェクトを参照できるようになります。しかし、この設定だけでは baz コンテナ配下のオブジェクトの一覧取得 (コンテナ baz に対する GET リクエスト)はエラー (401 Unauthorized)になります。オブジェクトの一覧取得を許可しても良いときは、読み出しアクセス用の ACL にさらにキーワード ".rlistings" を加える必要があります。

example.com サイトのうち、spam.example.com からのアクセスだけは禁止したいこともあるでしょう。
その場合、これらを反映したACLの設定は次のようになります。

X-Container-Read: .r:.example.com,r:.-spam.example.com,.r:.valinux.co.jp,orion,.rlistings

5. 特権ユーザとアクセス制御

特権を与えられたユーザは、ここで説明してきた ACL 設定の影響は受けません。admin 権限を与えられたユーザは、ユーザが属するアカウント内の全てのコンテナやオブジェクトに対して、あらゆるアクセスが許されます。 reseller 権限を与えられたユーザも ACL 設定の影響を受けません。reseller 権限はサービス提供事業者用の権限であり、ACL 設定に関わらず全てのアカウントのあらゆるコンテナとオブジェクトのアクセスを許されます。

ページトップ

第 7 章 メタデータ

Swiftでは、アカウント・コンテナ・オブジェクトに対してユーザが自由にメタデータを登録することができる。これらメタデータは、Swiftの動作に影響を与えない。 メタデータは「鍵と値の組」で複数登録可能であるが、いくつかの制限がある。

1. オブジェクトのメタデータ

オブジェクトに対する PUT リクエスト、POST リクエストで設定することが可能です。PUT リクエストによるオブジェクトの作成時に、拡張ヘッダでメタデータを設定することができ、また、既存のオブジェクトに対する POST リクエストによりメタデータのみの設定を行うこともできます。PUT リクエスト・POST リクエスト時、"X-Object-Meta-" から始まる名前の拡張ヘッダ (鍵) に対して、値を設定します。

オブジェクトへのメタデータ登録は、オブジェクトへの書き込み許可があるユーザであれば、誰でも実行可能です。
また、オブジェクトに対し GET リクエスト・HEAD リクエストを送ると、そのレスポンスのヘッダにてメタデータを取り出せます。

2. コンテナのメタデータ

コンテナに対する PUT リクエスト、POST リクエストで設定することが可能です。PUT リクエストによるコンテナの作成時に、拡張ヘッダでメタデータを設定することができ、また、既存のコンテナに対するPUT リクエスト・POST リクエストによりメタデータのみの設定を行うこともできます。PUT リクエスト・POST リクエスト時、"X-Container-Meta-" から始まる名前の拡張ヘッダ (鍵) に対して、値を設定します。

コンテナへのメタデータ登録は、admin 権限を持つユーザのみが実行することができます。
また、コンテナに対し GET リクエスト・HEAD リクエストを送ると、そのレスポンスのヘッダにてメタデータを取り出せます。

3. アカウントのメタデータ

アカウントに対する POST リクエストで設定することが可能です。POST リクエスト時、"X-Account-Meta-" から始まる名前の拡張ヘッダ (鍵) に対して、値を設定します。
アカウントへのメタデータ登録は、admin 権限を持つユーザのみが実行することができます。
また、アカウントに対し GET リクエスト・HEAD リクエストを送ると、そのレスポンスのヘッダにてメタデータを取り出せます。

4. 注意点

アカウントとコンテナへのメタデータ登録時の動きと、オブジェクトへのメタデータの登録時の動きが異なるため、オブジェクトのメタデータを失わないように注意する必要があります。

アカウントとコンテナの場合、一部のメタデータだけの書き換えが可能です。

  • 登録しようとするメタデータのキーが存在しなかった場合、「キーと値」を対にして登録する。
  • 登録しようとするメタデータのキーが、既に登録されてい場合、値だけを更新する。

例として、コンテナ grub にメタデータ「X-Container-Meta-Fruit: apple」と「X-Container-Meta-Vegie: carrot」とが設定されている場合を見てみましょう。コンテナ grub に HEAD リクエストを送ることにより、設定されているメタデータを確認できます。

  • HEADリクエスト
    HEAD /v1/AUTH_orion-cabinet/grub 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_tk52b871ea91cc4fe9a78c130029545bcd
    
  • レスポンス
    HTTP/1.1 204 No Content
    X-Container-Object-Count: 1
    X-Container-Meta-Vegie: carrot
    X-Container-Bytes-Used: 4
    X-Container-Meta-Fruit: apple
    Content-Length: 0
    Date: Sun, 24 Jul 2011 03:38:11 GMT
    

ここで、コンテナ grub のメタデータとして、「X-Container-Meta-Vegie: cabbage」と「X-Container-Meta-Grain: wheat」 を設定してみましょう。

  • POST リクエスト (メタデータ変更)
    POST /v1/AUTH_orion-cabinet/grub 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_tk52b871ea91cc4fe9a78c130029545bcd
    X-Container-Meta-Vegie: cabbage
    X-Container-Meta-Grain: wheat
    
  • レスポンス
    HTTP/1.1 204 No Content
    Content-Length: 0
    Content-Type: text/html; charset=UTF-8
    Date: Sun, 24 Jul 2011 05:10:42 GMT
    

コンテナ grub のメタデータがどのように変更されたか、HEAD リクエストを用いて確認します。「X-Container-Meta-Fruit:」の設定は保存され、「X-Container-Meta-Vegie:」の値は carrot から cabbage に書き換えられ、「X-Container-Meta-Grain: wheat」が新規に追加されていることが分かります。

  • HEAD リクエスト (メタデータ変更後)
    HEAD /v1/AUTH_orion-cabinet/grub 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_tk52b871ea91cc4fe9a78c130029545bcd
    
  • レスポンス
    HTTP/1.1 204 No Content
    X-Container-Object-Count: 1
    X-Container-Meta-Vegie: cabbage
    X-Container-Meta-Grain: wheat
    X-Container-Bytes-Used: 4
    X-Container-Meta-Fruit: apple
    Content-Length: 0
    Date: Sun, 24 Jul 2011 05:12:28 GMT
    

5. オブジェクトの場合

登録されているメタデータを全て削除したうえで、新しいメタデータが登録されます。必要があれば、まず HEAD リクエストで現在登録されているメタデータを取り出し、これから登録しようとしているメタデータとマージした上で、POST リクエストでメタデータを登録する方がよいでしょう。 オブジェクト food にメタデータ「X-Object-Meta-Fruit: orange」と「X-Object-Meta-Vegie: celery」とが設定されている場合を例に挙げると、オブジェクト food に HEAD リクエストを送ることにより、設定されているメタデータを確認できます。

  • HEAD リクエスト
    HEAD /v1/AUTH_orion-cabinet/grub/food 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_tk52b871ea91cc4fe9a78c130029545bcd
    
  • レスポンス
    HTTP/1.1 200 OK
    Last-Modified: Sun, 24 Jul 2011 03:57:42 GMT
    Etag: 81dc9bdb52d04dc20036dbd8313ed055
    X-Object-Meta-Fruit: orange
    X-Object-Meta-Vegie: celery
    Content-Length: 4
    Content-Type: application/x-www-form-urlencoded
    Date: Sun, 24 Jul 2011 03:57:42 GMT
    

ここで、オブジェクト food のメタデータとして、「X-Object-Meta-Vegie: mushroom」と「X-Object-Meta-Grain: rice」を設定してみましょう。

  • POSTリクエスト(メタデータ変更)
    POST /v1/AUTH_orion-cabinet/grub/food 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_tk52b871ea91cc4fe9a78c130029545bcd
    X-Object-Meta-Vegie: mushroom
    X-Object-Meta-Grain: rice
    
  • レスポンス
    HTTP/1.1 202 Accepted
    Content-Length: 159
    Content-Type: text/html; charset=UTF-8
    Date: Sun, 24 Jul 2011 03:59:50 GMT
    
    <html>
     <head>
      <title>202 Accepted</title>
     </head>
     <body>
      <h1>202 Accepted</h1>
      The request is accepted for processing.<br /><br />
    
     </body>
    

オブジェクト food のメタデータがどのように変更されたか、HEAD リクエストを用いて確認します。
「X-Object-Meta-Vegie: mushroom」と「X-Object-Meta-Grain: rice」は設定されていますが、メタデータ「X-Object-Meta-Fruit:」の設定が破棄されていることが確認できます。

  • HEADリクエスト
    HEAD /v1/AUTH_orion-cabinet/grub/food 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_tk52b871ea91cc4fe9a78c130029545bcd
    
  • レスポンス
    HTTP/1.1 200 OK
    X-Object-Meta-Grain: rice
    Last-Modified: Sun, 24 Jul 2011 03:59:50 GMT
    Etag: 81dc9bdb52d04dc20036dbd8313ed055
    X-Object-Meta-Vegie: mushroom
    Content-Length: 4
    Content-Type: application/x-www-form-urlencoded
    Date: Sun, 24 Jul 2011 03:59:50 GMT
    

本記事でSwift【API 編】は最終回となります。

ページトップ