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

1. アカウントサービス

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

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

 

 

【リクエスト】

【レスポンス】

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

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

format 省略時
1
2
3
4
コンテナ名
コンテナ名
    :
コンテナ名
format=json
1
2
3
4
5
[{"name":"コンテナ名",
  "count":オブジェクト数,
  "bytes":オブジェクト総容量},
  {...}, ...
]
format=xml
1
2
3
4
5
6
7
8
9
<?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 リクエスト
1
2
3
4
5
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
レスポンス
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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 リクエスト
1
2
3
4
5
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
レスポンス
1
2
3
4
5
6
7
8
9
10
11
12
13
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 リクエスト
1
2
3
4
5
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
レスポンス
1
2
3
4
5
6
7
8
9
10
11
12
13
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 リクエスト
1
2
3
4
5
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
レスポンス
1
2
3
4
5
6
7
8
9
10
11
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リクエスト
1
2
3
4
5
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
レスポンス
1
2
3
4
5
6
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
1
2
3
4
5
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
レスポンス
1
2
3
4
5
6
7
8
9
10
11
12
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 リクエスト
1
2
3
4
5
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
レスポンス
1
2
3
4
5
6
7
8
9
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 リクエスト
1
2
3
4
5
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
レスポンス
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
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 リクエスト
1
2
3
4
5
6
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
レスポンス
1
2
3
4
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 リクエスト
1
2
3
4
5
6
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
レスポンス
1
2
3
4
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

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

 

POSTリクエスト
1
2
3
4
5
6
7
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
  
レスポンス
1
2
3
4
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 リクエスト
1
2
3
4
5
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
レスポンス
1
2
3
4
5
6
7
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