第12章 REST API
12.1. REST インターフェース
Red Hat JBoss Data Grid は REST インターフェースを提供し、クライアントとサーバー間の疎結合を可能にします。REST インターフェースの主な利点は既存の HTTP クライアントとの相互運用性や、php クライアントへの接続の提供です。さらに、特定のバージョンのクライアントライブラリーやバインディングが必要ありません。
REST API によってオーバーヘッドが発生します。REST コールの理解や作成に REST クライアントまたはカスタムコードが必要になります。パフォーマンスに懸念がある場合は Hot Rod クライアントの使用が推奨されます。
Red Hat JBoss Data Grid の REST API と対話するには、HTTP クライアントライブラリーのみが必要です。Java の場合は、Apache HTTP Commons Client や java.net API になります。
以下の例は、REST セキュリティーが REST コネクターで無効になっていることを前提としています。REST セキュリティーを削除するには、コネクターから authentication
および encryption
要素を削除します。
12.2. Ruby クライアントコード
以下のコードは ruby を使用して Red Hat JBoss Data Grid の REST API と対話する例です。提供されたコードは特別なライブラリーを必要とせず、標準的な net/HTTP ライブラリーを使用できます。
Ruby での REST API の使用
require 'net/http' http = Net::HTTP.new('localhost', 8080) #An example of how to create a new entry http.post('/rest/MyData/MyKey', 'DATA_HERE', {"Content-Type" => "text/plain"}) #An example of using a GET operation to retrieve the key puts http.get('/rest/MyData/MyKey').body #An Example of using a PUT operation to overwrite the key http.put('/rest/MyData/MyKey', 'MORE DATA', {"Content-Type" => "text/plain"}) #An example of Removing the remote copy of the key http.delete('/rest/MyData/MyKey') #An example of creating binary data http.put('/rest/MyImages/Image.png', File.read('/Users/michaelneale/logo.png'), {"Content-Type" => "image/png"})
12.3. Ruby の例で JSON を使用
前提条件
ruby で JavaScript Object Notation (JSON
) を使用して Red Hat JBoss Data Grid の REST インターフェースと対話するには、JSON Ruby ライブラリーをインストールし (プラットフォームのパッケージマネージャーまたは Ruby ドキュメンテーションを参照)、以下のコードを使用して要件を宣言します。
require 'json'
Ruby での JSON の使用
以下のコードは、Ruby で JavaScript Object Notation (JSON
) と PUT
関数を使用して特定のデータ (この場合は、個人の名前と年齢) を送信する例です。
data = {:name => "michael", :age => 42 } http.put('/rest/Users/data/0', data.to_json, {"Content-Type" => "application/json"})
12.4. Python クライアントコード
以下のコードは Python を使用して Red Hat JBoss Data Grid の REST API と対話する例です。提供されたコードは、標準的な HTTP ライブラリーのみを必要とします。
Python での REST API の使用
import httplib #How to insert data conn = httplib.HTTPConnection("localhost:8080") data = "SOME DATA HERE \!" #could be string, or a file... conn.request("POST", "/rest/default/0", data, {"Content-Type": "text/plain"}) response = conn.getresponse() print response.status #How to retrieve data import httplib conn = httplib.HTTPConnection("localhost:8080") conn.request("GET", "/rest/default/0") response = conn.getresponse() print response.status print response.read()
12.5. Java クライアントコード
以下のコードは Java を使用して Red Hat JBoss Data Grid の REST API と対話する例です。
インポートの定義
import java.io.BufferedReader; import java.io.IOException; import java.io.InputStreamReader; import java.io.OutputStreamWriter; import java.net.HttpURLConnection; import java.net.URL;
文字列値をキャッシュに追加
// Using the imports in the previous example public class RestExample { /** * Method that puts a String value in cache. * @param urlServerAddress * @param value * @throws IOException */ public void putMethod(String urlServerAddress, String value) throws IOException { System.out.println("----------------------------------------"); System.out.println("Executing PUT"); System.out.println("----------------------------------------"); URL address = new URL(urlServerAddress); System.out.println("executing request " + urlServerAddress); HttpURLConnection connection = (HttpURLConnection) address.openConnection(); System.out.println("Executing put method of value: " + value); connection.setRequestMethod("PUT"); connection.setRequestProperty("Content-Type", "text/plain"); connection.setDoOutput(true); OutputStreamWriter outputStreamWriter = new OutputStreamWriter(connection.getOutputStream()); outputStreamWriter.write(value); connection.connect(); outputStreamWriter.flush(); System.out.println("----------------------------------------"); System.out.println(connection.getResponseCode() + " " + connection.getResponseMessage()); System.out.println("----------------------------------------"); connection.disconnect(); }
以下のコードは、Red Hat JBoss Data Grid REST インターフェースと対話するために Java を使用して URL に指定された値を読み取るメソッドの例です。
キャッシュから文字列値を取得
// Continuation of RestExample defined in previous example /** * Method that gets an value by a key in url as param value. * @param urlServerAddress * @return String value * @throws IOException */ public String getMethod(String urlServerAddress) throws IOException { String line = new String(); StringBuilder stringBuilder = new StringBuilder(); System.out.println("----------------------------------------"); System.out.println("Executing GET"); System.out.println("----------------------------------------"); URL address = new URL(urlServerAddress); System.out.println("executing request " + urlServerAddress); HttpURLConnection connection = (HttpURLConnection) address.openConnection(); connection.setRequestMethod("GET"); connection.setRequestProperty("Content-Type", "text/plain"); connection.setDoOutput(true); BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(connection.getInputStream())); connection.connect(); while ((line = bufferedReader.readLine()) != null) { stringBuilder.append(line + '\n'); } System.out.println("Executing get method of value: " + stringBuilder.toString()); System.out.println("----------------------------------------"); System.out.println(connection.getResponseCode() + " " + connection.getResponseMessage()); System.out.println("----------------------------------------"); connection.disconnect(); return stringBuilder.toString(); }
Java Main メソッドの使用
// Continuation of RestExample defined in previous example /** * Main method example. * @param args * @throws IOException */ public static void main(String[] args) throws IOException { //Note that the cache name is "cacheX" RestExample restExample = new RestExample(); restExample.putMethod("http://localhost:8080/rest/cacheX/1", "Infinispan REST Test"); restExample.getMethod("http://localhost:8080/rest/cacheX/1"); } }
12.6. REST インターフェースの使用
12.6.1. REST インターフェースの使用
REST インターフェースを Red Hat JBoss Data Grid のリモートクライアントサーバーモードで使用すると、以下の操作を実行できます。
- データの追加
- データの取得
- データの削除
12.6.2. REST を使用したデータの追加
12.6.2.1. REST を使用したデータの追加
Red Hat JBoss Data Grid の REST インターフェースで、次のメソッドを使用してデータをキャッシュに追加します。
-
HTTP
PUT
メソッド -
HTTP
POST
メソッド
PUT
および POST
メソッドが使用される場合、要求の本文には、ユーザーにより追加された情報を含むこのデータが含まれます。
PUT
および POST
メソッドの両方には、Content-Type ヘッダーが必要です。
12.6.2.2. PUT /{cacheName}/{cacheKey} について
提供された URL フォームからの PUT
要求により、提供されたキーを使用して要求本文からのペイロードがターゲットキャッシュに配置されます。このタスクが正常に完了するには、ターゲットキャッシュがサーバーに存在する必要があります。
例として、以下の URL では、値 hr
がキャッシュ名であり、payRoll%2F3
がキーです。値 %2F
は、/
がキーで使用されたことを示します。
http://someserver/rest/hr/payRoll%2F3
既存のデータは置き換えられ、更新が必要な場合は Time-To-Live
値および Last-Modified
値が更新されます。
以下の引数を使用してサーバーが起動された場合は、キーの /
を表す値 %2F
を含むキャッシュキー (提供された例を参照) を正常に実行できます。
-Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true
12.6.2.3. POST /{cacheName}/{cacheKey} について
提供された URL フォームからの POST
メソッドにより、提供されたキーを使用して (要求本文からの) ペイロードがターゲットキャッシュに配置されます。ただし、POST
メソッドでは、値がキャッシュ/キーに存在する場合に、HTTP CONFLICT
ステータスが返され、内容が更新されません。
12.6.3. REST を使用したデータの取得
12.6.3.1. REST を使用したデータの取得
Red Hat JBoss Data Grid の REST インターフェースで、次のメソッドを使用してキャッシュからデータを取得します。
-
HTTP
GET
メソッド -
HTTP
HEAD
メソッド
12.6.3.2. GET /{cacheName}/{cacheKey} について
GET
メソッドは、指定の cacheName
に存在し、関連するキーに一致するデータを応答の本文として返します。Content-Type ヘッダーは、データのタイプを提供します。ブラウザーはキャッシュに直接アクセスできます。
各エントリーに対して、要求された URL
でデータの状態を示す Last-Modified ヘッダーとともに一意のエンティティータグ (ETag) が返されます。ETag により、ブラウザー (および他のクライアント) は、(帯域幅を節約するために) データが変更された場合のみデータを要求できます。ETag は、HTTP 標準の一部であり、Red Hat JBoss Data Grid によりサポートされます。
格納されたコンテンツのタイプは、返されたタイプです。例として、文字列が格納された場合は、文字列が返されます。シリアライズされた形式で格納されたオブジェクトは、手動でデシリアライズする必要があります。
12.6.3.3. HEAD /{cacheName}/{cacheKey} について
HEAD
メソッドは、GET
メソッドと同様に動作しますが、コンテンツを返しません (ヘッダーフィールドが返されます)。
12.6.4. REST を使用したデータの削除
12.6.4.1. REST を使用したデータの削除
REST インターフェースを使用して Red Hat JBoss Data Grid からデータを削除するには、HTTP DELETE
メソッドを使用してキャッシュからデータを取得します。DELETE
メソッドは以下を実行できます。
-
キャッシュエントリー/値を削除します (
DELETE /{cacheName}/{cacheKey}
) -
キャッシュからすべてのエントリーを削除します (
DELETE /{cacheName}
)
12.6.4.2. DELETE /{cacheName}/{cacheKey} について
DELETE
メソッドがこのコンテキスト (DELETE /{cacheName}/{cacheKey}) で使用された場合、指定のキーのキャッシュからキー/値を削除します。
12.6.4.3. DELETE /{cacheName} について
このコンテキスト (DELETE /{cacheName}
) では、DELETE
メソッドが名前付きキャッシュ内のすべてのエントリーを削除します。正常な DELETE
操作後に、HTTP ステータスコード 200
が返されます。
12.6.4.4. バックグラウンド削除操作
performAsync
ヘッダーの値を true
に設定して、削除操作がバックグラウンドで続行される状態で値がすぐに返されるようにします。
12.6.5. REST インターフェース操作ヘッダー
以下の表は、Red Hat JBoss Data Grid REST インターフェースに含まれるヘッダーを示しています。
ヘッダー | 必須/任意 | 値 | デフォルト値 | 説明 |
---|---|---|---|---|
Content-Type |
必須 |
- |
- |
Content-Type が application/x-java-serialized-object に設定された場合は、Java オブジェクトとして格納されます。 |
performAsync |
任意 |
True/False |
- |
|
timeToLiveSeconds |
任意 |
数値 (正の値および負の値) |
|
該当するエントリーが自動的に削除されるまでの秒数を反映します。timeToLiveSeconds に負の値を設定すると、デフォルト値と同じ結果が提供されます。 |
maxIdleTimeSeconds |
任意 |
数値 (正の値および負の値) |
|
エントリーが自動的に削除される場合の、最後の使用時以降の秒数を含みます。負の値を渡すと、デフォルト値と同じ結果が提供されます。 |
timeToLiveSeconds
ヘッダーおよび maxIdleTimeSeconds
ヘッダーには以下の組み合わせを設定できます。
-
timeToLiveSeconds
ヘッダーとmaxIdleTimeSeconds
ヘッダーの両方に値0
が割り当てられた場合、キャッシュは XML またはプログラムを使用して設定されたデフォルトのtimeToLiveSeconds
値とmaxIdleTimeSeconds
値を使用します。 -
maxIdleTimeSeconds
ヘッダー値のみが0
に設定された場合は、timeToLiveSeconds
値をパラメーターとして渡す必要があります (パラメーターが存在しない場合はデフォルトの-1
)。さらにmaxIdleTimeSeconds
パラメーター値は、デフォルトで XML またはプログラムを使用して設定された値に設定されます。 -
timeToLiveSeconds
ヘッダー値のみが0
に設定された場合は、エクスパレーションが即座に発生し、maxIdleTimeSeconds
値がパラメーターとして渡された値に設定されます (パラメーターが提供されなかった場合はデフォルトの-1
)。
ETag ベースのヘッダー
各 REST インターフェースエントリーに対して、提供された URL
でデータの状態を示す Last-Modified
ヘッダーとともに、ETag (エンティティータグ) が返されます。ETag は、帯域幅を節約するためにデータが変更された場合にのみ、データを要求する HTTP 操作で使用されます。以下のヘッダーは、ETag (エンティティータグ) ベースの楽観的ロックをサポートします。
Header | アルゴリズム | 例 | 説明 |
---|---|---|---|
If-Match |
If-Match = "If-Match" ":" ( "*" | 1#entity-tag ) |
- |
(リソースから以前に取得された) 指定されたエンティティーが最新であることを確認するために、関連するエンティティータグのリストとともに使用されます。 |
If-None-Match |
- |
(リソースから以前に取得された) 指定されたエンティティーが最新でないことを確認するために、関連するエンティティータグのリストとともに使用されます。この機能により、必要なときに、最小のトランザクションオーバーヘッドで、キャッシュされた情報が効率的に更新されます。 | |
If-Modified-Since |
If-Modified-Since = "If-Modified-Since" ":" HTTP-date |
If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT |
要求されたバリアントの最終変更日時と、提供された時間および日付の値とを比較します。指定された日時以降に要求されたバリアントが変更されなかった場合は、エンティティーの代わりに |
If-Unmodified-Since |
If-Unmodified-Since = "If-Unmodified-Since" ":" HTTP-date |
If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT |
要求されたバリアントの最終変更日時と、提供された時間および日付の値とを比較します。指定された日時以降に要求されたリソースが変更されなかった場合は、指定された操作が実行されます。指定された日時以降に要求されたリソースが変更された場合は、操作が実行されず、エンティティーの代わりに |