第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 ヘッダー
| ヘッダー | 必須またはオプション | パラメーター |
|---|---|---|
|
| 必須 |
Data Grid 設定のペイロードの MediaType を設定します ( |
|
| オプション | AdminFlags を設定するために使用されます |
References
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 ヘッダー
| ヘッダー | 必須またはオプション | パラメーター |
|---|---|---|
|
| オプション |
コンテンツを返すために必要な形式を設定します。対応フォーマットは、 |
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-Live と Last-Modified の値を更新します。
指定されたキーの値がすでに存在する場合、POST リクエストは HTTP CONFLICT ステータスを返し、値を変更しません。値を更新するには、PUT リクエストを使用する必要があります。エントリーの入れ替え をご覧ください。
表2.3 ヘッダー
| ヘッダー | 必須またはオプション | パラメーター |
|---|---|---|
|
| オプション | リクエストのキーのコンテンツタイプを設定します。詳細は、Key-Content-Type を参照してください。 |
|
| オプション | キーの値の MediaType を設定します。 |
|
| オプション | エントリーが自動的に削除されるまでの秒数を設定します。このパラメーターを設定しない場合、DataGrid は設定のデフォルト値を使用します。負の値を設定すると、エントリーが削除されることはありません。 |
|
| オプション | エントリーがアイドル状態になることができる秒数を設定します。最大アイドル時間が経過してもエントリーの読み取りまたは書き込み操作が発生しない場合、エントリーは自動的に削除されます。このパラメーターを設定しない場合、DataGrid は設定のデフォルト値を使用します。負の値を設定すると、エントリーが削除されることはありません。 |
|
| オプション | エントリーの追加に使用されるフラグ。詳細については、フラグ を参照してください。 |
flags ヘッダーは、キャッシュでのデータ操作を含む他のすべての操作にも適用されます。
timeToLiveSeconds と maxIdleTimeSeconds の両方の値が 0 の場合、Data Grid は設定のデフォルトの lifespan と maxIdle の値を使用します。
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 ヘッダー
| ヘッダー | 必須またはオプション | パラメーター |
|---|---|---|
|
| オプション |
リクエストのキーのコンテンツタイプを設定します。デフォルトは |
|
| オプション | コンテンツを返すために必要な形式を設定します。詳細については、 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 ヘッダー
| ヘッダー | 必須またはオプション | パラメーター |
|---|---|---|
|
| オプション |
リクエストのキーのコンテンツタイプを設定します。デフォルトは |
2.1.11. エントリーの削除
DELETE リクエストを使用してキャッシュからエントリーを 削除 します。
DELETE /rest/v2/caches/{cacheName}/{cacheKey}表2.6 ヘッダー
| ヘッダー | 必須またはオプション | パラメーター |
|---|---|---|
|
| オプション |
リクエストのキーのコンテンツタイプを設定します。デフォルトは |
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 リクエストパラメーター
| パラメーター | 必須またはオプション | 値 |
|---|---|---|
|
| オプション |
キーを取得するときの内部バッチサイズを指定します。デフォルト値は |
2.1.14. キャッシュのクリア
キャッシュからすべてのデータを削除するには、GET リクエストに ?action=clear パラメーターを付けて実行します。
GET /rest/v2/caches/{cacheName}?action=clear2.1.15. キャッシュサイズの取得
GET リクエストと ?action=size パラメーターを使用して、クラスター全体のキャッシュのサイズを取得します。
GET /rest/v2/caches/{cacheName}?action=size2.1.16. キャッシュ統計の取得
GET リクエストを使用してキャッシュの実行時統計を取得します。
GET /rest/v2/caches/{cacheName}?action=stats2.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 リクエストパラメーター
| パラメーター | 必須またはオプション | 値 |
|---|---|---|
|
| 必須 | クエリー文字列を指定します。 |
|
| オプション |
返す結果の数を設定します。デフォルトは |
|
| オプション |
返される最初の結果のインデックスを指定します。デフォルトは |
|
| オプション |
Data Grid サーバーがクエリーを実行する方法を指定します。値は |
クエリーパラメーターを指定せずにリクエストの本文を使用するには、以下のように 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の応答を返します。 -
asyncは200の応答を即座に返し、再インデックス化操作はクラスター内で実行を継続します。Index StatisticsREST コールで状態を確認できます。
2.1.19. インデックスのパージ
GET リクエストと ?action=clear パラメーターを使用して、キャッシュからすべてのインデックスを削除します。
GET /v2/caches/{cacheName}/search/indexes?action=clear2.1.20. インデックス統計情報の取得
GET リクエストでキャッシュ内のインデックスの情報を取得します。
GET /v2/caches/{cacheName}/search/indexes/statsData 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/statsData 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=clear2.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 リターンステータス
| 値 | 説明 |
|---|---|
|
| ローカルクラスター内のすべてのノードには、バックアップの場所を含むクロスサイトビューがあります。 |
|
| ローカルクラスター内のノードには、バックアップの場所とのクロスサイトビューがありません。 |
|
| ローカルクラスター内の一部のノードにはバックアップの場所を含むクロスサイトビューがあり、ローカルクラスター内の他のノードにはクロスサイトビューがありません。応答は、各ノードのステータスを示します。 |
2.1.24.2. 特定のバックアップ場所のステータスの取得
GET リクエストでバックアップロケーションのステータスを取得する。
GET /v2/caches/{cacheName}/x-site/backups/{siteName}Data Grid は、以下の例のように、サイト内の各ノードのステータスを JSON 形式で応答します。
{
"NodeA":"offline",
"NodeB":"online"
}表2.10 リターンステータス
| 値 | 説明 |
|---|---|
|
| ノードはオンラインです。 |
|
| ノードはオフラインです。 |
|
| ステータスを取得できません。リモートキャッシュがシャットダウンしているか、リクエスト中にネットワークエラーが発生した可能性があります。 |
2.1.24.3. バックアップ先をオフラインにする
GET リクエストと ?action=take-offline パラメーターを使用して、バックアップの場所をオフラインにします。
GET /v2/caches/{cacheName}/x-site/backups/{siteName}?action=take-offline2.1.24.4. バックアップ場所をオンラインにする
?action=bring-online パラメーターを使用してバックアップ場所をオンラインにします。
GET /v2/caches/{cacheName}/x-site/backups/{siteName}?action=bring-online2.1.24.5. バックアップ場所への状態のプッシュ
?action=start-push-state パラメーターを使用して、キャッシュ状態をバックアップ場所にプッシュします。
GET /v2/caches/{cacheName}/x-site/backups/{siteName}?action=start-push-state2.1.24.6. 状態転送のキャンセル
?action=cancel-push-state パラメーターを使用して状態転送操作をキャンセルします。
GET /v2/caches/{cacheName}/x-site/backups/{siteName}?action=cancel-push-state2.1.24.7. 状態転送ステータスの取得
?action=push-state-status パラメーターを使用して状態転送操作のステータスを取得します。
GET /v2/caches/{cacheName}/x-site/backups?action=push-state-statusData Grid は、以下の例のように、各バックアップ拠点の状態移行の状況を JSON 形式で応答します。
{
"NYC":"CANCELED",
"LON":"OK"
}表2.11 リターンステータス
| 値 | 説明 |
|---|---|
|
| バックアップ場所への状態転送が進行中です。 |
|
| 状態の転送が正常に完了しました。 |
|
| 状態転送でエラーが発生しました。ログファイルを確認してください。 |
|
| 状態移行のキャンセルが進行中です。 |
2.1.24.8. 状態転送ステータスのクリア
?action=clear-push-state-status パラメーターを使用して送信サイトの状態転送ステータスをクリアします。
GET /v2/caches/{cacheName}/x-site/local?action=clear-push-state-status2.1.24.9. オフラインテイク条件の変更
特定の条件が満たされると、サイトはオフラインになります。オフラインにするパラメーターを変更して、バックアップロケーションが自動的にオフラインになるタイミングを制御します。
手順
GETリクエストとtake-offline-configパラメーターで設定されたテイクオフラインパラメーターを確認します。GET /v2/caches/{cacheName}/x-site/backups/{siteName}/take-offline-configData Grid のレスポンスには、以下のように
after_failuresとmin_waitフィールドがあります。{ "after_failures": 2, "min_wait": 1000 }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-state2.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