第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 インターフェースに含まれるヘッダーを示しています。

表12.1 ヘッダータイプ
ヘッダー必須/任意デフォルト値説明

Content-Type

必須

-

-

Content-Type が application/x-java-serialized-object に設定された場合は、Java オブジェクトとして格納されます。

performAsync

任意

True/False

-

true に設定された場合は、すぐに返され、独自にクラスターにデータがレプリケートされます。この機能は、大量のデータ挿入と大きいクラスターを取り扱う場合に役に立ちます。

timeToLiveSeconds

任意

数値 (正の値および負の値)

-1 (この値により、timeToLiveSeconds の直接的な結果としてエクスパレーションが回避されます。このデフォルト値よりも、他の場所で設定されたエクスパレーションの値が優先されます。)

該当するエントリーが自動的に削除されるまでの秒数を反映します。timeToLiveSeconds に負の値を設定すると、デフォルト値と同じ結果が提供されます。

maxIdleTimeSeconds

任意

数値 (正の値および負の値)

-1 (この値により、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 (エンティティータグ) ベースの楽観的ロックをサポートします。

表12.2 エンティティータグ関連ヘッダー
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

要求されたバリアントの最終変更日時と、提供された時間および日付の値とを比較します。指定された日時以降に要求されたバリアントが変更されなかった場合は、エンティティーの代わりに 304 (未変更) 応答がメッセージ本文なしで返されます。

If-Unmodified-Since

If-Unmodified-Since = "If-Unmodified-Since" ":" HTTP-date

If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT

要求されたバリアントの最終変更日時と、提供された時間および日付の値とを比較します。指定された日時以降に要求されたリソースが変更されなかった場合は、指定された操作が実行されます。指定された日時以降に要求されたリソースが変更された場合は、操作が実行されず、エンティティーの代わりに 412 (事前条件失敗) 応答が返されます。

Red Hat logoGithubRedditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

© 2024 Red Hat, Inc.