Service Registry ユーザーガイド
Service Registry 2.3 の使用
概要
前書き
多様性を受け入れるオープンソースの強化
Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。まずは、マスター (master)、スレーブ (slave)、ブラックリスト (blacklist)、ホワイトリスト (whitelist) の 4 つの用語の置き換えから始めます。この取り組みは膨大な作業を要するため、今後の複数のリリースで段階的に用語の置き換えを実施して参ります。詳細は、Red Hat CTO である Chris Wright のメッセージ をご覧ください。
第1章 Service Registry の概要
本章では、Service Registry の概念および機能を紹介し、レジストリーに保存されるサポート対象のアーティファクトタイプの詳細を提供します。
- 「Service Registry とは」
- 「Service Registry のスキーマと API アーティファクト」
- 「Service Registry Web コンソールを使用したコンテンツの管理」
- 「Service Registry コア REST API」
- 「Service Registry ストレージのオプション」
- 「スキーマと Java クライアントシリアライザー/デシリアライザーを使用した Kafka メッセージの検証」
- 「Kafka Connect コンバーターを使用した外部システムへのデータのストリーミング」
- 「Service Registry デモ例」
- 「Service Registry で利用可能なディストリビューション」
1.1. 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 の機能
- Apache Avro、JSON スキーマ、Protobuf、AsyncAPI、OpenAPI などの標準イベントスキーマおよび API 仕様の複数のペイロード形式
- AMQ Streams または PostgreSQL データベースのプラグ可能なレジストリーストレージオプション
- レジストリーコンテンツが時間とともにどのように進化するかを管理するためのコンテンツ検証とバージョン互換性のルール
- Web コンソール、REST API、コマンドライン、Maven プラグイン、または Java クライアントを使用したレジストリーコンテンツ管理
- 外部システム用の Kafka Connect との統合を含む、Apache Kafka スキーマレジストリーの完全なサポート
- 実行時にメッセージタイプを検証する Kafka クライアントシリアライザー/デシリアライザー (SerDes)
- 既存の Confluent または IBM スキーマレジストリークライアントアプリケーションとの互換性
- メモリーフットプリントが低く、デプロイメントの時間が高速化されるクラウドネイティブ Quarkus Java ランタイム
- OpenShift での Service Registry の Operator ベースのインストール
- Red Hat Single Sign-On を使用した OpenID Connect (OIDC) 認証
1.2. Service Registry のスキーマと API アーティファクト
イベントスキーマや API 設計などの Service Registry に保存される項目は、レジストリーアーティファクトと呼ばれます。以下は、単純な株価アプリケーションの JSON 形式の Apache Avro スキーマアーティファクトの例を示しています。
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 などがあります。
スキーマと API のグループ
アーティファクトグループ は、スキーマまたは API アーティファクトのオプションの名前付きコレクションです。各グループには、論理的に関連したスキーマまたは API 設計のセットが含まれており、通常、特定のアプリケーションまたは組織に属する単一のエンティティーにより管理されます。
スキーマと API 設計を追加するときに、オプションのアーティファクトグループを作成して、Service Registry でそれらを整理できます。たとえば、development および production アプリケーション環境、あるいは sales および engineering 組織に一致するグループを作成できます。
スキーマおよび API グループには複数のアーティファクトタイプを含めることができます。たとえば、Protobuf、Avro、JSON スキーマ、OpenAPI、または AsyncAPI アーティファクトをすべて同じグループに含めることができます。
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 という名前のアーティファクトグループを作成し、アーティファクト ID が share-price の Avro スキーマを追加します。
Service Registry Web コンソールを使用する場合にグループの指定は任意です。この場合、default グループが自動的に作成されます。REST API または Maven プラグインを使用し、一意のグループを作成したくない場合は API パスで default グループを指定します。
関連情報
- スキーマおよびグループの詳細は、Cloud Native Computing Foundation (CNCF) Schema Registry API を参照してください。
- Service Registry コア REST API の詳細は、Apicurio Registry REST API のドキュメント を参照してください。
他のスキーマと API への参照
一部の Service Registry アーティファクトタイプには、別のアーティファクトファイルへの アーティファクト参照 を含めることができます。再利用可能なスキーマまたは API コンポーネントを定義し、それらを複数の場所から参照して効率を高めることができます。たとえば、$ref ステートメントを使用して JSON スキーマまたは OpenAPI で参照を指定したり、import ステートメントを使用して Google protobuf で参照を指定したり、ネストされた名前空間を使用して Apache Avro で参照を指定したりできます。
次の例は、ネストされた名前空間を使用して Exchange という名前の別のスキーマへの参照を含む、TradeKey という名前の単純な Avro スキーマを示しています。
ネストされた Exchange スキーマを持つ TradeKey スキーマ
{
"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"]
}
アーティファクト参照は、アーティファクトタイプ固有の参照から内部 Service Registry 参照にマップされるアーティファクトメタデータのコレクションとしてService Registry に格納されます。Service Registry の各アーティファクト参照は、以下で構成されます。
- グループ ID
- アーティファクト ID
- アーティファクトのバージョン
- アーティファクト参照名
Service Registry コア REST API、Maven プラグイン、および Java シリアライザー/デシリアライザー (SerDes) を使用して、アーティファクト参照を管理できます。Service Registry は、アーティファクトコンテンツとともにアーティファクト参照を保存します。Service Registry は、すべてのアーティファクトリーファレンスのコレクションも保持しているため、コレクションを検索したり、特定のアーティファクトのすべてのリファレンスを一覧表示したりできます。
サポートされているアーティファクトタイプ
Service Registry は現在、次のアーティファクトタイプのアーティファクトリーファレンスのみをサポートしています。
- Avro
- Protobuf
- JSON スキーマ
関連情報
アーティファクト参照の管理の詳細は、以下を参照してください。
- Java コードの例については、Apicurio Registry SerDes with references を参照してください。
1.3. Service Registry Web コンソールを使用したコンテンツの管理
Service Registry Web コンソールを使用して、レジストリーに保存されているスキーマと API アーティファクトおよびオプションのグループを閲覧および検索し、新しいスキーマと API アーティファクト、グループ、およびバージョンを追加できます。ラベル、名前、グループ、および説明でアーティファクトを検索できます。アーティファクトのコンテンツや利用可能なバージョンを表示するか、アーティファクトファイルをローカルでダウンロードできます。
また、レジストリーコンテンツのオプションのルールを、グローバルに、およびスキーマと API アーティファクトごとに設定することもできます。コンテンツの検証および互換性に関するこれらの任意のルールは、新しいスキーマと API アーティファクトまたはバージョンをレジストリーにアップロードする際に適用されます。
詳細は、9章Service Registry アーティファクトの参照 を参照してください。
図1.1 Service Registry Web コンソール

Service Registry Web コンソールは http://MY_REGISTRY_URL/ui から利用できます。
1.4. Service Registry コア REST API
クライアントアプリケーションは、Service Registry コア v2 REST API の使用を参照して、Service Registry のスキーマと API アーティファクトを管理できます。この API では、以下を行うために作成、読み取り、更新、および削除の操作が提供されます。
- アーティファクト
- レジストリーに保存されたスキーマおよび API アーティファクトを管理します。アーティファクトのライフサイクル状態 (enabled、disabled、または deprecated) を管理することもできます。
- アーティファクトのバージョン
- スキーマまたは API アーティファクトの更新時に作成されるバージョンを管理します。アーティファクトバージョンのライフサイクル状態: enabled、disabled、または deprecated を管理することもできます。
- アーティファクトのメタデータ
- スキーマまたは API アーティファクトに関する詳細 (作成または変更された日時、現在の状態など) を管理します。アーティファクト名、説明、またはラベルを編集できます。アーティファクトグループと、アーティファクトが作成または変更された時期は読み取り専用です。
- アーティファクトルール
- 特定のスキーマまたは API アーティファクトのコンテンツ展開を管理するルールを設定して、無効または互換性のないコンテンツがレジストリーに追加されないようにします。アーティファクトルールは、設定されたグローバルルールを上書きします。
- グローバルルール
- すべてのスキーマおよび API アーティファクトのコンテンツ展開を管理するルールを設定して、無効または互換性のないコンテンツがレジストリーに追加されないようにします。グローバルルールは、アーティファクトに独自の特定のアーティファクトルールが設定されていない場合にのみ適用されます。
- 検索
- スキーマと API アーティファクトおよびバージョンを、名前、グループ、説明、ラベルなどで参照または検索します。
- Admin
-
.zipファイルでレジストリーコンテンツをエクスポートまたはインポートし、実行時にレジストリーサーバーインスタンスのログレベルを管理します。
他のスキーマレジストリー REST API との互換性
Service Registry は、それぞれの REST API の実装を含めることで、次のスキーマレジストリーとの互換性を提供します。
- Service Registry コア v1
- Confluent スキーマレジストリー v6
- IBM Event Streams スキーマレジストリー v1
- CNCF CloudEvents スキーマレジストリー v0
Confluent クライアントライブラリーを使用するアプリケーションは Service Registry をドロップイン置換として使用できます。詳細については、Confluent Schema Registry の置換 を参照してください。
関連情報
- 詳細な参照情報は、Apicurio Registry REST API ドキュメント を参照してください。
-
Service Registry REST API のコア API と、互換性のあるすべての API の API ドキュメントは、Service Registry インスタンスのメインエンドポイント (
http://MY-REGISTRY-URL/apisなど) から利用できます。
1.5. Service Registry ストレージのオプション
Service Registry は、レジストリーデータの基礎となるストレージに対して以下のオプションを提供します。
表1.1 Service Registry データストレージオプション
| ストレージオプション | 説明 |
|---|---|
| PostgreSQL 12 database | PostgreSQL は、実稼働環境でのパフォーマンス、安定性、およびデータ管理 (バックアップ/復元など) に推奨されるデータストレージオプションです。 |
| AMQ Streams 2.1 | Kafka ストレージは、データベース管理の専門知識が利用できない実稼働環境、または Kafka のストレージが特定の要件である実稼働環境向けに提供されています。 |
関連情報
- ストレージオプションの詳細は、OpenShift での Service Registry のインストールおよびデプロイ を参照してください。
1.6. スキーマと Java クライアントシリアライザー/デシリアライザーを使用した Kafka メッセージの検証
Kafka プロデューサーアプリケーションは、シリアライザーを使用して、特定のイベントスキーマに準拠するメッセージをエンコードできます。Kafka コンシューマーアプリケーションはデシリアライザーを使用して、特定のスキーマ ID に基づいてメッセージが適切なスキーマを使用してシリアライズされたことを検証できます。
図1.2 Service Registry および Kafka クライアント SerDes アーキテクチャー

Service Registry は、実行時に以下のメッセージタイプを検証するために Kafka クライアントシリアライザー/デシリアライザー (SerDes) を提供します。
- Apache Avro
- Google プロトコルバッファー
- JSON スキーマ
Service Registry Maven リポジトリーおよびソースコードディストリビューションには、これらのメッセージタイプの Kafka SerDe 実装が含まれ、Kafka クライアントアプリケーション開発者がレジストリーと統合するために使用できます。
これらの実装には、サポートされているメッセージタイプごとにカスタム Java クラスが含まれます (例: io.apicurio.registry.serde.avro)。これを使用して、クライアントアプリケーションは、検証のために実行時にレジストリーからスキーマをプルできます。
1.7. Kafka Connect コンバーターを使用した外部システムへのデータのストリーミング
Apache Kafka Connect と Service Registry を使用して、Kafka と外部システム間でデータをストリーミングできます。Kafka Connect を使用すると、異なるシステムのコネクターを定義して、大量のデータを Kafka ベースのシステムに出し入れできます。
図1.3 Service Registry および Kafka Connect アーキテクチャー

Service Registry は、Kafka Connect に次の機能を提供します。
- Kafka Connect スキーマのストレージ
- Apache Avro および JSON スキーマの Kafka Connect コンバーター
- スキーマを管理するレジストリー REST API
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 を使用して変更イベントをデシリアライズすることができます。これらの SerDes は Kafka ベースのシステムにインストールし、Kafka Connect や Debezium および Camel Kafka Connector などの Kafka Connect ベースのシステムと共に使用できます。
1.8. Service Registry デモ例
Service Registry は、異なるユースケースで Service Registry を使用する方法を示すオープンソースサンプルアプリケーションを提供します。たとえば、これには、Kafka シリアライザーおよびデシリアライザー (SerDes) クラスによって使用されるスキーマを保存することが含まれます。これらの Java クラスは、Kafka メッセージペイロードをシリアライズ、デシリアライズ、または検証する操作を生成または消費するときに使用するレジストリーからスキーマをフェッチします。
これらのサンプルアプリケーションには、以下が含まれます。
- Apache Avro SerDes
- Google Protobuf SerDes
- JSON Schema SerDes
- Confluent SerDes
- Custom ID strategy
- REST client
- Cloud Events
- Quarkus と Kafka
- Quarkus と Kafka を使用した Apache Camel
関連情報
- 詳細は、 https://github.com/Apicurio/apicurio-registry-examples を参照してください
1.9. Service Registry で利用可能なディストリビューション
Service Registry には、次のディストリビューションオプションがあります。
表1.2 Service Registry Operator およびイメージ
| ディストリビューション | 場所 | リリースカテゴリー |
|---|---|---|
| Service Registry Operator | Operators → OperatorHub の OpenShift Web コンソール | 一般公開 (GA) |
| Service Registry Operator のコンテナーイメージ | 一般公開 (GA) | |
| AMQ Streams での Kafka ストレージのコンテナーイメージ | 一般公開 (GA) | |
| PostgreSQL でのデータベースストレージのコンテナーイメージ | 一般公開 (GA) |
表1.3 Service Registry zip ダウンロード
| ディストリビューション | 場所 | リリースカテゴリー |
|---|---|---|
| Example custom resource definitions for installation | 一般公開 (GA) | |
| Service Registry v1 to v2 migration tool | 一般公開 (GA) | |
| Maven repository | 一般公開 (GA) | |
| Source code | 一般公開 (GA) | |
| Kafka Connect converters | 一般公開 (GA) |
利用可能な Service Registry ディストリビューションにアクセスするには、Red Hat Integration のサブスクリプションが必要で、Red Hat カスタマーポータルにログインする必要があります。
第2章 Service Registry のコンテンツルール
本章では、レジストリーコンテンツを管理するために使用されるオプションのルールを紹介し、利用可能なルール設定の詳細を説明します。
2.1. ルールを使用したレジストリーコンテンツの管理
レジストリーコンテンツの展開を管理するために、レジストリーに追加されるアーティファクトコンテンツの任意のルールを設定できます。設定されたグローバルルールまたはアーティファクトルールはすべて、新しいアーティファクトバージョンをレジストリーにアップロードする前に渡す必要があります。設定されたアーティファクトルールは、設定されたグローバルルールを上書きします。
これらのルールの目的は、無効なコンテンツがレジストリーに追加されないようにすることです。たとえば、次の理由でコンテンツが無効になる可能性があります。
-
特定のアーティファクトタイプ (
AVROやPROTOBUF など) の構文が無効です - 有効な構文で、セマンティクスが仕様に違反している
- 新しいコンテンツに現在のアーティファクトバージョンに関連する変更の違反が含まれる場合の非互換性
Service Registry Web コンソール、REST API コマンド、または Java クライアントアプリケーションを使用して、任意のコンテンツルールを有効にできます。
2.1.1. ルールの適用時
ルールは、コンテンツがレジストリーに追加される場合にのみ適用されます。これには、以下の REST 操作が含まれます。
- アーティファクトの追加
- アーティファクトの更新
- アーティファクトバージョンの追加
ルールに違反した場合、Service Registry は HTTP エラーを返します。応答本文には、違反したルールと、何が問題だったのかを示すメッセージが含まれます。
2.1.2. ルールの優先順位
Service Registry のコンテンツルールは、グローバルレベルおよびアーティファクトレベルで設定できます。優先順位は次のとおりです。
- Artifact ルールと同等のグローバルルールを有効にすると、Artifact ルールがグローバルルールをオーバーライドします。
- Artifact ルールを無効にして、同等のグローバルルールを有効にすると、グローバルルールが適用されます。
- アーティファクトレベルおよびグローバルレベルでルールを無効にすると、すべてのアーティファクトのルールが無効になります。
-
アーティファクトレベルでルール値を
NONEに設定すると、有効なグローバルルールがオーバーライドされます。この場合、アーティファクトルール値NONEがこのアーティファクトでは優先されますが、有効なグローバルルールは、ルールがアーティファクトレベルで無効になっている他のすべてのアーティファクトに引き続き適用されます。
2.1.3. ルールの仕組み
各ルールには、名前と設定情報があります。レジストリーは、各アーティファクトのルール一覧とグローバルルールの一覧を維持します。リスト内の各ルールは、ルール実装の名前と設定で構成されます。
アーティファクトの現在のバージョン (存在する場合) および追加されるアーティファクトの新しいバージョンのコンテンツを含むルールが提供されます。ルール実装は、アーティファクトがルールを渡すかどうかに応じて true または false を返します。そうでない場合、レジストリーはその理由を HTTP エラー応答で報告します。一部のルールは、コンテンツの以前のバージョンを使用しない場合があります。たとえば、互換性ルールは以前のバージョンを使用しますが、構文またはセマンティック妥当性ルールは使用しません。
その他のリソース
詳細は、9章Service Registry アーティファクトの参照 を参照してください。
2.1.4. コンテンツルールの設定
アーティファクトごとに個別にルールを設定することも、グローバルに設定することもできます。Service Registry は、特定のアーティファクトに設定したルールを適用します。そのレベルでルールが設定されていない場合、Service Registry はグローバルに設定されたルールを適用します。グローバルルールが設定されていない場合は、ルールが適用されません。
アーティファクトルールの設定
Service Registry Web コンソールまたは REST API を使用してアーティファクトルールを設定できます。詳細は以下を参照してください。
グローバルルールの設定
グローバルルールは、複数の方法で設定できます。
-
REST API で
/rules操作を使用します - Service Registry Web コンソールの使用
- Service Registry アプリケーションプロパティーを使用したデフォルトのグローバルルールの設定
デフォルトのグローバルルールの設定
アプリケーションレベルで Service Registry を設定して、グローバルなルールを有効または無効にすることができます。以下のアプリケーションプロパティー形式を使用して、インストール後の設定を行わずに、インストール時にデフォルトのグローバルルールを設定できます。
registry.rules.global.<ruleName>
現在、以下のルール名がサポートされています。
-
compatibility -
validity
application プロパティーの値は、設定されたルールに固有の有効な設定オプションである必要があります。
これらのアプリケーションプロパティーは、Java システムプロパティーとして設定することも、Quarkus application.properties ファイルに含めることもできます。詳細は、Quarkus のドキュメント を参照してください。
第3章 Web コンソールを使用した Service Registry コンテンツの管理
本章では、Service Registry Web コンソールを使用して、レジストリーに保存されているスキーマおよび API アーティファクトを管理する方法を説明します。これには、レジストリーコンテンツのアップロードと参照、およびオプションのルールの設定が含まれます。
3.1. Service Registry Web コンソールを使用したアーティファクトの表示
Service Registry Web コンソールを使用して、レジストリーに保存されているイベントスキーマおよび API アーティファクトを参照できます。本セクションでは、Service Registry アーティファクト、グループ、バージョン、およびアーティファクトルールを表示する簡単な例を紹介します。
前提条件
- Service Registry が環境にインストールされ、実行している。
Service Registry Web コンソールにログインしている。
http://MY_REGISTRY_URL/ui- Web コンソール、コマンドライン、Maven プラグイン、または Java クライアントアプリケーションを使用して、アーティファクトが Service Registry に追加されました。
手順
アーティファクト タブで、Service Registry に保存されているアーティファクトのリストを参照するか、検索文字列を入力してアーティファクトを見つけます。リストから選択して、名前、グループ、ラベル、グローバル ID などの特定の条件で検索できます。
図3.1 Service Registry Web コンソールでのアーティファクト

アーティファクトをクリックすると、次の詳細が表示されます。
- 概要: 名前、オプションのグループと ID、グローバル ID、コンテンツ ID、ラベル、プロパティーなどのアーティファクトバージョンのメタデータを表示します。また、アーティファクトコンテンツに対して設定できる有効性および互換性のルールも表示されます。
- ドキュメント (OpenAPI および AsyncAPI のみ): 自動生成された REST API ドキュメントを表示します。
- Content: 全アーティファクトコンテンツの読み取り専用ビューを表示します。JSON コンテンツの場合、JSON または YAML をクリックして、好みの形式を表示できます。
- このアーティファクトの追加バージョンが追加されている場合は、ページヘッダーの バージョン リストから選択できます。
-
アーティファクトの内容を
my-protobuf-schema.protoなどのローカルファイルに保存するには、ページの最後にある Download をクリックします。
3.2. Service Registry Web コンソールを使用したアーティファクトの追加
Service Registry Web コンソールを使用して、イベントスキーマと API アーティファクトをレジストリーにアップロードできます。このセクションでは、Service Registry アーティファクトをアップロードし、新しいアーティファクトバージョンを追加する簡単な例を示します。
前提条件
- Service Registry が環境にインストールされ、実行している。
Service Registry Web コンソールにログインしている。
http://MY_REGISTRY_URL/ui
手順
アーティファクト タブで アーティファクトのアップロード をクリックし、次の詳細を指定します。
-
Group & ID: デフォルトの空の設定を使用して、アーティファクト ID を自動的に生成し、アーティファクトを
デフォルトのアーティファクトグループに追加します。または、オプションのアーティファクトグループ名または ID を入力することもできます。 Type: デフォルトの Auto-Detect 設定を使用してアーティファクトタイプを自動的に検出し、リストからアーティファクトタイプを選択します (例: Avro Schema または OpenAPI)。
注記Service Registry は、Kafka Connect Schema アーティファクトタイプを自動的に検出できません。このアーティファクトタイプを手動で選択する必要があります。
Artifact: 次のいずれかのオプションを使用して、アーティファクトの場所を指定します。
-
ファイルから: Browse をクリックしてファイルを選択するか、ファイルをドラッグアンドドロップします。たとえば、
my-openapi.jsonまたはmy-schema.protoです。 -
URL から: 有効かつアクセス可能な URL を入力し、Fetch をクリックします。例:
https://petstore3.swagger.io/api/v3/openapi.json。
-
ファイルから: Browse をクリックしてファイルを選択するか、ファイルをドラッグアンドドロップします。たとえば、
-
Group & ID: デフォルトの空の設定を使用して、アーティファクト ID を自動的に生成し、アーティファクトを
Upload をクリックし、アーティファクトの詳細を表示します。
- 概要: 名前、アーティファクト ID、グローバル ID、コンテンツ ID、ラベル、プロパティーなどのアーティファクトバージョンのメタデータを表示します。また、アーティファクトコンテンツに対して設定できる有効性および互換性のルールも表示されます。
- ドキュメント (OpenAPI および AsyncAPI のみ): 自動生成された REST API ドキュメントを表示します。
Content: 全アーティファクトコンテンツの読み取り専用ビューを表示します。JSON コンテンツの場合、JSON または YAML をクリックして、好みの形式を表示できます。
次の例は、Protobuf スキーマアーティファクトの例を示しています。
図3.2 Service Registry Web コンソールのアーティファクトの詳細

Overview タブで、Edit 鉛筆アイコンをクリックして、名前や説明などのアーティファクトメタデータを編集します。
オプションで、検索用のラベルのコンマ区切りリストを入力したり、アーティファクトに関連付けられた任意のプロパティーのキーと値のペアを追加したりすることもできます。プロパティーを追加するには、次の手順を実行します。
- Add property をクリックします。
- キー名と値を入力します。
- 複数のプロパティーを追加するには、最初の 2 つの手順を繰り返します。
- Save をクリックします。
-
アーティファクトの内容を
my-protobuf-schema.protoなどのローカルファイルに保存するには、ページの最後にある Download をクリックします。 -
新しいアーティファクトバージョンを追加するには、ページヘッダーで Upload new version をクリックし、ドラッグアンドドロップするか Browse をクリックして、
my-avro-schema.jsonやmy-openapi.jsonなどのファイルをアップロードします。 アーティファクトを削除するには、ページヘッダーの Delete をクリックします。
警告アーティファクトを削除すると、アーティファクトとそのバージョンがすべて削除され、元に戻すことはできません。アーティファクトバージョンはイミュータブルで、個別に削除できません。
3.3. Service Registry Web コンソールを使用したコンテンツルールの設定
Service Registry Web コンソールを使用して、無効なコンテンツがレジストリーに追加されないようにオプションのルールを設定できます。設定されたアーティファクトルールまたはグローバルルールはすべて、新しいアーティファクトバージョンを Service Registry にアップロードする前に渡す必要があります。設定されたアーティファクトルールは、設定されたグローバルルールを上書きします。本セクションでは、グローバルルールとアーティファクトルールを設定する簡単な例を紹介します。
前提条件
- Service Registry が環境にインストールされ、実行している。
Service Registry Web コンソールにログインしている。
http://MY_REGISTRY_URL/ui- Web コンソール、コマンドライン、Maven プラグイン、または Java クライアントアプリケーションを使用して、アーティファクトが Service Registry に追加されました。
手順
- Artifacts タブで、Service Registry のアーティファクトのリストを参照するか、検索文字列を入力してアーティファクトを見つけます。リストから選択して、アーティファクト名、グループ、ラベル、またはグローバル ID などの特定の基準で検索できます。
- アーティファクトをクリックして、そのバージョンの詳細とコンテンツルールを表示します。
Content rules で Enable をクリックして、アーティファクトコンテンツの有効性ルールまたは互換性ルールを設定し、一覧から適切なルール設定を選択します (有効性ルールの場合は Full など)。
図3.3 Service Registry Web コンソールのアーティファクトコンテンツルール

- グローバルルールにアクセスするには、Service Registry インスタンスをクリックし、Global rules タブをクリックします。Enable をクリックして、すべてのアーティファクトコンテンツに対してグローバルな妥当性ルールまたは互換性ルールを設定し、リストから適切なルール設定を選択します。
- アーティファクトルールまたはグローバルルールを無効にするには、ルールの横にあるゴミ箱アイコンをクリックします。
3.4. Web コンソールを使用した Service Registry インスタンス設定の設定
管理者は、Service Registry Web コンソールを使用して、実行時に Service Registry インスタンスの動的設定を指定できます。認証、承認、API 互換性などの機能の設定オプションを管理できます。
Service Registry インスタンスのデプロイ時に認証がすでに有効になっている場合、認証と承認の設定は Web コンソールにのみ表示されます。詳細は、OpenShift での Service Registry のインストールおよびデプロイ を参照してください。
前提条件
- Service Registry インスタンスがすでにデプロイされている。
管理者アクセスで Service Registry Web コンソールにログインしている。
http://MY_REGISTRY_URL/ui
手順
- Service Registry Web コンソールで、Settings タブをクリックします。
この Service Registry インスタンスに対して設定するオプションを選択します。
表3.1 認証設定
設定 説明 HTTP Basic 認証
認証が有効な場合のみ表示されます。選択すると、Service Registry ユーザーは、OAuth に加えて HTTP 基本認証を使用して認証できます。デフォルトでは選択されていません。
表3.2 認可設定
設定 説明 匿名の読み取りアクセス
すでに認証が選択されている場合のみ表示されます。選択すると、Service Registry は、認証情報がない匿名ユーザーからの要求に対して、読み取り専用アクセスを許可します。この設定は、このインスタンスを使用してスキーマまたは API を外部に公開する場合に役立ちます。デフォルトでは選択されていません。
アーティファクトの所有者のみの承認
認証が有効な場合のみ表示されます。選択すると、アーティファクトを作成したユーザーのみがそのアーティファクトを変更できます。デフォルトでは選択されていません。
アーティファクトグループの所有者のみの承認
認証がすでに有効で、Artifact 所有者のみの許可 が選択されている場合にのみ表示されます。選択すると、アーティファクトグループを作成したユーザーのみが、そのアーティファクトグループへの書き込みアクセス権 (そのグループのアーティファクトの追加や削除など) を持ちます。デフォルトでは選択されていません。
認証された読み取りアクセス
認証が有効な場合のみ表示されます。選択すると、Service Registry は、ユーザーロールに関係なく、認証されたユーザーからのリクエストに対して、少なくとも読み取り専用アクセスを許可します。デフォルトでは選択されていません。
表3.3 互換性設定
設定 説明 レガシー ID モード (互換 API)
選択すると、Confluent Schema Registry 互換性 API は
contentIdの代わりにglobalIdをアーティファクト識別子として使用します。この設定は、v1 Core Registry API をベースにする、従来の Service Registry インスタンスから移行する場合に役立ちます。デフォルトでは選択されていません。表3.4 Web コンソールの設定
設定 説明 ダウンロードリンクの有効期限
インスタンスからアーティファクトデータをエクスポートする場合など、セキュリティー上の理由で有効期限が切れる前に、生成された
.zipダウンロードファイルへのリンクがアクティブである秒数。デフォルトは 30 秒です。UI 読み取り専用モード
選択すると、Service Registry Web コンソールが読み取り専用に設定され、作成、読み取り、更新、または削除操作が禁止されます。Core Registry API を使用して行われた変更は、この設定の影響を受けません。デフォルトでは選択されていません。
3.5. Service Registry Web コンソールを使用したアーティファクト所有者の変更
管理者として、またはスキーマまたは API アーティファクトの所有者として、Service Registry Web コンソールを使用して、アーティファクトの所有者を別のユーザーアカウントに変更できます。
たとえば、この機能は、所有者または管理者のみがアーティファクトを変更できるように、Settings タブでService Registry インスタンスに対して アーティファクトの所有者のみの許可 オプションが設定されている場合に役立ちます。所有者ユーザーが組織を離れた場合、または所有者アカウントが削除された場合は、所有者の変更が必要になる場合があります。
アーティファクトの所有者のみの承認 設定とアーティファクトの 所有者 フィールドは、Service Registry インスタンスのデプロイ時に認証が有効になっている場合に のみ 表示されます。詳細は、Installing and deploying Service Registry on OpenShiftを参照してください。
前提条件
- Service Registry インスタンスがデプロイされ、アーティファクトが作成されている。
アーティファクトの現在の所有者または管理者として Service Registry Web コンソールにログインしている。
http://MY_REGISTRY_URL/ui
手順
- アーティファクト タブで、Service Registry に保存されているアーティファクトのリストを参照するか、検索文字列を入力してアーティファクトを見つけます。リストから選択して、名前、グループ、ラベル、グローバル ID などの条件で検索できます。
- 再割り当てするアーティファクトをクリックします。
- Version metadata セクションで、Owner フィールドの横にある鉛筆アイコンをクリックします。
- New owner フィールドで、アカウント名を選択または入力します。
- Change owner をクリックします。
3.6. Service Registry Web コンソールを使用したレジストリーコンテンツのエクスポートとインポート
管理者は、Service Registry Web コンソールを使用して、ある Service Registry インスタンスからデータをエクスポートし、それを別の Service Registry インスタンスにインポートできます。この機能を使用して、異なるインスタンス間でデータを簡単に移行できます。
次の例は、Service Registry インスタンス間で .zip ファイル内の既存のデータをエクスポートおよびインポートする方法を示しています。Service Registry インスタンスに含まれるすべてのアーティファクトデータは、.zip ファイルにエクスポートされます。
別の Service Registry インスタンスからエクスポートされた Service Registry データのみをインポートできます。
前提条件
Service Registry インスタンスは次のように作成されている。
- エクスポート元のソースインスタンスには、少なくとも 1 つのスキーマまたは API アーティファクトが含まれている
- インポート先のターゲットインスタンスは、一意の ID を保持するために空である
管理者アクセスで Service Registry Web コンソールにログインしている。
http://MY_REGISTRY_URL/ui
手順
- ソース Service Registry インスタンスの Web コンソールで、Artifacts タブを表示します。
-
Upload artifact の横にあるオプションアイコン (3 つの縦リーダー) をクリックし、Download all artifacts (.zip file) を選択して、このインスタンスのレジストリーデータを
.zipダウンロードファイルにエクスポートします。 - ターゲット Service Registry インスタンスの Web コンソールで、Artifacts タブを表示します。
- Upload artifact の横にあるオプションアイコンをクリックし、Upload multiple artifacts を選択します。
-
以前にエクスポートした
.zipダウンロードファイルをドラッグアンドドロップするか、参照します。 - Upload をクリックして、データがインポートされるまで待ちます。
第4章 REST API を使用した Service Registry コンテンツの管理
クライアントアプリケーションは、Registry REST API 操作を使用して、Service Registry のスキーマおよび API アーティファクトを管理できます (例: 実稼働環境用にデプロイされる CI/CD パイプラインなど)。Registry REST API は、レジストリーに保存されるアーティファクト、バージョン、メタデータ、およびルールの作成、読み取り、更新、および削除操作を提供します。詳細は、Apicurio Registry REST API のドキュメント を参照してください。
本章では、Service Registry core REST API について説明し、これを使用してレジストリーに保存されているスキーマおよび API アーティファクトを管理する方法を説明します。
その他のリソース
4.1. Service Registry REST API コマンドを使用したスキーマおよび API アーティファクトの管理
このセクションでは、Service Registry コア REST API を使用して、Service Registry で Apache Avro スキーマアーティファクトを追加および取得する簡単な curl ベースの例を示します。
前提条件
- Service Registry が環境にインストールされ、実行している
手順
/groups/{group}/artifacts操作を使用してアーティファクトをレジストリーに追加します。以下のcurlコマンドの例は、株価アプリケーションの単純なアーティファクトを追加します。$ curl -X POST -H "Content-Type: application/json; artifactType=AVRO" \ -H "X-Registry-ArtifactId: share-price" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ --data '{"type":"record","name":"price","namespace":"com.example", \ "fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}' \ MY-REGISTRY-URL/apis/registry/v2/groups/my-group/artifacts-
この例では、
share-priceのアーティファクト ID を持つ Avro スキーマアーティファクトを追加します。一意のアーティファクト ID を指定しない場合、Service Registry は UUID として自動的に生成します。 -
MY-REGISTRY-URLは、Service Registry がデプロイされているホスト名です。例:my-cluster-service-registry-myproject.example.com。 -
この例では、API パスで
my-groupのグループ ID を指定します。一意のグループ ID を指定しない場合は、API パスで../groups/defaultを指定する必要があります。
-
この例では、
応答に、アーティファクトが追加されたことを確認するために、想定される JSON ボディーが含まれていることを確認します。以下に例を示します。
{"createdBy":"","createdOn":"2021-04-16T09:07:51+0000","modifiedBy":"", "modifiedOn":"2021-04-16T09:07:51+0000","id":"share-price","version":"1", "type":"AVRO","globalId":2,"state":"ENABLED","groupId":"my-group","contentId":2}-
アーティファクトの追加時にバージョンが指定されなかったため、デフォルトのバージョン
1が自動的に作成されます。 -
これはレジストリーに追加された 2 つ目のアーティファクトであるため、グローバル ID とコンテンツ ID の値は
2になります。
-
アーティファクトの追加時にバージョンが指定されなかったため、デフォルトのバージョン
API パスでアーティファクト ID を使用して、レジストリーからアーティファクトコンテンツを取得します。この例では、指定された ID は
share-priceです。$ curl -H "Authorization: Bearer $ACCESS_TOKEN" \ MY-REGISTRY-URL/apis/registry/v2/groups/my-group/artifacts/share-price \ {"type":"record","name":"price","namespace":"com.example", "fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}
関連情報
- REST API のサンプル要求の詳細は、Apicurio Registry REST API のドキュメント を参照してください。
4.2. Service Registry REST API コマンドを使用したスキーマおよび API アーティファクトのバージョンの管理
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 を使用してアーティファクトを追加または更新したり、アーティファクトバージョンを追加したりするときにカスタムバージョンを指定できます。
前提条件
- Service Registry が環境にインストールされ、実行している
手順
/groups/{group}/artifacts操作を使用して、レジストリーにアーティファクトバージョンを追加します。以下のcurlコマンドの例は、株価アプリケーションの単純なアーティファクトを追加します。$ curl -X POST -H "Content-Type: application/json; artifactType=AVRO" \ -H "X-Registry-ArtifactId: my-share-price" -H "X-Registry-Version: 1.1.1" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ --data '{"type":"record","name":" p","namespace":"com.example", \ "fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}' \ MY-REGISTRY-URL/apis/registry/v2/groups/my-group/artifacts-
この例では、アーティファクト ID が
my-share-priceでバージョンが1.1.1の Avro スキーマアーティファクトを追加します。バージョンを指定しないと、Service Registry によってデフォルトのバージョン1が自動的に生成されます。 -
MY-REGISTRY-URLは、Service Registry がデプロイされているホスト名です。例:my-cluster-service-registry-myproject.example.com。 -
この例では、API パスで
my-groupのグループ ID を指定します。一意のグループ ID を指定しない場合は、API パスで../groups/defaultを指定する必要があります。
-
この例では、アーティファクト ID が
応答に、カスタムアーティファクトバージョンが追加されたことを確認するために、想定される JSON ボディーが含まれていることを確認します。以下に例を示します。
{"createdBy":"","createdOn":"2021-04-16T10:51:43+0000","modifiedBy":"", "modifiedOn":"2021-04-16T10:51:43+0000","id":"my-share-price","version":"1.1.1", "type":"AVRO","globalId":3,"state":"ENABLED","groupId":"my-group","contentId":3}-
アーティファクトの追加時に、
1.1.1のカスタムバージョンが指定されました。 -
これはレジストリーに追加された 3 つ目のアーティファクトであるため、グローバル ID とコンテンツ ID の値は
3になります。
-
アーティファクトの追加時に、
API パスでアーティファクト ID とバージョンを使用して、レジストリーからアーティファクトコンテンツを取得します。この例では、指定された ID は
my-share-priceであり、バージョンは1.1.1です。$ curl -H "Authorization: Bearer $ACCESS_TOKEN" \ MY-REGISTRY-URL/apis/registry/v2/groups/my-group/artifacts/my-share-price/versions/1.1.1 {"type":"record","name":"price","namespace":"com.example", "fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}
関連情報
- REST API のサンプル要求の詳細は、Apicurio Registry REST API のドキュメント を参照してください。
4.3. Service Registry REST API コマンドを使用したアーティファクト参照の管理
Apache Avro、Protobuf、JSON スキーマなどの Service Registry アーティファクトタイプには、あるアーティファクトファイルから別のアーティファクトファイルへの アーティファクト参照 を含めることができます。再利用可能なスキーマと API アーティファクトを定義し、それらを複数の場所から参照することで、効率を高めることができます。
このセクションでは、Service Registry コア REST API を使用して、Service Registry の単純な Avro スキーマアーティファクトへのアーティファクト参照を追加および取得する簡単な curl ベースの例を示します。
この例では、最初に ItemId という名前のスキーマアーティファクトを作成します。
ItemId スキーマ
{
"namespace":"com.example.common",
"name":"ItemId",
"type":"record",
"fields":[
{
"name":"id",
"type":"int"
}
]
}
次に、この例では、ネストされた ItemId アーティファクトへの参照を含む、Item という名前のスキーマアーティファクトを作成します。
ネストされた ItemId スキーマを持つアイテムスキーマ
{
"namespace":"com.example.common",
"name":"Item",
"type":"record",
"fields":[
{
"name":"itemId",
"type":"com.example.common.ItemId"
},
]
}
前提条件
- Service Registry が環境にインストールされ、実行している
手順
/groups/{group}/artifactsオペレーションを使用して、ネストされたアーティファクト参照を作成するItemIdスキーマアーティファクトを追加します。$ curl -X POST MY-REGISTRY-URL/apis/registry/v2/groups/my-group/artifacts \ -H "Content-Type: application/json; artifactType=AVRO" \ -H "X-Registry-ArtifactId: ItemId" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ --data '{"namespace": "com.example.common", "type": "record", "name": "ItemId", "fields":[{"name":"id", "type":"int"}]}'-
この例では、
ItemIdのアーティファクト ID を持つ Avro スキーマ アーティファクトを追加します。一意のアーティファクト ID を指定しない場合、Service Registry は UUID として自動的に生成します。 -
MY-REGISTRY-URLは、Service Registry がデプロイされているホスト名です。例:my-cluster-service-registry-myproject.example.com。 -
この例では、API パスで
my-groupのグループ ID を指定します。一意のグループ ID を指定しない場合は、API パスで../groups/defaultを指定する必要があります。
-
この例では、
応答に、アーティファクトが追加されたことを確認するために、想定される JSON ボディーが含まれていることを確認します。以下に例を示します。
{"name":"ItemId","createdBy":"","createdOn":"2022-04-14T10:50:09+0000","modifiedBy":"","modifiedOn":"2022-04-14T10:50:09+0000","id":"ItemId","version":"1","type":"AVRO","globalId":1,"state":"ENABLED","groupId":"my-group","contentId":1,"references":[]}/groups/{group}/artifacts操作を使用して、ItemIdスキーマへのアーティファクト参照を含むアイテムスキーマアーティファクトを追加します。$ curl -X POST MY-REGISTRY-URL/apis/registry/v2/groups/my-group/artifacts \ -H 'Content-Type: application/create.extended+json' \ -H "X-Registry-ArtifactId: Item" \ -H 'X-Registry-ArtifactType: AVRO' \ -H "Authorization: Bearer $ACCESS_TOKEN" \ --data-raw '{ "content": "{\r\n \"namespace\":\"com.example.common\",\r\n \"name\":\"Item\",\r\n \"type\":\"record\",\r\n \"fields\":[\r\n {\r\n \"name\":\"itemId\",\r\n \"type\":\"com.example.common.ItemId\"\r\n }\r\n ]\r\n}", "references": [ { "groupId": "my-group", "artifactId": "ItemId", "name": "com.example.common.ItemId", "version": "1" } ] }'-
アーティファクト参照の場合には、
application/jsonコンテンツタイプを拡張するapplication/create.extended+jsonのカスタムコンテンツタイプを指定する必要があります。
-
アーティファクト参照の場合には、
アーティファクトが参照を使用して作成されたことを確認するために、予期される JSON 本文が応答に含まれていることを確認します。以下に例を示します。
{"name":"Item","createdBy":"","createdOn":"2022-04-14T11:52:15+0000","modifiedBy":"","modifiedOn":"2022-04-14T11:52:15+0000","id":"Item","version":"1","type":"AVRO","globalId":2,"state":"ENABLED","groupId":"my-group","contentId":2,"references":[1]}参照を含むアーティファクトのグローバル ID を指定して、Service Registry からアーティファクト参照を取得します。この例では、指定されたグローバル ID は
2です。$ curl MY-REGISTRY-URL/apis/registry/v2/ids/globalIds/2/references
応答に、このアーティファクト参照に必要とされる JSON 本文が含まれていることを確認してください。以下に例を示します。
[{"groupId":"my-group","artifactId":"ItemId","version":"1","name":"com.example.common.ItemId"}]
関連情報
- 詳細は、Apicurio Registry REST API のドキュメント を参照してください。
4.4. Service Registry REST API コマンドを使用したレジストリーコンテンツのエクスポートとインポート
管理者は、Service Registry REST API を使用して、ある Service Registry インスタンスからデータをエクスポートし、それを別の Service Registry インスタンスにインポートできるため、異なるインスタンス間でデータを移行できます。
本セクションでは、コアレジストリー v2 REST API を使用して、既存のレジストリーデータをある Service Registry インスタンスから別の Service Registry インスタンスに .zip 形式でエクスポートおよびインポートするシンプルな curl ベースの例を示します。Service Registry インスタンスに含まれるすべてのアーティファクトデータは、.zip ファイルにエクスポートされます。
別の Service Registry インスタンスからエクスポートされた Service Registry データのみをインポートできます。
前提条件
- Service Registry が環境にインストールされ、実行している
Service Registry インスタンスが作成されている。
- データのエクスポート元のソースインスタンスには、少なくとも 1 つのスキーマまたは API アーティファクトが含まれている
- データをインポートするターゲットインスタンスは、一意の ID を保持するために空である
手順
既存のソースの Service Registry インスタンスからレジストリーデータをエクスポートします。
$ curl MY-REGISTRY-URL/apis/registry/v2/admin/export \ -H "Authorization: Bearer $ACCESS_TOKEN" \ --output my-registry-data.zip
MY-REGISTRY-URLは、ソース ServiceRegistry がデプロイされているホスト名です。例:my-cluster-source-registry-myproject.example.com。レジストリーデータをターゲット Service Registry インスタンスにインポートします。
$ curl -X POST "MY-REGISTRY-URL/apis/registry/v2/admin/import" \ -H "Content-Type: application/zip" -H "Authorization: Bearer $ACCESS_TOKEN" \ --data-binary @my-registry-data.zip
MY-REGISTRY-URLは、ターゲットの Service Registry がデプロイされているホスト名です。例:my-cluster-target-registry-myproject.example.com。
関連情報
-
詳細は、Apicurio Registry REST API documentation の
adminエンドポイントを参照してください。 - Service Registry バージョン 1.x から 2.x に移行するためのエクスポートツールの詳細については、Apicurio Registry export utility for 1.x versions を参照してください。
第5章 Maven プラグインを使用した Service Registry コンテンツの管理
本章では、Service Registry Maven プラグインを使用して、レジストリーに保存されているスキーマおよび API アーティファクトを管理する方法を説明します。
前提条件
- 1章Service Registry の概要 を参照
- Service Registry が環境にインストールされ、実行されている。
- Maven が使用している環境にインストールおよび設定されている。
5.1. Maven プラグインを使用したスキーマおよび API アーティファクトの追加
Maven プラグインの最も一般的なユースケースは、ビルド中にアーティファクトを追加することです。これは、register 実行目標を使用して実現できます。
前提条件
- Service Registry が環境にインストールされ、実行している
手順
Maven pom.xml ファイルを更新して、 apicurio-registry-maven-plugin を使用してアーティファクトを登録します。以下の例は、Apache Avro および GraphQL スキーマの登録を示しています。
<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>MY-REGISTRY-URL/apis/registry/v2</registryUrl> 2
<authServerUrl>MY-AUTH-SERVER</authServerUrl>
<clientId>MY-CLIENT-ID</clientId>
<clientSecret>MY-CLIENT-SECRET</clientSecret> 3
<artifacts>
<artifact>
<groupId>TestGroup</groupId> 4
<artifactId>FullNameRecord</artifactId>
<file>${project.basedir}/src/main/resources/schemas/record.avsc</file>
<ifExists>FAIL</ifExists>
</artifact>
<artifact>
<groupId>TestGroup</groupId>
<artifactId>ExampleAPI</artifactId> 5
<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>-
スキーマアーティファクトをレジストリーにアップロードするための実行目標として
registerを指定します。 -
../apis/registry/v2エンドポイントでService Registry URL を指定します。 - 認証が必要な場合は、認証サーバーおよびクライアントの認証情報を指定できます。
-
Service Registry アーティファクトグループ ID を指定します。一意のグループ ID を使用しない場合は、
defaultのグループを指定できます。 - 指定したグループ ID、アーティファクト ID、および場所を使用して複数のアーティファクトを登録できます。
5.2. Maven プラグインを使用したスキーマおよび API アーティファクトのダウンロード
Maven プラグインを使用して Service Registry からアーティファクトをダウンロードできます。これは、たとえば、登録されたスキーマからコードを生成する場合などに便利です。
前提条件
- Service Registry が環境にインストールされ、実行している
手順
Maven pom.xml ファイルを更新して、apicurio-registry-maven-plugin を使用してアーティファクトをダウンロードします。以下の例は、Apache Avro および GraphQL スキーマのダウンロードを示しています。
<plugin>
<groupId>io.apicurio</groupId>
<artifactId>apicurio-registry-maven-plugin</artifactId>
<version>${apicurio.version}</version>
<executions>
<execution>
<phase>generate-sources</phase>
<goals>
<goal>download</goal> 1
</goals>
<configuration>
<registryUrl>MY-REGISTRY-URL/apis/registry/v2</registryUrl> 2
<authServerUrl>MY-AUTH-SERVER</authServerUrl>
<clientId>MY-CLIENT-ID</clientId>
<clientSecret>MY-CLIENT-SECRET</clientSecret> 3
<artifacts>
<artifact>
<groupId>TestGroup</groupId> 4
<artifactId>FullNameRecord</artifactId> 5
<file>${project.build.directory}/classes/record.avsc</file>
<overwrite>true</overwrite>
</artifact>
<artifact>
<groupId>TestGroup</groupId>
<artifactId>ExampleAPI</artifactId>
<version>1</version>
<file>${project.build.directory}/classes/example.graphql</file>
<overwrite>true</overwrite>
</artifact>
</artifacts>
</configuration>
</execution>
</executions>
</plugin>-
実行目標として
downloadを指定します。 -
../apis/registry/v2エンドポイントでService Registry URL を指定します。 - 認証が必要な場合は、認証サーバーおよびクライアントの認証情報を指定できます。
-
Service Registry アーティファクトグループ ID を指定します。一意のグループを使用しない場合は、
defaultのグループを指定できます。 - アーティファクト ID を使用すると、複数のアーティファクトを指定したディレクトリーにダウンロードできます。
5.3. Service Registry Maven プラグインを使用したアーティファクト参照の追加
Apache Avro、Protobuf、JSON スキーマなどの Service Registry アーティファクトタイプには、あるアーティファクトファイルから別のアーティファクトファイルへの アーティファクト参照 を含めることができます。再利用可能なスキーマと API アーティファクトを定義し、アーティファクト参照で複数の場所から参照して、効率を高めることができます。
このセクションでは、Service Registry Maven プラグインを使用して、Service Registry に格納されている単純な Avro スキーマアーティファクトへのアーティファクト参照を登録する簡単な例を示します。この例では、次の Exchange スキーマアーティファクトが Service Registry にすでに作成されていることを前提としています。
交換スキーマ
{
"namespace": "com.kubetrade.schema.common",
"type": "enum",
"name": "Exchange",
"symbols" : ["GEMINI"]
}
次に、この例では、ネストされた Exchange スキーマアーティファクトへの参照を含む TradeKey スキーマアーティファクトを作成します。
ネストされた Exchange スキーマを持つ TradeKey スキーマ
{
"namespace": "com.kubetrade.schema.trade",
"type": "record",
"name": "TradeKey",
"fields": [
{
"name": "exchange",
"type": "com.kubetrade.schema.common.Exchange"
},
{
"name": "key",
"type": "string"
}
]
}
前提条件
- Service Registry が環境にインストールされ、実行している
-
Exchangeスキーマアーティファクトは Service Registry にすでに作成されている
手順
apicurio-registry-maven-plugin を使用して TradeKey スキーマを登録するように Maven pom.xml ファイルを更新します。これには、次のように Exchange スキーマへのネストされた参照が含まれます。
<plugin>
<groupId>io.apicurio</groupId>
<artifactId>apicurio-registry-maven-plugin</artifactId>
<version>${apicurio-registry.version}</version>
<executions>
<execution>
<id>register-artifact</id>
<goals>
<goal>register</goal> 1
</goals>
<configuration>
<registryUrl>MY-REGISTRY-URL/apis/registry/v2</registryUrl> 2
<authServerUrl>MY-AUTH-SERVER</authServerUrl>
<clientId>MY-CLIENT-ID</clientId>
<clientSecret>MY-CLIENT-SECRET</clientSecret> 3
<artifacts>
<artifact>
<groupId>test-group</groupId> 4
<artifactId>TradeKey</artifactId>
<version>2.0</version>
<type>AVRO</type>
<file>
${project.basedir}/src/main/resources/schemas/TradeKey.avsc
</file>
<ifExists>RETURN_OR_UPDATE</ifExists>
<canonicalize>true</canonicalize>
<references>
<reference> 5
<name>com.kubetrade.schema.common.Exchange</name>
<groupId>test-group</groupId>
<artifactId>Exchange</artifactId>
<version>2.0</version>
<type>AVRO</type>
<file>
${project.basedir}/src/main/resources/schemas/Exchange.avsc
</file>
<ifExists>RETURN_OR_UPDATE</ifExists>
<canonicalize>true</canonicalize>
</reference>
</references>
</artifact>
</artifacts>
</configuration>
</execution>
</executions>
</plugin>-
スキーマアーティファクトをレジストリーにアップロードするための実行目標として
registerを指定します。 -
../apis/registry/v2エンドポイントでService Registry URL を指定します。 - 認証が必要な場合は、認証サーバーおよびクライアントの認証情報を指定できます。
-
Service Registry アーティファクトグループ ID を指定します。一意のグループ ID を使用しない場合は、
defaultのグループを指定できます。 - グループ ID、アーティファクト ID、バージョン、タイプ、および場所を使用して、Service Registry アーティファクト参照を指定します。この方法で、複数のアーティファクト参照を登録できます。
5.4. Maven プラグインを使用したスキーマおよび API アーティファクトのテスト
実際にアーティファクトを変更せずに、アーティファクトをが登録できることを確認する場合があります。これは、ルールが Service Registry に設定されている場合に役に立ちます。アーティファクトのコンテンツが設定済みのルールのいずれかに違反する場合、アーティファクトのテストに失敗します。
Maven プラグインを使用してアーティファクトをテストする場合には、アーティファクトがテストに合格しても、Service Registry にコンテンツが追加されません。
前提条件
- Service Registry が環境にインストールされ、実行されている。
手順
Maven pom.xml ファイルを更新して、 apicurio-registry-maven-plugin を使用してアーティファクトをテストします。Apache Avro スキーマのテストの例を以下に示します。
<plugin>
<groupId>io.apicurio</groupId>
<artifactId>apicurio-registry-maven-plugin</artifactId>
<version>${apicurio.version}</version>
<executions>
<execution>
<phase>generate-sources</phase>
<goals>
<goal>test-update</goal> 1
</goals>
<configuration>
<registryUrl>MY-REGISTRY-URL/apis/registry/v2</registryUrl> 2
<authServerUrl>MY-AUTH-SERVER</authServerUrl>
<clientId>MY-CLIENT-ID</clientId>
<clientSecret>MY-CLIENT-SECRET</clientSecret> 3
<artifacts>
<artifact>
<groupId>TestGroup</groupId> 4
<artifactId>FullNameRecord</artifactId>
<file>${project.basedir}/src/main/resources/schemas/record.avsc</file> 5
</artifact>
<artifact>
<groupId>TestGroup</groupId>
<artifactId>ExampleAPI</artifactId>
<type>GRAPHQL</type>
<file>${project.basedir}/src/main/resources/apis/example.graphql</file>
</artifact>
</artifacts>
</configuration>
</execution>
</executions>
</plugin>-
スキーマアーティファクトをテストするための実行目標として
test-updateを指定します。 -
../apis/registry/v2エンドポイントでService Registry URL を指定します。 - 認証が必要な場合は、認証サーバーおよびクライアントの認証情報を指定できます。
-
Service Registry アーティファクトグループ ID を指定します。一意のグループを使用しない場合は、
defaultのグループを指定できます。 - アーティファクト ID を使用すると、指定のディレクトリーから複数のアーティファクトをテストできます。
第6章 Java クライアントを使用した Service Registry コンテンツの管理
本章では、Service Registry Java クライアントを使用する方法を説明します。
6.1. Service Registry Java クライアント
Java クライアントアプリケーションを使用して、Service Registry に保存されているアーティファクトを管理できます。Service Registry Java クライアントクラスを使用して、レジストリーに保存されているアーティファクトを作成、読み取り、更新、または削除できます。グローバルなルールの管理やレジストリーデータのインポートおよびエクスポートなど、クライアントを使用して管理機能を実行することもできます。
正しい依存関係をプロジェクトに追加すると、Service Registry Java クライアントにアクセスできます。詳細は、「Service Registry Java クライアントアプリケーションの作成」 を参照してください。
Service Registry クライアントは、JDK によって提供される HTTP クライアントを使用して実装されます。これにより、カスタムヘッダーの追加や TLS (Transport Layer Security) 認証のオプションの有効化など、使用をカスタマイズすることができます。詳細は、「Service Registry Java クライアント設定」 を参照してください。
6.2. Service Registry Java クライアントアプリケーションの作成
本セクションでは、Java クライアントアプリケーションを使用して Service Registry に保存されているアーティファクトを管理する方法を説明します。
前提条件
- Service Registry が環境にインストールされ、実行している
手順
以下の依存関係を Maven プロジェクトに追加します。
<dependency> <groupId>io.apicurio</groupId> <artifactId>apicurio-registry-client</artifactId> <version>${apicurio-registry.version}</version> </dependency>以下のようにレジストリークライアントを作成します。
public class ClientExample { private static final RegistryRestClient client; public static void main(String[] args) throws Exception { // Create a registry client String registryUrl = "https://my-registry.my-domain.com/apis/registry/v2"; RegistryClient client = RegistryClientFactory.create(registryUrl); } }-
https://my-registry.my-domain.comのサンプルレジストリー URL を指定すると、クライアントは自動的に/apis/registry/v2を追加します。 - Service Registry クライアント作成時の他のオプションは、次のセクションの Java クライアント設定を参照してください。
-
クライアントが作成されると、Service Registry REST API で使用可能なすべての操作をクライアントで使用できます。詳細は、Apicurio Registry REST API のドキュメント を参照してください。
その他のリソース
- Service Registry クライアントを使用およびカスタマイズする方法のオープンソースの例については、Registry REST クライアントのデモの例 を参照してください。
- プロデューサーおよびコンシューマーアプリケーションで Service Registry Kafka クライアントシリアライザー/デシリアライザー (SerDes) を使用する方法は、7章Java クライアントでシリアライザー/デシリアライザーを使用した Kafka メッセージの検証 を参照してください。
6.3. Service Registry Java クライアント設定
Service Registry Java クライアントには、クライアントファクトリーを基にした以下の設定オプションが含まれます。
表6.1 Service Registry Java クライアント設定オプション
| オプション | 説明 | 引数 |
|---|---|---|
| プレーンクライアント | 実行中のレジストリーと対話するために使用される基本的な REST クライアント。 |
|
| カスタム設定のあるクライアント | ユーザーによって提供される設定を使用するレジストリークライアント。 |
|
| カスタム設定および認証のあるクライアント | カスタム設定を含むマップを受け入れるレジストリークライアント。たとえば、これは、呼び出しにカスタムヘッダーを追加する場合に便利です。リクエストを認証するための認証サーバーも提供する必要があります。 |
|
カスタムヘッダー設定
カスタムヘッダーを設定するには、configs マップキーに apicurio.registry.request.headers 接頭辞を追加する必要があります。たとえば、値が Basic:xxxxx の apicurio.registry.request.headers.Authorization のキーは、値が Basic: xxxxx の Authorization のヘッダーになります。
TLS 設定オプション
以下のプロパティーを使用して、Service Registry Java クライアントの Transport Layer Security (TLS) 認証を設定できます。
-
apicurio.registry.request.ssl.truststore.location -
apicurio.registry.request.ssl.truststore.password -
apicurio.registry.request.ssl.truststore.type -
apicurio.registry.request.ssl.keystore.location -
apicurio.registry.request.ssl.keystore.password -
apicurio.registry.request.ssl.keystore.type -
apicurio.registry.request.ssl.key.password
関連情報
- Service Registry Kafka クライアントシリアライザー/デシリアライザー (SerDes) の認証を設定する方法の詳細は、7章Java クライアントでシリアライザー/デシリアライザーを使用した Kafka メッセージの検証 を参照してください。
第7章 Java クライアントでシリアライザー/デシリアライザーを使用した Kafka メッセージの検証
Service Registry によって、Java で書かれた Kafka プロデューサーおよびコンシューマーアプリケーションのクライアントシリアライザー/デシリアライザー (SerDes) が提供されます。Kafka プロデューサーアプリケーションは、シリアライザーを使用して、特定のイベントスキーマに準拠するメッセージをエンコードします。Kafka コンシューマーアプリケーションはデシリアライザーを使用して、特定のスキーマ ID に基づいてメッセージが適切なスキーマを使用してシリアライズされたことを検証します。これにより、スキーマが一貫して使用されるようにし、実行時にデータエラーが発生しないようにします。
本章では、プロデューサーおよびコンシューマークライアントアプリケーションで Kafka クライアント SerDes を使用する方法について説明します。
前提条件
- 1章Service Registry の概要 を読む。
- Service Registry がインストールされている。
Kafka プロデューサーおよびコンシューマークライアントアプリケーションが作成済みである。
Kafka クライアントアプリケーションの詳細は OpenShift での AMQ Streams のデプロイとアップグレード を参照してください。
7.1. Kafka クライアントアプリケーションおよび Service Registry
Service Registry は、クライアントアプリケーション設定からスキーマ管理を分離します。クライアントコードに URL を指定すると、Java クライアントアプリケーションが Service Registry からスキーマを使用できます。
Service Registry にスキーマを保存して、メッセージをシリアライズおよびデシリアライズできます。クライアントアプリケーションからスキーマが参照され、送受信されるメッセージとこれらのスキーマの互換性を維持するようにします。Kafka クライアントアプリケーションは実行時にスキーマを Service Registry からプッシュまたはプルできます。
スキーマは進化するので、Service Registry でルールを定義できます。たとえば、スキーマの変更が有効で、アプリケーションによって使用される以前のバージョンとの互換性を維持するようにします。Service Registry は、変更済みのスキーマと以前のスキーマバージョンを比較することで、互換性をチェックします。
Service Registry スキーマテクノロジー
Service Registry は、以下のようなスキーマテクノロジーのスキーマレジストリーサポートを提供します。
- Avro
- Protobuf
- JSON スキーマ
これらのスキーマテクノロジーは、Service Registry によって提供される Kafka クライアントのシリアライザー/デシリアライザー (SerDes) サービスを介してクライアントアプリケーションで使用できます。Service Registry によって提供される SerDes クラスの成熟度および使用法は異なる場合があります。以降のセクションでは、各スキーマタイプの詳細を提供します。
プロデューサースキーマの設定
プロデューサークライアントアプリケーションは、シリアライザーを使用して、特定のブローカートピックに送信するメッセージを正しいデータ形式にします。
プロデューサーが Service Registry を使用してシリアライズできるようにするには、以下を行います。
- スキーマを Service Registry に定義、登録します (存在しない場合)。
以下を使用して プロデューサークライアントコードの設定を行います。
- Service Registry の URL
- メッセージで使用する Service Registry シリアライザー
- Kafka メッセージを Service Registry のスキーマアーティファクトにマップするストラテジー
- Service Registry でのシリアライズに使用するスキーマを検索または登録するストラテジー
スキーマを登録したら、Kafka および Service Registry を開始するときに、スキーマにアクセスして、プロデューサーにより Kafka ブローカートピックに送信されるメッセージをフォーマットできます。または、設定に応じて、プロデューサーは最初の使用時にスキーマを自動的に登録できます。
スキーマがすでに存在する場合、Service Registry に定義される互換性ルールに基づいて、レジストリー REST API を使用して新バージョンのスキーマを作成できます。バージョンは、スキーマの進化にともなう互換性チェックに使用します。グループ ID、アーティファクト ID、およびバージョンは、スキーマを識別する一意のタプルを表します。
コンシューマースキーマの設定
コンシューマークライアントアプリケーションは、デシリアライザーを使用することで、そのアプリケーションが消費するメッセージを特定のブローカートピックから正しいデータ形式にします。
コンシューマーがデシリアライズに Service Registry を使用できるようにするには、以下を実行します。
- スキーマを Service Registry に定義、登録します (存在しない場合)。
以下を使用して コンシューマークライアントコードを設定します。
- Service Registry の URL
- メッセージで使用する Service Registry デシリアライザー
- デシリアライズの入力データストリーム
グローバル ID を使用したスキーマの取得
デフォルトでは、スキーマは、消費されるメッセージに指定されるグローバル ID を使用してデシリアライザーによって Service Registry から取得されます。スキーマグローバル ID は、プロデューサーアプリケーションの設定に応じて、メッセージヘッダーまたはメッセージペイロードに配置できます。
メッセージペイロードでグローバル ID を見つけるとき、データの形式は、コンシューマーへの信号として使用されるマジックバイトで始まり、通常通りグローバル ID とメッセージデータが続きます。以下に例を示します。
# ... [MAGIC_BYTE] [GLOBAL_ID] [MESSAGE DATA]
これで、Kafka および Service Registry を開始するとき、スキーマにアクセスして、Kafka ブローカートピックから受信するメッセージをフォーマットできます。
コンテンツ ID を使用したスキーマの取得
または、アーティファクトコンテンツの一意の ID であるコンテンツ ID に基づいて、Service Registry からスキーマを取得するように設定できます。グローバル ID はアーティファクトバージョンの一意の ID です。
コンテンツ ID はバージョンを一意に識別しませんが、バージョンコンテンツのみを一意に識別します。複数のバージョンがまったく同じコンテンツを共有している場合、グローバル ID は異なりますが、コンテンツ ID は同じです。Confluent Schema Registry はデフォルトでコンテンツ ID を使用します。
7.2. Service Registry でスキーマを検索するストラテジー
Kafka クライアントのシリアライザーは 検索ストラテジー を使用して、メッセージスキーマが Service Registry に登録されるアーティファクト ID およびグローバル ID を決定します。特定のトピックとメッセージについて、ArtifactReferenceResolverStrategy Java インターフェイスのさまざまな実装を使用して、レジストリー内のアーティファクトへの参照を返すことができます。
各ストラテジーのクラスは、io.apicurio.registry.serde.strategy パッケージに含まれています。Avro SerDes の特定のストラテジークラスは、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();
-
topicパラメーターは、メッセージを受信する Kafka トピックの名前です。 -
isKeyパラメーターは、メッセージキーがシリアライズされている場合はtrueであり、メッセージ値がシリアライズされている場合はfalseです。 -
schemaパラメーターは、シリアライズ/デシリアライズされたメッセージのスキーマです。 -
返される
ArtifactReferenceには、スキーマが登録されているアーティファクト ID が含まれています。
使用する検索アップストラテジーは、スキーマを保存する方法と場所によって異なります。たとえば、同じ Avro メッセージタイプを持つ Kafka トピックが複数ある場合、レコード ID を使用するストラテジーを使用することがあります。
アーティファクトリーゾルバーストラテジー
アーティファクトリーゾルバーストラテジーは、Kafka トピックおよびメッセージ情報を Service Registry のアーティファクトにマップする方法を提供します。マッピングの共通規則は、Kafka メッセージのキーと値のどちらにシリアライザーを使用するかによって、Kafka トピック名と key または value を結合することです。
ただし、Service Registry によって提供されるストラテジーを使用するか、io.apicurio.registry.serde.strategy.ArtifactReferenceResolverStrategy を実装するカスタム Java クラスを作成することにより、マッピングに代替規則を使用できます。
アーティファクトへの参照を返すストラテジー
Service Registry は、ArtifactReferenceResolverStrategy の実装に基づいてアーティファクトへの参照を返すために、次の戦略を提供します。
RecordIdStrategy- スキーマのフルネームを使用する Avro 固有のストラテジー。
TopicRecordIdStrategy- トピック名およびスキーマのフルネームを使用する Avro 固有のストラテジー。
TopicIdStrategy-
トピック名と、
keyまたはvalue接尾辞を使用するデフォルトストラテジー。 SimpleTopicIdStrategy- トピック名のみを使用する単純なストラテジー。
DefaultSchemaResolver インターフェイス
デフォルトのスキーマリゾルバーは、アーティファクトリーゾルバーストラテジーによって提供されるアーティファクト参照の下に登録されたスキーマの特定バージョンを見つけて識別します。すべてのアーティファクトのすべてのバージョンには、グローバルで一意の識別子が 1 つだけあり、それを使用してそのアーティファクトの内容を取得できます。このグローバル ID はすべての Kafka メッセージに含まれていいるため、デシリアライザーは Apicurio レジストリーからスキーマを適切に取得できます。
デフォルトのスキーマリゾルバーは、既存のアーティファクトバージョンを検索できます。見つからない場合は、使用するストラテジーに応じて登録できます。io.apicurio.registry.resolver.SchemaResolver を実装するカスタム Java クラスを作成することにより、独自のストラテジーを提供することもできます。ただし、DefaultSchemaResolver を使用して、代わりに設定プロパティーを指定することをお勧めします。
レジストリー検索オプションの設定
DefaultSchemaResolver を使用する場合、アプリケーションのプロパティーを使用してその動作を設定できます。次の表は、一般的に使用される例を示しています。
表7.1 Service Registry 検索設定オプション
| プロパティー | タイプ | 説明 | デフォルト |
|---|---|---|---|
|
|
| シリアライザーが対応するグループ ID およびアーティファクト ID のレジストリー内で最新のアーティファクトの検索を試行するかどうかを指定します。 |
|
|
|
| 指定された ID を Kafka に書き込むようシリアライザーに指示し、この ID を使用してスキーマを見つけるようにデシリアライザーに指示します。 | None |
|
|
| シリアライザーがレジストリーでアーティファクトを作成しようとするかどうかを指定します。JSON スキーマシリアライザーはこれをサポートしません。 |
|
|
|
| グローバル ID をキャッシュする期間をミリ秒単位で指定します。設定されていない場合は、グローバル ID は毎回フェッチされます。 | なし |
7.3. スキーマの Service Registry への登録
スキーマを Apache Avro などの適切な形式で定義したら、スキーマを Service Registry に追加できます。
以下の方法を使用してスキーマを追加できます。
- Service Registry Web コンソール
- Service Registry REST API を使用する curl コマンド
- Service Registry に付属する Maven プラグイン
- クライアントコードに加えられたスキーマ設定
スキーマを登録するまでは、クライアントアプリケーションは 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
- シンプルな Avro スキーマアーティファクト。
- Service Registry を公開する OpenShift ルート名。
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>-
スキーマアーティファクトをレジストリーにアップロードするための実行目標として
registerを指定します。 -
../apis/registry/v2エンドポイントでService Registry URL を指定します。 - Service Registry アーティファクトグループ ID を指定します。
- 指定したグループ ID、アーティファクト ID、および場所を使用して複数のアーティファクトをアップロードできます。
プロデューサークライアントを使用した設定例
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(
"AVRO",
artifactId,
new ByteArrayInputStream(LogInput.SCHEMA$.toString().getBytes())
);
csa.toCompletableFuture().get();
}
}- 複数の URL ノードに対してプロパティーを登録できます。
- アーティファクト ID に基づいてスキーマがすでに存在しているかを確認します。
7.4. Kafka コンシューマークライアントからのスキーマの使用
この手順では、Service Registry からのスキーマを使用するように Java で書かれた Kafka コンシューマークライアントを設定する方法について説明します。
前提条件
- Service Registry がインストールされている必要があります。
- スキーマが Service Registry に登録されている必要があります。
手順
Service Registry の URL でクライアントを設定します。以下に例を示します。
String registryUrl = "https://registry.example.com/apis/registry/v2"; Properties props = new Properties(); props.putIfAbsent(SerdeConfig.REGISTRY_URL, registryUrl);
Service Registry デシリアライザーでクライアントを設定します。以下に例を示します。
// Configure 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"); // Configure deserializer settings props.putIfAbsent(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, AvroKafkaDeserializer.class.getName()); 1 props.putIfAbsent(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, AvroKafkaDeserializer.class.getName()); 2- 1.Service Registry によって提供されるデシリアライザー。
- 2.デシリアライズは Apache Avro JSON 形式です。
7.5. Kafka プロデューサークライアントからのスキーマの使用
この手順では、Service Registry からのスキーマを使用するように Java で書かれた Kafka プロデューサークライアントを設定する方法について説明します。
前提条件
- Service Registry がインストールされている必要があります。
- スキーマが Service Registry に登録されている必要があります。
手順
Service Registry の URL でクライアントを設定します。以下に例を示します。
String registryUrl = "https://registry.example.com/apis/registry/v2"; Properties props = new Properties(); props.putIfAbsent(SerdeConfig.REGISTRY_URL, registryUrl);
クライアントをシリアライザーで設定し、Service Registry でスキーマを検索するようにストラテジーを設定します。以下に例を示します。
props.put(CommonClientConfigs.BOOTSTRAP_SERVERS_CONFIG, "my-cluster-kafka-bootstrap:9092"); props.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, AvroKafkaSerializer.class.getName()); 1 props.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, AvroKafkaSerializer.class.getName()); 2 props.put(SerdeConfig.FIND_LATEST_ARTIFACT, Boolean.TRUE); 3
- 1.Service Registry により提供されるメッセージキーのシリアライザー。
- 2.Service Registry により提供されるメッセージ値のシリアライザー。
- 3.スキーマのグローバル ID を検索する検索ストラテジー。
7.6. Kafka Streams アプリケーションからのスキーマの使用
この手順では、Service Registry からの Apache Avro スキーマを使用するように Java で書かれた Kafka Streams クライアントを設定する方法について説明します。
前提条件
- Service Registry がインストールされている必要があります。
- スキーマが Service Registry に登録されている必要があります。
手順
Service Registry URL を使用して Java クライアントを作成して設定します。
String registryUrl = "https://registry.example.com/apis/registry/v2"; RegistryService client = RegistryClient.cached(registryUrl);
シリアライザーおよびデシリアライザーを設定します。
Serializer<LogInput> serializer = new AvroKafkaSerializer<LogInput>(); 1 Deserializer<LogInput> deserializer = new AvroKafkaDeserializer <LogInput>(); 2 Serde<LogInput> logSerde = Serdes.serdeFrom( serializer, deserializer ); Map<String, Object> config = new HashMap<>(); config.put(SerdeConfig.REGISTRY_URL, registryUrl); config.put(AvroKafkaSerdeConfig.USE_SPECIFIC_AVRO_READER, true); logSerde.configure(config, false); 3
- 1.Service Registry によって提供される Avro シリアライザー。
- 2.Service Registry によって提供される Avro デシリアライザー。
- 3.Avro 形式でデシリアライズ用の Service Registry URL および Avro リーダーを設定します。
Kafka Streams クライアントを作成します。
KStream<String, LogInput> input = builder.stream( INPUT_TOPIC, Consumed.with(Serdes.String(), logSerde) );
第8章 Java クライアントでの Kafka シリアライザー/デシリアライザーの設定
本章では、プロデューサーおよびコンシューマー Java クライアントアプリケーションで Kafka SerDes を設定する方法について詳しく説明します。
8.1. クライアントアプリケーションの Service Registry シリアライザー/デシリアライザーの設定
本セクションの定数例を使用して、特定のクライアントシリアライザー/デシリアライザー (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- Service Registry の必須の URL。
-
ID 処理を拡張することで、他の ID 形式をサポートし、その形式に Service Registry SerDe サービスとの互換性を持たせます。たとえば、ID 形式を
LongからIntegerに変更すると Confluent ID 形式がサポートされます。 -
Confluent ID の処理を簡素化します。
trueに設定すると、Integerがグローバル ID の検索に使用されます。この設定は、ID_HANDLERオプションと一緒に使用しないでください。
関連情報
- 設定オプションの詳細は、「Service Registry シリアライザー/デシリアライザー設定プロパティー」 を参照してください。
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 SerDe とアーティファクト ID の間をマッピングする Java クラス。デフォルトはトピック ID ストラテジーです。これはシリアライザークラスによってのみ使用されます。
-
スキーマリゾルバーを実装する Java クラス。デフォルトは
DefaultSchemaResolverです。これは、シリアライザーおよびデシリアライザークラスによって使用されます。
その他のリソース
- 検索ストラテジーの詳細は、7章Java クライアントでシリアライザー/デシリアライザーを使用した Kafka メッセージの検証 を参照してください。
- 設定オプションの詳細は、「Service Registry シリアライザー/デシリアライザー設定プロパティー」 を参照してください。
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- Service Registry Kafka コンバーターと使用するために必要なシリアライザー。
- Service Registry Kafka コンバーターと使用するために必要なデシリアライザー。
その他のリソース
- 詳細は、SerdeBasedConverter Java class を参照してください。
さまざまなスキーマタイプの設定
さまざまなスキーマ技術に SerDe を設定する方法は、以下を参照してください。
8.2. Service Registry シリアライザー/デシリアライザー設定プロパティー
本セクションでは、Service Registry Kafka シリアライザー/デシリアライザー (SerDes) の Java 設定プロパティーに関する参照情報を提供します。
SchemaResolver インターフェイス
Service Registry SerDes は、レジストリーへのアクセスを抽象化し、サポートされるすべての形式の SerDes クラスに同じ検索ロジックを適用する SchemaResolver インターフェイスをベースとしています。
表8.1 SchemaResolver インターフェイスの設定プロパティー
| Constant | プロパティー | 説明 | 型 | デフォルト |
|---|---|---|---|---|
|
|
|
シリアライザーおよびデシリアライザーによって使用されます。 | String |
|
DefaultSchemaResolver が推奨され、ほとんどのユースケースに役立つ機能を提供します。一部の高度なユースケースでは、 SchemaResolver のカスタム実装を使用する場合があります。
DefaultSchemaResolver クラス
DefaultSchemaResolver を使用して、次のような機能を設定できます。
- レジストリー API へのアクセス
- レジストリーでアーティファクトを検索する方法
- Kafka との間でアーティファクト情報を読み書きする方法
- デシリアライザーのフォールバックオプション
レジストリー API アクセスオプションの設定
DefaultSchemaResolver は、コアレジストリー API へのアクセスを設定するために次のプロパティーを提供します。
表8.2 レジストリー API にアクセスするための設定プロパティー
| Constant | プロパティー | 説明 | 型 | デフォルト |
|---|---|---|---|---|
|
|
| シリアライザーおよびデシリアライザーによって使用されます。レジストリー API にアクセスするための URL。 |
| None |
|
|
| シリアライザーおよびデシリアライザーによって使用されます。認証サービスの URL。OAuth クライアントクレデンシャルフローを使用してセキュアなレジストリーにアクセスする際に必須です。 |
| None |
|
|
| シリアライザーおよびデシリアライザーによって使用されます。認証サービスにアクセスするためのレルム。OAuth クライアントクレデンシャルフローを使用してセキュアなレジストリーにアクセスする際に必須です。 |
| None |
|
|
| シリアライザーおよびデシリアライザーによって使用されます。認証サービスにアクセスするためのクライアント ID。OAuth クライアントクレデンシャルフローを使用してセキュアなレジストリーにアクセスする際に必須です。 |
| None |
|
|
| シリアライザーおよびデシリアライザーによって使用されます。認証サービスにアクセスするためのクライアントシークレット。OAuth クライアントクレデンシャルフローを使用してセキュアなレジストリーにアクセスする際に必須です。 |
| None |
|
|
| シリアライザーおよびデシリアライザーによって使用されます。レジストリーにアクセスするためのユーザー名HTTP Basic 認証を使用してセキュアなレジストリーにアクセスする際に必須です。 |
| None |
|
|
| シリアライザーおよびデシリアライザーによって使用されます。レジストリーにアクセスするためのパスワードHTTP Basic 認証を使用してセキュアなレジストリーにアクセスする際に必須です。 |
| None |
レジストリー検索オプションの設定
DefaultSchemaResolver は、次のプロパティーを使用して、ServiceRegistry でアーティファクトを検索する方法を設定します。
表8.3 レジストリーアーティファクト検索の設定プロパティー
| Constant | プロパティー | 説明 | 型 | デフォルト |
|---|---|---|---|---|
|
|
|
シリアライザーによってのみ使用されます。 |
|
|
|
|
|
シリアライザーによってのみ使用されます。アーティファクトのクエリーまたは作成に使用される |
| None |
|
|
|
シリアライザーによってのみ使用されます。アーティファクトのクエリーまたは作成に使用される |
| None |
|
|
|
シリアライザーによってのみ使用されます。アーティファクトの問い合わせまたは作成に使用されるアーティファクトバージョンを設定します。 |
| None |
|
|
| シリアライザーによってのみ使用されます。シリアライザーが対応するグループ ID およびアーティファクト ID のレジストリー内で最新のアーティファクトの検索を試行するかどうかを指定します。 |
|
|
|
|
| シリアライザーによってのみ使用されます。シリアライザーがレジストリーでアーティファクトを作成しようとするかどうかを指定します。JSON スキーマシリアライザーはこの機能をサポートしません。 |
|
|
|
|
|
シリアライザーによってのみ使用されます。アーティファクトがすでに存在するためにアーティファクトの作成で競合が発生した場合のクライアントの動作を設定します。使用可能な値は、 |
|
|
|
|
| シリアライザーおよびデシリアライザーによって使用されます。自動エビクションの前にアーティファクトをキャッシュする期間を指定します。設定されていない場合、アーティファクトは毎回フェッチされます。 |
| None |
|
|
|
シリアライザーおよびデシリアライザーによって使用されます。指定された |
|
|
Kafka でレジストリーアーティファクトを読み書きするための設定
DefaultSchemaResolver は、次のプロパティーを使用して、アーティファクト情報の Kafka への書き込みおよび Kafka からの読み取り方法を設定します。
表8.4 Kafka でアーティファクト情報を読み書きするための設定プロパティー
| Constant | プロパティー | 説明 | 型 | デフォルト |
|---|---|---|---|---|
|
|
| シリアライザーおよびデシリアライザーによって使用されます。メッセージペイロードではなく、Kafka メッセージヘッダーに対してアーティファクト識別子を読み書きするように設定します。 |
|
|
|
|
|
シリアライザーおよびデシリアライザーによって使用されます。 |
|
|
|
|
|
シリアライザーおよびデシリアライザーによって使用されます。 |
|
|
|
|
|
シリアライザーおよびデシリアライザーによって使用されます。 |
|
|
デシリアライザーのフォールバックオプションの設定
DefaultSchemaResolver は、次のプロパティーを使用して、すべてのデシリアライザーのフォールバックプロバイダーを設定します。
表8.5 デシリアライザーのフォールバックプロバイダーの設定プロパティー
| Constant | プロパティー | 説明 | 型 | デフォルト |
|---|---|---|---|---|
|
|
|
デシリアライザーによってのみ使用されます。デシリアライズに使用されるアーティファクトを解決するための |
|
|
DefaultFallbackArtifactProvider は、次のプロパティーを使用して、デシリアライザーのフォールバックオプションを設定します。
表8.6 デシリアライザーのフォールバックオプションの設定プロパティー
| Constant | プロパティー | 説明 | 型 | デフォルト |
|---|---|---|---|---|
|
|
|
デシリアライザーによってのみ使用されます。デシリアライズに使用されるアーティファクトを解決するためのフォールバックとして使用される |
| None |
|
|
|
デシリアライザーによってのみ使用されます。デシリアライズに使用されるグループのフォールバックとして使用される |
| None |
|
|
| デシリアライザーによってのみ使用されます。デシリアライズに使用されるアーティファクトを解決するために使用されるバージョンを設定します。 |
| None |
その他のリソース
- 詳細は、SerdeConfig Java class を参照しください。
-
アプリケーションプロパティーを Java システムプロパティーとして設定することも、Quarkus
application.propertiesファイルに含めることもできます。詳細は、Quarkus のドキュメント を参照してください。
8.3. さまざまなクライアントシリアライザー/デシリアライザータイプの設定方法
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 コンシューマーアプリケーションでデシリアライザーを設定する方法を示しています。
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;
}
Kafka コンシューマーのデシリアライザー設定の例
// 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;
}
関連情報
- アプリケーションの例については Simple Avro example を参照してください。
8.3.1. Service Registry を使用した Avro SerDes の設定
このトピックでは、Apache Avro の Kafka クライアントシリアライザーおよびデシリアライザー (SerDes) クラスを使用する方法について説明します。
Service Registry は、Avro 用に次の Kafka クライアント SerDes クラスを提供します。
-
io.apicurio.registry.serde.avro.AvroKafkaSerializer -
io.apicurio.registry.serde.avro.AvroKafkaDeserializer
Avro シリアライザーの設定
以下のように Avro シリアライザークラスを設定することができます。
- Service Registry の URL
- アーティファクトリーゾルバーストラテジー
- ID の場所
- ID エンコーディング
- Avro datum プロバイダー
- Avro エンコーディング
ID の場所
シリアライザーは、スキーマの一意の ID を Kafka メッセージの一部として渡し、コンシューマーがデシリアライズに正しいスキーマを使用できるようにします。ID は、メッセージのペイロードまたはメッセージヘッダーに存在できます。デフォルトの場所はメッセージペイロードです。メッセージヘッダーで ID を送信するには、以下の設定プロパティーを設定します。
props.putIfAbsent(SerdeConfig.ENABLE_HEADERS, "true")
プロパティー名は apicurio.registry.headers.enabled です。
ID エンコーディング
Kafka メッセージボディーに渡すときにスキーマ ID をエンコードする方法をカスタマイズできます。apicurio.registry.id-handler 設定プロパティーを、io.apicurio.registry.serde.IdHandler インターフェイスを実装するクラスに設定します。Service Registry は以下の実装を提供します。
-
io.apicurio.registry.serde.DefaultIdHandler:ID を 8 バイト長として格納します -
io.apicurio.registry.serde.Legacy4ByteIdHandler:ID を 4 バイト整数として格納します
Service Registry はスキーマ ID を long として表しますが、従来の理由、または他のレジストリーまたは SerDe クラスとの互換性のため、ID の送信時に 4 バイトの使用が推奨される場合があります。
Avro datum プロバイダー
Avro は、データを読み書きするためのさまざまなデータライターとリーダーを提供します。Service Registry は、3 つの異なるタイプをサポートします。
- Generic
- Specific
- Reflect
Service Registry AvroDatumProvider は、使用されるタイプの抽象概念であり、DefaultAvroDatumProvider がデフォルトで使用されます。
以下の設定オプションを設定できます。
-
apicurio.registry.avro-datum-provider:AvroDatumProvider実装の完全修飾 Java クラス名を指定します (例えば、io.apicurio.registry.serde.avro.ReflectAvroDatumProvider)。 -
apicurio.registry.use-specific-avro-reader:DefaultAvroDatumProviderを使用するときに特定のタイプを使用するには、trueに設定します
Avro エンコーディング
Avro を使用してデータをシリアライズする場合は、Avro バイナリーエンコーディング形式を使用して、データを可能な限り効率的な形式でエンコードすることができます。Avro は JSON としてデータのエンコードもサポートします。これにより、ロギングやデバッグなどの各メッセージのペイロードの検証が容易になります。
apicurio.registry.avro.encoding プロパティーを JSON または BINARY の値で設定することにより、Avro エンコーディングを設定できます。デフォルトは BINARY です。
Avro デシリアライザーの設定
Avro デシリアライザーの設定設定を、シリアライザーの設定と一致するように、Avro デシリアライザークラスを設定する必要があります。
- Service Registry の URL
- ID エンコーディング
- Avro datum プロバイダー
- Avro エンコーディング
これらの設定オプションは、シリアライザーセクションを参照してください。プロパティー名と値は同じです。
デシリアライザーの設定時には、以下のオプションは必要ありません。
- アーティファクトリーゾルバーストラテジー
- ID の場所
デシリアライザークラスは、メッセージからこれらのオプションの値を判断できます。シリアライザーはメッセージの一部として ID を送信するため、ストラテジーは必要ありません。
ID の位置は、メッセージペイロードの先頭にあるマジックバイトを確認することで決定されます。そのバイトが見つかると、設定されたハンドラーを使用してメッセージペイロードから ID が読み取られます。マジックバイトが見つからない場合、ID はメッセージヘッダーから読み込まれます。
Avro SerDes とアーティファクトの参照
レコードがネスト化された Avro メッセージとスキーマを使用する場合に、ネストされたレコードごとに新しいアーティファクトが登録されます。たとえば、次の TradeKey スキーマには、ネストされた Exchange スキーマが含まれています。
ネストされた Exchange スキーマを持つ TradeKey スキーマ
{
"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 スキーマを使用するメッセージがシリアライズまたはデシリアライズされるたびに、両方のスキーマが取得されるため、定義を異なるファイルに分割できます。
関連情報
- Avro 設定の詳細は、AvroKafkaSerdeConfig Java クラス を参照してください。
Java のサンプルアプリケーションについては、以下を参照してください。
8.3.2. Service Registry を使用した JSON スキーマ SerDes の設定
このトピックでは、JSON スキーマの Kafka クライアントシリアライザーおよびデシリアライザー (SerDes) クラスを使用する方法について説明します。
Service Registry は、JSON スキーマ用に次の Kafka クライアント SerDes クラスを提供します。
-
io.apicurio.registry.serde.jsonschema.JsonSchemaKafkaSerializer -
io.apicurio.registry.serde.jsonschema.JsonSchemaKafkaDeserializer
Apache Avro とは異なり、JSON スキーマはシリアライズテクノロジーではなく、検証テクノロジーです。その結果、JSON スキーマの設定オプションは大きく異なります。たとえば、データは常に JSON としてエンコードされるため、エンコーディングオプションはありません。
JSON スキーマシリアライザーの設定
JSON スキーマシリアライザークラスを以下のように設定できます。
- Service Registry の URL
- アーティファクトリーゾルバーストラテジー
- スキーマ検証
唯一の標準以外の設定プロパティーは、デフォルトで有効になっている JSON スキーマバリデーションです。これを無効にするには、apicurio.registry.serde.validation-enabled を false に設定します。以下に例を示します。
props.putIfAbsent(SerdeConfig.VALIDATION_ENABLED, Boolean.FALSE)
JSON スキーマデシリアライザーの設定
JSON スキーマデシリアライザークラスを以下のように設定できます。
- Service Registry の URL
- スキーマ検証
- データをデシリアライズするためのクラス
スキーマをロードできるように、Service Registry の場所を指定する必要があります。他の設定はオプションです。
デシリアライザーの検証は、シリアライザーが Kafka メッセージでグローバル ID を渡す場合にのみ機能します。これは、シリアライザーで検証が有効になっている場合にのみ発生します。
JSON スキーマの SerDes とアーティファクトの参照
JSON スキーマ SerDes はメッセージペイロードからスキーマを検出できないため、事前にスキーマアーティファクトを登録する必要があり、これはアーティファクト参照にも適用されます。
スキーマの内容に応じて、$ref の値は URL に置き換えます。SerDes はこの URL を使用して参照のスキーマを解決しようとし、主要なスキーマに対するデータの検証、ネスト化されたスキーマに対するネスト化された値の検証など、検証は通常どおりに行われます。Service Registry でアーティファクトを参照するためのサポートも実装されています。
たとえば、次の city.json スキーマは city.json スキーマを参照ししています。
city.json スキーマを参照する citizen.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"
}
}
}
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 スキーマに対する検証が可能になります。
関連情報
- 詳細は、JsonSchemaKafkaDeserializerConfig Java クラス を参照してください。
Java のサンプルアプリケーションについては、以下を参照してください。
8.3.3. Service Registry を使用した Protobuf SerDes の設定
このトピックでは、Google Protobuf の Kafka クライアントシリアライザーおよびデシリアライザー (SerDes) クラスを使用する方法について説明します。
Service Registry は、Protobuf 用に次の Kafka クライアント SerDes クラスを提供します。
-
io.apicurio.registry.serde.protobuf.ProtobufKafkaSerializer -
io.apicurio.registry.serde.protobuf.ProtobufKafkaDeserializer
Protobuf シリアライザーの設定
Protobuf シリアライザークラスを以下のように設定できます。
- Service Registry の URL
- アーティファクトリーゾルバーストラテジー
- ID の場所
- ID エンコーディング
- スキーマ検証
これらの設定オプションの詳細は、以下のセクションを参照してください。
Protobuf デシリアライザーの設定
シリアライザーの以下の設定と一致するように、Protobuf デシリアライザークラスを設定する必要があります。
- Service Registry の URL
- ID エンコーディング
設定プロパティー名と値はシリアライザーの場合と同じです。
デシリアライザーの設定時には、以下のオプションは必要ありません。
- アーティファクトリーゾルバーストラテジー
- ID の場所
デシリアライザークラスは、メッセージからこれらのオプションの値を判断できます。シリアライザーはメッセージの一部として ID を送信するため、ストラテジーは必要ありません。
ID の位置は、メッセージペイロードの先頭にあるマジックバイトを確認することで決定されます。そのバイトが見つかると、設定されたハンドラーを使用してメッセージペイロードから ID が読み取られます。マジックバイトが見つからない場合、ID はメッセージヘッダーから読み込まれます。
Protobuf デシリアライザーは、正確な Protobuf Message 実装へデシリアライズしません。DynamicMessage インスタンスへデシリアライズします。設定しない場合は、適切な API はありません。
Protobuf SerDes とアーティファクト参照
import ステートメントを含む複雑な Protobuf メッセージが使用される場合に、インポートされた Protobuf メッセージは個別のアーティファクトとして Service Registry に保存されます。次に、Service Registry がメインスキーマを取得して Protobuf メッセージをチェックすると、完全なメッセージスキーマをチェックしてシリアル化できるように参照されているスキーマも取得されます。
たとえば、次の table_info.proto スキーマファイルには、インポートされた mode.proto スキーマファイルが含まれています。
インポートされた .mode.proto ファイルを含む table_info.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;
}
mode.proto ファイル
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 で参照されるアーティファクトとして返されます。
関連情報
Java のサンプルアプリケーションについては、以下を参照してください。
第9章 Service Registry アーティファクトの参照
本章では、Service Registry に保存されるサポート対象のアーティファクトタイプ、状態、メタデータ、およびコンテンツルールの詳細を説明します。
その他のリソース
- 詳細は、Apicurio Registry REST API のドキュメント を参照してください。
9.1. Service Registry アーティファクトタイプ
Service Registry では、さまざまなスキーマおよび API アーティファクトタイプを保存して管理できます。
表9.1 Service Registry アーティファクトタイプ
| 型 | 説明 |
|---|---|
|
| AsyncAPI 仕様 |
|
| Apache Avro スキーマ |
|
| GraphQL スキーマ |
|
| JSON スキーマ |
|
| Apache Kafka Connect スキーマ |
|
| OpenAPI 仕様 |
|
| Google プロトコルバッファースキーマ |
|
| Web Services Definition Language |
|
| XML Schema Definition |
9.2. Service Registry アーティファクトの状態
Service Registry の有効なアーティファクトの状態は、ENABLED、DISABLED、および DEPRECATED です。
表9.2 Service Registry アーティファクトの状態
| 状態 | 説明 |
|---|---|
|
| 基本状態、全ての操作が可能です。 |
|
| アーティファクトとそのメタデータは、Service Registry Web コンソールを使用して表示および検索できますが、そのコンテンツはどのクライアントでもフェッチできません。 |
|
| アーティファクトは完全に使用可能ですが、アーティファクトのコンテンツがフェッチされるたびに、ヘッダーが REST API 応答に追加されます。Service Registry Rest Client は、非推奨となったコンテンツが見つかったときにも警告をログに記録します。 |
9.3. Service Registry アーティファクトのメタデータ
アーティファクトが Service Registry に追加されると、メタデータプロパティーのセットがアーティファクトの内容と共に保存されます。このメタデータは、設定可能な一部のプロパティーと、生成された読み取り専用プロパティーのセットで設定されます。
表9.3 Service Registry メタデータプロパティー
| プロパティー | 型 | 編集可能 |
|---|---|---|
|
| string | false |
|
| ArtifactType | false |
|
| ArtifactState | true |
|
| integer | false |
|
| string | false |
|
| date | false |
|
| string | false |
|
| date | false |
|
| string | true |
|
| string | true |
|
| 文字列の配列 | true |
|
| map | true |
アーティファクトメタデータの更新
- Service Registry REST API を使用して、メタデータエンドポイントを使用して編集可能なプロパティーのセットを更新できます。
-
stateプロパティーは、状態遷移 API を使用することでのみ編集できます。たとえば、アーティファクトをdeprecatedまたはdisabledとしてマークできます。
関連情報
詳細は、Apicurio Registry REST API documentation の /artifacts/{artifactId}/meta セクションを参照してください。
9.4. Service Registry コンテンツルールタイプ
VALIDITY および COMPATIBILITY ルールタイプを指定して、Service Registry でのコンテンツの変化を制御できます。
表9.4 Service Registry コンテンツルールタイプ
| 型 | 説明 |
|---|---|
|
| レジストリーに追加する前にデータを検証します。このルールに使用できる設定値は以下のとおりです。
|
|
| 新たに追加されたアーティファクトが以前に追加したバージョンと互換性があることを確認します。このルールに使用できる設定値は以下のとおりです。
|
9.5. Service Registry コンテンツルールの成熟度
すべてのコンテンツルールは、Service Registry でサポートされるすべてのアーティファクトタイプに対して完全に実装されるわけではありません。以下の表は、各ルールおよびアーティファクトタイプの現在の成熟度レベルを示しています。
表9.5 Service Registry コンテンツルールの成熟度マトリックス
| アーティファクトタイプ | 検証ルール | 互換性ルール |
|---|---|---|
| Avro | Full | Full |
| Protobuf | 完全 | 完全 |
| JSON スキーマ | Full | Full |
| OpenAPI | Full | なし |
| AsyncAPI | Syntax Only | なし |
| GraphQL | Syntax Only | なし |
| Kafka Connect | Syntax Only | なし |
| WSDL | Syntax Only | なし |
| XSD | Syntax Only | None |
9.6. Service Registry コンテンツルールの優先順位
アーティファクトを追加して更新すると、Service Registry はルールを適用して、アーティファクトコンテンツの有効性と互換性をチェックします。次の表に示すように、設定されたアーティファクトルールは、同等の設定済みグローバルルールをオーバーライドします。
表9.6 Service Registry コンテンツルールの優先順位
| アーティファクトルール | グローバルルール | このアーティファクトに適用されるルール | 他のアーティファクトで利用できるグローバルルール |
|---|---|---|---|
| 有効 | 有効 | アーティファクト | はい |
| Disabled | 有効 | グローバル | はい |
| Disabled | Disabled | None | いいえ |
| 有効、None に設定 | 有効 | None | はい |
| Disabled | 有効、None に設定 | None | いいえ |
付録A サブスクリプションの使用
Service Registry は、ソフトウェアサブスクリプションから提供されます。サブスクリプションを管理するには、Red Hat カスタマーポータルでアカウントにアクセスします。
アカウントへのアクセス
- access.redhat.com に移動します。
- アカウントがない場合は、作成します。
- アカウントにログインします。
サブスクリプションのアクティベート
- access.redhat.com に移動します。
- サブスクリプション に移動します。
- Activate a subscription に移動し、16 桁のアクティベーション番号を入力します。
ZIP および TAR ファイルのダウンロード
ZIP または TAR ファイルにアクセスするには、カスタマーポータルを使用して、ダウンロードする関連ファイルを検索します。RPM パッケージを使用している場合は、この手順は必要ありません。
- ブラウザーを開き、access.redhat.com/downloads で Red Hat カスタマーポータルの Product Downloads ページにログインします。
- Integration and Automation カテゴリーで Red Hat Integration エントリーを見つけます。
- 必要な Service Registry 製品を選択します。Software Downloads ページが開きます。
- コンポーネントの Download リンクをクリックします。
パッケージ用のシステムの登録
Red Hat Enterprise Linux に RPM パッケージをインストールするには、システムを登録する必要があります。ZIP または TAR ファイルを使用している場合、この手順は必要ありません。
- access.redhat.com に移動します。
- Registration Assistant に移動します。
- ご使用の OS バージョンを選択し、次のページに進みます。
- システムターミナルで listed コマンドを使用して、登録を完了します。
詳細は How to Register and Subscribe a System to the Red Hat Customer Portal を参照してください。