Basic Requests

大雑把な意訳、訳しにくい箇所は英文と一緒に転載します
http://docs.basho.com/riak/1.3.2/tutorials/querying/Basic-Operations/

Overview

Riak は key の value を格納するか検索します。このセクションでは、Riak HTTP API を使用する方法を述べますが、この概念は同じように Riak の Protocol Buffers Client API インタフェースにも同様です。

Riak は Erlang, Java, PHP, Python, Rub, C/C++ 向けのクライアントライブラリを提供します。さらに .NET, Node.js, Python (and Twisted), Griffon, Small Talk, Perl, Scala, Clojure 向けのクライアントライブラリがコミュニティによって提供されています。

Best Practices for HTTP

HTTP によって Riak にリクエストを送る場合は、これらのポイントを意識することが重要です。まず、存在している全ての Objects は X-Riak-Vclock ヘッダーを含んでいます。X-Riak-Vclock ヘッダーは、Object と共に Riak から取り出されます。次に、buckets, keys, link は、エスケープしていないスラッシュを含まないかもしれません。URL エスケープライブラリを使用するか、スラッシュを %2F に置き換えてください。

Read an Object

bucket から指定した key で value を検索するコマンドを下記に記載します。value が存在している場合は、レスポンスの body に Object の内容が含まれます。

GET /riak/bucket/key

Riak は多くの定義された HTTP ヘッダーを理解します。like Accept for content-type negotiation (relevant when dealing with siblings, see the sibling examples for the HTTP API, and If-None-Match/ETag and If-Modified-Since/Last-Modified for conditional requests.

Riak はいくつかのクエリーパラメータを受け入れます。クエリーパラメータの r は、GET リクエストに R-value を設定するために使われます。R-value は、存在する Object を検索する成功レスポンスを返すために必要とするレプリカ数です。R-value は Fast Track Tutorial の最後のセクションで詳細を説明しています。もしクエリーパラメータ r を省略した場合は、デフォルト値の 2 になります。

通常のレスポンスコード:

200 OK
300 Multiple Choices
304 Not Modified

典型的なエラーコード:

404 Not Found

Example Error Code

bucket "test" から key "doc2" の value を検索する GET コマンドを下記に記載します。key "doc2" の value が存在してなければ、404 Not Found を返します。

[on server01]$ http localhost:8098/riak/test/doc2
HTTP/1.1 404 Object Not Found
Content-Length: 10
Content-Type: text/plain
Date: Thu, 27 Jun 2013 07:30:10 GMT
Server: MochiWeb/1.1 WebMachine/1.9.2 (someone had painted it blue)

not found

Store an object with existing or user-defined key

アプリケーションがデータ用の key を生成する仕組みがあれば、データの格納は簡単です。基本的なリクエストを下記に記載します。

PUT /riak/bucket/key

bucket に key を追加すると、bucket は自動的に作成されます。明示的に bucket を作成する必要はありません。bucket に関しての詳細は後述します。

PUT は、いくつかのリクエストヘッダーが求められます。まず Object を格納するために Content-Type ヘッダーをセットしなければいけません。Content-Type ヘッダーは、格納した Object を検索するときに期待する値をセットします。つぎに、既に存在している Object を更新する時は X-Riak-Vclock が必要になる場合があります。新しい Object を格納する場合は、X-Riak-Vclock ヘッダーは省略されるかもしれません。

PUT は、オプションとして他のリクエストヘッダーがあります。任意の metadata ヘッダーを Object に追加するには X-Riak-Meta-YOUR_HEADER を利用できます。他のリソースにリンクを定義するために Link ヘッダーが利用できます。

GET リクエストのクエリーパタメータ r を対応しているのと同じように、PUT リクエストもこれらのクエリーパタメータに対応しています。Object を書き込む前に必要とするレプリカ数をクエリーパタメータ r (default:2) に指定できます。成功レスポンスを返す前に書き込むために必要とするレプリカ数をクエリーパタメータ w (default:2) に指定できます。成功レスポンスを返す前に永続的に書き込むために必要とするレプリカ数をクエリーパタメータ dw (default:2) に指定できます。格納されたオブジェクトの内容を返すかどうかをクエリーパタメータ returnbody (default:false)に指定できます。

通常のレスポンスコード:

200 OK
204 No Content
300 Multiple Choices

Example

If returnbody=true, any of the response headers expected from a GET request may be present. Like a GET request, 300 Multiple Choices may be returned if siblings existed or were created as part of the operation, and the response can be dealt with similarly.

[on server01]$ curl -v -X PUT -d '{"bar":"baz"}' -H "Content-Type: application/json" -H "X-Riak-Vclock: a85hYGBgzGDKBVIszMk55zKYEhnzWBlKIniO8mUBAA==" http://127.0.0.1:8098/riak/test/doc?returnbody=true
* About to connect() to 127.0.0.1 port 8098 (#0)
*   Trying 127.0.0.1... connected
* Connected to 127.0.0.1 (127.0.0.1) port 8098 (#0)
> PUT /riak/test/doc?returnbody=true HTTP/1.1
> User-Agent: curl/7.19.7 (x86_64-redhat-linux-gnu) libcurl/7.19.7 NSS/3.14.0.0 zlib/1.2.3 libidn/1.18 libssh2/1.4.2
> Host: 127.0.0.1:8098
> Accept: */*
> Content-Type: application/json
> X-Riak-Vclock: a85hYGBgzGDKBVIszMk55zKYEhnzWBlKIniO8mUBAA==
> Content-Length: 13
> 
< HTTP/1.1 200 OK
< X-Riak-Vclock: a85hYGBgymDKBVIcXvnPqwNPT16cwZTImMfKsKjE4TQfRIqFOTnnHFS4JILnKF8WAA==
< Vary: Accept-Encoding
< Server: MochiWeb/1.1 WebMachine/1.9.2 (someone had painted it blue)
< Link: </riak/test>; rel="up"
< Last-Modified: Thu, 27 Jun 2013 08:32:34 GMT
< ETag: "3eEEVirfkj28g8gQTZBt8k"
< Date: Thu, 27 Jun 2013 08:32:34 GMT
< Content-Type: application/json
< Content-Length: 13
< 
* Connection #0 to host 127.0.0.1 left intact
* Closing connection #0

Store a new object and assign random key

アプリケーションが key の生成を Riak に任せる場合は、bucket/key ペアへの PUT の代わりに bucket に対して POST リクエストを送信します。

POST /riak/bucket

bucket/key に PUT リクエストを送信するのと同じヘッダーを対応します。この場合は新しいデータの追加になるため、X-Riak-Vclock ヘッダーが使われることはありません。また、クエリーパタメータに関しても、bucket/key に PUT リクエストを送信するのと同じクエリーパタメータをサポートします。

通常のレスポンスコード:

201 Created

Example

bucket "test" に key を指定せずに Object を格納するリクエストを下記に記載します。

[on server01]$ curl -v -XPOST -d 'this is a test' -H "Content-Type: text/plain" http://127.0.0.1:8098/riak/test
* About to connect() to 127.0.0.1 port 8098 (#0)
*   Trying 127.0.0.1... connected
* Connected to 127.0.0.1 (127.0.0.1) port 8098 (#0)
> POST /riak/test HTTP/1.1
> User-Agent: curl/7.19.7 (x86_64-redhat-linux-gnu) libcurl/7.19.7 NSS/3.14.0.0 zlib/1.2.3 libidn/1.18 libssh2/1.4.2
> Host: 127.0.0.1:8098
> Accept: */*
> Content-Type: text/plain
> Content-Length: 14
> 
< HTTP/1.1 201 Created
< Vary: Accept-Encoding
< Server: MochiWeb/1.1 WebMachine/1.9.2 (someone had painted it blue)
< Location: /riak/test/HO313FBkJahapJduMtb68E3FiFl
< Date: Thu, 27 Jun 2013 08:46:39 GMT
< Content-Type: text/plain
< Content-Length: 0
< 
* Connection #0 to host 127.0.0.1 left intact
* Closing connection #0

格納した Object の key が、レスポンスの Location ヘッダーに記録されています。今回の場合は、下記のように新しく作成された Object を参照できます。

[on server01]$ http localhost:8098/riak/test/HO313FBkJahapJduMtb68E3FiFl
HTTP/1.1 200 OK
Content-Encoding: gzip
Content-Length: 32
Content-Type: text/plain
Date: Thu, 27 Jun 2013 08:50:44 GMT
ETag: "6iXtRc13WEzeHjRlhA2KUK"
Last-Modified: Thu, 27 Jun 2013 08:46:39 GMT
Link: </riak/test>; rel="up"
Server: MochiWeb/1.1 WebMachine/1.9.2 (someone had painted it blue)
Vary: Accept-Encoding
X-Riak-Vclock: a85hYGBgzGDKBVIcXvnPqwMPOMtmMCUy5rEyvC93OM2XBQA=

this is a test

Delete an object

bucket から指定した key の Object を削除するコマンドを下記に記載します。

DELETE /riak/bucket/key

通常のレスポンスコード:

204 No Content
404 Not Found

Example

bucket "test" から key "doc" の Object を削除するリクエストを下記に記載します。

[on server01]$  curl -v -X DELETE http http://127.0.0.1:8098/riak/test/doc
* getaddrinfo(3) failed for http:80
* Couldn't resolve host 'http'
* Closing connection #0
curl: (6) Couldn't resolve host 'http'
* About to connect() to 127.0.0.1 port 8098 (#0)
*   Trying 127.0.0.1... connected
* Connected to 127.0.0.1 (127.0.0.1) port 8098 (#0)
> DELETE /riak/test/doc HTTP/1.1
> User-Agent: curl/7.19.7 (x86_64-redhat-linux-gnu) libcurl/7.19.7 NSS/3.14.0.0 zlib/1.2.3 libidn/1.18 libssh2/1.4.2
> Host: 127.0.0.1:8098
> Accept: */*
> 
< HTTP/1.1 204 No Content
< Vary: Accept-Encoding
< Server: MochiWeb/1.1 WebMachine/1.9.2 (someone had painted it blue)
< Date: Thu, 27 Jun 2013 09:00:13 GMT
< Content-Type: application/json
< Content-Length: 0
< 
* Connection #0 to host 127.0.0.1 left intact
* Closing connection #0

End

一貫性レベル調整の r, pr やら w, dw, pr やらは実際に試しながら挙動見てみなきゃ、なんとも言えないな。別記事で試してみよう。