第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 |
要求されたバリアントの最終変更日時と、提供された時間および日付の値とを比較します。指定された日時以降に要求されたリソースが変更されなかった場合は、指定された操作が実行されます。指定された日時以降に要求されたリソースが変更された場合は、操作が実行されず、エンティティーの代わりに |