Service Registry ユーザーガイド

Service Registry は、API およびイベント駆動型アーキテクチャー全体で標準的なイベントスキーマおよび API 設計を共有するためのデータストアです。Service Registry を使用して、クライアントアプリケーションからデータの構造を切り離し、REST インターフェイスを使用して実行時にデータ型と API の記述を共有および管理できます。

たとえば、クライアントアプリケーションは、再デプロイせずに最新のスキーマ更新を実行時に Service Registry との間で動的にプッシュまたはプルできます。開発者チームは、すでに実稼働でデプロイされているサービスに必要な既存のスキーマのレジストリーをクエリーでき、新規サービスを開発する際に新しいスキーマを登録できます。

クライアントアプリケーションが、クライアントアプリケーションでレジストリー URL を指定することで、Service Registry に保存されているスキーマおよび API 設計を使用できるようにすることができます。たとえば、レジストリーにはメッセージをシリアライズおよびデシリアライズするために使用されるスキーマを保存できます。その後、クライアントアプリケーションからスキーマを参照して、送受信されるメッセージとこれらのスキーマの互換性を維持することができます。

Service Registry を使用して、アプリケーションからデータ構造を切り離し、メッセージ全体のサイズを減らすことでコストを削減し、組織内のスキーマおよび API 設計の一貫性を高めて効率化します。Service Registry は、開発者および管理者がレジストリーコンテンツの管理を簡単に行えるように Web コンソールを提供します。

さらに、オプションのルールを設定して、レジストリーコンテンツの展開を管理できます。たとえば、これらには、アップロードされたコンテンツが構文的および意味的に有効であること、または他のバージョンとの上位互換性と下位互換性があることを確認するためのルールが含まれます。設定済みのルールは新規バージョンをレジストリーにアップロードする前に渡す必要があります。これにより、無効または互換性のないスキーマや API 設計に無駄な時間を費やさないようにします。

Service Registry は、Apicurio Registry オープンソースコミュニティープロジェクトに基づいています。詳細は https://github.com/apicurio/apicurio-registry を参照してください。

Service Registry の機能

イベントスキーマや API 設計などの Service Registry に保存される項目は、レジストリーアーティファクトと呼ばれます。以下は、単純な株価アプリケーションの JSON 形式の Apache Avro スキーマアーティファクトの例を示しています。

{
   "type": "record",
   "name": "price",
   "namespace": "com.example",
   "fields": [
       {
           "name": "symbol",
           "type": "string"
       },
       {
           "name": "price",
           "type": "string"
       }
   ]
}

スキーマまたは API 設計がレジストリーのアーティファクトとして追加されると、クライアントアプリケーションはそのスキーマまたは API デザインを使用して、実行時にクライアントメッセージが正しいデータ構造に準拠することを確認できます。

Service Registry は、標準のイベントスキーマおよび API 仕様の幅広いメッセージペイロード形式をサポートしています。たとえば、サポートされている形式には、Apache Avro、Google Protobuf、GraphQL、AsyncAPI、OpenAPI などがあります。詳細は 8章Service Registry アーティファクトの参照 を参照してください。

スキーマおよび API グループ

アーティファクトグループ は、スキーマまたは API アーティファクトのオプションの名前付きコレクションです。各グループには、論理的に関連したスキーマまたは API 設計のセットが含まれており、通常、特定のアプリケーションまたは組織に属する単一のエンティティーにより管理されます。

スキーマと API 設計を追加するときに、オプションのアーティファクトグループを作成して、Service Registry でそれらを整理できます。たとえば、development および production アプリケーション環境、あるいは sales および engineering 組織に一致するグループを作成できます。

スキーマおよび API グループには複数のアーティファクトタイプを含めることができます。たとえば、同じグループ内に Protobuf、Avro、JSON Schema、OpenAPI、および AsyncAPI スキーマおよび API アーティファクトがあるとします。

Service Registry Web コンソール、コア REST API、Maven プラグイン、または Java クライアントアプリケーションを使用して、スキーマと API アーティファクトおよびオプションのグループを作成できます。以下の例は、REST API を使用する方法を示しています。

$ curl -X POST -H "Content-type: application/json; artifactType=AVRO" \
  -H "X-Registry-ArtifactId: share-price" \
  --data '{"type":"record","name":"price","namespace":"com.example", \
   "fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}' \
  https://my-registry.example.com/apis/registry/v2/groups/my-group/artifacts

この例では、my-group という名前のアーティファクトグループに share-price のアーティファクト ID を持つ Avro スキーマを追加します。

Service Registry Web コンソールを使用して、レジストリーに保存されているスキーマと API アーティファクトおよびオプションのグループを閲覧および検索し、新しいスキーマと API アーティファクト、グループ、およびバージョンを追加できます。ラベル、名前、グループ、および説明でアーティファクトを検索できます。アーティファクトのコンテンツや利用可能なバージョンを表示するか、アーティファクトファイルをローカルでダウンロードできます。

Web コンソールを使用して、グローバルに、スキーマと API アーティファクトごとに、レジストリーコンテンツの任意のルールを設定することもできます。コンテンツの検証および互換性に関するこれらの任意のルールは、新しいスキーマと API アーティファクトまたはバージョンをレジストリーにアップロードする際に適用されます。詳細は 8章Service Registry アーティファクトの参照 を参照してください。

図1.1 Service Registry Web コンソール

Service Registry Web コンソールは、Service Registry デプロイメントのメインエンドポイント (たとえば、http://MY-REGISTRY-URL/ui) から利用できます。

Service Registry は、レジストリーデータの基礎となるストレージに対して以下のオプションを提供します。

Kafka プロデューサーアプリケーションは、シリアライザーを使用して、特定のイベントスキーマに準拠するメッセージをエンコードできます。Kafka コンシューマーアプリケーションはデシリアライザーを使用して、特定のスキーマ ID に基づいてメッセージが適切なスキーマを使用してシリアライズされたことを検証できます。

図1.2 Service Registry および Kafka クライアント SerDe アーキテクチャー

Service Registry は、実行時に以下のメッセージタイプを検証するために Kafka クライアントシリアライザー/デシリアライザー (SerDes) を提供します。

Service Registry Maven リポジトリーおよびソースコードディストリビューションには、これらのメッセージタイプの Kafka SerDe 実装が含まれ、Kafka クライアント開発者がレジストリーと統合するために使用できます。これらの実装には、サポートされているメッセージタイプごとにカスタム Java クラスが含まれます (例: io.apicurio.registry.serde.avro)。これを使用して、クライアントアプリケーションは、検証のために実行時にレジストリーからスキーマをプルできます。

Apache Kafka Connect と Service Registry を使用して、Kafka と外部システム間でデータをストリーミングできます。Kafka Connect を使用すると、異なるシステムのコネクターを定義して、大量のデータを Kafka ベースのシステムに出し入れできます。

図1.3 Service Registry および Kafka Connect アーキテクチャー

Service Registry は、Kafka Connect に次の機能を提供します。

Avro および JSON スキーマコンバーターを使用して、Kafka Connect スキーマを Avro または JSON スキーマにマッピングすることができます。これらのスキーマは、メッセージのキーと値をコンパクトな Avro バイナリー形式または人間が判読できる JSON 形式にシリアライズすることができます。メッセージにはスキーマ情報が含まれず、スキーマ ID のみが含まれるため、変換された JSON も冗長性が低くなります。

Service Registry は、Kafka トピックで使用される Avro および JSON スキーマを管理および追跡できます。スキーマは Service Registry に保存され、メッセージコンテンツから切り離されるため、各メッセージには小さなスキーマ識別子だけを含める必要があります。Kafka など I/O 律速のシステムの場合、これはプロデューサーおよびコンシューマーのトータルスループットが向上することを意味します。

Service Registry が提供する Avro および JSON スキーマのシリアライザーとデシリアライザー (SerDes) は、このユース ケースの Kafka プロデューサーとコンシューマーによっても使用されます。変更イベントを使用するために作成する Kafka コンシューマーアプリケーションは、Avro または JSON Serdes を使用して変更イベントをデシリアライズすることができます。これらの Serde は Kafka ベースのシステムにインストールし、Kafka Connect や Debezium および Camel Kafka Connector などの Kafka Connect ベースのシステムと共に使用できます。

Service Registry は、異なるユースケースでレジストリーを使用する方法を示すオープンソースサンプルアプリケーションを提供します。たとえば、これには、Kafka シリアライザーおよびデシリアライザー (SerDe) クラスによって使用されるスキーマを保存することが含まれます。これらの Java クラスは、Kafka メッセージペイロードをシリアライズ、デシリアライズ、または検証する操作を生成または消費するときに使用するレジストリーからスキーマをフェッチします。

これらのサンプルアプリケーションには、以下が含まれます。

詳細は、 https://github.com/Apicurio/apicurio-registry-examples を参照してください

レジストリーコンテンツの展開を管理するために、レジストリーに追加されるアーティファクトコンテンツの任意のルールを設定できます。設定されたグローバルルールまたはアーティファクトルールはすべて、新しいアーティファクトバージョンをレジストリーにアップロードする前に渡す必要があります。設定されたアーティファクトルールは、設定されたグローバルルールを上書きします。

これらのルールの目的は、無効なコンテンツがレジストリーに追加されないようにすることです。たとえば、次の理由でコンテンツが無効になる可能性があります。

Service Registry Web コンソール、REST API コマンド、または Java クライアントアプリケーションを使用して、これらのコンテンツルールを追加できます。

ルールは、コンテンツがレジストリーに追加される場合にのみ適用されます。これには、以下の REST 操作が含まれます。

ルールに違反した場合、Service Registry は HTTP エラーを返します。応答本文には、違反したルールと、何が問題だったのかを示すメッセージが含まれます。

各ルールには、名前と任意の設定情報があります。レジストリーストレージは、各アーティファクトのルール一覧とグローバルルールの一覧を維持します。リスト内の各ルールは、ルール実装に固有の名前と設定プロパティーのセットで設定されます。

アーティファクトの現在のバージョン (存在する場合) および追加されるアーティファクトの新しいバージョンのコンテンツを含むルールが提供されます。ルール実装は、アーティファクトがルールを渡すかどうかに応じて true または false を返します。そうでない場合、レジストリーはその理由を HTTP エラー応答で報告します。一部のルールは、コンテンツの以前のバージョンを使用しない場合があります。たとえば、互換性ルールは以前のバージョンを使用しますが、構文またはセマンティック妥当性ルールは使用しません。

アーティファクトごとに個別にルールを設定することも、グローバルに設定することもできます。Service Registry は、特定のアーティファクトに設定したルールを適用します。そのレベルでルールが設定されていない場合、Service Registry はグローバルに設定されたルールを適用します。グローバルルールが設定されていない場合は、ルールが適用されません。

アーティファクトルールの設定

Service Registry Web コンソールまたは REST API を使用してアーティファクトルールを設定できます。詳細は以下を参照してください。

グローバルルールの設定

グローバルルールは、複数の方法で設定できます。

registry.rules.global.<ruleName>

現在、以下のルール名がサポートされています。

application プロパティーの値は、設定されたルールに固有の有効な設定オプションである必要があります。以下の表は、各ルールの有効な値を示しています。

Service Registry Web コンソールを使用して、イベントスキーマと API デザインアーティファクトをレジストリーにアップロードできます。アップロード可能なアーティファクトタイプに関する詳細は、8章Service Registry アーティファクトの参照 を参照してください。本セクションでは、Service Registry アーティファクトのアップロード、アーティファクトルールの適用、および新しいアーティファクトバージョンの追加の簡単な例を紹介します。

Service Registry Web コンソールを使用して、レジストリーに保存されているイベントスキーマおよび API デザインアーティファクトを参照できます。本セクションでは、Service Registry アーティファクト、グループ、バージョン、およびアーティファクトルールを表示する簡単な例を紹介します。レジストリーに保存されているアーティファクトタイプの詳細は、8章Service Registry アーティファクトの参照 を参照してください。

Service Registry Web コンソールを使用して、無効なコンテンツがレジストリーに追加されないようにオプションのルールを設定できます。設定されたアーティファクトルールまたはグローバルルールはすべて、新しいアーティファクトバージョンをレジストリーにアップロードする前に渡す必要があります。設定されたアーティファクトルールは、設定されたグローバルルールを上書きします。詳細は 2章Service Registry のコンテンツルール を参照してください。

本セクションでは、グローバルルールとアーティファクトルールを設定する簡単な例を紹介します。選択可能なさまざまなルールタイプおよび関連する設定の詳細は、8章Service Registry アーティファクトの参照 を参照してください。

本セクションでは、レジストリー v2 コア REST API を使用して、レジストリーに Apache Avro スキーマアーティファクトを追加および取得するための単純な curl ベースの例を紹介します。

v2 REST API を使用してスキーマおよび API アーティファクトを Service Registry に追加する際にアーティファクトバージョンを指定しない場合、Service Registry は自動的にアーティファクトバージョンを生成します。新規アーティファクト作成時のデフォルトのバージョンは 1 です。

Service Registry は、X-Registry-Version HTTP リクエストヘッダーを文字列として使用してバージョンを指定できるカスタムバージョン管理もサポートしています。カスタムバージョン値を指定すると、アーティファクトの作成または更新時に通常割り当てられるデフォルトのバージョンが上書きされます。バージョンを必要とする REST API 操作を実行する場合は、このバージョン値を使用できます。

本セクションでは、レジストリー v2 コア REST API を使用して、レジストリーに カスタム Apache Avro スキーマアバージョンを追加および取得するための単純な curl ベースの例を紹介します。REST API を使用してアーティファクトを追加または更新したり、アーティファクトバージョンを追加したりするときにカスタムバージョンを指定できます。

本セクションでは、レジストリー v2 コア REST API を使用して、既存のレジストリーデータをある Service Registry インスタンスから別の Service Registry インスタンスに .zip 形式でエクスポートおよびインポートするシンプルな curl ベースの例を示します。たとえば、これは Service Registry v2.x インスタンスから別のインスタンスに移行またはアップグレードする場合に役立ちます。

Maven プラグインの最も一般的なユースケースは、ビルド中にアーティファクトを追加することです。これは、register 実行目標を使用して実現できます。

Maven プラグインを使用して Service Registry からアーティファクトをダウンロードできます。これは、たとえば、登録されたスキーマからコードを生成する場合などに便利です。

実際にアーティファクトを変更せずに、アーティファクトをが登録できることを確認する場合があります。これは、ルールが Service Registry に設定されている場合に役に立ちます。アーティファクトのコンテンツが設定済みのルールのいずれかに違反する場合、アーティファクトのテストに失敗します。

Java クライアントアプリケーションを使用して、Service Registry に保存されているアーティファクトを管理できます。Service Registry Java クライアントクラスを使用して、レジストリーに保存されているアーティファクトを作成、読み取り、更新、または削除できます。グローバルなルールの管理やレジストリーデータのインポートおよびエクスポートなど、クライアントを使用して管理機能を実行することもできます。

正しい依存関係をプロジェクトに追加すると、Service Registry Java クライアントにアクセスできます。詳細は 「Service Registry クライアントアプリケーションの作成」 を参照してください。

Service Registry クライアントは、JDK によって提供される HTTP クライアントを使用して実装されます。これにより、カスタムヘッダーの追加や TLS (Transport Layer Security) 認証のオプションの有効化など、使用をカスタマイズすることができます。詳細は 「Service Registry Java クライアント設定」 を参照してください。

本セクションでは、Java クライアントアプリケーションを使用して Service Registry に保存されているアーティファクトを管理する方法を説明します。

Service Registry Java クライアントには、クライアントファクトリーを基にした以下の設定オプションが含まれます。

カスタムヘッダー設定

カスタムヘッダーを設定するには、configs マップキーに apicurio.registry.request.headers 接頭辞を追加する必要があります。たとえば、値が Basic:xxxxx の apicurio.registry.request.headers.Authorization のキーは、値が Basic: xxxxx の Authorization のヘッダーになります。

TLS 設定オプション

以下のプロパティーを使用して、Service Registry Java クライアントの Transport Layer Security (TLS) 認証を設定できます。

Service Registry は、クライアントアプリケーション設定からスキーマ管理を分離します。クライアントコードに URL を指定すると、Java クライアントアプリケーションが Service Registry からスキーマを使用できます。

Service Registry にスキーマを保存して、メッセージをシリアライズおよびデシリアライズできます。クライアントアプリケーションからスキーマが参照され、送受信されるメッセージとこれらのスキーマの互換性を維持するようにします。Kafka クライアントアプリケーションは実行時にスキーマを Service Registry からプッシュまたはプルできます。

スキーマは進化するので、Service Registry でルールを定義できます。たとえば、スキーマの変更が有効で、アプリケーションによって使用される以前のバージョンとの互換性を維持するようにします。Service Registry は、変更済みのスキーマと以前のスキーマバージョンを比較することで、互換性をチェックします。

Service Registry スキーマテクノロジー

Service Registry は、以下のようなスキーマテクノロジーのスキーマレジストリーサポートを提供します。

これらのスキーマテクノロジーは、Service Registry によって提供される Kafka クライアントのシリアライザー/デシリアライザー (SerDe) サービスを介してクライアントアプリケーションで使用できます。Service Registry によって提供される SerDe クラスの成熟度および使用法は異なる場合があります。以降のセクションでは、各スキーマタイプの詳細を提供します。

プロデューサースキーマの設定

プロデューサークライアントアプリケーションは、シリアライザーを使用して、特定のブローカートピックに送信するメッセージを正しいデータ形式にします。

プロデューサーが Service Registry を使用してシリアライズできるようにするには、以下を行います。

スキーマを登録したら、Kafka および Service Registry を開始するときに、スキーマにアクセスして、プロデューサーにより Kafka ブローカートピックに送信されるメッセージをフォーマットできます。または、設定に応じて、プロデューサーは最初の使用時にスキーマを自動的に登録できます。

スキーマがすでに存在する場合、Service Registry に定義される互換性ルールに基づいて、レジストリー REST API を使用して新バージョンのスキーマを作成できます。バージョンは、スキーマの進化にともなう互換性チェックに使用します。グループ ID、アーティファクト ID、およびバージョンは、スキーマを識別する一意のタプルを表します。

コンシューマースキーマの設定

コンシューマークライアントアプリケーションは、デシリアライザーを使用することで、そのアプリケーションが消費するメッセージを特定のブローカートピックから正しいデータ形式にします。

コンシューマーがデシリアライズに Service Registry を使用できるようにするには、以下を実行します。

メッセージペイロードでグローバル ID を見つけるとき、データの形式は、コンシューマーへの信号として使用されるマジックバイトで始まり、通常通りグローバル ID とメッセージデータが続きます。以下に例を示します。

# ...
[MAGIC_BYTE]
[GLOBAL_ID]
[MESSAGE DATA]

これで、Kafka および Service Registry を開始するとき、スキーマにアクセスして、Kafka ブローカートピックから受信するメッセージをフォーマットできます。

コンテンツ ID はバージョンを一意に識別しませんが、バージョンコンテンツのみを一意に識別します。複数のバージョンがまったく同じコンテンツを共有している場合、グローバル ID は異なりますが、コンテンツ ID は同じです。Confluent スキーマレジストリーは、デフォルトでコンテンツ ID を使用します。

Kafka クライアントのシリアライザーは 検索ストラテジー を使用して、メッセージスキーマが Service Registry に登録されるアーティファクト ID およびグローバル ID を決定します。特定のトピックとメッセージについて、 ArtifactResolverStrategy Java インターフェイスのさまざまな実装を使用して、レジストリー内のアーティファクトへの参照を返すことができます。

各ストラテジーのクラスは、io.apicurio.registry.serde.strategy パッケージに含まれています。Avro SerDe の特定のストラテジークラスは、io.apicurio.registry.serde.avro.strategy package に含まれています。デフォルトのストラテジー、TopicIdStrategy は、メッセージを受信する Kafka トピックと同じ名前の Service Registry アーティファクトを検索します。

public ArtifactReference artifactReference(String topic, boolean isKey, T schema) {
        return ArtifactReference.builder()
                .groupId(null)
                .artifactId(String.format("%s-%s", topic, isKey ? "key" : "value"))
                .build();

使用する検索アップストラテジーは、スキーマを保存する方法と場所によって異なります。たとえば、同じ Avro メッセージタイプを持つ Kafka トピックが複数ある場合、レコード ID を使用するストラテジーを使用することがあります。

KeystoneOpenIdcaceResolverStrategy インターフェイス

アーティファクトリーゾルバーストラテジーは、Kafka トピックおよびメッセージ情報を Service Registry のアーティファクトにマップする方法を提供します。マッピングの共通規則は、Kafka メッセージのキーと値のどちらにシリアライザーを使用するかによって、Kafka トピック名と key または value を結合することです。

ただし、Service Registry によって提供されるストラテジーを使用するか、io.apicurio.registry.serde.strategy.ArtifactResolverStrategy を実装するカスタム Java クラスを作成することにより、マッピングに代替規則を使用できます。

アーティファクト参照を返すストラテジー

Service Registry は、 ArtifaceResolverStrategy の実装に基づいてアーティファクト参照を返すために次のストラテジーを提供します。

DefaultSchemaResolver インターフェイス

デフォルトのスキーマリゾルバーは、アーティファクトリーゾルバーストラテジーによって提供されるアーティファクト参照の下に登録されたスキーマの特定バージョンを見つけて識別します。すべてのアーティファクトのすべてのバージョンには、グローバルで一意の識別子が 1 つだけあり、それを使用してそのアーティファクトの内容を取得できます。このグローバル ID はすべての Kafka メッセージに含まれていいるため、デシリアライザーは Apicurio レジストリーからスキーマを適切に取得できます。

デフォルトのスキーマリゾルバーは、既存のアーティファクトバージョンを検索できます。見つからない場合は、使用するストラテジーに応じて登録できます。io.apicurio.registry.serde.SchemaResolver を実装するカスタム Java クラスを作成することにより、独自のストラテジーを提供することもできます。ただし、DefaultSchemaResolver を使用して、代わりに設定プロパティーを指定することをお勧めします。

グローバル ID を返すストラテジー

DefaultSchemaResolver を使用する場合、アプリケーションのプロパティーを使用してその動作を設定できます。次の表は、一般的に使用される例を示しています。

本セクションの定数例を使用して、特定のクライアントシリアライザー/デシリアライザー (SerDe) サービスおよびスキーマ検索ストラテジーを直接クライアントアプリケーションに設定できます。または、ファイルまたはインスタンスで対応する Service Registry アプリケーションプロパティーを設定できます。

以下のセクションでは、SerDe 定数および設定オプションの例を紹介します。

SerDe サービスの設定

public class SerdeConfig {

   public static final String REGISTRY_URL = "apicurio.registry.url"; 1
   public static final String ID_HANDLER = "apicurio.registry.id-handler"; 2
   public static final String ENABLE_CONFLUENT_ID_HANDLER = "apicurio.registry.as-confluent"; 3

SerDe 検索ストラテジーの設定

public class SerdeConfig {

   public static final String ARTIFACT_RESOLVER_STRATEGY = "apicurio.registry.artifact-resolver-strategy";
...

Kafka コンバーターの設定

public class SerdeBasedConverter<S, T> extends SchemaResolverConfigurer<S, T> implements Converter, Closeable {

   public static final String REGISTRY_CONVERTER_SERIALIZER_PARAM = "apicurio.registry.converter.serializer"; 1
   public static final String REGISTRY_CONVERTER_DESERIALIZER_PARAM = "apicurio.registry.converter.deserializer"; 2

さまざまなスキーマタイプの設定

さまざまなスキーマ技術に SerDe を設定する方法は、以下を参照してください。

Kafka クライアントアプリケーションでスキーマを使用する場合は、ユースケースに応じて、使用する特定のスキーマタイプを選択する必要があります。Service Registry は、Apache Avro、JSON スキーマ、および Google Protobuf 用の SerDe Java クラスを提供します。以下のセクションでは、各タイプを使用するように Kafka アプリケーションを設定する方法を説明します。

また、Kafka を使用してカスタムシリアライザーおよびデシリアライザークラスを実装し、Service Registry REST Java クライアントを使用して Service Registry 機能を活用することもできます。

シリアライザー/デシリアライザーの Kafka アプリケーション設定

Kafka アプリケーションで Service Registry によって提供される SerDe クラスを使用するには、正しい設定プロパティーを設定する必要があります。以下の簡単な Avro の例は、Kafka プロデューサーアプリケーションでシリアライザーを設定する方法と、Kafka コンシューマーアプリケーションでデシリアライザーを設定する方法を示しています。

// Create the Kafka producer
private static Producer<Object, Object> createKafkaProducer() {
    Properties props = new Properties();

    // Configure standard Kafka settings
    props.putIfAbsent(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, SERVERS);
    props.putIfAbsent(ProducerConfig.CLIENT_ID_CONFIG, "Producer-" + TOPIC_NAME);
    props.putIfAbsent(ProducerConfig.ACKS_CONFIG, "all");

    // Use Service Registry-provided Kafka serializer for Avro
    props.putIfAbsent(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, StringSerializer.class.getName());
    props.putIfAbsent(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, AvroKafkaSerializer.class.getName());

    // Configure the Service Registry location
    props.putIfAbsent(SerdeConfig.REGISTRY_URL, REGISTRY_URL);

    // Register the schema artifact if not found in the registry.
    props.putIfAbsent(SerdeConfig.AUTO_REGISTER_ARTIFACT, Boolean.TRUE);

    // Create the Kafka producer
    Producer<Object, Object> producer = new KafkaProducer<>(props);
    return producer;
}

// Create the Kafka consumer
private static KafkaConsumer<Long, GenericRecord> createKafkaConsumer() {
    Properties props = new Properties();

    // Configure standard Kafka settings
    props.putIfAbsent(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, SERVERS);
    props.putIfAbsent(ConsumerConfig.GROUP_ID_CONFIG, "Consumer-" + TOPIC_NAME);
    props.putIfAbsent(ConsumerConfig.ENABLE_AUTO_COMMIT_CONFIG, "true");
    props.putIfAbsent(ConsumerConfig.AUTO_COMMIT_INTERVAL_MS_CONFIG, "1000");
    props.putIfAbsent(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest");

    // Use Service Registry-provided Kafka deserializer for Avro
    props.putIfAbsent(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class.getName());
    props.putIfAbsent(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, AvroKafkaDeserializer.class.getName());

    // Configure the Service Registry location
    props.putIfAbsent(SerdeConfig.REGISTRY_URL, REGISTRY_URL);

    // No other configuration needed because the schema globalId the deserializer uses is sent
    // in the payload. The deserializer extracts the globalId and uses it to look up the schema
    // from the registry.

    // Create the Kafka consumer
    KafkaConsumer<Long, GenericRecord> consumer = new KafkaConsumer<>(props);
    return consumer;
}

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

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

スキーマを Apache Avro などの適切な形式で定義したら、スキーマを Service Registry に追加できます。

以下の方法を使用してスキーマを追加できます。

スキーマを登録するまでは、クライアントアプリケーションは Service Registry を使用できません。

Service Registry Web コンソール

Service Registry のインストール時に、ui エンドポイントから Web コンソールに接続できます。

http://MY-REGISTRY-URL/ui

コンソールから、スキーマを追加、表示、および設定できます。また、レジストリーに無効なコンテンツが追加されないようにするルールを作成することもできます。

curl コマンドの例

 curl -X POST -H "Content-type: application/json; artifactType=AVRO" \
   -H "X-Registry-ArtifactId: share-price" \ 1
   --data '{
     "type":"record",
     "name":"price",
     "namespace":"com.example",
     "fields":[{"name":"symbol","type":"string"},
     {"name":"price","type":"string"}]}'
   https://my-cluster-my-registry-my-project.example.com/apis/registry/v2/groups/my-group/artifacts -s 2

Maven プラグインの例

<plugin>
  <groupId>io.apicurio</groupId>
  <artifactId>apicurio-registry-maven-plugin</artifactId>
  <version>${apicurio.version}</version>
  <executions>
      <execution>
        <phase>generate-sources</phase>
        <goals>
            <goal>register</goal>  1
        </goals>
        <configuration>
            <registryUrl>http://REGISTRY-URL/apis/registry/v2</registryUrl> 2
            <artifacts>
                <artifact>
                    <groupId>TestGroup</groupId> 3
                    <artifactId>FullNameRecord</artifactId>
                    <file>${project.basedir}/src/main/resources/schemas/record.avsc</file>
                    <ifExists>FAIL</ifExists>
                </artifact>
                <artifact>
                    <groupId>TestGroup</groupId>
                    <artifactId>ExampleAPI</artifactId> 4
                    <type>GRAPHQL</type>
                    <file>${project.basedir}/src/main/resources/apis/example.graphql</file>
                    <ifExists>RETURN_OR_UPDATE</ifExists>
                    <canonicalize>true</canonicalize>
                </artifact>
            </artifacts>
        </configuration>
    </execution>
  </executions>
 </plugin>

プロデューサークライアントを使用した設定例

String registryUrl_node1 = PropertiesUtil.property(clientProperties, "registry.url.node1",
    "https://my-cluster-service-registry-myproject.example.com/apis/registry/v2"); 1
try (RegistryService service = RegistryClient.create(registryUrl_node1)) {
    String artifactId = ApplicationImpl.INPUT_TOPIC + "-value";
    try {
        service.getArtifactMetaData(artifactId); 2
    } catch (WebApplicationException e) {
        CompletionStage <ArtifactMetaData> csa = service.createArtifact(
            ArtifactType.AVRO,
            artifactId,
            new ByteArrayInputStream(LogInput.SCHEMA$.toString().getBytes())
        );
        csa.toCompletableFuture().get();
    }
}

この手順では、Service Registry からのスキーマを使用するように Java で書かれた Kafka コンシューマークライアントを設定する方法について説明します。

この手順では、Service Registry からのスキーマを使用するように Java で書かれた Kafka プロデューサークライアントを設定する方法について説明します。

この手順では、Service Registry からの Apache Avro スキーマを使用するように Java で書かれた Kafka Streams クライアントを設定する方法について説明します。

以下のアーティファクトタイプは Service Registry に保存および管理できます。

以下は、Service Registry の有効なアーティファクト状態です。

アーティファクトが Service Registry に追加されると、メタデータプロパティーのセットがアーティファクトの内容と共に保存されます。このメタデータは、設定可能な一部のプロパティーと、生成された読み取り専用プロパティーのセットで設定されます。

Service Registry のコンテンツ展開を管理するには、以下のルールタイプを指定できます。

すべてのコンテンツルールは、Service Registry でサポートされるすべてのアーティファクトタイプに対して完全に実装されるわけではありません。以下の表は、各ルールおよびアーティファクトタイプの現在の成熟度レベルを示しています。