8.3. さまざまなクライアントシリアライザー/デシリアライザータイプの設定方法

このトピックでは、Apache Avro の Kafka クライアントシリアライザーおよびデシリアライザー (SerDes) クラスを使用する方法を説明します。

Service Registry は、Avro 用に次の Kafka クライアント SerDes クラスを提供します。

props.putIfAbsent(SerdeConfig.ENABLE_HEADERS, "true")

プロパティー名は apicurio.registry.headers.enabled です。

Service Registry はスキーマ ID を long として表しますが、従来の理由、または他のレジストリーまたは SerDe クラスとの互換性のため、ID の送信時に 4 バイトの使用が推奨される場合があります。

Service Registry AvroDatumProvider は、使用されるタイプの抽象概念であり、DefaultAvroDatumProvider がデフォルトで使用されます。

以下の設定オプションを設定できます。

apicurio.registry.avro.encoding プロパティーを JSON または BINARY の値で設定することにより、Avro エンコーディングを設定できます。デフォルトは BINARY です。

これらの設定オプションは、シリアライザーセクションを参照してください。プロパティー名と値は同じです。

デシリアライザークラスは、メッセージからこれらのオプションの値を判断できます。シリアライザーはメッセージの一部として ID を送信するため、ストラテジーは必要ありません。

ID の位置は、メッセージペイロードの先頭にあるマジックバイトを確認することで決定されます。そのバイトが見つかると、設定されたハンドラーを使用してメッセージペイロードから ID が読み取られます。マジックバイトが見つからない場合、ID はメッセージヘッダーから読み込まれます。

{
  "namespace": "com.kubetrade.schema.trade",
  "type": "record",
  "name": "TradeKey",
  "fields": [
    {
      "name": "exchange",
      "type": "com.kubetrade.schema.common.Exchange"
    },
    {
      "name": "key",
      "type": "string"
    }
  ]
}

{
  "namespace": "com.kubetrade.schema.common",
  "type": "enum",
  "name": "Exchange",
  "symbols" : ["GEMINI"]
}

これらのスキーマを Avro SerDes で使用すると、Service Registry に、TradeKey スキーマ用と、Exchange スキーマ用の 2 つのアーティファクトが作成されます。TradeKey スキーマを使用するメッセージがシリアライズまたはデシリアライズされるたびに、両方のスキーマが取得されるため、定義を異なるファイルに分割できます。

このトピックでは、JSON スキーマの Kafka クライアントシリアライザーおよびデシリアライザー (SerDes) クラスを使用する方法を説明します。

Service Registry は、JSON スキーマ用に次の Kafka クライアント SerDes クラスを提供します。

Apache Avro とは異なり、JSON スキーマはシリアライズテクノロジーではなく、検証テクノロジーです。その結果、JSON スキーマの設定オプションは大きく異なります。たとえば、データは常に JSON としてエンコードされるため、エンコーディングオプションはありません。

唯一の標準以外の設定プロパティーは、デフォルトで有効になっている JSON スキーマバリデーションです。これを無効にするには、apicurio.registry.serde.validation-enabled を "false" に設定します。以下に例を示します。

props.putIfAbsent(SerdeConfig.VALIDATION_ENABLED, Boolean.FALSE)

スキーマをロードできるように、Service Registry の場所を指定する必要があります。他の設定はオプションです。

スキーマの内容に応じて、$ref の値は URL に置き換えます。SerDes はこの URL を使用して参照のスキーマを解決しようとし、主要なスキーマに対するデータの検証、ネスト化されたスキーマに対するネスト化された値の検証など、検証は通常どおりに行われます。Service Registry でアーティファクトを参照するためのサポートも実装されています。

たとえば、次の city.json スキーマは city.json スキーマを参照ししています。

{
 "$id": "https://example.com/citizen.schema.json",
 "$schema": "http://json-schema.org/draft-07/schema#",
 "title": "Citizen",
 "type": "object",
 "properties": {
   "firstName": {
     "type": "string",
     "description": "The citizen's first name."
   },
   "lastName": {
     "type": "string",
     "description": "The citizen's last name."
   },
   "age": {
     "description": "Age in years which must be equal to or greater than zero.",
     "type": "integer",
     "minimum": 0
   },
   "city": {
     "$ref": "city.json"
   }
 }
}

{
 "$id": "https://example.com/city.schema.json",
 "$schema": "http://json-schema.org/draft-07/schema#",
 "title": "City",
 "type": "object",
 "properties": {
   "name": {
     "type": "string",
     "description": "The city's name."
   },
   "zipCode": {
     "type": "integer",
     "description": "The zip code.",
     "minimum": 0
   }
 }
}

この例では、citizen に city が含まれます。Service Registry では、city アーティファクトへの参照を持つ citizen アーティファクトが、city.json という名前を使用して作成されます。SerDes では、citizen スキーマをフェッチすると、citizen スキーマから参照されるため、city スキーマもフェッチされます。データをシリアライズ/デシリアライズする場合、ネストされたスキーマを解決するために参照名が使用され、citizen スキーマとネストされた city スキーマに対する検証が可能になります。

このトピックでは、Google Protobuf の Kafka クライアントシリアライザーおよびデシリアライザー (SerDes) クラスを使用する方法を説明します。

Service Registry は、Protobuf 用に次の Kafka クライアント SerDes クラスを提供します。

これらの設定オプションの詳細は、以下のセクションを参照してください。

設定プロパティー名と値はシリアライザーの場合と同じです。

デシリアライザークラスは、メッセージからこれらのオプションの値を判断できます。シリアライザーはメッセージの一部として ID を送信するため、ストラテジーは必要ありません。

ID の位置は、メッセージペイロードの先頭にあるマジックバイトを確認することで決定されます。そのバイトが見つかると、設定されたハンドラーを使用してメッセージペイロードから ID が読み取られます。マジックバイトが見つからない場合、ID はメッセージヘッダーから読み込まれます。

たとえば、次の table_info.proto スキーマファイルには、インポートされた mode.proto スキーマファイルが含まれています。

syntax = "proto3";
package sample;
option java_package = "io.api.sample";
option java_multiple_files = true;

import "sample/mode.proto";

message TableInfo {

 int32 winIndex = 1;
 Mode mode = 2;
 int32 min = 3;
 int32 max = 4;
 string id = 5;
 string dataAdapter = 6;
 string schema = 7;
 string selector = 8;
 string subscription_id = 9;
}

syntax = "proto3";
package sample;
option java_package = "io.api.sample";
option java_multiple_files = true;

enum Mode {

MODE_UNKNOWN = 0;
RAW = 1;
MERGE = 2;
DISTINCT = 3;
COMMAND = 4;
}

この例では、TableInfo 用と Mode 用の 2 つの Protobuf アーティファクトが Service Registry に格納されます。ただし、Mode は TableInfo の一部であるため、SerDes 内のメッセージをチェックするために TableInfo がフェッチされるたびに、Mode も TableInfo で参照されるアーティファクトとして返されます。