第2章 Data Grid REST API との連携
Data Grid REST API は、Data Grid の展開を監視、維持、管理し、データへのアクセスを提供します。
デフォルトでは、Data Grid REST API の操作は、成功すると 200 (OK) を返します。ただし、一部の操作が正常に処理されると、 200 ではなく 204 や 202 などの HTTP ステータスコードが返されます。
2.1. キャッシュの作成と管理
Data Grid のキャッシュを作成・管理し、データに対する操作を行うことができます。
2.1.1. キャッシュの作成
XML または JSON 設定をペイロードに含む POST リクエストで、Data Grid クラスター全体に名前付きキャッシュを作成します。
POST /rest/v2/caches/{cacheName}表2.1 ヘッダー
| ヘッダー | 必須またはオプション | パラメーター |
|---|---|---|
|
| 必須 |
Data Grid 設定のペイロードの MediaType を設定します ( |
|
| オプション | AdminFlags を設定するために使用されます |
2.1.1.1. キャッシュ設定
XML、JSON、および YAML 形式で宣言型キャッシュ設定を作成できます。
すべての宣言型キャッシュは Data Grid スキーマに準拠する必要があります。JSON 形式の設定は XML 設定の構造に従う必要があります。要素がオブジェクトに対応し、属性はフィールドに対応します。
Data Grid では、キャッシュ名またはキャッシュテンプレート名の文字数を最大 255 文字に制限しています。この文字制限を超えると、Data Grid は例外を出力します。簡潔なキャッシュ名とキャッシュテンプレート名を記述します。
ファイルシステムによってファイル名の長さに制限が設定される場合があるため、キャッシュの名前がこの制限を超えないようにしてください。キャッシュ名がファイルシステムの命名制限を超えると、そのキャッシュに対する一般的な操作または初期化操作が失敗する可能性があります。簡潔なファイル名を書きます。
分散キャッシュ
XML
<distributed-cache owners="2"
segments="256"
capacity-factor="1.0"
l1-lifespan="5000"
mode="SYNC"
statistics="true">
<encoding media-type="application/x-protostream"/>
<locking isolation="REPEATABLE_READ"/>
<transaction mode="FULL_XA"
locking="OPTIMISTIC"/>
<expiration lifespan="5000"
max-idle="1000" />
<memory max-count="1000000"
when-full="REMOVE"/>
<indexing enabled="true"
storage="local-heap">
<index-reader refresh-interval="1000"/>
<indexed-entities>
<indexed-entity>org.infinispan.Person</indexed-entity>
</indexed-entities>
</indexing>
<partition-handling when-split="ALLOW_READ_WRITES"
merge-policy="PREFERRED_NON_NULL"/>
<persistence passivation="false">
<!-- Persistent storage configuration. -->
</persistence>
</distributed-cache>
JSON
{
"distributed-cache": {
"mode": "SYNC",
"owners": "2",
"segments": "256",
"capacity-factor": "1.0",
"l1-lifespan": "5000",
"statistics": "true",
"encoding": {
"media-type": "application/x-protostream"
},
"locking": {
"isolation": "REPEATABLE_READ"
},
"transaction": {
"mode": "FULL_XA",
"locking": "OPTIMISTIC"
},
"expiration" : {
"lifespan" : "5000",
"max-idle" : "1000"
},
"memory": {
"max-count": "1000000",
"when-full": "REMOVE"
},
"indexing" : {
"enabled" : true,
"storage" : "local-heap",
"index-reader" : {
"refresh-interval" : "1000"
},
"indexed-entities": [
"org.infinispan.Person"
]
},
"partition-handling" : {
"when-split" : "ALLOW_READ_WRITES",
"merge-policy" : "PREFERRED_NON_NULL"
},
"persistence" : {
"passivation" : false
}
}
}
YAML
distributedCache:
mode: "SYNC"
owners: "2"
segments: "256"
capacityFactor: "1.0"
l1Lifespan: "5000"
statistics: "true"
encoding:
mediaType: "application/x-protostream"
locking:
isolation: "REPEATABLE_READ"
transaction:
mode: "FULL_XA"
locking: "OPTIMISTIC"
expiration:
lifespan: "5000"
maxIdle: "1000"
memory:
maxCount: "1000000"
whenFull: "REMOVE"
indexing:
enabled: "true"
storage: "local-heap"
indexReader:
refreshInterval: "1000"
indexedEntities:
- "org.infinispan.Person"
partitionHandling:
whenSplit: "ALLOW_READ_WRITES"
mergePolicy: "PREFERRED_NON_NULL"
persistence:
passivation: "false"
# Persistent storage configuration.
レプリケートされたキャッシュ
XML
<replicated-cache segments="256"
mode="SYNC"
statistics="true">
<encoding media-type="application/x-protostream"/>
<locking isolation="REPEATABLE_READ"/>
<transaction mode="FULL_XA"
locking="OPTIMISTIC"/>
<expiration lifespan="5000"
max-idle="1000" />
<memory max-count="1000000"
when-full="REMOVE"/>
<indexing enabled="true"
storage="local-heap">
<index-reader refresh-interval="1000"/>
<indexed-entities>
<indexed-entity>org.infinispan.Person</indexed-entity>
</indexed-entities>
</indexing>
<partition-handling when-split="ALLOW_READ_WRITES"
merge-policy="PREFERRED_NON_NULL"/>
<persistence passivation="false">
<!-- Persistent storage configuration. -->
</persistence>
</replicated-cache>
JSON
{
"replicated-cache": {
"mode": "SYNC",
"segments": "256",
"statistics": "true",
"encoding": {
"media-type": "application/x-protostream"
},
"locking": {
"isolation": "REPEATABLE_READ"
},
"transaction": {
"mode": "FULL_XA",
"locking": "OPTIMISTIC"
},
"expiration" : {
"lifespan" : "5000",
"max-idle" : "1000"
},
"memory": {
"max-count": "1000000",
"when-full": "REMOVE"
},
"indexing" : {
"enabled" : true,
"storage" : "local-heap",
"index-reader" : {
"refresh-interval" : "1000"
},
"indexed-entities": [
"org.infinispan.Person"
]
},
"partition-handling" : {
"when-split" : "ALLOW_READ_WRITES",
"merge-policy" : "PREFERRED_NON_NULL"
},
"persistence" : {
"passivation" : false
}
}
}
YAML
replicatedCache:
mode: "SYNC"
segments: "256"
statistics: "true"
encoding:
mediaType: "application/x-protostream"
locking:
isolation: "REPEATABLE_READ"
transaction:
mode: "FULL_XA"
locking: "OPTIMISTIC"
expiration:
lifespan: "5000"
maxIdle: "1000"
memory:
maxCount: "1000000"
whenFull: "REMOVE"
indexing:
enabled: "true"
storage: "local-heap"
indexReader:
refreshInterval: "1000"
indexedEntities:
- "org.infinispan.Person"
partitionHandling:
whenSplit: "ALLOW_READ_WRITES"
mergePolicy: "PREFERRED_NON_NULL"
persistence:
passivation: "false"
# Persistent storage configuration.
複数のキャッシュ
XML
<infinispan
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:infinispan:config:14.0 https://infinispan.org/schemas/infinispan-config-14.0.xsd
urn:infinispan:server:14.0 https://infinispan.org/schemas/infinispan-server-14.0.xsd"
xmlns="urn:infinispan:config:14.0"
xmlns:server="urn:infinispan:server:14.0">
<cache-container name="default"
statistics="true">
<distributed-cache name="mycacheone"
mode="ASYNC"
statistics="true">
<encoding media-type="application/x-protostream"/>
<expiration lifespan="300000"/>
<memory max-size="400MB"
when-full="REMOVE"/>
</distributed-cache>
<distributed-cache name="mycachetwo"
mode="SYNC"
statistics="true">
<encoding media-type="application/x-protostream"/>
<expiration lifespan="300000"/>
<memory max-size="400MB"
when-full="REMOVE"/>
</distributed-cache>
</cache-container>
</infinispan>
YAML
infinispan:
cacheContainer:
name: "default"
statistics: "true"
caches:
mycacheone:
distributedCache:
mode: "ASYNC"
statistics: "true"
encoding:
mediaType: "application/x-protostream"
expiration:
lifespan: "300000"
memory:
maxSize: "400MB"
whenFull: "REMOVE"
mycachetwo:
distributedCache:
mode: "SYNC"
statistics: "true"
encoding:
mediaType: "application/x-protostream"
expiration:
lifespan: "300000"
memory:
maxSize: "400MB"
whenFull: "REMOVE"
JSON
{
"infinispan" : {
"cache-container" : {
"name" : "default",
"statistics" : "true",
"caches" : {
"mycacheone" : {
"distributed-cache" : {
"mode": "ASYNC",
"statistics": "true",
"encoding": {
"media-type": "application/x-protostream"
},
"expiration" : {
"lifespan" : "300000"
},
"memory": {
"max-size": "400MB",
"when-full": "REMOVE"
}
}
},
"mycachetwo" : {
"distributed-cache" : {
"mode": "SYNC",
"statistics": "true",
"encoding": {
"media-type": "application/x-protostream"
},
"expiration" : {
"lifespan" : "300000"
},
"memory": {
"max-size": "400MB",
"when-full": "REMOVE"
}
}
}
}
}
}
}
2.1.2. キャッシュの変更
ペイロードに XML または JSON 設定を含む PUT リクエストを使用して、Data Grid クラスター全体のキャッシュ設定の属性を変更します。
変更が既存の設定と互換性がある場合にのみ、キャッシュを変更できます。
たとえば、レプリケートされたキャッシュ設定を使用して分散キャッシュを変更することはできません。同様に、特定の属性を使用してキャッシュ設定を作成する場合、代わりに別の属性を使用するように設定を変更することはできません。たとえば、max-count 属性の値を指定してキャッシュ設定を変更しようとすると、max-size がすでに設定されている場合、無効な設定になります。
PUT /rest/v2/caches/{cacheName}表2.2 ヘッダー
| ヘッダー | 必須またはオプション | パラメーター |
|---|---|---|
|
| 必須 |
Data Grid 設定のペイロードの MediaType を設定します ( |
|
| オプション | AdminFlags を設定するために使用されます |
2.1.3. キャッシュの検証
HEAD リクエストで Data Grid クラスターでキャッシュが利用可能かどうかを確認します。
HEAD /rest/v2/caches/{cacheName}2.1.4. テンプレートを使用したキャッシュの作成
POST リクエストと ?template= パラメーターを使用して、Data Grid テンプレートからキャッシュを作成します。
POST /rest/v2/caches/{cacheName}?template={templateName}使用可能なキャッシュテンプレートを一覧表示する を参照してください。
2.1.5. キャッシュ設定の取得
GET リクエストで Data Grid のキャッシュ設定を取得します。
GET /rest/v2/caches/{name}?action=config表2.3 ヘッダー
| ヘッダー | 必須またはオプション | パラメーター |
|---|---|---|
|
| オプション |
コンテンツを返すために必要な形式を設定します。対応フォーマットは、 |
2.1.6. XML、JSON、YAML 間のキャッシュ設定の変換
有効な設定と ?action=convert パラメーターを使用して POST リクエストを呼び出します。Data Grid は、Accept ヘッダで指定されたタイプの設定の同等の表現で応答します。
POST /rest/v2/caches?action=convert
キャッシュ設定を変換するには、Content-Type ヘッダーで設定の入力形式を指定し、Accept ヘッダーで目的の出力形式を指定する必要があります。たとえば、次のコマンドは、レプリケートされたキャッシュ設定を XML から YAML に変換します。
curl localhost:11222/rest/v2/caches?action=convert \ --digest -u username:password \ -X POST -H "Accept: application/yaml" -H "Content-Type: application/xml" \ -d '<replicated-cache mode="SYNC" statistics="false"><encoding media-type="application/x-protostream"/><expiration lifespan="300000" /><memory max-size="400MB" when-full="REMOVE"/></replicated-cache>'
2.1.7. キャッシュ設定の比較
2 つのキャッシュ設定と ?action=compare パラメーターを含む multipart/form-data 本体で POST 要求を呼び出します。
POST /rest/v2/caches?action=compare
比較で変更可能な属性を無視するには、ignoreMutable=true パラメーターを追加します。
Data Grid は、設定が等しい場合は 204 (No Content) で応答し、設定が異なる場合は 409 (Conflict) で応答します。
2.1.8. すべてのキャッシュの詳細を取得する
GET リクエストを呼び出し、Data Grid キャッシュのすべての詳細を取得します。
GET /rest/v2/caches/{name}?action=statsData 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,
"rebalancing_enabled": true,
"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。 -
rebalancing_enabledは、リバランシングが有効な場合は true。このプロパティーの取得は、サーバーで失敗する可能性があります。その場合、プロパティーはペイロードに存在しません。 -
bounded有効期限が有効になっている。 -
indexedキャッシュがインデックス化されている場合は true。 -
persistentキャッシュが永続化されている場合は true。 -
transactionalキャッシュがトランザクショナルである場合は true。 -
securedキャッシュが保護されている場合は true。 -
has_remote_backupキャッシュがリモートバックアップを持っている場合は true。 -
key_storageキャッシュキーのメディアタイプです。 -
value_storageキャッシュの値のメディアタイプです。
key_storage と value_storage は、キャッシュのエンコーディング設定と一致します。エンコーディングなしのサーバーキャッシュの場合、Data Grid はキャッシュがインデックス化されている場合は application/x-protostream を、それ以外の場合は application/unknown を想定しています。
2.1.9. キャッシュのデータ分散の取得
GET 要求を呼び出して、Data Grid キャッシュのデータ配布に関するすべての詳細を取得します。
GET /rest/v2/caches/{name}?action=distributionData Grid は、以下のような JSON レスポンスを提供します。
[
{
"node_name": "NodeA",
"node_addresses": [
"127.0.0.1:44175"
],
"memory_entries": 0,
"total_entries": 0,
"memory_used": 528512
},
{
"node_name":"NodeB",
"node_addresses": [
"127.0.0.1:44187"
],
"memory_entries": 0,
"total_entries": 0,
"memory_used": 528512
}
]リスト内の各要素はノードを表します。プロパティーは次のとおりです。
-
node_nameはノード名です -
node_addressesは、すべてのノードの物理アドレスのリストです。 -
memory_entriesノードがキャッシュに属するメモリーに保持するエントリーの数。 -
total_entriesノードがキャッシュに属するメモリーとディスクに持つエントリーの数。 -
memory_usedは、エビクションアルゴリズムがキャッシュの占有量を推定するバイト単位の値です。エヴィクションが有効になっていない場合は -1 を返します。
2.1.10. すべての可変キャッシュ設定属性の取得
GET 要求を呼び出して、Data Grid キャッシュのすべての可変キャッシュ設定属性を取得します。
GET /rest/v2/caches/{name}?action=get-mutable-attributesData Grid は、以下のような JSON レスポンスを提供します。
[ "jmx-statistics.statistics", "locking.acquire-timeout", "transaction.single-phase-auto-commit", "expiration.max-idle", "transaction.stop-timeout", "clustering.remote-timeout", "expiration.lifespan", "expiration.interval", "memory.max-count", "memory.max-size" ]
値や型の情報を得るには、full パラメーターを追加します。
GET /rest/v2/caches/mycache?action=get-mutable-attributes&full=true
Data Grid は、以下のような JSON レスポンスを提供します。
{
"jmx-statistics.statistics": {
"value": true,
"type": "boolean"
},
"locking.acquire-timeout": {
"value": 15000,
"type": "long"
},
"transaction.single-phase-auto-commit": {
"value": false,
"type": "boolean"
},
"expiration.max-idle": {
"value": -1,
"type": "long"
},
"transaction.stop-timeout": {
"value": 30000,
"type": "long"
},
"clustering.remote-timeout": {
"value": 17500,
"type": "long"
},
"expiration.lifespan": {
"value": -1,
"type": "long"
},
"expiration.interval": {
"value": 60000,
"type": "long"
},
"memory.max-count": {
"value": -1,
"type": "long"
},
"memory.max-size": {
"value": null,
"type": "string"
}
}
enum 型の属性の場合、追加の universe プロパティーには、可能な値のセットが含まれます。
2.1.11. キャッシュ設定属性の更新
変更可能なキャッシュ設定属性を変更するために、POST リクエストを呼び出します。
POST /rest/v2/caches/{name}?action=set-mutable-attributes&attribute-name={attributeName}&attribute-value={attributeValue}2.1.12. エントリーの追加
POST リクエストでキャッシュにエントリーを追加します。
POST /rest/v2/caches/{cacheName}/{cacheKey}
前述の要求は cacheKey キーで cacheName を指定のキャッシュに、ペイロード、またはリクエストボディを配置します。リクエストは、既存のデータを置き換え、適用可能であれば、Time-To-Live と Last-Modified の値を更新します。
エントリーが正常に作成されると、サービスは 204 (No Content) を返します。
指定されたキーに既に値が存在する場合、POST リクエストは 409 (Conflict) を返し、値の変更は行いません。値を更新するには、PUT リクエストを使用する必要があります。エントリーの入れ替え をご覧ください。
表2.4 ヘッダー
| ヘッダー | 必須またはオプション | パラメーター |
|---|---|---|
|
| オプション | リクエストのキーのコンテンツタイプを設定します。詳細は、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.13. エントリーの置き換え
キャッシュ内のエントリーを PUT リクエストに置き換えます。
PUT /rest/v2/caches/{cacheName}/{cacheKey}
指定されたキーの値がすでに存在する場合、 PUT 要求は値を更新します。既存の値を変更したくない場合は、値を変更する代わりに、409 (Conflict) を返す POST リクエストを使用してください。値の追加 を参照してください。
2.1.14. キーによるデータの取得
GET リクエストを使用して特定のキーのデータを取得します。
GET /rest/v2/caches/{cacheName}/{cacheKey}
サーバーは、応答本文の指定されたキー cacheKey の下にある指定されたキャッシュ cacheName からデータを返します。応答には、MediaType ネゴシエーションに対応する Content-Type ヘッダーが含まれています。
ブラウザーは、たとえばコンテンツ配信ネットワーク (CDN) として、キャッシュに直接アクセスすることもできます。Data Grid は、各エントリーに固有のETagを、Last-Modified および Expires ヘッダーフィールドとともに返します。
これらのフィールドは、リクエストで返されるデータの状態に関する情報を提供します。ETag を使用すると、ブラウザーやその他のクライアントは、変更されたデータのみを要求できるため、帯域幅が節約されます。
表2.5 ヘッダー
| ヘッダー | 必須またはオプション | パラメーター |
|---|---|---|
|
| オプション |
リクエストのキーのコンテンツタイプを設定します。デフォルトは |
|
| オプション | コンテンツを返すために必要な形式を設定します。詳細については、 Accept を参照してください。 |
extended パラメーターをクエリー文字列に追加して、追加情報を取得します。
GET /rest/v2/caches/{cacheName}/{cacheKey}?extended上記のリクエストはカスタムヘッダーを返します:
-
Cluster-Primary-Ownerは、キーのプライマリー所有者であるノード名を返します。 -
Cluster-Node-Nameは、要求を処理したサーバーの JGroups ノード名を返します。 -
Cluster-Physical-Addressは、要求を処理したサーバーの物理 JGroups アドレスを返します。
2.1.15. エントリーが存在するかどうかの確認
HEAD リクエストで特定のエントリーが存在することを確認します。
HEAD /rest/v2/caches/{cacheName}/{cacheKey}上記のリクエストは、ヘッダーフィールドと、エントリーとともに保存したものと同じコンテンツのみを返します。たとえば、文字列を保存した場合、リクエストは文字列を返します。バイナリー、base64 エンコード、blob、またはシリアル化された Java オブジェクトを保存した場合、DataGrid はリクエストのコンテンツを逆シリアル化しません。
HEAD リクエストは、extended パラメーターもサポートしています。
表2.6 ヘッダー
| ヘッダー | 必須またはオプション | パラメーター |
|---|---|---|
|
| オプション |
リクエストのキーのコンテンツタイプを設定します。デフォルトは |
2.1.16. エントリーの削除
DELETE リクエストを使用してキャッシュからエントリーを 削除 します。
DELETE /rest/v2/caches/{cacheName}/{cacheKey}表2.7 ヘッダー
| ヘッダー | 必須またはオプション | パラメーター |
|---|---|---|
|
| オプション |
リクエストのキーのコンテンツタイプを設定します。デフォルトは |
2.1.17. キャッシュの削除
DELETE リクエストを使用して Data Grid クラスターからキャッシュを DELETE 削除します。
DELETE /rest/v2/caches/{cacheName}2.1.18. キャッシュからのすべてのキーの取得
GET リクエストを呼び出して、キャッシュ内のすべてのキーを JSON 形式で取得します。
GET /rest/v2/caches/{cacheName}?action=keys表2.8 リクエストパラメーター
| パラメーター | 必須またはオプション | 値 |
|---|---|---|
|
| オプション |
InputStream を使用して取得するキーの最大数を指定します。負の値はすべてのキーを取得します。デフォルト値は |
|
| オプション |
キーを取得するときの内部バッチサイズを指定します。デフォルト値は |
2.1.19. キャッシュからのすべてのエントリーの取得
GET リクエストを呼び出し、キャッシュ内のすべてのエントリーを JSON 形式で取得します。
GET /rest/v2/caches/{cacheName}?action=entries表2.9 リクエストパラメーター
| パラメーター | 必須またはオプション | 値 |
|---|---|---|
|
| オプション |
応答の各エントリーのメタデータが含まれます。デフォルト値は |
|
| オプション |
応答に含めるキーの最大数を指定します。負の値はすべてのキーを取得します。デフォルト値は |
|
| オプション |
キーを取得するときの内部バッチサイズを指定します。デフォルト値は |
|
| オプション |
|
Data Grid は、以下のような JSON レスポンスを提供します。
[
{
"key":1,
"value":"value1",
"timeToLiveSeconds":-1,
"maxIdleTimeSeconds":-1,
"created":-1,
"lastUsed":-1,
"expireTime":-1
},
{
"key":2,
"value":"value2",
"timeToLiveSeconds":10,
"maxIdleTimeSeconds":45,
"created":1607966017944,
"lastUsed": 1607966017944,
"expireTime":1607966027944
}
]-
keyエントリーのキー。 -
valueエントリーの値。 -
timeToLiveSecondsエントリーの有効期間に基づきますが、秒単位です。エントリーが期限切れにならない場合は-1です。metadata = "true"を設定しない限り、返されません。 -
maxIdleTimeSeconds最大アイドル時間 (秒単位)。エントリーが期限切れにならない場合は-1。metadata = "true"を設定しない限り、返されません。 -
作成済みエントリーが
createdされた時刻、または不滅のエントリーの場合は-1。metadata = "true"を設定しない限り、返されません。 -
lastUsedエントリーに対して操作が行われた最後の時刻、または不滅のエントリーでは-1。metadata = "true"を設定しない限り、返されません。 -
expireTimeエントリーが期限切れになる時間、または不死身のエントリーの場合は-1。metadata = "true"を設定しない限り、返されません。
2.1.20. キャッシュのクリア
キャッシュからすべてのデータを削除するには、POST リクエストに ?action=clear パラメーターを付けて実行します。
POST /rest/v2/caches/{cacheName}?action=clear
操作が正常に完了すると、サービスは 204 (No Content) を返します。
2.1.21. キャッシュサイズの取得
GET リクエストと ?action=size パラメーターを使用して、クラスター全体のキャッシュのサイズを取得します。
GET /rest/v2/caches/{cacheName}?action=size2.1.22. キャッシュ統計の取得
GET リクエストを使用してキャッシュの実行時統計を取得します。
GET /rest/v2/caches/{cacheName}?action=stats2.1.23. キャッシュの一覧表示
GET リクエストを使用して、 Data Grid クラスターで使用可能なすべてのキャッシュを一覧表示します。
GET /rest/v2/caches/
2.1.24. キャッシュイベントをリッスンする
Server-Sent Events でキャッシュイベントを受信する。event 値は、cache-entry-created、cache-entry-removed、cache-entry-updated、cache-entry-expired のいずれかになります。data 値には、Accept ヘッダーで設定された形式でイベントを発生させたエントリーのキーが含まれます。
GET /rest/v2/caches/{name}?action=listen表2.10 ヘッダー
| ヘッダー | 必須またはオプション | パラメーター |
|---|---|---|
|
| オプション |
コンテンツを返すために必要な形式を設定します。サポートされている形式は、 |
2.1.25. リバランスの有効化
特定のキャッシュの自動リバランスをオンにします。
POST /rest/v2/caches/{cacheName}?action=enable-rebalancing2.1.26. リバランスの無効化
特定のキャッシュの自動リバランスをオフにします。
POST /rest/v2/caches/{cacheName}?action=disable-rebalancing2.1.27. キャッシュの可用性の取得
キャッシュの可用性を取得します。
GET /rest/v2/caches/{cacheName}?action=get-availability内部キャッシュの可用性を取得できますが、これは将来の Data Grid バージョンで変更される可能性があります。
2.1.28. キャッシュの可用性の設定
DENY_READ_WRITES または ALLOW_READS パーティション処理戦略のいずれかを使用する場合は、クラスター化されたキャッシュの可用性を変更します。
POST /rest/v2/caches/{cacheName}?action=set-availability&availability={AVAILABILITY}表2.11 リクエストパラメーター
| パラメーター | 必須またはオプション | 値 |
|---|---|---|
|
| 必須 | AVAILABLE または DEGRADED_MODE |
-
AVAILABLEは、ネットワークパーティション内のすべてのノードでキャッシュを利用できるようにします。 -
DEGRADED_MODEは、ネットワークパーティションが発生したときにキャッシュの読み取りおよび書き込み操作を防止します。
内部キャッシュの可用性を設定できますが、これは将来の Data Grid バージョンで変更される可能性があります。
2.1.29. RESTAPI を使用したインデックス作成とクエリー
HTTP クライアントから GET リクエストと ?action=search&query パラメーターを使って、リモートキャッシュにクエリーを実行します。
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.12 リクエストパラメーター
| パラメーター | 必須またはオプション | 値 |
|---|---|---|
|
| 必須 | クエリー文字列を指定します。 |
|
| オプション |
返す結果の数を設定します。デフォルトは |
|
| オプション |
返される最初の結果のインデックスを指定します。デフォルトは |
|
| オプション |
|
クエリーパラメーターを指定せずにリクエストの本文を使用するには、以下のように POST リクエストを呼び出します。
POST /rest/v2/caches/{cacheName}?action=searchリクエスト本文のクエリー
{
"query":"from Entity where name:\"user1\"",
"max_results":20,
"offset":10
}
2.1.29.1. インデックスの再構築
フィールドを削除するか、インデックスフィールド定義を変更する場合は、インデックスを再構築して、インデックスがキャッシュ内のデータと一致していることを確認する必要があります。
REST、CLI、Data Grid Console、またはリモートクライアントを使用して Protobuf スキーマを再構築すると、不整合が発生する可能性があります。リモートクライアントには Protostream エンティティーのバージョンが異なる場合があり、信頼性の低い動作が発生する可能性があります。
POST リクエストと ?action=reindex パラメーターを使用して、キャッシュ内のすべてのデータのインデックスを再作成します。
POST /v2/caches/{cacheName}/search/indexes?action=reindex表2.13 リクエストパラメーター
| パラメーター | 必須またはオプション | 値 |
|---|---|---|
|
| オプション |
|
|
| オプション |
|
2.1.29.2. インデックススキーマの更新
インデックススキーマの更新操作を使用すると、最小限のダウンタイムでスキーマの変更を追加できます。Data Grid は、以前にインデックス化されたデータを削除してインデックススキーマを再作成する代わりに、新しいフィールドを既存のスキーマに追加します。
POST リクエストと ?action=updateSchema パラメーターを使用して、キャッシュ内の値のインデックススキーマを更新します。
POST /v2/caches/{cacheName}/search/indexes?action=updateSchema2.1.29.3. インデックスのパージ
POST リクエストと ?action=clear パラメーターを使用して、キャッシュからすべてのインデックスを削除します。
POST /rest/v2/caches/{cacheName}/search/indexes?action=clear
操作が正常に完了すると、サービスは 204 (No Content) を返します。
2.1.29.4. インデックスのメタモデル取得
このキャッシュで定義されたすべてのインデックスの完全なインデックススキーマメタモデルを提示します。
GET /rest/v2/caches/{cacheName}/search/indexes/metamodelData Grid の応答
[{
"entity-name": "org.infinispan.query.test.Book",
"java-class": "org.infinispan.query.test.Book",
"index-name": "org.infinispan.query.test.Book",
"value-fields": {
"description": {
"multi-valued": false,
"multi-valued-in-root": false,
"type": "java.lang.String",
"projection-type": "java.lang.String",
"argument-type": "java.lang.String",
"searchable": true,
"sortable": false,
"projectable": false,
"aggregable": false,
"analyzer": "standard"
},
"name": {
"multi-valued": false,
"multi-valued-in-root": true,
"type": "java.lang.String",
"projection-type": "java.lang.String",
"argument-type": "java.lang.String",
"searchable": true,
"sortable": false,
"projectable": false,
"aggregable": false,
"analyzer": "standard"
},
"surname": {
"multi-valued": false,
"multi-valued-in-root": true,
"type": "java.lang.String",
"projection-type": "java.lang.String",
"argument-type": "java.lang.String",
"searchable": true,
"sortable": false,
"projectable": false,
"aggregable": false
},
"title": {
"multi-valued": false,
"multi-valued-in-root": false,
"type": "java.lang.String",
"projection-type": "java.lang.String",
"argument-type": "java.lang.String",
"searchable": true,
"sortable": false,
"projectable": false,
"aggregable": false
}
},
"object-fields": {
"authors": {
"multi-valued": true,
"multi-valued-in-root": true,
"nested": true,
"value-fields": {
"name": {
"multi-valued": false,
"multi-valued-in-root": true,
"type": "java.lang.String",
"projection-type": "java.lang.String",
"argument-type": "java.lang.String",
"searchable": true,
"sortable": false,
"projectable": false,
"aggregable": false,
"analyzer": "standard"
},
"surname": {
"multi-valued": false,
"multi-valued-in-root": true,
"type": "java.lang.String",
"projection-type": "java.lang.String",
"argument-type": "java.lang.String",
"searchable": true,
"sortable": false,
"projectable": false,
"aggregable": false
}
}
}
}
}, {
"entity-name": "org.infinispan.query.test.Author",
"java-class": "org.infinispan.query.test.Author",
"index-name": "org.infinispan.query.test.Author",
"value-fields": {
"surname": {
"multi-valued": false,
"multi-valued-in-root": false,
"type": "java.lang.String",
"projection-type": "java.lang.String",
"argument-type": "java.lang.String",
"searchable": true,
"sortable": false,
"projectable": false,
"aggregable": false
},
"name": {
"multi-valued": false,
"multi-valued-in-root": false,
"type": "java.lang.String",
"projection-type": "java.lang.String",
"argument-type": "java.lang.String",
"searchable": true,
"sortable": false,
"projectable": false,
"aggregable": false,
"analyzer": "standard"
}
}
}]
2.1.29.5. クエリーおよびインデックス統計の取得
GET 要求を使用して、キャッシュでクエリーとインデックスに関する情報を取得します。
キャッシュ設定で統計を有効にする必要があります。有効にしないと、結果が空になります。
GET /rest/v2/caches/{cacheName}/search/stats表2.14 リクエストパラメーター
| パラメーター | 必須またはオプション | 値 |
|---|---|---|
|
| オプション |
クラスターの全メンバーの連結統計情報を取得するには、 |
Data Grid の応答
{
"query": {
"indexed_local": {
"count": 1,
"average": 12344.2,
"max": 122324,
"slowest": "FROM Entity WHERE field > 4"
},
"indexed_distributed": {
"count": 0,
"average": 0.0,
"max": -1,
"slowest": "FROM Entity WHERE field > 4"
},
"hybrid": {
"count": 0,
"average": 0.0,
"max": -1,
"slowest": "FROM Entity WHERE field > 4 AND desc = 'value'"
},
"non_indexed": {
"count": 0,
"average": 0.0,
"max": -1,
"slowest": "FROM Entity WHERE desc = 'value'"
},
"entity_load": {
"count": 123,
"average": 10.0,
"max": 120
}
},
"index": {
"types": {
"org.infinispan.same.test.Entity": {
"count": 5660001,
"size": 0
},
"org.infinispan.same.test.AnotherEntity": {
"count": 40,
"size": 345560
}
},
"reindexing": false
}
}
のセクション
query
-
indexed_localインデックス付きのクエリーの詳細を提供します。 -
indexed_distributed分散したインデックス付きクエリーの詳細を提供します。 -
hybridインデックスを部分的にしか使用していないクエリーの詳細を提供します。 -
non_indexedインデックスを使用しなかったクエリーの詳細を提供します。 -
entity_loadインデックス付きクエリーの実行後にオブジェクトをフェッチするためのキャッシュ操作に関する詳細を提供します。
時間は常にナノ秒単位で測定されます。
のセクション
index
typesキャッシュに設定されている各インデックスタイプ (クラス名や protobuf メッセージ) の詳細を提供する。-
countそのタイプにインデックスされているエンティティーの数。 -
size型の使用量 (バイト)。
-
-
reindexing値がtrueの場合、Indexerはキャッシュで動作しています。
2.1.29.6. クエリー統計のクリア
POST リクエストと ?action=clear パラメーターを使用して、ランタイムの統計情報をリセットすることができます。
POST /rest/v2/caches/{cacheName}/search/stats?action=clearData Grid は、ローカルノードのクエリー実行時間のみをリセットします。この操作では、インデックス統計はクリアされません。
2.1.29.7. インデックス統計の取得 (非推奨)
GET リクエストでキャッシュ内のインデックスの情報を取得します。
GET /rest/v2/caches/{cacheName}/search/indexes/statsData Grid の応答
{
"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.29.8. クエリー統計の取得 (非推奨)
GET リクエストでキャッシュに実行されたクエリーの情報を取得します。
GET /rest/v2/caches/{cacheName}/search/query/statsData Grid の応答
{
"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.29.9. クエリー統計情報のクリア (非推奨)
POST リクエストと ?action=clear パラメーターを使用して、ランタイムの統計情報をリセットすることができます。
POST /rest/v2/caches/{cacheName}/search/query/stats?action=clear2.1.30. キャッシュを利用したクロスサイト・オペレーション
Data Grid REST API を使用して、クロスサイトレプリケーション操作を行います。
2.1.30.1. すべてのバックアップロケーションのステータス取得
GET リクエストですべてのバックアップロケーションのステータスを取得します。
GET /rest/v2/caches/{cacheName}/x-site/backups/Data Grid は、以下の例のように、各バックアップロケーションのステータスを JSON 形式で応答します。
{
"NYC": {
"status": "online"
},
"LON": {
"status": "mixed",
"online": [
"NodeA"
],
"offline": [
"NodeB"
]
}
}表2.15 リターンステータス
| 値 | 説明 |
|---|---|
|
| ローカルクラスター内のすべてのノードには、バックアップの場所を含むクロスサイトビューがあります。 |
|
| ローカルクラスター内のノードには、バックアップの場所とのクロスサイトビューがありません。 |
|
| ローカルクラスター内の一部のノードにはバックアップの場所を含むクロスサイトビューがあり、ローカルクラスター内の他のノードにはクロスサイトビューがありません。応答は、各ノードのステータスを示します。 |
2.1.30.2. 特定のバックアップの場所のステータスの取得
GET リクエストでバックアップロケーションのステータスを取得する。
GET /rest/v2/caches/{cacheName}/x-site/backups/{siteName}Data Grid は、以下の例のように、サイト内の各ノードのステータスを JSON 形式で応答します。
{
"NodeA":"offline",
"NodeB":"online"
}表2.16 リターンステータス
| 値 | 説明 |
|---|---|
|
| ノードはオンラインです。 |
|
| ノードはオフラインです。 |
|
| ステータスを取得できません。リモートキャッシュがシャットダウンしているか、リクエスト中にネットワークエラーが発生した可能性があります。 |
2.1.30.3. バックアップの場所をオフラインにする
POST リクエストと ?action=take-offline パラメーターを使用して、バックアップの場所をオフラインにします。
POST /rest/v2/caches/{cacheName}/x-site/backups/{siteName}?action=take-offline2.1.30.4. バックアップの場所をオンラインにする
?action=bring-online パラメーターを使用してバックアップ場所をオンラインにします。
POST /rest/v2/caches/{cacheName}/x-site/backups/{siteName}?action=bring-online2.1.30.5. バックアップ場所への状態のプッシュ
?action=start-push-state パラメーターを使用して、キャッシュ状態をバックアップ場所にプッシュします。
POST /rest/v2/caches/{cacheName}/x-site/backups/{siteName}?action=start-push-state2.1.30.6. 状態遷移のキャンセル
?action=cancel-push-state パラメーターを使用して状態転送操作をキャンセルします。
POST /rest/v2/caches/{cacheName}/x-site/backups/{siteName}?action=cancel-push-state2.1.30.7. 状態遷移ステータスの取得
?action=push-state-status パラメーターを使用して状態転送操作のステータスを取得します。
GET /rest/v2/caches/{cacheName}/x-site/backups?action=push-state-statusData Grid は、以下の例のように、各バックアップ拠点の状態移行の状況を JSON 形式で応答します。
{
"NYC":"CANCELED",
"LON":"OK"
}表2.17 リターンステータス
| 値 | 説明 |
|---|---|
|
| バックアップ場所への状態転送が進行中です。 |
|
| 状態の転送が正常に完了しました。 |
|
| 状態転送でエラーが発生しました。ログファイルを確認してください。 |
|
| 状態移行のキャンセルが進行中です。 |
2.1.30.8. 状態遷移ステータスのクリア
?action=clear-push-state-status パラメーターを使用して送信サイトの状態転送ステータスをクリアします。
POST /rest/v2/caches/{cacheName}/x-site/local?action=clear-push-state-status2.1.30.9. オフラインにする条件の変更
特定の条件が満たされると、サイトはオフラインになります。オフラインにするパラメーターを変更して、バックアップロケーションが自動的にオフラインになるタイミングを制御します。
手順
GETリクエストとtake-offline-configパラメーターで設定されたテイクオフラインパラメーターを確認します。GET /rest/v2/caches/{cacheName}/x-site/backups/{siteName}/take-offline-configData Grid のレスポンスには、以下のように
after_failuresとmin_waitフィールドがあります。{ "after_failures": 2, "min_wait": 1000 }PUTリクエストの本文のオフライン取得パラメーターを変更します。PUT /rest/v2/caches/{cacheName}/x-site/backups/{siteName}/take-offline-config操作が正常に完了すると、サービスは
204 (No Content)を返します。
2.1.30.10. 受信サイトからの状態遷移のキャンセル
2 つのバックアップ場所間の接続が切断された場合、プッシュを受信しているサイトでの状態転送をキャンセルできます。
?action=cancel-receive-state パラメーターで、リモートサイトからの状態転送をキャンセルし、ローカルキャッシュの現在の状態を維持する。
POST /rest/v2/caches/{cacheName}/x-site/backups/{siteName}?action=cancel-receive-state2.1.31. ローリングアップグレード
Data Grid クラスター間でキャッシュデータのローリングアップグレードを実行します
2.1.31.1. ソースクラスターの接続
ターゲット・クラスターとソース・クラスターの接続は
POST /rest/v2/caches/{cacheName}/rolling-upgrade/source-connection
本文として JSON 形式の remote-store 定義を提供する必要があります。
JSON
{
"remote-store": {
"cache": "my-cache",
"shared": true,
"raw-values": true,
"socket-timeout": 60000,
"protocol-version": "2.9",
"remote-server": [
{
"host": "127.0.0.2",
"port": 12222
}
],
"connection-pool": {
"max-active": 110,
"exhausted-action": "CREATE_NEW"
},
"async-executor": {
"properties": {
"name": 4
}
},
"security": {
"authentication": {
"server-name": "servername",
"digest": {
"username": "username",
"password": "password",
"realm": "realm",
"sasl-mechanism": "DIGEST-MD5"
}
},
"encryption": {
"protocol": "TLSv1.2",
"sni-hostname": "snihostname",
"keystore": {
"filename": "/path/to/keystore_client.jks",
"password": "secret",
"certificate-password": "secret",
"key-alias": "hotrod",
"type": "JKS"
},
"truststore": {
"filename": "/path/to/gca.jks",
"password": "secret",
"type": "JKS"
}
}
}
}
}
security 、 async-executor 、 connection-pool など、いくつかの要素はオプションです。この設定には、最低限、キャッシュ名、false に設定された raw-values、ソースクラスター内の単一ポートのホスト/IP が含まれていなければなりません。remote-store 設定の詳細については、XSD Schemaを参照してください。
操作が正常に完了した場合、サービスは 204(No Content) を返します。ターゲット・クラスターがソース・クラスターに既に接続されている場合は、ステータス 304(Not Modified) を返します。
2.1.31.2. ソースクラスター接続の詳細の取得
キャッシュの remote-store 定義を取得するには、 GET リクエストを使用します。
GET /rest/v2/caches/{cacheName}/rolling-upgrade/source-connection
キャッシュが以前に接続されていた場合は、関連付けられた remote-store の設定を JSON 形式とステータス 200(OK) で返します。それ以外の場合は、404(見つかりません) ステータスを返します。
これはクラスター全体の操作ではなく、REST の呼び出しが処理されたノードのキャッシュのリモートストアのみを返します。
2.1.31.3. キャッシュが接続されているかどうかの確認
キャッシュがリモートクラスターに接続されているかどうかを確認するには、HEAD リクエストを使用します。
HEAD /rest/v2/caches/{cacheName}/rolling-upgrade/source-connection
クラスターのすべてのノードにおいて、cacheName に 1 つのリモートストアが設定されている場合は 200(OK)、そうでない場合は 404(NOT_FOUND) を返します。
2.1.31.4. データの同期
ソースクラスターからターゲットクラスターへのデータの同期には、POST リクエストと ?action=sync-data パラメーターを使用します。
POST /rest/v2/caches/{cacheName}?action=sync-data操作が完了すると、Data Grid はターゲットクラスターにコピーされたエントリーの合計数で応答します。
2.1.31.5. ソースクラスターの接続
ターゲット・クラスターにデータを同期させた後、DELETE リクエストでソース・クラスターから切断します。
DELETE /rest/v2/caches/{cacheName}/rolling-upgrade/source-connection
操作が正常に完了すると、サービスは 204 (No Content) を返します。ソースが接続されていない場合、コード 304(変更なし) を返します。