第2章 Data Grid REST API との連携

Data Grid REST API は、Data Grid の展開を監視、維持、管理し、データへのアクセスを提供します。

2.1. キャッシュの作成と管理

Data Grid のキャッシュを作成・管理し、データに対する操作を行うことができます。

2.1.1. キャッシュの作成

XML または JSON 設定をペイロードに含む POST リクエストで、Data Grid クラスター全体に名前付きキャッシュを作成します。

POST /rest/v2/caches/{cacheName}

表2.1 ヘッダー

ヘッダー必須またはオプションパラメーター

Content-Type

必須

Data Grid 設定のペイロードの MediaType を設定します ( application/xml または application/json のいずれか)。

Flags

オプション

AdminFlags を設定するために使用されます

2.1.1.1. XML の設定

XML 形式の Data Grid 設定はスキーマに準拠し、以下を含める必要があります。

  • <infinispan> ルート要素。
  • <cache-container> 定義。

XML 設定のサンプル

<infinispan>
    <cache-container>
        <distributed-cache name="cacheName" mode="SYNC">
            <memory>
                <object size="20"/>
            </memory>
        </distributed-cache>
    </cache-container>
</infinispan>

2.1.1.2. JSON 設定

JSON 形式の Data Grid 設定:

  • キャッシュ定義のみが必要です。
  • XML 設定の構造に従う必要があります。

    • XML 要素は JSON オブジェクトになります。
    • XML 属性は JSON フィールドになります。

JSON 設定の例

{
  "distributed-cache": {
    "mode": "SYNC",
    "memory": {
      "object": {
        "size": 20
      }
    }
  }
}

2.1.2. キャッシュの検証

HEAD リクエストで Data Grid クラスターでキャッシュが利用可能かどうかを確認します。

HEAD /rest/v2/caches/{cacheName}

2.1.3. テンプレートを使用したキャッシュの作成

POST リクエストと ?template= パラメーターを使用して、Data Grid テンプレートからキャッシュを作成します。

POST /rest/v2/caches/{cacheName}?template={templateName}

2.1.4. キャッシュ設定の取得

GET リクエストで Data Grid のキャッシュ設定を取得します。

GET /rest/v2/caches/{name}?action=config

表2.2 ヘッダー

ヘッダー必須またはオプションパラメーター

Accept

オプション

コンテンツを返すために必要な形式を設定します。対応フォーマットは、application/xmlapplication/json です。デフォルトは application/json です。詳細については、 Accept を参照してください。

2.1.5. キャッシュ設定を JSON に変換する

有効な XML 設定と ?action=toJSON パラメーターを使用して POST 要求を呼び出します。Data Grid は、設定の同等の JSON 表現で応答します。

POST /rest/v2/caches?action=toJSON

2.1.6. すべてのキャッシュの詳細を取得する

GET リクエストを呼び出し、Data Grid キャッシュのすべての詳細を取得します。

GET /rest/v2/caches/{name}

Data Grid は、以下のような JSON レスポンスを提供します。

{
  "stats": {
    "time_since_start": -1,
    "time_since_reset": -1,
    "hits": -1,
    "current_number_of_entries": -1,
    "current_number_of_entries_in_memory": -1,
    "total_number_of_entries": -1,
    "stores": -1,
    "off_heap_memory_used": -1,
    "data_memory_used": -1,
    "retrievals": -1,
    "misses": -1,
    "remove_hits": -1,
    "remove_misses": -1,
    "evictions": -1,
    "average_read_time": -1,
    "average_read_time_nanos": -1,
    "average_write_time": -1,
    "average_write_time_nanos": -1,
    "average_remove_time": -1,
    "average_remove_time_nanos": -1,
    "required_minimum_number_of_nodes": -1
  },
  "size": 0,
  "configuration": {
    "distributed-cache": {
      "mode": "SYNC",
      "transaction": {
        "stop-timeout": 0,
        "mode": "NONE"
      }
    }
  },
  "rehash_in_progress": false,
  "bounded": false,
  "indexed": false,
  "persistent": false,
  "transactional": false,
  "secured": false,
  "has_remote_backup": false,
  "indexing_in_progress": false,
  "statistics": false
}
  • stats キャッシュの現在の状態を表示します。
  • size キャッシュの推定サイズ。
  • configuration キャッシュ設定。
  • rehash_in_progress リハッシュが進行中の場合は true。
  • indexing_in_progress インデックス作成中の場合は true。
  • bounded 有効期限が有効になっている。
  • indexed キャッシュがインデックス化されている場合は true。
  • persistent キャッシュが永続化されている場合は true。
  • transactional キャッシュがトランザクショナルである場合は true。
  • secured キャッシュが保護されている場合は true。
  • has_remote_backup キャッシュがリモートバックアップを持っている場合は true。

2.1.7. エントリーの追加

POST リクエストでキャッシュにエントリーを追加します。

POST /rest/v2/caches/{cacheName}/{cacheKey}

前述の要求は cacheKey キーで cacheName を指定のキャッシュに、ペイロード、またはリクエストボディを配置します。リクエストは、既存のデータを置き換え、適用可能であれば、Time-To-LiveLast-Modified の値を更新します。

指定されたキーの値がすでに存在する場合、POST リクエストは HTTP CONFLICT ステータスを返し、値を変更しません。値を更新するには、PUT リクエストを使用する必要があります。エントリーの入れ替え をご覧ください。

表2.3 ヘッダー

ヘッダー必須またはオプションパラメーター

Key-Content-Type

オプション

リクエストのキーのコンテンツタイプを設定します。詳細は、Key-Content-Type を参照してください。

Content-Type

オプション

キーの値の MediaType を設定します。

timeToLiveSeconds

オプション

エントリーが自動的に削除されるまでの秒数を設定します。このパラメーターを設定しない場合、DataGrid は設定のデフォルト値を使用します。負の値を設定すると、エントリーが削除されることはありません。

maxIdleTimeSeconds

オプション

エントリーがアイドル状態になることができる秒数を設定します。最大アイドル時間が経過してもエントリーの読み取りまたは書き込み操作が発生しない場合、エントリーは自動的に削除されます。このパラメーターを設定しない場合、DataGrid は設定のデフォルト値を使用します。負の値を設定すると、エントリーが削除されることはありません。

flags

オプション

エントリーの追加に使用されるフラグ。詳細については、フラグ を参照してください。

注記

flags ヘッダーは、キャッシュでのデータ操作を含む他のすべての操作にも適用されます。

注記

timeToLiveSecondsmaxIdleTimeSeconds の両方の値が 0 の場合、Data Grid は設定のデフォルトの lifespanmaxIdle の値を使用します。

only maxIdleTimeSeconds のみ値が 0 の場合、Data Grid が使用します。

  • コンフィグレーションのデフォルトの maxIdle 値を使用します。
  • リクエストパラメーターとして渡した timeToLiveSeconds の値、または値を渡さなかった場合は -1 の値です。

timeToLiveSeconds の値だけが 0 の場合、Data Grid は

  • 設定のデフォルトの lifespan 値を使用。
  • リクエストパラメーターとして渡された maxIdle の値、または値を渡さない場合は -1 の値を使用。

2.1.8. エントリーの置き換え

キャッシュ内のエントリーを PUT リクエストに置き換えます。

PUT /rest/v2/caches/{cacheName}/{cacheKey}

指定されたキーの値がすでに存在する場合、 PUT 要求は値を更新します。既存の値を変更したくない場合は、値を変更する代わりに HTTP CONFLICT ステータスを返す POST リクエストを使用します。値の追加 を参照してください。

2.1.9. キーによるデータの取得

GET リクエストを使用して特定のキーのデータを取得します。

GET /rest/v2/caches/{cacheName}/{cacheKey}

サーバーは、応答本文の指定されたキー cacheKey の下にある指定されたキャッシュ cacheName からデータを返します。応答には、MediaType ネゴシエーションに対応する Content-Type ヘッダーが含まれています。

注記

ブラウザーは、たとえばコンテンツ配信ネットワーク (CDN) として、キャッシュに直接アクセスすることもできます。Data Grid は、各エントリーに固有のETagを、Last-Modified および Expires ヘッダーフィールドとともに返します。

これらのフィールドは、リクエストで返されるデータの状態に関する情報を提供します。ETag を使用すると、ブラウザーやその他のクライアントは、変更されたデータのみを要求できるため、帯域幅が節約されます。

表2.4 ヘッダー

ヘッダー必須またはオプションパラメーター

Key-Content-Type

オプション

リクエストのキーのコンテンツタイプを設定します。デフォルトは application/x-java-object; type=java.lang.String です。詳細は、Key-Content-Type を参照してください。

Accept

オプション

コンテンツを返すために必要な形式を設定します。詳細については、 Accept を参照してください。

ヒント

extended パラメーターをクエリー文字列に追加して、追加情報を取得します。

GET /rest/v2/caches/{cacheName}/{cacheKey}?extended

上記のリクエストはカスタムヘッダーを返します:

  • Cluster-Primary-Owner は、キーのプライマリー所有者であるノード名を返します。
  • Cluster-Node-Name は、要求を処理したサーバーの JGroups ノード名を返します。
  • Cluster-Physical-Address は、要求を処理したサーバーの物理 JGroups アドレスを返します。

2.1.10. エントリーが存在するかどうかの確認

HEAD リクエストで特定のエントリーが存在することを確認します。

HEAD /rest/v2/caches/{cacheName}/{cacheKey}

上記のリクエストは、ヘッダーフィールドと、エントリーとともに保存したものと同じコンテンツのみを返します。たとえば、文字列を保存した場合、リクエストは文字列を返します。バイナリー、base64 エンコード、blob、またはシリアル化された Java オブジェクトを保存した場合、DataGrid はリクエストのコンテンツを逆シリアル化しません。

注記

HEAD リクエストは、extended パラメーターもサポートしています。

表2.5 ヘッダー

ヘッダー必須またはオプションパラメーター

Key-Content-Type

オプション

リクエストのキーのコンテンツタイプを設定します。デフォルトは application/x-java-object; type=java.lang.String です。詳細は、Key-Content-Type を参照してください。

2.1.11. エントリーの削除

DELETE リクエストを使用してキャッシュからエントリーを 削除 します。

DELETE /rest/v2/caches/{cacheName}/{cacheKey}

表2.6 ヘッダー

ヘッダー必須またはオプションパラメーター

Key-Content-Type

オプション

リクエストのキーのコンテンツタイプを設定します。デフォルトは application/x-java-object; type=java.lang.String です。詳細は、Key-Content-Type を参照してください。

2.1.12. キャッシュの削除

DELETE リクエストを使用して Data Grid クラスターからキャッシュを DELETE 削除します。

DELETE /rest/v2/caches/{cacheName}

2.1.13. キャッシュからのすべてのキーの取得

GET リクエストを呼び出して、キャッシュ内のすべてのキーを JSON 形式で取得します。

GET /rest/v2/caches/{cacheName}?action=keys

表2.7 リクエストパラメーター

パラメーター必須またはオプション

batch-size

オプション

キーを取得するときの内部バッチサイズを指定します。デフォルト値は 1000 です。

2.1.14. キャッシュのクリア

キャッシュからすべてのデータを削除するには、GET リクエストに ?action=clear パラメーターを付けて実行します。

GET /rest/v2/caches/{cacheName}?action=clear

2.1.15. キャッシュサイズの取得

GET リクエストと ?action=size パラメーターを使用して、クラスター全体のキャッシュのサイズを取得します。

GET /rest/v2/caches/{cacheName}?action=size

2.1.16. キャッシュ統計の取得

GET リクエストを使用してキャッシュの実行時統計を取得します。

GET /rest/v2/caches/{cacheName}?action=stats

2.1.17. キャッシュのクエリー

GET リクエストと ?action=search&query パラメーターを使用して、キャッシュに対して Ickle クエリーを実行します。

GET /rest/v2/caches/{cacheName}?action=search&query={ickle query}

Data Grid は、次のようなクエリーヒットで応答します。

{
  "total_results" : 150,
  "hits" : [ {
    "hit" : {
      "name" : "user1",
      "age" : 35
    }
  }, {
    "hit" : {
       "name" : "user2",
       "age" : 42
    }
  }, {
    "hit" : {
       "name" : "user3",
       "age" : 12
    }
  } ]
}
  • total_results は、クエリーの結果の合計数を表示します。
  • hits は、クエリーからのマッチの配列です。
  • hit は、クエリーにマッチするオブジェクトです。

    ヒント

    ヒットにはすべてのフィールドを含めることができますが、Select 句を使用するとフィールドのサブセットを含めることができます。

表2.8 リクエストパラメーター

パラメーター必須またはオプション

query

必須

クエリー文字列を指定します。

max_results

オプション

返す結果の数を設定します。デフォルトは 10 です。

offset

オプション

返される最初の結果のインデックスを指定します。デフォルトは 0 です。

query_mode

オプション

Data Grid サーバーがクエリーを実行する方法を指定します。値は FETCH および BROADCAST です。デフォルトは FETCH です。

クエリーパラメーターを指定せずにリクエストの本文を使用するには、以下のように POST リクエストを呼び出します。

POST /rest/v2/caches/{cacheName}?action=search

次の例は、リクエスト本文のクエリーを示しています。

{
 "query":"from Entity where name:\"user1\"",
 "max_results":20,
 "offset":10
}

2.1.18. データのインデックスの再作成

GET リクエストと ?action=mass-index&mode={mode} パラメーターを使用して、キャッシュ内のすべてのデータのインデックスを再作成します。

GET  /v2/caches/{cacheName}/search/indexes?action=mass-index&mode={mode}

mode パラメーターの値は以下の通りです。

  • sync は、インデックス変更操作が完了した後にのみ 200 の応答を返します。
  • async200 の応答を即座に返し、再インデックス化操作はクラスター内で実行を継続します。Index StatisticsREST コールで状態を確認できます。

2.1.19. インデックスのパージ

GET リクエストと ?action=clear パラメーターを使用して、キャッシュからすべてのインデックスを削除します。

GET  /v2/caches/{cacheName}/search/indexes?action=clear

2.1.20. インデックス統計情報の取得

GET リクエストでキャッシュ内のインデックスの情報を取得します。

GET /v2/caches/{cacheName}/search/indexes/stats

Data Grid は、以下のような JSON レスポンスを提供します。

{
    "indexed_class_names": ["org.infinispan.sample.User"],
    "indexed_entities_count": {
        "org.infinispan.sample.User": 4
    },
    "index_sizes": {
        "cacheName_protobuf": 14551
    },
    "reindexing": false
}
  • indexed_class_names キャッシュに存在するインデックスのクラス名を提供します。Protobuf の場合、値は常に org.infinispan.query.remote.impl.indexing.ProtobufValueWrapper です。
  • indexed_entities_count クラスごとにインデックスされているエンティティーの数を提供します。
  • index_sizes キャッシュ内の各インデックスのサイズをバイト単位で指定します。
  • reindexing キャッシュに対してインデックス変更操作が行われたかどうかを示す。この値が true の場合、MassIndexer はキャッシュで起動したことになります。

2.1.21. クエリー統計情報の取得

GET リクエストでキャッシュに実行されたクエリーの情報を取得します。

GET /v2/caches/{cacheName}/search/query/stats

Data Grid は、以下のような JSON レスポンスを提供します。

{
    "search_query_execution_count":20,
    "search_query_total_time":5,
    "search_query_execution_max_time":154,
    "search_query_execution_avg_time":2,
    "object_loading_total_time":1,
    "object_loading_execution_max_time":1,
    "object_loading_execution_avg_time":1,
    "objects_loaded_count":20,
    "search_query_execution_max_time_query_string": "FROM entity"
}
  • search_query_execution_count 実行されたクエリーの数を提供します。
  • search_query_total_time クエリーに費やされた総時間を提供します。
  • search_query_execution_max_time クエリーにかかる最大時間を指定します。
  • search_query_execution_avg_time クエリーの平均実行時間を提供します。
  • object_loading_total_time クエリー実行後にキャッシュからオブジェクトをロードするのにかかった時間の合計を提供します。
  • object_loading_execution_max_time オブジェクトのロード実行にかかる最大時間を提供します。
  • object_loading_execution_avg_time オブジェクトのロード実行にかかる最大時間を提供します。
  • objects_loaded_count ロードされたオブジェクトの数を提供します。
  • search_query_execution_max_time_query_string 実行された最も遅いクエリーを提供します。

2.1.22. クエリー統計のクリア

GET リクエストと ?action=clear パラメーターを使用して、ランタイムの統計情報をリセットすることができます。

GET /v2/caches/{cacheName}/search/query/stats?action=clear

2.1.23. キャッシュの一覧表示

GET リクエストを使用して、 Data Grid クラスターで使用可能なすべてのキャッシュを一覧表示します。

GET /rest/v2/caches/

2.1.24. キャッシュを利用したクロスサイト・オペレーション

Data Grid REST API を使用して、クロスサイトレプリケーション操作を行います。

2.1.24.1. すべてのバックアップロケーションのステータス取得

GET リクエストですべてのバックアップロケーションのステータスを取得します。

GET /v2/caches/{cacheName}/x-site/backups/

Data Grid は、以下の例のように、各バックアップロケーションのステータスを JSON 形式で応答します。

{
  "NYC": "online",
  "LON": "offline"
}

表2.9 リターンステータス

説明

online

ローカルクラスター内のすべてのノードには、バックアップの場所を含むクロスサイトビューがあります。

offline

ローカルクラスター内のノードには、バックアップの場所とのクロスサイトビューがありません。

mixed

ローカルクラスター内の一部のノードにはバックアップの場所を含むクロスサイトビューがあり、ローカルクラスター内の他のノードにはクロスサイトビューがありません。応答は、各ノードのステータスを示します。

2.1.24.2. 特定のバックアップ場所のステータスの取得

GET リクエストでバックアップロケーションのステータスを取得する。

GET /v2/caches/{cacheName}/x-site/backups/{siteName}

Data Grid は、以下の例のように、サイト内の各ノードのステータスを JSON 形式で応答します。

{
  "NodeA":"offline",
  "NodeB":"online"
}

表2.10 リターンステータス

説明

online

ノードはオンラインです。

offline

ノードはオフラインです。

failed

ステータスを取得できません。リモートキャッシュがシャットダウンしているか、リクエスト中にネットワークエラーが発生した可能性があります。

2.1.24.3. バックアップ先をオフラインにする

GET リクエストと ?action=take-offline パラメーターを使用して、バックアップの場所をオフラインにします。

GET /v2/caches/{cacheName}/x-site/backups/{siteName}?action=take-offline

2.1.24.4. バックアップ場所をオンラインにする

?action=bring-online パラメーターを使用してバックアップ場所をオンラインにします。

GET /v2/caches/{cacheName}/x-site/backups/{siteName}?action=bring-online

2.1.24.5. バックアップ場所への状態のプッシュ

?action=start-push-state パラメーターを使用して、キャッシュ状態をバックアップ場所にプッシュします。

GET /v2/caches/{cacheName}/x-site/backups/{siteName}?action=start-push-state

2.1.24.6. 状態転送のキャンセル

?action=cancel-push-state パラメーターを使用して状態転送操作をキャンセルします。

GET /v2/caches/{cacheName}/x-site/backups/{siteName}?action=cancel-push-state

2.1.24.7. 状態転送ステータスの取得

?action=push-state-status パラメーターを使用して状態転送操作のステータスを取得します。

GET /v2/caches/{cacheName}/x-site/backups?action=push-state-status

Data Grid は、以下の例のように、各バックアップ拠点の状態移行の状況を JSON 形式で応答します。

{
   "NYC":"CANCELED",
   "LON":"OK"
}

表2.11 リターンステータス

説明

SENDING

バックアップ場所への状態転送が進行中です。

OK

状態の転送が正常に完了しました。

ERROR

状態転送でエラーが発生しました。ログファイルを確認してください。

CANCELLING

状態移行のキャンセルが進行中です。

2.1.24.8. 状態転送ステータスのクリア

?action=clear-push-state-status パラメーターを使用して送信サイトの状態転送ステータスをクリアします。

GET /v2/caches/{cacheName}/x-site/local?action=clear-push-state-status

2.1.24.9. オフラインテイク条件の変更

特定の条件が満たされると、サイトはオフラインになります。オフラインにするパラメーターを変更して、バックアップロケーションが自動的にオフラインになるタイミングを制御します。

手順

  1. GET リクエストと take-offline-config パラメーターで設定されたテイクオフラインパラメーターを確認します。

    GET /v2/caches/{cacheName}/x-site/backups/{siteName}/take-offline-config

    Data Grid のレスポンスには、以下のように after_failuresmin_wait フィールドがあります。

    {
      "after_failures": 2,
      "min_wait": 1000
    }
  2. PUT リクエストの本文のオフライン取得パラメーターを変更します。

    PUT /v2/caches/{cacheName}/x-site/backups/{siteName}/take-offline-config

2.1.24.10. 受信サイトからの状態転送のキャンセル

2 つのバックアップ場所間の接続が切断された場合、プッシュを受信しているサイトでの状態転送をキャンセルできます。

?action=cancel-receive-state パラメーターで、リモートサイトからの状態転送をキャンセルし、ローカルキャッシュの現在の状態を維持する。

GET /v2/caches/{cacheName}/x-site/backups/{siteName}?action=cancel-receive-state

2.1.25. ローリングアップグレード

Data Grid クラスター間でキャッシュデータのローリングアップグレードを実行します

2.1.25.1. データの同期

ソースクラスターからターゲットクラスターへのデータの同期には、GET リクエストと ?action=sync-data パラメーターを使用します。

GET /v2/caches/{cacheName}?action=sync-data

操作が完了すると、Data Grid はターゲットクラスターにコピーされたエントリーの合計数で応答します。

2.1.25.2. ソースクラスターの接続

データをターゲットクラスターに同期した後、GET リクエストと ?action=disconnect-source パラメーターを使用してソースクラスターから切断します。

GET /v2/caches/{cacheName}?action=disconnect-source