1.3. データ形式と RESTAPI
Data Grid キャッシュは、MediaType で定義できる形式でデータを保存します。
MediaTypes と Data Grid を使用したデータのエンコードの詳細については、キャッシュのエンコードとマーシャリング を参照してください。
次の例では、エントリーのストレージ形式を設定します。
<distributed-cache>
<encoding>
<key media-type="application/x-java-object"/>
<value media-type="application/xml; charset=UTF-8"/>
</encoding>
</distributed-cache>
MediaType を設定しない場合、DataGrid はデフォルトでキーと値の両方に対して application/octet-stream になります。しかし、キャッシュがインデックス化されている場合、Data Grid のデフォルトは application/x-protostream です。
1.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-protostream と application/json の間で変換することもできます。
REST API へのすべての呼び出しは、書き込まれたコンテンツまたは読み取るときに必要なコンテンツの形式を説明するヘッダーを提供できます。Data Grid は、値に適用される標準的な HTTP/1.1 ヘッダーの "Content-Type "と "Accept "に加えて、キーに同様の効果を持つ "Key-Content-Type "をサポートしています。
1.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 を試みます (2 番目に高い優先度 0.7)。最後に、Data Grid は*/*にフォールバックし、キャッシュの設定に基づいて適切なフォーマットを選択します。
1.3.3. 特殊文字を含む名前
REST リソースの作成には、URL の一部となる名前が必要です。この名前に RFC 3986 仕様のセクション 2.2 で定義されている特殊文字が含まれている場合には、Percent encoding メカニズムでエンコードする必要があります。
1.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-object の type パラメーターは次のように制限されています。
- Primitive wrapper types
-
java.lang.String -
バイトで、
application/x-java-object;type=Bytesがapplication/octet-stream;encoding=hexと同等になります。
1.3.5. JSON /プロトストリーム変換
キャッシュがインデックス化されている場合や、application/x-protostream を保存するように特別に設定されている場合、Protobuf との間で自動的に変換された JSON ドキュメントを送受信することができます。
変換を機能させるには、Protobuf スキーマを登録する必要があります。
REST 経由で protobuf スキーマを登録するには、次の例のように、POST または PUT を起動して ___protobuf_metadata キャッシュを起動します。
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 Message を識別するための特別なフィールド _type は、ドキュメントに対応する Protobuf Messageを識別するために、ドキュメント内に存在する必要があります。
Person.proto
message Person {
required string name = 1;
required int32 age = 2;
}
Person.json
{
"_type": "Person",
"name": "user1",
"age": 32
}