第2章 Data Grid REST API との連携

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

POST /rest/v2/caches/{cacheName}

<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"/>
  </indexing>
  <partition-handling when-split="ALLOW_READ_WRITES"
                      merge-policy="PREFERRED_NON_NULL"/>
  <persistence passivation="false">
    <!-- Persistent storage configuration. -->
  </persistence>
</distributed-cache>

{
  "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"
      }
    },
    "partition-handling" : {
      "when-split" : "ALLOW_READ_WRITES",
      "merge-policy" : "PREFERRED_NON_NULL"
    },
    "persistence" : {
      "passivation" : false
    }
  }
}

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"
  partitionHandling:
    whenSplit: "ALLOW_READ_WRITES"
    mergePolicy: "PREFERRED_NON_NULL"
  persistence:
    passivation: "false"
    # Persistent storage configuration.

<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"/>
  </indexing>
  <partition-handling when-split="ALLOW_READ_WRITES"
                      merge-policy="PREFERRED_NON_NULL"/>
  <persistence passivation="false">
    <!-- Persistent storage configuration. -->
  </persistence>
</replicated-cache>

{
  "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"
      }
    },
    "partition-handling" : {
      "when-split" : "ALLOW_READ_WRITES",
      "merge-policy" : "PREFERRED_NON_NULL"
    },
    "persistence" : {
      "passivation" : false
    }
  }
}

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"
  partitionHandling:
    whenSplit: "ALLOW_READ_WRITES"
    mergePolicy: "PREFERRED_NON_NULL"
  persistence:
    passivation: "false"
    # Persistent storage configuration.

<infinispan
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="urn:infinispan:config:13.0 https://infinispan.org/schemas/infinispan-config-13.0.xsd
                          urn:infinispan:server:13.0 https://infinispan.org/schemas/infinispan-server-13.0.xsd"
      xmlns="urn:infinispan:config:13.0"
      xmlns:server="urn:infinispan:server:13.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>

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"

{
  "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"
            }
          }
        }
      }
    }
  }
}

ペイロードに XML または JSON 設定を含む PUT リクエストを使用して、Data Grid クラスター全体のキャッシュ設定の属性を変更します。

PUT /rest/v2/caches/{cacheName}

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

HEAD /rest/v2/caches/{cacheName}

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

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

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

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

有効な設定と ?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>'

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,
  "rebalancing_enabled": true,
  "bounded": false,
  "indexed": false,
  "persistent": false,
  "transactional": false,
  "secured": false,
  "has_remote_backup": false,
  "indexing_in_progress": false,
  "statistics": false
}

GET 要求を呼び出して、Data Grid キャッシュのすべての可変キャッシュ設定属性を取得します。

GET /rest/v2/caches/{name}?action=get-mutable-attributes

Data 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 プロパティーには、可能な値のセットが含まれます。

変更可能なキャッシュ設定属性を変更するために、POST リクエストを呼び出します。

POST /rest/v2/caches/{name}?action=set-mutable-attributes&attribute-name={attributeName}&attribute-value={attributeValue}

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

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

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

エントリーが正常に作成されると、サービスは 204 (No Content) を返します。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

DELETE /rest/v2/caches/{cacheName}

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

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

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

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

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
    }
]

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

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

操作が正常に完了すると、サービスは 204 (No Content) を返します。

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

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

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

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

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

GET /rest/v2/caches/

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

特定のキャッシュの自動リバランスをオンにします。

POST /rest/v2/caches/{cacheName}?action=enable-rebalancing

特定のキャッシュの自動リバランスをオフにします。

POST /rest/v2/caches/{cacheName}?action=disable-rebalancing

キャッシュの可用性を取得します。

GET /rest/v2/caches/{cacheName}?action=get-availability

DENY_READ_WRITES または ALLOW_READS パーティション処理戦略のいずれかを使用する場合は、クラスター化されたキャッシュの可用性を変更します。

POST /rest/v2/caches/{cacheName}?action=set-availability&availability={AVAILABILITY}

HTTP クライアントから GET リクエストと ?action=search&query パラメーターを使用して、リモートキャッシュにクエリーを実行します。

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

{
  "total_results" : 150,
  "hits" : [ {
    "hit" : {
      "name" : "user1",
      "age" : 35
    }
  }, {
    "hit" : {
       "name" : "user2",
       "age" : 42
    }
  }, {
    "hit" : {
       "name" : "user3",
       "age" : 12
    }
  } ]
}

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

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

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

POST  /v2/caches/{cacheName}/search/indexes?action=mass-index

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

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

{
  "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
  }
}

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

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

{
    "indexed_class_names": ["org.infinispan.sample.User"],
    "indexed_entities_count": {
        "org.infinispan.sample.User": 4
    },
    "index_sizes": {
        "cacheName_protobuf": 14551
    },
    "reindexing": false
}

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

{
    "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"
}

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

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

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

{
  "NYC": {
    "status": "online"
  },
  "LON": {
    "status": "mixed",
    "online": [
      "NodeA"
    ],
    "offline": [
      "NodeB"
    ]
  }
}

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

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

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

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

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

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

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

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

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

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

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

POST /rest/v2/caches/{cacheName}/rolling-upgrade/source-connection

{
  "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"
        }
      }
    }
  }
}

GET /rest/v2/caches/{cacheName}/rolling-upgrade/source-connection

HEAD /rest/v2/caches/{cacheName}/rolling-upgrade/source-connection

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

DELETE /rest/v2/caches/{cacheName}/rolling-upgrade/source-connection