Apicurio Registry ユーザーガイド

手順

1. Red Hat build of Keycloak 管理コンソールで、Apicurio Registry 用の Red Hat build of Keycloak レルムを作成します。デフォルトでは、Apicurio Registry は registry のレルム名を想定しています。レルムの作成に関する詳細は、Red Hat build of Keycloak のユーザードキュメント を参照してください。

2. Apicurio Registry API 用の Red Hat build of Keycloak クライアントを作成します。デフォルトでは、Apicurio Registry は次の設定を想定しています。

   • Client ID: registry-api
   • Client Protocol: openid-connect

   • Access Type: bearer-only

     他のクライアント設定にはデフォルト値を使用できます。

     注記

     Red Hat build of Keycloak サービスアカウントを使用している場合、クライアントの アクセスタイプ は bearer-only ではなく、confidential にする必要があります。

3. Apicurio Registry Web コンソール用の Red Hat build of Keycloak クライアントを作成します。デフォルトでは、Apicurio Registry は次の設定を想定しています。

   • Client ID: apicurio-registry
   • Client Protocol: openid-connect
   • Access Type: public
   • Valid Redirect URLs: http://my-registry-url:8080/*

   • Web Origins: +

     他のクライアント設定にはデフォルト値を使用できます。

4. OpenShift 上の Apicurio Registry デプロイメントで、次の Apicurio Registry 環境変数を指定し、Red Hat build of Keycloak を使用して認証を設定します。

   Expand

   表3.1 Red Hat build of Keycloak を使用した Apicurio レジストリー認証の設定

   環境変数	説明	型	デフォルト
   QUARKUS_OIDC_TENANT_ENABLED	Apicurio Registry の認証を有効にします。true に設定すると、Red Hat build of Keycloak を使用した認証に次の環境変数が必要になります。	String	false
   QUARKUS_OIDC_AUTH_SERVER_URL	Red Hat build of Keycloak 認証サーバーの URL。たとえば、http://localhost:8080 です。	String	-
   QUARKUS_OIDC_CLIENT_ID	Apicurio Registry REST API のクライアント ID。	String	registry-api
   APICURIO_UI_AUTH_OIDC_CLIENT-ID	Apicurio Registry Web コンソールのクライアント ID。	String	apicurio-registry

   Show more
   ヒント

   OpenShift に環境変数を設定する例は、「OpenShift での Apicurio Registry ヘルスチェックの設定」 を参照してください。

5. 以下のオプションを true に設定して、Red Hat build of Keycloak で Apicurio Registry ユーザーロールを有効にします。

   Expand

   表3.2 Apicurio Registry ロールベース認証の設定

   環境変数	Java システムプロパティー	型	デフォルト値
   APICURIO_AUTH_ROLE-BASED-AUTHORIZATION	apicurio.auth.role-based-authorization	Boolean	false

   Show more

6. Apicurio Registry ユーザーロールが有効になっている場合、Apicurio Registry ユーザーを、Red Hat build of Keycloak レルム内の以下のデフォルトユーザーロールの少なくとも 1 つに割り当てる必要があります。

   Expand

   表3.3 レジストリーの認証および認可のデフォルトユーザーロール

   ロール	アーティファクトの読み取り	アーティファクトの書き込み	グローバルルール	概要
   sr-admin	はい	はい	はい	すべての作成、読み取り、更新、および削除操作へのフルアクセス。
   sr-developer	はい	はい	いいえ	グローバルルールの設定を除く、作成、読み取り、更新、および削除操作へのアクセス。このロールは、アーティファクト固有のルールを設定できます。
   sr-readonly	はい	いいえ	いいえ	読み取りおよび検索操作のみへのアクセス。このロールはルールを設定できません。

   Show more

7. 以下を true に設定して、Apicurio Registry のスキーマおよび API アーティファクトの更新に対して所有者のみの認可を有効にします。

   Expand

   表3.4 所有者のみの認可の設定

   環境変数	Java システムプロパティー	型	デフォルト値
   APICURIO_AUTH_OWNER-ONLY-AUTHORIZATION_LIMIT-GROUP-ACCESS	apicurio.auth.owner-only-authorization.limit-group-access	Boolean	false

   Show more

手順

1. メールアドレスまたは GitHub アカウントを使用して Azure AD ポータルにログインします。

2. ナビゲーションメニューで、Manage > App registrations > New registration を選択し、次の設定を完了します。

   • Name: アプリケーション名を入力します。例: apicurio-registry-example
   • Supported account types: Accounts in any organizational directory をクリックします。

   • Redirect URI: リストから Single-page application を選択し、Apicurio Registry Web コンソールアプリケーションホストを入力します。例: https://test-registry.com/ui/

     重要

     Apicurio Registry アプリケーションホストを Redirect URI として登録する必要があります。ログインすると、ユーザーは認証のために Apicurio Registry から Azure AD にリダイレクトされます。その後、ユーザーをアプリケーションに戻す必要があります。Azure AD では、登録されていないリダイレクト URL は許可されません。

3. Register をクリックします。アプリケーション登録の詳細は、Manage > App registrations > apicurio-registry-example を選択すると表示されます。

4. Manage > Authentication を選択し、アプリケーションがリダイレクト URL とトークンを使用して次のように設定されていることを確認します。

   • Redirect URIs: たとえば、https://test-registry.com/ui/ です。
   • Implicit grant and hybrid flows: ID tokens (used for implicit and hybrid flows) をクリックします。
5. Azure AD > Admin > App registrations > Your app > Application (client) ID を選択します。例: 123456a7-b8c9-012d-e3f4-5fg67h8i901
6. Azure AD > Admin > App registrations > Your app > Directory (tenant) ID を選択します。例: https://login.microsoftonline.com/1a2bc34d-567e-89f1-g0hi-1j2kl3m4no56/v2.0

7. Apicurio Registry で、Azure AD 設定を使用して次の環境変数を設定します。

   Expand

   表3.5 Apicurio Registry での Azure AD の設定

   環境変数	説明	設定
   QUARKUS_OIDC_CLIENT-ID	Apicurio Registry REST API のクライアントアプリケーション ID	手順 5 で取得した Azure AD アプリケーション (クライアント) ID。例: 123456a7-b8c9-012d-e3f4-5fg67h8i901
   APICURIO_UI_AUTH_OIDC_CLIENT-ID	Apicurio Registry Web コンソールのクライアントアプリケーション ID。	手順 5 で取得した Azure AD アプリケーション (クライアント) ID。例: 123456a7-b8c9-012d-e3f4-5fg67h8i901
   QUARKUS_OIDC_AUTH-SERVER-URL	Azure AD での認証用 URL。	手順 6 で取得した Azure AD アプリケーション (テナント) ID。例: https://login.microsoftonline.com/1a2bc34d-567e-89f1-g0hi-1j2kl3m4no56/v2.0。

   Show more

8. Apicurio Registry で、Apicurio Registry 固有の設定用に次の環境変数を設定します。

   Expand

   表3.6 Apicurio レジストリー固有の設定

   環境変数	説明	設定
   QUARKUS_OIDC_TENANT-ENABLED	Apicurio Registry の認証を有効にします。	true
   QUARKUS_HTTP_CORS_ORIGINS	cross-origin resource sharing (CORS) 用の Apicurio Registry デプロイメントのホスト。	例: https://test-registry.com
   APICURIO_UI_AUTH_OIDC_REDIRECT-URI	Apicurio Registry Web コンソールのホスト。	例: https://test-registry.com/ui
   APICURIO_AUTH_ROLE-BASED-AUTHORIZATION	Apicurio レジストリーでロールベースの認証を有効にします。	true
   QUARKUS_OIDC_ROLES_ROLE-CLAIM-PATH	Azure AD がロールを保存するクレームの名前。	roles

   Show more
   注記

   Apicurio Registry でロールを有効にする場合は、アプリケーションロールとして同じロールを Azure AD でも作成する必要があります。Apicurio Registry で想定されるデフォルトのロールは、sr-admin、sr-developer、sr-readonly です。

9. Apicurio Registry UI で、次の環境変数を設定します。

手順

1. Explore タブで、Apicurio Registry に保存されているアーティファクトのリストを参照するか、検索文字列を入力してアーティファクトを検索します。リストから選択して、名前、グループ、ラベル、グローバル ID などの特定の条件で検索できます。

   図5.1 Apicurio Registry Web コンソールのアーティファクト

   

   View larger image

   

2. アーティファクトをクリックすると、次の詳細が表示されます。

   • 概要: アーティファクト ID、名前、説明、ラベルなどのアーティファクトメタデータを表示します。また、アーティファクトコンテンツに対して設定できる有効性および互換性のルールも表示されます。
   • バージョン: すべてのアーティファクトバージョンのリストを表示します。アーティファクトの作成時に最初のバージョンをアップロードすることを選択しない限り、これは空になります。

   • ブランチ: アーティファクトのブランチのリストを表示します。これにより、少なくとも latest ブランチが表示されますが、設定によっては他の生成されたブランチが表示される場合もあります。

     図5.2 Apicurio Registry Web コンソールのアーティファクトの詳細

     

     View larger image

     

3. すべてのアーティファクトバージョンのリストを表示するには、Versions タブをクリックします。次に、リスト内のいずれかのバージョンをクリックするか、リスト内のバージョンの Action メニューから View Version を選択します。続いて、以下のアーティファクトバージョンの詳細が表示されます。

   • Overview: バージョン名、説明、グローバル ID、コンテンツ ID、ラベルなどのアーティファクトバージョンのメタデータを表示します。アーティファクトバージョンに対して作成されたコメントも表示されます。
   • Documentation (OpenAPI および AsyncAPI のみ): 自動生成された REST API ドキュメントを表示します。
   • Content: 完全なアーティファクトバージョンコンテンツの読み取り専用ビューを表示します。JSON コンテンツの場合、JSON または YAML をクリックして、好みの形式を表示できます。

   • References: このアーティファクトによって参照されるすべてのアーティファクトの読み取り専用ビューを表示します。View artifacts that reference this artifact version をクリックすることもできます。

     図5.3 Apicurio Registry Web コンソールのアーティファクトバージョンの詳細

     

     View larger image

     
4. アーティファクトの内容を my-openapi.json または my-protobuf-schema.proto などのローカルファイルに保存するには、Download をクリックします。

手順

1. Explore タブで Create artifact をクリックし、Create artifact ウィザードを完了します。

   注記

   コンテンツなしでプレースホルダーアーティファクトを作成できますが、Apicurio Registry はコンテンツタイプを自動的に検出できないため、アーティファクトタイプを指定する必要があります。プレースホルダーを作成すると、最初にルールを作成し、後でコンテンツを追加できます。

   1. Artifact Coordinates を指定して、Next をクリックします。

      • Group ID & Artifact ID: デフォルトの空の設定を使用して、アーティファクト ID を自動的に生成し、アーティファクトを default のアーティファクトグループに追加します。または、オプションのアーティファクトグループまたはアーティファクト ID を入力することもできます。
      • Type: デフォルトの Auto-Detect 設定を使用してアーティファクトタイプを自動的に検出するか (空のアーティファクトを作成する場合は許可されません)、リストからアーティファクトタイプを選択します (例: Avro Schema または OpenAPI)。自動検出できない Kafka Connect Schema アーティファクトタイプを手動で選択する必要があります。

   2. Artifact Metadata を指定して、Next をクリックします。

      • Name: 新しいアーティファクトの任意のわかりやすい名前を入力します。
      • Description: 新しいアーティファクトの任意の説明を入力します。
      • Labels: オプションで、新しいアーティファクトに 1 つ以上のラベル (名前と値のペア) を追加します。

   3. Version Content を指定して、Next をクリックします。

      • Version Number: 最初のバージョンを作成する場合は、任意のバージョン文字列を追加します。

      • コンテンツ: 次のいずれかのオプションを使用してコンテンツを指定します。

        • From file: Browse をクリックしてファイルを選択するか、ファイルをドラッグアンドドロップします。たとえば、my-openapi.json、my-schema.proto などです。または、テキストボックスにファイルの内容を入力することもできます。
        • From URL: 有効かつアクセス可能な URL を入力し、Fetch をクリックします。たとえば、https://petstore3.swagger.io/api/v3/openapi.json です。

   4. Version Metadata を指定します。

      • Name: オプションで、最初のアーティファクトバージョンのフレンドリーネームを入力します。
      • Description: オプションで、最初のアーティファクトバージョンの説明を入力します。
      • Labels: オプションで、最初のアーティファクトバージョンに 1 つ以上のラベル (名前と値のペア) を追加します。

2. Create をクリックして、アーティファクトの詳細を表示します。

   • 概要: アーティファクト ID、名前、説明、ラベルなどのアーティファクトメタデータを表示します。また、アーティファクトコンテンツに対して設定できる有効性および互換性のルールも表示されます。
   • バージョン: すべてのアーティファクトバージョンのリストを表示します。アーティファクトの作成時に最初のバージョンをアップロードすることを選択しない限り、これは空になります。

   • ブランチ: アーティファクトのブランチのリストを表示します。これにより、少なくとも latest ブランチが表示されますが、設定によっては他の生成されたブランチが表示される場合もあります。

     次の例は、Apache Avro アーティファクトの例を示しています。

     図5.4 Apicurio Registry Web コンソールのアーティファクトの詳細

     

     View larger image

     

3. Overview タブで、Edit 鉛筆アイコンをクリックして、名前や説明などのアーティファクトメタデータを編集します。

   分類や検索の目的で、0 個以上のラベル (名前 + 値) を追加することもできます。ラベルを追加するには、次の手順を実行します。

   1. Add label をクリックします。
   2. キー名と値を入力します (オプション)。
   3. 複数のプロパティーを追加するには、最初の 2 つの手順を繰り返します。
   4. Save をクリックします。
4. アーティファクトの内容を my-protobuf-schema.proto または my-openapi.json などのローカルファイルに保存するには、ページの最後にある Download をクリックします。

5. 新しいアーティファクトバージョンを追加するには、Versions タブに切り替えて、ツールバーの Create version をクリックします。次に、以下の情報を提供します。

   1. Version Number: オプションで、新しいバージョンのバージョン文字列を追加します。

   2. コンテンツ: 次のいずれかのオプションを使用してコンテンツを指定します。

      1. From file: Browse をクリックしてファイルを選択するか、ファイルをドラッグアンドドロップします。たとえば、my-openapi.json、my-schema.proto などです。または、テキストボックスにファイルの内容を入力することもできます。
      2. From URL: 有効かつアクセス可能な URL を入力し、Fetch をクリックします。たとえば、https://petstore3.swagger.io/api/v3/openapi.json です。
   3. これで、Create ボタンをクリックして新しいバージョンを作成できます。

6. アーティファクトを削除するには、ページヘッダーの Delete をクリックします。

   警告

   アーティファクトを削除すると、アーティファクトとそのバージョンがすべて削除され、元に戻すことはできません。

手順 (グループ固有ルール)

1. Explore タブで、"Search for" メニューから Groups を選択して、Apicurio Registry 内のグループのリストを参照します。
2. グループをクリックすると、その詳細とコンテンツルールが表示されます。

3. Group-specific rules で Enable をクリックして、グループ内のすべてのアーティファクトコンテンツの有効性、互換性、または整合性ルールを設定し、リストから適切なルール設定を選択します。たとえば、Validity rule では、Full を選択します。

   図5.5 Apicurio Registry Web コンソールのグループ固有ルール

   

   View larger image

   

手順 (アーティファクト固有ルール)

1. Explore タブで、"Search for" メニューから Artifacts を選択して、Apicurio Registry 内のアーティファクトのリストを参照します。
2. リストからアーティファクトをクリックすると、その詳細とコンテンツルールが表示されます。

3. Artifact-specific rules で、Enable をクリックしてアーティファクトコンテンツの有効性、互換性、または整合性ルールを設定し、リストから適切なルール設定を選択します。たとえば、Validity rule では、Full を選択します。

   図5.6 Apicurio Registry Web コンソールの Artifact コンテンツルール

   

   View larger image

   

手順 (グローバルルール)

1. グローバルルールにアクセスするには、Global rules タブをクリックします。

2. Enable をクリックして、すべてのアーティファクトコンテンツに対してグローバルな有効性、互換性または整合性のルールを設定し、リストから適切なルール設定を選択します。

   図5.7 Apicurio Registry Web コンソールの Artifact コンテンツルール

   

   View larger image

   

手順

1. Explore タブで、Apicurio Registry に保存されているアーティファクトのリストを参照するか、検索文字列を入力してアーティファクトを検索します。リストから選択して、名前、グループ、ラベル、グローバル ID などの条件で検索できます。
2. 再割り当てするアーティファクトをクリックします。
3. Overview セクションで、Owner フィールドの横にある鉛筆アイコンをクリックします。
4. New owner フィールドで、アカウント名を選択または入力します。
5. Change owner をクリックします。

手順

1. Apicurio Registry Web コンソールで、Settings タブをクリックします。

2. Apicurio Registry 用の設定を選択します。

   Expand

   表5.1 認証設定

   設定	説明
   HTTP Basic 認証	認証がすでに有効になっている場合にのみ表示されます (デプロイメント中)。選択すると、Apicurio Registry ユーザーは、OAuth に加えて HTTP 基本認証を使用して認証できます。デフォルトでは選択されていません。

   Show more
   Expand

   表5.2 承認設定

   設定	説明
   匿名の読み取りアクセス	認証が有効な場合のみ表示されます。選択すると、Apicurio Registry は、認証情報がない匿名ユーザーからの要求に対して、読み取り専用アクセスを許可します。この設定は、Apicurio Registry を使用してスキーマまたは API を外部に公開する場合に便利です。デフォルトでは選択されていません。
   アーティファクト所有者のみの承認	認証が有効な場合のみ表示されます。選択すると、アーティファクトを作成したユーザーのみがそのアーティファクトを変更できます。デフォルトでは選択されていません。
   アーティファクトグループ所有者のみの承認	認証がすでに有効で、Artifact owner-only authorization も有効な場合にのみ表示されます。選択すると、アーティファクトグループを作成したユーザーのみが、そのアーティファクトグループへの書き込みアクセス権 (そのグループのアーティファクトの追加や削除など) を持ちます。デフォルトでは選択されていません。
   認証された読み取りアクセス	認証が有効な場合のみ表示されます。選択すると、Apicurio Registry は、ユーザーロールに関係なく、認証されたユーザーからのリクエストに対して、少なくとも読み取り専用アクセスを許可します。デフォルトでは選択されていません。

   Show more
   Expand

   表5.3 互換性設定

   設定	説明
   正規ハッシュモード (互換性 API)	選択すると、Schema Registry 互換性 API はコンテンツの通常のハッシュではなく標準的なハッシュを使用します。
   レガシー ID モード (互換 API)	選択すると、Confluent Schema Registry 互換性 API は contentId の代わりに globalId をアーティファクト識別子として使用します。
   返されるサブジェクトの最大数 (互換性 API)	Confluent Schema Registry 互換性 API (/subjects エンドポイント用) によって返されるサブジェクトの最大数を決定します。

   Show more
   Expand

   表5.4 Web コンソールの設定

   設定	説明
   ダウンロードリンクの有効期限	セキュリティー上の理由により期限切れになるまでに、.zip ダウンロードファイルへの生成されたリンクがアクティブな秒数 (例: Apicurio Registry からアーティファクトデータをエクスポートする場合)。デフォルトは 30 秒です。

   Show more
   Expand

   表5.5 Semantic versioning 設定

   設定	説明
   semver ブランチを自動的に作成する	有効にすると、メジャー ('A.x') およびマイナー ('A.B.x') アーティファクトバージョンのブランチが自動的に作成または更新されます。
   すべてのバージョン番号が 'semver' と互換性があることを確認する	有効にすると、すべてのアーティファクトバージョンが Semantic Versioning 2 形式 (https://semver.org) に準拠していることが検証されます。

   Show more
   Expand

   表5.6 追加のプロパティー

   設定	説明
   アーティファクトの削除	選択すると、ユーザーは Core Registry API を使用して Apicurio Registry 内のアーティファクトを削除できるようになります。デフォルトでは選択されていません。
   アーティファクトバージョンの削除	選択すると、ユーザーは Core Registry API を使用して Apicurio Registry 内のアーティファクトバージョンを削除できるようになります。デフォルトでは選択されていません。
   グループの削除	選択すると、ユーザーは Core Registry API を使用して Apicurio Registry 内のグループを削除できるようになります。デフォルトでは選択されていません。
   ストレージ読み取り専用モード	選択すると、レジストリーはストレージへの書き込み操作に対してエラーを返します (このプロパティーを除く)。デフォルトでは有効になっていません。

   Show more

手順

1. ソース Apicurio Registry インスタンスの Web コンソールで、Explore タブを表示します。
2. ツールバーの Create artifact の横にある追加のアクションアイコン (縦に並んだ 3 つのドット) をクリックし、Export all (as .ZIP) を選択して、この Apicurio Registry インスタンスのデータを .zip ダウンロードファイルにエクスポートします。
3. ターゲットの Apicurio Registry インスタンスの Web コンソールで、Explore タブを表示します。
4. ツールバーの Create artifact の横にある追加のアクションアイコン (縦に並んだ 3 つのドット) をクリックし、Import from .ZIP を選択します。
5. 以前にエクスポートした .zip ダウンロードファイルをドラッグアンドドロップするか、参照します。
6. Import をクリックし、データがインポートされるまで待ちます。

手順

1. /groups/{groupId}/artifacts 操作を使用して、Apicurio Registry にアーティファクトを追加します。次の curl コマンドの例では、株価アプリケーションの単純なスキーマアーティファクトを追加します。

   $ curl -X POST MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     --data-raw '{
       "artifactId": "share-price",
       "artifactType": "AVRO",
       "firstVersion": {
           "content": {
               "content": "{\"type\":\"record\",\"name\":\" p\",\"namespace\":\"com.example\", \"fields\":[{\"name\":\"symbol\",\"type\":\"string\"},{\"name\":\"price\",\"type\":\"string\"}]}",
               "contentType": "application/json"
           }
       }
   }'

   Copy to Clipboard Toggle word wrap
   • この例では、アーティファクト ID が share-price の Apache Avro スキーマアーティファクトを追加します。一意のアーティファクト ID を指定しない場合、Apicurio Registry は UUID として自動的に生成します。
   • MY-REGISTRY-URL は、Apicurio Registry がデプロイされているホスト名です。たとえば、http://localhost:8080 です。
   • この例では、API パスで my-group のグループ ID を指定します。一意のグループ ID を指定しない場合は、API パスで ../groups/default を指定する必要があります。

2. 応答に、アーティファクトが追加されたことを確認するために、想定される JSON body が含まれていることを確認します。以下に例を示します。

   {"artifact":{"owner":"","createdOn":"2024-09-26T17:24:21Z","modifiedBy":"","modifiedOn":"2024-09-26T17:24:21Z","artifactType":"AVRO","groupId":"my-group","artifactId":"share-price"},"version":{"version":"1","owner":"","createdOn":"2024-09-26T17:24:21Z","artifactType":"AVRO","globalId":2,"state":"ENABLED","groupId":"my-group","contentId":2,"artifactId":"share-price"}}

   Copy to Clipboard Toggle word wrap
   • アーティファクトの追加時にバージョンが指定されなかったため、デフォルトのバージョン 1 が自動的に作成されます。
   • これは Apicurio Registry に追加された 2 番目のアーティファクトであるため、グローバル ID とコンテンツ ID の値は 2 です。

3. API パスのアーティファクト ID を使用して、Apicurio Registry からアーティファクトバージョンコンテンツを取得します。この例では、指定された ID は share-price です。

   $ curl -H "Authorization: Bearer $ACCESS_TOKEN" \
    MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts/share-price/versions/1/content
    {"type":"record","name":"price","namespace":"com.example",
     "fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}

   Copy to Clipboard Toggle word wrap

手順

1. /groups/{groupId}/artifacts 操作を使用して、レジストリーにアーティファクトバージョンを追加します。以下の curl コマンドの例は、株価アプリケーションの単純なアーティファクトを追加します。

   $ curl -X POST MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     --data-raw '{
       "artifactId": "my-share-price",
       "artifactType": "AVRO",
       "firstVersion": {
           "version": "1.1.1",
           "content": {
               "content": "{\"type\":\"record\",\"name\":\" p\",\"namespace\":\"com.example\", \"fields\":[{\"name\":\"symbol\",\"type\":\"string\"},{\"name\":\"price\",\"type\":\"string\"}]}",
               "contentType": "application/json"
           }
       }
   }'

   Copy to Clipboard Toggle word wrap
   • この例では、アーティファクト ID が my-share-price でバージョンが 1.1.1 の Avro スキーマアーティファクトを追加します。バージョンを指定しない場合、Apicurio Registry はデフォルトバージョンの 1 を自動的に生成します。
   • MY-REGISTRY-URL は、Apicurio Registry がデプロイされているホスト名です。たとえば、http://localhost:8080 です。
   • この例では、API パスで my-group のグループ ID を指定します。一意のグループ ID を指定しない場合は、API パスで ../groups/default を指定する必要があります。

2. 応答に、カスタムアーティファクトバージョンが追加されたことを確認するために、想定される JSON body が含まれていることを確認します。以下に例を示します。

   {"artifact":{"owner":"","createdOn":"2024-09-26T17:06:21Z","modifiedBy":"","modifiedOn":"2024-09-26T17:06:21Z","artifactType":"AVRO","groupId":"my-group","artifactId":"my-share-price"},"version":{"version":"1.1.1","owner":"","createdOn":"2024-09-26T17:06:21Z","artifactType":"AVRO","globalId":4,"state":"ENABLED","groupId":"my-group","contentId":4,"artifactId":"my-share-price"}}

   Copy to Clipboard Toggle word wrap
   • アーティファクトの追加時に、1.1.1 のカスタムバージョンが指定されました。
   • これはレジストリーに追加された 4 つ目のアーティファクトであるため、グローバル ID とコンテンツ ID の値は 4 になります。

3. API パスでアーティファクト ID とバージョンを使用して、レジストリーからアーティファクトコンテンツを取得します。この例では、指定された ID は my-share-price であり、バージョンは 1.1.1 です。

   $ curl -H "Authorization: Bearer $ACCESS_TOKEN" \
       MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts/my-share-price/versions/1.1.1/content
   {"type":"record","name":"price","namespace":"com.example",
     "fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}

   Copy to Clipboard Toggle word wrap

手順

1. /groups/{groupId}/artifacts 操作を使用して、ネストされたアーティファクト参照を作成する ItemId スキーマアーティファクトを追加します。

   $ curl -X POST MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      --data '{"artifactId":"ItemId","artifactType":"AVRO","firstVersion":{"version":"1.0.0","content":{"content":"{\"namespace\":\"com.example.common\",\"name\":\"ItemId\",\"type\":\"record\",\"fields\":[{\"name\":\"id\",\"type\":\"int\"}]}","contentType":"application/json"}}}'

   Copy to Clipboard Toggle word wrap
   • この例では、ItemId のアーティファクト ID を持つ Avro スキーマアーティファクトを追加します。一意のアーティファクト ID を指定しない場合、Apicurio Registry は UUID として自動的に生成します。
   • MY-REGISTRY-URL は、Apicurio Registry がデプロイされているホスト名です。たとえば、http://localhost:8080 です。
   • この例では、API パスで my-group のグループ ID を指定します。一意のグループ ID を指定しない場合は、API パスで ../groups/default を指定する必要があります。

2. 応答に、アーティファクトが追加されたことを確認するために、想定される JSON body が含まれていることを確認します。以下に例を示します。

   {"artifact":{"owner":"","createdOn":"2024-09-26T16:27:38Z","modifiedBy":"","modifiedOn":"2024-09-26T16:27:38Z","artifactType":"AVRO","groupId":"my-group","artifactId":"ItemId"},"version":{"version":"1.0.0","owner":"","createdOn":"2024-09-26T16:27:38Z","artifactType":"AVRO","globalId":2,"state":"ENABLED","groupId":"my-group","contentId":2,"artifactId":"ItemId"}}

   Copy to Clipboard Toggle word wrap

3. /groups/{groupId}/artifacts 操作を使用して、ItemId スキーマへのアーティファクト参照を含む Item スキーマアーティファクトを追加します。

   $ curl -X POST MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts \
   -H 'Content-Type: application/json' \
   -H "Authorization: Bearer $ACCESS_TOKEN" \
   --data-raw '{
   	"artifactId": "Item",
   	"artifactType": "AVRO",
   	"firstVersion": {
   		"version": "1.0.0",
   		"content": {
   			"content": "{\"namespace\":\"com.example.common\",\"name\":\"Item\",\"type\":\"record\",\"fields\":[{\"name\":\"itemId\",\"type\":\"com.example.common.ItemId\"}]}",
   			"contentType": "application/json",
   			"references": [
   				{
   					"name": "com.example.common.ItemId",
   					"groupId": "my-group",
   					"artifactId": "ItemId",
   					"version": "1.0.0"
   				}
   			]
   		}
   	}
   }'

   Copy to Clipboard Toggle word wrap

4. アーティファクトが参照を使用して作成されたことを確認するために、予期される JSON body が応答に含まれていることを確認します。以下に例を示します。

   {"artifact":{"owner":"","createdOn":"2024-09-26T16:28:45Z","modifiedBy":"","modifiedOn":"2024-09-26T16:28:45Z","artifactType":"AVRO","groupId":"my-group","artifactId":"Item"},"version":{"version":"1.0.0","owner":"","createdOn":"2024-09-26T16:28:45Z","artifactType":"AVRO","globalId":3,"state":"ENABLED","groupId":"my-group","contentId":3,"artifactId":"Item"}}

   Copy to Clipboard Toggle word wrap

5. 参照を含むアーティファクトの座標を指定して、Apicurio Registry からアーティファクト参照を取得します。

   $ curl -H "Authorization: Bearer $ACCESS_TOKEN" MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts/Item/versions/1.0.0/references

   Copy to Clipboard Toggle word wrap

6. 応答に、このアーティファクト参照に必要とされる JSON 本文が含まれていることを確認してください。以下に例を示します。

   [{"groupId":"my-group","artifactId":"ItemId","version":"1.0.0","name":"com.example.common.ItemId"}]

   Copy to Clipboard Toggle word wrap

1. 逆参照された (インライン化された) スキーマコンテンツを取得します。

   $ curl -H "Authorization: Bearer $ACCESS_TOKEN" MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts/Item/versions/1.0.0/content?references=DEREFERENCE

   Copy to Clipboard Toggle word wrap

2. 応答に、参照がインライン化されたこのアーティファクトコンテンツの予想される JSON 本文が含まれていることを確認します。以下に例を示します。

   {"type":"record","name":"Item","namespace":"com.example.common","fields":[{"name":"itemId","type":{"type":"record","name":"ItemId","fields":[{"name":"id","type":"int"}]}}]}

   Copy to Clipboard Toggle word wrap

手順

1. 既存のソース Apicurio Registry インスタンスから Apicurio Registry データをエクスポートします。

   $ curl MY-REGISTRY-URL/apis/registry/v3/admin/export \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     --output my-registry-data.zip

   Copy to Clipboard Toggle word wrap

   MY-REGISTRY-URL は、ソース Apicurio Registry がデプロイされているホスト名です。たとえば、http://my-source-registry:8080 です。

2. レジストリーデータをターゲット Apicurio Registry インスタンスにインポートします。

   $ curl -X POST "MY-REGISTRY-URL/apis/registry/v3/admin/import" \
     -H "Content-Type: application/zip" -H "Authorization: Bearer $ACCESS_TOKEN" \
     --data-binary @my-registry-data.zip

   Copy to Clipboard Toggle word wrap

   MY-REGISTRY-URL は、ターゲットの Apicurio Registry がデプロイされているホスト名です。たとえば、http://my-target-registry:8080 です。

手順

1. 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/v3</registryUrl> 

   2

   
               <authServerUrl>MY-AUTH-SERVER</authServerUrl>
               <clientId>MY-CLIENT-ID</clientId>
               <clientSecret>MY-CLIENT-SECRET</clientSecret> 

   3

   
               <clientScope>MY-CLIENT-SCOPE</clientScope>
               <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

   
                       <artifactType>GRAPHQL</artifactType>
                       <file>${project.basedir}/src/main/resources/apis/example.graphql</file>
                       <ifExists>FIND_OR_CREATE_VERSION</ifExists>
                       <canonicalize>true</canonicalize>
                   </artifact>
               </artifacts>
           </configuration>
       </execution>
     </executions>
    </plugin>

   Copy to Clipboard Toggle word wrap

   1

   register を実行ゴールとして指定し、スキーマアーティファクトを Apicurio Registry にアップロードします。

   2

   ../apis/registry/v3 エンドポイントで Apicurio Registry URL を指定します。

   3

   認証が必要な場合は、認証サーバーおよびクライアントの認証情報を指定できます。

   4

   Apicurio Registry アーティファクトグループ ID を指定します。一意のグループ ID を使用しない場合は、default のグループを指定できます。

   5

   指定したグループ ID、アーティファクト ID、および場所を使用して複数のアーティファクトを登録できます。

2. たとえば、mvn package コマンドを使用して、Maven プロジェクトをビルドします。

手順

1. 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/v3</registryUrl> 

   2

   
             <authServerUrl>MY-AUTH-SERVER</authServerUrl>
             <clientId>MY-CLIENT-ID</clientId>
             <clientSecret>MY-CLIENT-SECRET</clientSecret> 

   3

   
             <clientScope>MY-CLIENT-SCOPE</clientScope>
             <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>

   Copy to Clipboard Toggle word wrap

   1

   実行目標として download を指定します。

   2

   ../apis/registry/v3 エンドポイントで Apicurio Registry URL を指定します。

   3

   認証が必要な場合は、認証サーバーおよびクライアントの認証情報を指定できます。

   4

   Apicurio Registry アーティファクトグループ ID を指定します。一意のグループを使用しない場合は、default のグループを指定できます。

   5

   アーティファクト ID を使用すると、複数のアーティファクトを指定したディレクトリーにダウンロードできます。

2. たとえば、mvn package コマンドを使用して、Maven プロジェクトをビルドします。

手順

1. 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/v3</registryUrl> 

   2

   
               <authServerUrl>MY-AUTH-SERVER</authServerUrl>
               <clientId>MY-CLIENT-ID</clientId>
               <clientSecret>MY-CLIENT-SECRET</clientSecret> 

   3

   
               <clientScope>MY-CLIENT-SCOPE</clientScope>
               <artifacts>
                   <artifact>
                       <groupId>TestGroup</groupId> 

   4

   
                       <artifactId>FullNameRecord</artifactId>
                       <file>${project.basedir}/src/main/resources/schemas/record.avsc</file> 

   5

   
                   </artifact>
               </artifacts>
           </configuration>
       </execution>
     </executions>
    </plugin>

   Copy to Clipboard Toggle word wrap

   1

   スキーマアーティファクトをテストするための実行目標として test-update を指定します。

   2

   ../apis/registry/v3 エンドポイントで Apicurio Registry URL を指定します。

   3

   認証が必要な場合は、認証サーバーおよびクライアントの認証情報を指定できます。

   4

   Apicurio Registry アーティファクトグループ ID を指定します。一意のグループを使用しない場合は、default のグループを指定できます。

   5

   アーティファクト ID を使用すると、指定のディレクトリーから複数のアーティファクトをテストできます。

2. たとえば、mvn package コマンドを使用して、Maven プロジェクトをビルドします。

手順

1. 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>
               <phase>generate-sources</phase>
               <goals>
                   <goal>register</goal> 

   1

   
               </goals>
               <configuration>
                   <registryUrl>MY-REGISTRY-URL/apis/registry/v3</registryUrl> 

   2

   
                   <authServerUrl>MY-AUTH-SERVER</authServerUrl>
                   <clientId>MY-CLIENT-ID</clientId>
                   <clientSecret>MY-CLIENT-SECRET</clientSecret> 

   3

   
                   <clientScope>MY-CLIENT-SCOPE</clientScope>
                   <artifacts>
                       <artifact>
                           <groupId>test-group</groupId> 

   4

   
                           <artifactId>TradeKey</artifactId>
                           <version>2.0</version>
                           <artifactType>AVRO</artifactType>
                           <file>
                               ${project.basedir}/src/main/resources/schemas/TradeKey.avsc
                           </file>
                           <ifExists>FIND_OR_CREATE_VERSION</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>
                                   <artifactType>AVRO</artifactType>
                                   <file>
                                       ${project.basedir}/src/main/resources/schemas/Exchange.avsc
                                   </file>
                                   <ifExists>FIND_OR_CREATE_VERSION</ifExists>
                                   <canonicalize>true</canonicalize>
                               </reference>
                           </references>
                       </artifact>
                   </artifacts>
               </configuration>
           </execution>
       </executions>
   </plugin>

   Copy to Clipboard Toggle word wrap

   1

   register を実行ゴールとして指定し、スキーマアーティファクトを Apicurio Registry にアップロードします。

   2

   ../apis/registry/v3 エンドポイントを使用して Apicurio Registry URL を指定します。

   3

   認証が必要な場合は、認証サーバーおよびクライアントの認証情報を指定できます。

   4

   Apicurio Registry アーティファクトグループ ID を指定します。一意のグループ ID を使用しない場合は、default のグループを指定できます。

   5

   グループ ID、アーティファクト ID、バージョン、タイプ、および場所を使用して、Apicurio Registry アーティファクト参照を指定します。この方法で、複数のアーティファクト参照を登録できます。

2. たとえば、mvn package コマンドを使用して、Maven プロジェクトをビルドします。

手順

1. 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>
               <phase>generate-sources</phase>
               <goals>
                   <goal>register</goal> 

   1

   
               </goals>
               <configuration>
                   <registryUrl>MY-REGISTRY-URL/apis/registry/v3</registryUrl> 

   2

   
                   <authServerUrl>MY-AUTH-SERVER</authServerUrl>
                   <clientId>MY-CLIENT-ID</clientId>
                   <clientSecret>MY-CLIENT-SECRET</clientSecret> 

   3

   
                   <clientScope>MY-CLIENT-SCOPE</clientScope>
                   <artifacts>
                       <artifact>
                           <groupId>test-group</groupId> 

   4

   
                           <artifactId>TradeKey</artifactId>
                           <version>2.0</version>
                           <artifactType>AVRO</artifactType>
                           <file>
                               ${project.basedir}/src/main/resources/schemas/TradeKey.avsc 

   5

   
                           </file>
                           <ifExists>FIND_OR_CREATE_VERSION</ifExists>
                           <canonicalize>true</canonicalize>
                           <autoRefs>true</autoRefs> 

   6

   
                       </artifact>
                   </artifacts>
               </configuration>
           </execution>
       </executions>
   </plugin>

   Copy to Clipboard Toggle word wrap

   1

   register を実行ゴールとして指定し、スキーマアーティファクトを Apicurio Registry にアップロードします。

   2

   ../apis/registry/v3 エンドポイントを使用して Apicurio Registry URL を指定します。

   3

   認証が必要な場合は、認証サーバーおよびクライアントの認証情報を指定できます。

   4

   参照を含む親アーティファクトグループ ID を指定します。一意のグループ ID を使用しない場合は、default のグループを指定できます。

   5

   親アーティファクトファイルの場所を指定します。参照されるアーティファクトはすべて、同じディレクトリーに置く必要があります。

   6

   <autoRefs> オプションを true に設定すると、同じディレクトリー内のアーティファクトへのすべての参照が自動的に検出されて登録されます。この方法で、複数のアーティファクト参照を登録できます。

2. たとえば、mvn package コマンドを使用して、Maven プロジェクトをビルドします。

手順

1. Apicurio Registry の URL を使用してクライアントを設定します。以下に例を示します。

   String registryUrl = "https://registry.example.com/apis/registry/v3";
   Properties props = new Properties();
   props.putIfAbsent(SerdeConfig.REGISTRY_URL, registryUrl);

   Copy to Clipboard Toggle word wrap

2. Apicurio 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

   Copy to Clipboard Toggle word wrap

   1

   Apicurio Registry が提供するデシリアライザー。

   2

   デシリアライズは Apache Avro JSON 形式です。

手順

1. Apicurio Registry の URL を使用してクライアントを設定します。以下に例を示します。

   String registryUrl = "https://registry.example.com/apis/registry/v3";
   Properties props = new Properties();
   props.putIfAbsent(SerdeConfig.REGISTRY_URL, registryUrl);

   Copy to Clipboard Toggle word wrap

2. 設定するシリアライザーを使用してクライアントを設定し、Apicurio 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

   Copy to Clipboard Toggle word wrap

   1

   Apicurio Registry により提供されるメッセージキーのシリアライザー。

   2

   Apicurio Registry によって提供されるメッセージ値のシリアライザー。

   3

   スキーマのグローバル ID を検索する検索ストラテジー。

手順

1. Apicurio Registry URL を使用して Java クライアントを作成および設定します。

   String registryUrl = "https://registry.example.com/apis/registry/v3";
   
   RegistryService client = RegistryClient.cached(registryUrl);

   Copy to Clipboard Toggle word wrap

2. シリアライザーおよびデシリアライザーを設定します。

   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(AvroSerdeConfig.USE_SPECIFIC_AVRO_READER, true);
   logSerde.configure(config, false); 

   3

   Copy to Clipboard Toggle word wrap

   1

   Apicurio Registry が提供する Avro シリアライザー。

   2

   Apicurio Registry が提供する Avro デシリアライザー。

   3

   Avro 形式でデシリアライズ用の Apicurio Registry URL および Avro リーダーを設定します。

3. Kafka Streams クライアントを作成します。

   KStream<String, LogInput> input = builder.stream(
       INPUT_TOPIC,
       Consumed.with(Serdes.String(), logSerde)
   );

   Copy to Clipboard Toggle word wrap

1. Apicurio Registry の必須 URL。
2. ID 処理を拡張することで、他の ID 形式をサポートし、その形式に Apicurio Registry SerDes サービスとの互換性を持たせます。たとえば、Confluent の ID 形式とも互換性のあるデフォルトの ID 形式 Integer から Long に変更できます。

1. Apicurio Registry Kafka コンバーターと使用するために必要なシリアライザー。
2. Apicurio Registry Kafka コンバーターで使用するために必要なデシリアライザー。