Data Grid REST API

Red Hat Data Grid 8.1

Data Grid RESTAPIを構成して操作する

概要

データへのアクセス、クラスターの監視と保守、Data Grid RESTAPIを介した管理操作の実行。

第1章 Red Hat Data Grid

Data Grid は、高性能の分散型インメモリデータストアです。

スキーマレスデータ構造
さまざまなオブジェクトをキーと値のペアとして格納する柔軟性があります。
グリッドベースのデータストレージ
クラスター間でデータを分散および複製するように設計されています。
エラスティックスケーリング
サービスを中断することなく、ノードの数を動的に調整して要件を満たします。
データの相互運用性
さまざまなエンドポイントからグリッド内のデータを保存、取得、およびクエリーします。

1.1. Data Grid のドキュメント

Data Grid のドキュメントは、Red Hat カスタマーポータルで入手できます。

1.2. Data Grid のダウンロード

Red Hat カスタマーポータルで Data Grid Software Downloads にアクセスします。

注記

Data Gridソフトウェアにアクセスしてダウンロードするには、Red Hat アカウントが必要です。

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

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。まずは、マスター (master)、スレーブ (slave)、ブラックリスト (blacklist)、ホワイトリスト (whitelist) の 4 つの用語の置き換えから始めます。これは大規模な取り組みであるため、これらの変更は今後の複数のリリースで段階的に実施されます。詳細は、Red Hat CTO である Chris Wright のメッセージ をご覧ください。

第2章 Data Grid RESTエンドポイント

Data Grid サーバーは、Netty上に構築されたRESTエンドポイントを介してデータへのRESTful HTTP アクセスを提供します。

2.1. REST認証

Data Grid コマンドラインインターフェイス(CLI)とuserコマンドを使用して、RESTエンドポイントへの認証を構成します。CLIを使用すると、RESTエンドポイントにアクセスするためのユーザー、パスワード、および承認ロールを作成および管理できます。

2.2. サポートされているプロトコル

Data Grid RESTエンドポイントは、HTTP/1.1およびHTTP/2のプロトコルをサポートしています。

HTTP/2を使用するには、以下のいずれかの方法があります。

注記

JDK8を使用するTLS / ALPNには、追加のクライアント構成が必要です。RESTクライアントの適切なドキュメントを参照してください。ほとんどの場合、Jetty ALPNAgentまたはOpenSSLバインディングのいずれかを使用する必要があります。

2.3. データ形式とRESTAPI

Data Grid キャッシュは、MediaTypeで定義できる形式でデータを保存します。

以下の例では、エントリーのストレージ形式を設定します。

<cache>
   <encoding>
      <key media-type="application/x-java-object"/>
      <value media-type="application/xml; charset=UTF-8"/>
   </encoding>
</cache>

MediaTypeを構成しない場合、DataGridはデフォルトでキーと値の両方に対して application/octet-stream になります。しかし、キャッシュがインデックス化されている場合、Data Gridのデフォルトはapplication/x-protostreamです。

2.3.1. サポート対象の形式

さまざまな形式でデータの書き込みと読み取りを行うことができ、DataGridは必要に応じてそれらの形式間で変換できます。

次の「標準」フォーマットは交換可能です。

  • application/x-java-object
  • application/octet-stream
  • application/x-www-form-urlencoded
  • text/plain

上記のデータ形式を次の形式に変換することもできます。

  • application/xml
  • application/json
  • application/x-jboss-marshalling
  • application/x-protostream
  • application/x-java-serialized

Data Grid を使用すると、application/x-protostreamapplication/json の間で変換することもできます。

REST APIへのすべての呼び出しは、書き込まれたコンテンツまたは読み取るときに必要なコンテンツの形式を説明するヘッダーを提供できます。Data Gridは、値に適用される標準的なHTTP/1.1ヘッダーの "Content-Type "と "Accept "に加えて、キーに同様の効果を持つ "Key-Content-Type "をサポートしています。

2.3.2. ヘッダーを受け入れる

Data Grid RESTエンドポイントは RFC-2616 Acceptヘッダーに準拠しており、サポートされている変換に基づいて正しいMediaTypeをネゴシエートします。

例えば、データ読み込み時に次のようなヘッダーを送信します。

Accept: text/plain;q=0.7, application/json;q=0.8, */*;q=0.6

上記のヘッダーにより、Data Gridは最初にコンテンツをJSON形式(優先度0.8)で返します。ストレージフォーマットを JSON に変換しない場合、Data Grid は次の形式の text/plain を試行します(優先度の一位の 1 番目)。最後に、Data Gridは*/*にフォールバックし、キャッシュの設定に基づいて適切なフォーマットを選択します。

2.3.3. 特殊文字を含む名前

RESTリソースの作成には、URLの一部となる名前が必要です。この名前にRFC 3986仕様のセクション2.2で定義されている特殊文字が含まれている場合には、Percent encodingメカニズムでエンコードする必要があります。

2.3.4. Key-Content-Typeヘッダー

ほとんどのREST APIコールでは、URLにKeyが含まれています。Data Gridは、これらの呼び出しを処理する際に、Keyがjava.lang.Stringであることを前提としていますが、異なるフォーマットのキーに対しては、特定のヘッダーKey-Content-Typeを使用することができます。

Key-Content-Typeヘッダーの例

  • byte[] KeyをBase64文字列で指定する

API呼び出し:

`PUT /my-cache/AQIDBDM=`

ヘッダー:

Key-Content-Type: application/octet-stream

  • byte[] Keyを16進数の文字列で指定する。

API呼び出し:

GET /my-cache/0x01CA03042F

ヘッダー:

Key-Content-Type: application/octet-stream; encoding=hex
  • ダブルキーの指定:

API呼び出し:

POST /my-cache/3.141456

ヘッダー:

Key-Content-Type: application/x-java-object;type=java.lang.Double

application/x-java-objecttype パラメーターは以下に制限されます。

  • Primitive wrapper types
  • java.lang.String
  • bytes, making application/x-java-object;type=Bytes equivalent to application/octet-stream;encoding=hex

2.3.5. JSON /プロトストリーム変換

キャッシュがインデックス化される場合、またはとくに application/x-protostream を保存するように設定されている場合、Protostream に自動的に変換される JSON ドキュメントを送信および受信できます。

変換が機能するには、protobuf スキーマを登録する必要があります。

REST 経由で protobuf スキーマを登録するには、以下の例のように、get fyprotobuf_metadata キャッシュで POST または PUT を呼び出します。

curl -u user:password -X POST --data-binary @./schema.proto http://127.0.0.1:11222/rest/v2/caches/___protobuf_metadata/schema.proto

JSON ドキュメントを記述する際は、ドキュメントに対応する protobuf メッセージ を識別するために、特別なフィールド _type がドキュメントに存在する必要があります。

たとえば、以下のスキーマについて考えてみましょう。

message Person  {
  required string name = 1;
  required int32 age = 2;
}

対応する JSON ドキュメントは以下のとおりです。

{
   "_type": "Person",
   "name": "user1",
   "age": 32
}

2.4. クロスオリジンリソースシェアリング(CORS)リクエスト

Data Grid RESTコネクタは、プリフライトやリクエストの発信元に基づくルールなど、 CORSをサポートします。

以下に、CORSルールを使用したRESTコネクタ構成の例を示します。

<rest-connector name="rest1" socket-binding="rest" cache-container="default">
   <cors-rules>
      <cors-rule name="restrict host1"
                 allow-credentials="false">
         <allowed-origins>http://host1,https://host1</allowed-origins>
         <allowed-methods>GET</allowed-methods>
      </cors-rule>
      <cors-rule name="allow ALL"
                 allow-credentials="true"
                 max-age-seconds="2000">
         <allowed-origins>*</allowed-origins>
         <allowed-methods>GET,OPTIONS,POST,PUT,DELETE</allowed-methods>
         <allowed-headers>Key-Content-Type</allowed-headers>
      </cors-rule>
   </cors-rules>
</rest-connector>

Data Gridは、ブラウザが設定した "Origin "ヘッダに基づいてCORSルールを順次評価します。

前述の例では、オリジンが「http://host1」または「https://host1」のいずれかであれば、ルール「restrict host1」が適用されます。オリジンが異なる場合は、次のルールがテストされます。

"allow ALL"ルールはすべてのオリジンを許可するため、"http://host1" または"https://host1" 以外のオリジンを持つスクリプトは、許可されたメソッドを実行し、提供されたヘッダーを使用することができます。

CORS ルールの設定に関する詳細は、「 Data Grid Server Configuration Schema 」を参照してください。

2.4.1. 一部のオリジンに対してすべてのCORSパーミッションを許可する

VMプロパティのinfinispan.server.rest.cors-allowは、サーバーの起動時に使用して、1つまたは複数のオリジンにすべてのパーミッションを許可することができます。例:

./bin/server.sh -Dinfinispan.server.rest.cors-allow=http://192.168.1.78:11222,http://host.mydomain.com

この方法を使用して指定されたすべてのオリジンは、構成されたルールよりも優先されます。

第3章 Data Grid REST APIとの連携

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

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

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

3.1.1. キャッシュの作成

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

POST /rest/v2/caches/{cacheName}

表3.1 ヘッダー

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

Content-Type

必須

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

Flags

オプション

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

3.1.1.1. XML の設定

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

  • & lt;Infinispan& gt; ルート要素。
  • & lt;cache-container&gt; 定義。

XML 設定の例

<infinispan>
    <cache-container>
        <distributed-cache name="myCache" mode="SYNC">
          <encoding media-type="application/x-protostream"/>
          <memory max-count="1000000" when-full="REMOVE"/>
        </distributed-cache>
    </cache-container>
</infinispan>

3.1.1.2. JSON 設定

JSON 形式の Data Grid の設定:

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

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

JSON 設定の例

{
  "distributed-cache": {
    "name": "myCache",
    "mode": "SYNC",
    "encoding": {
      "media-type": "application/x-protostream"
      },
    "memory": {
      "max-count": 1000000,
      "when-full": "REMOVE"
    }
  }
}

3.1.2. キャッシュの検証

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

HEAD /rest/v2/caches/{cacheName}

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

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

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

3.1.4. キャッシュ構成の取得

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

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

表3.2 ヘッダー

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

Accept

オプション

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

3.1.5. キャッシュ設定の JSON への変換

有効な XML 設定と ?action=toJSON パラメーターで POST リクエストを呼び出します。Data Grid は、設定の同等の JSON 表現で応答します。

POST /rest/v2/caches?action=toJSON

3.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。

3.1.7. エントリーの追加

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

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

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

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

表3.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の値を使用。

3.1.8. エントリの置き換え

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

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

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

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

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

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

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

注記

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

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

表3.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アドレスを返します。

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

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

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

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

注記

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

表3.5 ヘッダー

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

Key-Content-Type

オプション

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

3.1.11. エントリーの削除

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

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

表3.6 ヘッダー

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

Key-Content-Type

オプション

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

3.1.12. キャッシュの削除

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

DELETE /rest/v2/caches/{cacheName}

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

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

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

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

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

batch-size

オプション

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

3.1.14. キャッシュのクリア

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

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

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

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

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

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

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

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

3.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句を使用するとフィールドのサブセットを含めることができます。

表3.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
}

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

POST リクエストおよび ?action=mass-index&mode={mode} パラメーターでキャッシュ内のすべてのデータを再インデックス します。

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

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

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

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

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

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

3.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はキャッシュで起動したことになります。

3.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 実行された最も遅いクエリを提供します。

3.1.22. クエリ統計のクリア

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

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

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

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

GET /rest/v2/caches/

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

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

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

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

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

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

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

表3.9 リターンステータス

説明

online

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

offline

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

mixed

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

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

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

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

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

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

表3.10 リターンステータス

説明

online

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

offline

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

failed

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

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

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

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

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

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

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

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

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

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

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

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

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

3.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"
}

表3.11 リターンステータス

説明

SENDING

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

OK

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

ERROR

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

CANCELLING

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

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

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

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

3.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

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

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

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

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

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

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

3.1.25.1. データの同期

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

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

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

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

データをターゲットクラスターに同期した後に、POST 要求と ?action=disconnect-source パラメーターでソースクラスターから接続を切断します。

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

3.2. カウンターの作成と管理

REST APIを使ってカウンターの作成、削除、修正ができます。

3.2.1. カウンターの作成

ペイロードに設定が含まれるPOSTリクエストでカウンターを作成します。

POST /rest/v2/counters/{counterName}

弱いカウンターの例

{
    "weak-counter":{
        "initial-value":5,
        "storage":"PERSISTENT",
        "concurrency-level":1
    }
}

強力なカウンターの例

{
    "strong-counter":{
        "initial-value":3,
        "storage":"PERSISTENT",
        "upper-bound":5
    }
}

3.2.2. カウンタの削除

DELETEリクエストで特定のカウンターを削除します。

DELETE /rest/v2/counters/{counterName}

3.2.3. カウンター構成の取得

GETリクエストで特定のカウンターの設定を取得します。

GET /rest/v2/counters/{counterName}/config

Data Gridは、JSON形式でカウンタの設定を応答します。

3.2.4. カウンターに値の追加

POST 要求で特定のカウンターに値を追加します。

重要

このメソッドは、プレーンテキスト のコンテンツのみを処理します。

POST /rest/v2/counters/{counterName}

リクエストペイロードが空の場合、カウンターは 1 つずつ増えます。そうでない場合は、ペイロードは署名済みとして解釈され、カウンターに追加されます。

注記

WEAK カウンターは、操作後に応答しません。

STRONG カウンターは、各操作の後に現在の値を返します。

3.2.5. カウンター値の取得

GETリクエストでカウンターの値を取得します。

GET /rest/v2/counters/{counterName}

表3.12 ヘッダー

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

Accept

オプション

コンテンツを返すために必要なフォーマットです。対応フォーマットは、application/jsontext/plainです。ヘッダーが指定されていない場合、JSONが想定されます。

3.2.6. カウンターのリセット

POST 要求なしでカウンターの整数の値を復元し、?action=reset パラメーターを復元します。

POST /rest/v2/counters/{counterName}?action=reset

3.2.7. カウンターのインクリメント

POSTリクエストに?action=incrementパラメータを指定して、カウンターの値を増加させます。

POST /rest/v2/counters/{counterName}?action=increment
注記

WEAK カウンターは、操作後に応答しません。

STRONG カウンターは、各操作の後に現在の値を返します。

3.2.8. カウンターへのデルタの追加

?action=addおよびdeltaパラメータを含むPOSTリクエストで、カウンターに任意の値を追加します。

POST /rest/v2/counters/{counterName}?action=add&delta={delta}
注記

WEAK カウンターは、操作後に応答しません。

STRONG カウンターは、各操作の後に現在の値を返します。

3.2.9. カウンター値のデクリメント

カウンタの値を減少させるには、POSTリクエストと?action=decrementパラメータを使用します。

POST /rest/v2/counters/{counterName}?action=decrement
注記

WEAK カウンターは、操作後に応答しません。

STRONG カウンターは、各操作の後に現在の値を返します。

3.2.10. ストロングカウンターでの compareAndSet オペレーションの実行

GETリクエストとcompareAndSetパラメータを使って、強力なカウンターの値をアトミックに設定します。

POST /rest/v2/counters/{counterName}?action=compareAndSet&expect={expect}&update={update}

Data Gridは、現在の値が{expect}の場合、{update}にアトミックに値を設定します。操作が成功した場合、Data Gridは true.

3.2.11. 強力なカウンターでのcompareAndSwap操作の実行

GETリクエストとcompareAndSwapパラメータで強力なカウンターの値をアトミックに設定します。

POST /rest/v2/counters/{counterName}?action=compareAndSwap&expect={expect}&update={update}

Data Gridは、現在の値が{expect}の場合、{update}にアトミックに値を設定します。操作が成功すると、 Data Grid はペイロードの前の値を返します。

3.2.12. カウンターの一覧表示

GETリクエストでData Gridクラスタのカウンタのリストを取得します。

GET /rest/v2/counters/

3.3. Protobufスキーマの操作

Data Grid REST APIを利用して、Protobufスキーマ.protoを作成・管理することができます。

3.3.1. Protobufスキーマの作成

ペイロードにprotobufファイルのコンテンツを含むPOSTリクエストで、Data Gridクラスタ全体にProtobufスキーマを作成します。

POST /rest/v2/schemas/{schemaName}

スキーマがすでに存在する場合、Data Grid は CONFLICT を返します。構文エラーのため、またはその依存関係の一部が欠落しているためにスキーマが有効でない場合、Data Gridはスキーマを格納し、応答本文にエラーを返します。

Data Grid は、スキーマ名とエラーで応答します。

{
  "name" : "users.proto",
  "error" : {
    "message": "Schema users.proto has errors",
    "cause": "java.lang.IllegalStateException:Syntax error in error.proto at 3:8: unexpected label: messoge"
  }
}
  • nameはProtobufスキーマの名前です。
  • errorは、有効なProtobufスキーマではnullです。Data Gridがスキーマを正常に検証できない場合、エラーを返します。

3.3.2. Protobufスキーマの読み取り

GETリクエストでData GridからProtobufスキーマを取得します。

GET /rest/v2/schemas/{schemaName}

3.3.3. Protobufスキーマの更新

ペイロードにprotobufファイルのコンテンツを含むPUTリクエストでProtobufスキーマを変更する。

PUT /rest/v2/schemas/{schemaName}

構文エラーのため、またはその依存関係の一部が欠落しているためにスキーマが有効でない場合、Data Gridはスキーマを更新し、応答本文にエラーを返します。

{
  "name" : "users.proto",
  "error" : {
    "message": "Schema users.proto has errors",
    "cause": "java.lang.IllegalStateException:Syntax error in error.proto at 3:8: unexpected label: messoge"
  }
}
  • nameはProtobufスキーマの名前です。
  • errorは、有効なProtobufスキーマではnullです。Data Gridがスキーマを正常に検証できない場合、エラーを返します。

3.3.4. Protobufスキーマの削除

DELETEリクエストでData GridクラスタからProtobufスキーマを削除します。

DELETE /rest/v2/schemas/{schemaName}

3.3.5. Protobufスキーマの一覧表示

GETリクエストで利用可能なすべてのProtobufスキーマをリストアップします。

GET /rest/v2/schemas/

Data Grid は、クラスターで使用可能なすべてのスキーマのリストで応答します。

[ {
  "name" : "users.proto",
  "error" : {
    "message": "Schema users.proto has errors",
    "cause": "java.lang.IllegalStateException:Syntax error in error.proto at 3:8: unexpected label: messoge"
  }
}, {
  "name" : "people.proto",
  "error" : null
}]
  • nameはProtobufスキーマの名前です。
  • errorは、有効なProtobufスキーマではnullです。Data Gridがスキーマを正常に検証できない場合、エラーを返します。

3.4. キャッシュマネージャーの操作

Data Grid キャッシュマネージャーと対話して、クラスターと使用状況の統計を取得します。

3.4.1. 基本的なキャッシュマネージャー情報の取得

GETリクエストでCache Managerの情報を取得します。

GET /rest/v2/cache-managers/{cacheManagerName}

Data Grid は、次の例のように、JSON形式の情報で応答します。

{
    "version":"xx.x.x-FINAL",
    "name":"default",
    "coordinator":true,
    "cache_configuration_names":[
        "___protobuf_metadata",
        "cache2",
        "CacheManagerResourceTest",
        "cache1"
    ],
    "cluster_name":"ISPN",
    "physical_addresses":"[127.0.0.1:35770]",
    "coordinator_address":"CacheManagerResourceTest-NodeA-49696",
    "cache_manager_status":"RUNNING",
    "created_cache_count":"3",
    "running_cache_count":"3",
    "node_address":"CacheManagerResourceTest-NodeA-49696",
    "cluster_members":[
        "CacheManagerResourceTest-NodeA-49696",
        "CacheManagerResourceTest-NodeB-28120"
    ],
    "cluster_members_physical_addresses":[
        "127.0.0.1:35770",
        "127.0.0.1:60031"
    ],
    "cluster_size":2,
    "defined_caches":[
        {
            "name":"CacheManagerResourceTest",
            "started":true
        },
        {
            "name":"cache1",
            "started":true
        },
        {
            "name":"___protobuf_metadata",
            "started":true
        },
        {
            "name":"cache2",
            "started":true
        }
    ]

}
  • versionは、 Data Grid バージョンが含まれています
  • nameには、コンフィギュレーションで定義されたキャッシュマネージャーの名前が含まれます。
  • coordinatorは、キャッシュ・マネージャーがクラスターのコーディネーターである場合には真となります。
  • cache_configuration_namesには、キャッシュマネージャーで定義されたすべてのキャッシュ構成の配列が含まれます
  • cluster_nameには、設定で定義されたクラスタの名前が含まれます。
  • physical_addressesは、キャッシュマネージャーに関連する物理ネットワークアドレスを含みます。
  • coordinator_addressには、クラスターのコーディネーターの物理ネットワークアドレスが含まれます
  • cache_manager_statusキャッシュマネージャーのライフサイクルの状態です。可能な値については、 org.infinispan.lifecycle.ComponentStatus ドキュメントを確認してください
  • created_cache_count作成されたキャッシュの数、すべての内部およびプライベートキャッシュを除く
  • running_cache_count実行中の作成されたキャッシュの数
  • node_addressには、キャッシュマネージャーの論理アドレスが含まれます
  • cluster_membersおよびcluster_members_physical_addressesは、クラスターのメンバーの論理アドレスと物理アドレスの配列です。
  • cluster_sizeクラスター内のメンバーの数
  • defined_cachesキャッシュマネージャーで定義されているすべてのキャッシュのリスト。プライベートキャッシュは除きますが、アクセス可能な内部キャッシュは含まれます。

3.4.2. クラスターヘルスの取得

GETリクエストを使用して Data Grid クラスターのヘルス情報を取得します。

GET /rest/v2/cache-managers/{cacheManagerName}/health

Data Grid は、次の例のように、JSON形式のクラスターヘルス情報で応答します。

{
    "cluster_health":{
        "cluster_name":"ISPN",
        "health_status":"HEALTHY",
        "number_of_nodes":2,
        "node_names":[
            "NodeA-36229",
            "NodeB-28703"
        ]
    },
    "cache_health":[
        {
            "status":"HEALTHY",
            "cache_name":"___protobuf_metadata"
        },
        {
            "status":"HEALTHY",
            "cache_name":"cache2"
        },
        {
            "status":"HEALTHY",
            "cache_name":"mycache"
        },
        {
            "status":"HEALTHY",
            "cache_name":"cache1"
        }
    ]

}
  • cluster_healthには、クラスターのヘルスが含まれます

    • cluster_nameは、構成で定義されているクラスターの名前を指定します。
    • health_statusは、次のいずれかを提供します。

      • DEGRADEDは、キャッシュの少なくとも1つが劣化モードにあることを示します。
      • HEALTHY_REBALANCINGは、少なくとも1つのキャッシュがリバランス状態にあることを示します。
      • HEALTHYは、クラスター内のすべてのキャッシュインスタンスが期待どおりに動作していることを示します。
      • FAILEDは、指定された構成でキャッシュを開始できなかったことを示します。
    • number_of_nodesは、クラスターメンバーの総数を表示します。非クラスター化(スタンドアロン)サーバーの場合は値0を返します。
    • node_namesは、すべてのクラスターメンバーの配列です。スタンドアロンサーバーの場合は空です。
  • cache_healthには、キャッシュごとのヘルス情報が含まれています

    • status はHEALTHY、DEGRADED、HEALTHY_REBALANCING または FAILEDです。
    • cache_name構成で定義されているキャッシュの名前。

3.4.3. キャッシュマネージャーのヘルスステータスの取得

認証を必要としないGETリクエストを使用してキャッシュマネージャーのヘルスステータスを取得します。

GET /rest/v2/cache-managers/{cacheManagerName}/health/status

Data Gridは以下のいずれかをtext/plain形式で応答します。

  • HEALTHY
  • HEALTHY_REBALANCING
  • DEGRADED
  • FAILED

3.4.4. RESTエンドポイントの可用性の確認

HEADリクエストを使用して Data Grid サーバーのRESTエンドポイントの可用性を確認します。

HEAD /rest/v2/cache-managers/{cacheManagerName}/health

正常な応答コードを受信した場合、Data Grid RESTサーバーが実行され、要求を処理しています。

3.4.5. キャッシュマネージャーのグローバル構成の取得

GET要求を使用してキャッシュマネージャーのグローバル構成を取得します。

GET /rest/v2/cache-managers/{cacheManagerName}/config

表3.13 ヘッダー

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

Accept

オプション

コンテンツを返すために必要なフォーマットです。対応フォーマットは、application/jsonapplication/xmlです。ヘッダーが指定されていない場合、JSONが想定されます。

3.4.6. すべてのキャッシュの構成を取得する

GETリクエストを使用してすべてのキャッシュの構成を取得します。

GET /rest/v2/cache-managers/{cacheManagerName}/cache-configs

Data Gridは、以下の例のように、各キャッシュとキャッシュ構成を含むJSON配列で応答します。

[
  {
      "name":"cache1",
      "configuration":{
          "distributed-cache":{
              "mode":"SYNC",
              "partition-handling":{
                  "when-split":"DENY_READ_WRITES"
              },
              "statistics":true
          }
      }
  },
  {
      "name":"cache2",
      "configuration":{
          "distributed-cache":{
              "mode":"SYNC",
              "transaction":{
                  "mode":"NONE"
              }
          }
      }
  }
]

3.4.7. 利用可能なキャッシュテンプレートの一覧表示

GETリクエストで、利用可能なすべてのData Gridキャッシュテンプレートを取得します。

GET /rest/v2/cache-managers/{cacheManagerName}/cache-configs/templates
ヒント

3.4.8. (実験的)キャッシュの状態および情報の取得

Cache Manager で利用可能なすべてのキャッシュのリストを、キャッシュ・ステータスおよび詳細とともに、GET要求で取得します。

GET /rest/v2/cache-managers/{cacheManagerName}/caches

Data Grid は、次の例のように、使用可能な各キャッシュを一覧表示して説明するJSON配列で応答します。

[ {
  "status" : "RUNNING",
  "name" : "cache1",
  "type" : "local-cache",
  "simple_cache" : false,
  "transactional" : false,
  "persistent" : false,
  "bounded": false,
  "secured": false,
  "indexed": true,
  "has_remote_backup": true,
  "health":"HEALTHY"
}, {
  "status" : "RUNNING",
  "name" : "cache2",
  "type" : "distributed-cache",
  "simple_cache" : false,
  "transactional" : true,
  "persistent" : false,
  "bounded": false,
  "secured": false,
  "indexed": true,
  "has_remote_backup": true,
  "health":"HEALTHY"
}]

3.4.9. キャッシュマネージャー統計の取得

GETリクエストを使用してキャッシュマネージャーの統計を取得します。

GET /rest/v2/cache-managers/{cacheManagerName}/stats

Data Grid は、次の例のように、JSON形式のキャッシュマネージャー統計で応答します。

{
    "statistics_enabled":true,
    "read_write_ratio":0.0,
    "time_since_start":1,
    "time_since_reset":1,
    "number_of_entries":0,
    "total_number_of_entries":0,
    "off_heap_memory_used":0,
    "data_memory_used":0,
    "misses":0,
    "remove_hits":0,
    "remove_misses":0,
    "evictions":0,
    "average_read_time":0,
    "average_read_time_nanos":0,
    "average_write_time":0,
    "average_write_time_nanos":0,
    "average_remove_time":0,
    "average_remove_time_nanos":0,
    "required_minimum_number_of_nodes":1,
    "hits":0,
    "stores":0,
    "current_number_of_entries_in_memory":0,
    "hit_ratio":0.0,
    "retrievals":0
}
  • statistics_enabledは、Cache Manager で統計情報の収集が有効になっている場合にtrue になります。
  • read_write_ratioは、すべてのキャッシュにわたる読み取り/書き込み比率を表示します。
  • time_since_startは、キャッシュマネージャーが開始されてからの時間を秒単位で示します。
  • time_since_resetは、キャッシュマネージャーの統計が最後にリセットされてからの秒数を示します。
  • number_of_entriesは、キャッシュマネージャーから現在すべてのキャッシュにあるエントリの総数を示します。この統計は、ローカルキャッシュインスタンスのエントリのみを返します。
  • total_number_of_entriesは、キャッシュマネージャーのすべてのキャッシュで実行されたストア操作の数を示します。
  • off_heap_memory_usedは、このキャッシュコンテナが使用しているオフヒープメモリの量をbytes[]単位で示します。
  • data_memory_usedは、現在の退避アルゴリズムが全キャッシュのデータに使用されていると推定している量をbytes[]単位で示します。エヴィクションが有効になっていない場合は0を返します。
  • missesは、すべてのキャッシュにおけるget()のミスの数を示しています。
  • remove_hitsは、すべてのキャッシュにわたる削除ヒットの数を示します。
  • remove_missesは、すべてのキャッシュにわたる削除ミスの数を示します。
  • evictionsは、すべてのキャッシュにおける エヴィクション の数を示しています。
  • average_read_timeは、すべてのキャッシュでget()操作にかかったミリ秒数の平均値を示します。
  • average_read_time_nanosaverage_read_timeと同じですが、単位はナノ秒です。
  • average_remove_timeは、すべてのキャッシュにおけるremove()操作の平均ミリ秒数を示します。
  • average_remove_time_nanosaverage_remove_timeと同じですが、単位はナノ秒です。
  • required_minimum_number_of_nodesは、データの一貫性を保証するために必要な最小のノード数を示します。
  • hitsは、すべてのキャッシュにおけるget()のヒット数を示します。
  • storesは、すべてのキャッシュにおけるput()操作の回数を提供します。
  • current_number_of_entries_in_memoryは、パッシベーションされたエントリを除く、現在すべてのキャッシュにあるエントリの総数を示します。
  • hit_ratioは、すべてのキャッシュの合計ヒット率/(ヒット+ミス)比率を提供します。
  • retrievalsは、get()操作の総数を示しています。

3.4.10. キャッシュ・マネージャーによるクロスサイト操作

Cache Managers でクロスサイト操作を行うと、すべてのキャッシュに操作が適用されます。

3.4.10.1. バックアップ場所のステータスの取得

GET要求により、キャッシュ・マネージャからすべてのバックアップ・ロケーションのステータスを取得します。

GET /rest/v2/cache-managers/{cacheManagerName}/x-site/backups/

Data Gridは、以下の例のようにJSON形式でステータスを応答します。

{
   "SFO-3":{
      "status":"online"
   },
   "NYC-2":{
      "status":"mixed",
      "online":[
         "CACHE_1"
      ],
      "offline":[
         "CACHE_2"
      ]
   }
}

表3.14 リターンステータス

説明

online

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

offline

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

mixed

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

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

?action=take-offlineパラメータで、バックアップロケーションをオフラインにします。

POST /rest/v2/cache-managers/{cacheManagerName}/x-site/backups/{siteName}?action=take-offline

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

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

POST /rest/v2/cache-managers/{cacheManagerName}/x-site/backups/{siteName}?action=bring-online

3.4.10.4. 状態転送の開始

?action=start-push-stateパラメーターを使用して、すべてのキャッシュの状態をリモートサイトにプッシュします。

POST /rest/v2/cache-managers/{cacheManagerName}/x-site/backups/{siteName}?action=start-push-state

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

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

POST /rest/v2/cache-managers/{cacheManagerName}/x-site/backups/{siteName}?action=cancel-push-state

3.5. Data Grid サーバーの操作

Data Grid サーバーインスタンスを監視および管理します。

3.5.1. 基本的なサーバー情報の取得

GETリクエストを使用して Data Grid サーバーに関する基本情報を表示します。

GET /rest/v2/server

Data Gridは、次の例のように、サーバー名、コードネーム、およびバージョンをJSON形式で応答します。

{
  "version":"Infinispan 'Codename' xx.x.x.Final"
}

3.5.2. キャッシュマネージャーの取得

GETリクエストでData Gridサーバのキャッシュマネージャのリストを取得します。

GET /rest/v2/server/cache-managers

Data Grid は、サーバー用に構成されたキャッシュマネージャー名の配列で応答します。

3.5.3. 無視リストへのキャッシュの追加

特定のキャッシュをクライアントの要求から一時的に除外するようにData Gridを設定します。キャッシュマネージャー名とキャッシュの名前を含むPOSTリクエストを送信します。

POST /v2/server/ignored-caches/{cache-manager}/{cache}

Data Grid は、REST クライアント要求のサービス利用不可ステータス(503)を、Hotgitops クライアントリクエストの Server Error(code 0x85)を返します。

注記

Data Grid は現在、サーバーごとに1つのキャッシュマネージャーのみをサポートしています。将来の互換性のために、リクエストでキャッシュマネージャー名を指定する必要があります。

3.5.4. 無視リストからのキャッシュの削除

DELETEリクエストでキャッシュを無視リストから削除します。

DELETE /v2/server/ignored-caches/{cache-manager}/{cache}

3.5.5. 無視されたキャッシュの確認

GETリクエストでキャッシュが無視されることを確認します。

GET /v2/server/ignored-caches/{cache-manager}

3.5.6. サーバー構成の取得

GETリクエストでData Gridサーバの設定を取得します。

GET /rest/v2/server/config

Data Gridは、以下のようにJSON形式で設定を応答します。

{
    "server":{
        "interfaces":{
            "interface":{
                "name":"public",
                "inet-address":{
                    "value":"127.0.0.1"
                }
            }
        },
        "socket-bindings":{
            "port-offset":0,
            "default-interface":"public",
            "socket-binding":[
                {
                    "name":"memcached",
                    "port":11221,
                    "interface":"memcached"
                }
            ]
        },
        "security":{
            "security-realms":{
                "security-realm":{
                    "name":"default"
                }
            }
        },
        "endpoints":{
            "socket-binding":"default",
            "security-realm":"default",
            "hotrod-connector":{
                "name":"hotrod"
            },
            "rest-connector":{
                "name":"rest"
            }
        }
    }
}

3.5.7. 環境変数の取得

GETリクエストでData Gridサーバのすべての環境変数を取得します。

GET /rest/v2/server/env

3.5.8. JVMメモリの詳細の取得

GETリクエストでData GridサーバのJVMメモリ使用量情報を取得します。

GET /rest/v2/server/memory

Data Gridは、ヒープと非ヒープのメモリ統計、直接のメモリ使用量、メモリプールとガベージコレクションに関する情報をJSON形式で応答します。

3.5.9. JVMスレッドダンプの取得

GETリクエストで、JVMの現在のスレッドダンプを取得します。

GET /rest/v2/server/threads

Data Gridは現在のスレッドダンプをtext/plain形式で応答します。

3.5.10. Data Grid Server の診断レポートの取得

GETリクエストでData Gridサーバの集約されたレポートを取得します。

GET /rest/v2/server/report

Data Gridは、Data Gridサーバーとホストの両方に関する診断情報を含む集約されたレポートを含むtar.gzアーカイブで応答します。レポートは、設定ファイルやログファイルに加えて、CPU、メモリー、オープンファイル、ネットワークソケットとルーティング、スレッドに関する詳細を提供します。

3.5.11. Data Grid サーバーの停止

POSTリクエストでData Gridサーバを停止する。

POST /rest/v2/server?action=stop

Data Grid は 200(OK) で応答し、実行を停止します。

3.6. Data Grid クラスターの操作

Data Grid クラスターの管理タスクを監視および実行します。

3.6.1. Data Grid クラスターの停止

POST要求を使用して Data Grid クラスター全体をシャットダウンします。

POST /rest/v2/cluster?action=stop

Data Grid は 200(OK) で応答し、クラスター全体を順番にシャットダウンします。

3.6.2. クラスター内の特定の Data Grid サーバーの停止

GETリクエストに?action=stop&serverパラメータを指定して、Data Gridクラスタ内の1つまたは複数の特定のサーバをシャットダウンすることができます。

POST /rest/v2/cluster?action=stop&server={server1_host}&server={server2_host}

Data Grid は 200(OK) で応答します。

3.7. Data Grid サーバーのログ構成

実行時に Data Grid クラスターのログ構成を表示および変更します。

3.7.1. ロギングアペンダーの一覧表示

GETリクエストで構成されたすべてのアペンダーのリストを表示します。

GET /rest/v2/logging/appenders

Data Grid は、次の例のように、JSON形式のアペンダーのリストで応答します。

{
  "STDOUT" : {
    "name" : "STDOUT"
  },
  "JSON-FILE" : {
    "name" : "JSON-FILE"
  },
  "HR-ACCESS-FILE" : {
    "name" : "HR-ACCESS-FILE"
  },
  "FILE" : {
    "name" : "FILE"
  },
  "REST-ACCESS-FILE" : {
    "name" : "REST-ACCESS-FILE"
  }
}

3.7.2. ロガーの一覧表示

GETリクエストで構成されたすべてのロガーのリストを表示します。

GET /rest/v2/logging/loggers

Data Grid は、次の例のように、JSON形式のロガーのリストで応答します。

[ {
  "name" : "",
  "level" : "INFO",
  "appenders" : [ "STDOUT", "FILE" ]
}, {
  "name" : "org.infinispan.HOTROD_ACCESS_LOG",
  "level" : "INFO",
  "appenders" : [ "HR-ACCESS-FILE" ]
}, {
  "name" : "com.arjuna",
  "level" : "WARN",
  "appenders" : [ ]
}, {
  "name" : "org.infinispan.REST_ACCESS_LOG",
  "level" : "INFO",
  "appenders" : [ "REST-ACCESS-FILE" ]
} ]

3.7.3. ロガーの作成/変更

新しいロガーを作成するか、 PUTリクエストで既存のロガーを変更します。

PUT /rest/v2/logging/loggers/{loggerName}?level={level}&appender={appender}&appender={appender}...

Data Gridは、{loggerName}で識別されるロガーのレベルを{level}に設定します。オプションで、ロガーに1つ以上のアペンダーを設定できます。アペンダーが指定されていない場合は、ルートロガーで指定されたアペンダーが使用されます。

3.7.4. ロガーの削除

DELETEリクエストで既存のロガーを削除します。

DELETE /rest/v2/logging/loggers/{loggerName}

Data Grid は、{loggerName}で識別されるロガーを削除し、rootロガー設定の使用に効果的に戻します。

3.8. サーバータスクの使用

Data Grid サーバータスクを取得、実行、およびアップロードします。

3.8.1. サーバータスク情報の取得

GETリクエストで利用可能なサーバータスクに関する情報を表示します。

GET /rest/v2/tasks

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

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

type

オプション

user: 内部(管理者)のタスクを結果から除外します。

Data Grid は、利用可能なタスクのリストで応答します。リストには、次の例のように、タスクの名前、タスクを処理するエンジン、タスクの名前付きパラメーター、タスクの実行モード(ONE_NODEまたはALL_NODES)、許可されるセキュリティロールがJSON形式で記載されています。

[
  {
    "name": "SimpleTask",
    "type": "TaskEngine",
    "parameters": [
      "p1",
      "p2"
    ],
    "execution_mode": "ONE_NODE",
    "allowed_role": null
  },
  {
    "name": "RunOnAllNodesTask",
    "type": "TaskEngine",
    "parameters": [
      "p1"
    ],
    "execution_mode": "ALL_NODES",
    "allowed_role": null
  },
  {
    "name": "SecurityAwareTask",
    "type": "TaskEngine",
    "parameters": [],
    "execution_mode": "ONE_NODE",
    "allowed_role": "MyRole"
  }
]

3.8.2. タスクの実行

タスク名と、param のプレフィックスが付けられた必須パラメーターを含む GET リクエストでタスクを実行します。

GET /rest/v2/tasks/myTask?action=exec&param.p1=v1&param.p2=v2

Data Grid はタスクの結果で応答します。

3.8.3. スクリプトタスクのアップロード

PUTまたはPOSTリクエストでスクリプトタスクをアップロードします。

リクエストのコンテンツペイロードとしてスクリプトを提供します。Data Gridがスクリプトをアップロードした後、GETリクエストでスクリプトを実行することができます。

POST /rest/v2/tasks/taskName