Apicurio Registry ユーザーガイド

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

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

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

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

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

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

Apicurio Registry 機能

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

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

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

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

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

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

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

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

Apicurio 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 スキーマを追加します。

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

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

図1.1 Apicurio Registry Web コンソール

Apicurio Registry Web コンソールは、http://MY-REGISTRY-URL/ui など、Apicurio Registry デプロイメントのメインエンドポイントから入手できます。

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

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

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

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

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

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

図1.3 Apicurio Registry と Kafka Connect のアーキテクチャー

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

グローバルルールの設定

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

registry.rules.global.<ruleName>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

このセクションでは、Java クライアントアプリケーションを使用して Apicurio Registry に格納されたアーティファクトを管理する方法について説明します。

Apicurio Registry Java クライアントには、クライアントファクトリーに基づく次の設定オプションが含まれています。

カスタムヘッダー設定

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

TLS 設定オプション

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

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

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

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

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

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

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

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

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

プロデューサーがシリアル化に Apicurio Registry を使用できるようにするには:

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

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

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

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

コンシューマーが逆シリアル化に Apicurio Registry を使用できるようにするには:

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

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

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

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

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

各ストラテジーのクラスは、io.apicurio.registry.serde.strategy パッケージに含まれています。Avro SerDe の特定のストラテジークラスは、io.apicurio.registry.serde.avro.strategy package に含まれています。デフォルトのストラテジー、TopicIdStrategy は、メッセージを受信する Kafka トピックと同じ名前の Apicurio 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 トピックおよびメッセージ情報を Apicurio Registry のアーティファクトにマップする方法を提供します。マッピングの共通規則は、Kafka メッセージのキーと値のどちらにシリアライザーを使用するかによって、Kafka トピック名と key または value を結合することです。

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

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

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

DefaultSchemaResolver インターフェイス

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

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

レジストリー検索オプションの設定

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

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

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

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

Apicurio Registry Web コンソール

Apicurio 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();
    }
}

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

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

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

本セクションの定数例を使用して、特定のクライアントシリアライザー/デシリアライザー (SerDe) サービスおよびスキーマ検索ストラテジーを直接クライアントアプリケーションに設定できます。または、ファイルまたはインスタンスで対応する Apicurio 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"; 1
   public static final String SCHEMA_RESOLVER = "apicurio.registry.schema-resolver"; 2
...

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 を設定する方法は、以下を参照してください。

本セクションでは、Apicurio Registry Kafka シリアライザー/デシリアライザー (SerDes) の Java 設定プロパティーに関する参照情報を提供します。

SchemaResolver インターフェイス

Apicurio Registry SerDes は、レジストリーへのアクセスを抽象化し、サポートされるすべての形式の SerDes クラスに同じ検索ロジックを適用する SchemaResolver インターフェイスをベースとしています。

DefaultSchemaResolver クラス

DefaultSchemaResolver を使用して、次のような機能を設定できます。

レジストリー API アクセスオプションの設定

DefaultSchemaResolver は、コアレジストリー API へのアクセスを設定するために次のプロパティーを提供します。

レジストリー検索オプションの設定

DefaultSchemaResolver は、次のプロパティーを使用して、Apicurio Registry でアーティファクトを検索する方法を設定します。

Kafka でレジストリーアーティファクトを読み書きするための設定

DefaultSchemaResolver は、次のプロパティーを使用して、アーティファクト情報の Kafka への書き込みおよび Kafka からの読み取り方法を設定します。

デシリアライザーのフォールバックオプションの設定

DefaultSchemaResolver は、次のプロパティーを使用して、すべてのデシリアライザーのフォールバックプロバイダーを設定します。

DefaultFallbackArtifactProvider は、次のプロパティーを使用して、デシリアライザーのフォールバックオプションを設定します。

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

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

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

Kafka アプリケーションで Apicurio 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 Apicurio 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 Apicurio 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 Apicurio 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 Apicurio 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)

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

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

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

以下のルールタイプを指定して、Apicurio Registry でコンテンツ展開を管理できます。

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