Apicurio Registry ユーザーガイド

手順

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

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

   

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

   • Overview: アーティファクト名、アーティファクト ID、グローバル ID、コンテンツ ID、ラベル、プロパティーなどのアーティファクトバージョンメタデータを表示します。また、アーティファクトコンテンツに対して設定できる有効性および互換性のルールも表示されます。
   • Documentaion (OpenAPI および AsyncAPI のみ): 自動生成された REST API ドキュメントを表示します。
   • Content: 全アーティファクトコンテンツの読み取り専用ビューを表示します。JSON コンテンツの場合、JSON または YAML をクリックして、好みの形式を表示できます。
   • References: このアーティファクトによって参照されるすべてのアーティファクトの読み取り専用ビューを表示します。View artifacts that reference this artifact クリックすることもできます。
3. このアーティファクトの追加バージョンが追加されている場合は、ページヘッダーの Version リストから選択できます。
4. アーティファクトの内容を my-openapi.json または my-protobuf-schema.proto などのローカルファイルに保存するには、ページの最後にある Download をクリックします。

手順

1. Artifacts タブで Upload artifact をクリックし、次の詳細を指定します。

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

   • Artifact: 次のいずれかのオプションを使用して、アーティファクトの場所を指定します。

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

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

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

   • References: このアーティファクトによって参照されるすべてのアーティファクトの読み取り専用ビューを表示します。View artifacts that reference this artifact クリックすることもできます。Apicurio Registry Maven プラグインまたは REST API のみを使用して、アーティファクト参照を追加できます。

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

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

     

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

   オプションで、検索用のラベルのコンマ区切りリストを入力したり、アーティファクトに関連付けられた任意のプロパティーのキーと値のペアを追加したりすることもできます。プロパティーを追加するには、次の手順を実行します。

   1. Add property をクリックします。
   2. キー名と値を入力します。
   3. 複数のプロパティーを追加するには、最初の 2 つの手順を繰り返します。
   4. Save をクリックします。
4. アーティファクトの内容を my-protobuf-schema.proto または my-openapi.json などのローカルファイルに保存するには、ページの最後にある Download をクリックします。
5. 新しいアーティファクトバージョンを追加するには、ページヘッダーで Upload new version をクリックし、ドラッグアンドドロップするか Browse をクリックして、my-avro-schema.json や my-openapi.json などのファイルをアップロードします。

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

   警告

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

手順

1. Artifacts タブで、Apicurio Registry のアーティファクトのリストを参照するか、検索文字列を入力してアーティファクトを見つけます。リストから選択して、アーティファクト名、グループ、ラベル、またはグローバル ID などの特定の基準で検索できます。
2. アーティファクトをクリックして、そのバージョンの詳細とコンテンツルールを表示します。

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

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

   
4. グローバルルールにアクセスするには、Global rules タブをクリックします。Enable をクリックして、すべてのアーティファクトコンテンツに対してグローバルな有効性、互換性または整合性のルールを設定し、リストから適切なルール設定を選択します。
5. アーティファクトルールまたはグローバルルールを無効にするには、ルールの横にあるゴミ箱アイコンをクリックします。

手順

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

3. Version metadata セクションで、Generate client SDK をクリックし、ダイアログで以下を設定します。

   • Language: クライアント SDK を生成するプログラミング言語 (Java など) を選択します。
   • Generated client class name: クライアント SDK のクラス名 (例: MyJavaClientSDK.) を入力します。
   • Generated client package name: クライアント SDK のパッケージ名 (例: io.my.example.sdk) を入力します。

4. Show advanced settings をクリックして、包含または除外するパスパターンのオプションのコンマ区切りリストを設定します。

   • Include path patterns: クライアント SDK の生成時に含める特定のパス (例: **/.*, **/my-path/*) を入力します。このフィールドが空の場合、すべてのパスが含まれています。

   • Exclude path patterns: クライアント SDK の生成時に除外する特定のパス (例: **/my-other-path/*) を入力します。このフィールドが空の場合、すべてのパスは除外されません。

     図3.4 Apicurio Registry Web コンソールでの Java クライアント SDK の生成

     
5. ダイアログで設定を行ったら、Generate and download をクリックします。
6. ダイアログにクライアント SDK のファイル名 (例: my-client-java.zip) を入力し、Save をクリックしてダウンロードします。

手順

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

手順

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

2. この Apicurio Registry インスタンスに対して設定する設定を選択します。

   表3.1 認証設定

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

   表3.2 認可設定

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

   表3.3 互換性設定

   設定	説明
   レガシー ID モード (互換 API)	選択すると、Confluent Schema Registry 互換性 API は contentId の代わりに globalId をアーティファクト識別子として使用します。この設定は、v1 Core Registry API をベースにする、従来の Apicurio Registry インスタンスから移行する場合に役立ちます。デフォルトでは選択されていません。

   表3.4 Web コンソールの設定

   設定	説明
   ダウンロードリンクの有効期限	インスタンスからアーティファクトデータをエクスポートする場合など、セキュリティー上の理由で有効期限が切れる前に、生成された .zip ダウンロードファイルへのリンクがアクティブである秒数。デフォルトは 30 秒です。
   UI 読み取り専用モード	選択すると、Apicurio Registry Web コンソールが読み取り専用に設定され、作成、読み取り、更新、または削除操作が禁止されます。Core Registry API を使用して行われた変更は、この設定の影響を受けません。デフォルトでは選択されていません。

   表3.5 追加のプロパティー

   設定	説明
   アーティファクトバージョンの削除	選択した場合、ユーザーは Core Registry API を使用して、このインスタンスのアーティファクトバージョンを削除できます。デフォルトでは選択されていません。

手順

1. ソース Apicurio Registry インスタンスの Web コンソールで、Artifacts タブを表示します。
2. Upload artifact の横にあるオプションアイコン (3 つの縦のドット) をクリックし、Download all artifacts (.zip file) を選択して、この Apicurio Registry インスタンスのデータを .zip ダウンロードファイルにエクスポートします。
3. ターゲットの Apicurio Registry インスタンスの Web コンソールで、Artifacts タブを表示します。
4. Upload artifact の横にあるオプションアイコンをクリックし、Upload multiple artifacts を選択します。
5. 以前にエクスポートした .zip ダウンロードファイルをドラッグアンドドロップするか、参照します。
6. Upload をクリックして、データがインポートされるまで待ちます。

手順

1. /groups/{group}/artifacts オペレーションを使用して、アーティファクトを Apicurio Registry に追加します。次の 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

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

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

   {"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 が自動的に作成されます。
   • これは 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/v2/groups/my-group/artifacts/share-price
    {"type":"record","name":"price","namespace":"com.example",
     "fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}

手順

1. /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 スキーマアーティファクトを追加します。バージョンを指定しない場合、Apicurio Registry はデフォルトバージョンの 1 を自動的に生成します。
   • MY-REGISTRY-URL は、Apicurio Registry がデプロイされているホスト名です。例: my-cluster-service-registry-myproject.example.com
   • この例では、API パスで my-group のグループ ID を指定します。一意のグループ ID を指定しない場合は、API パスで ../groups/default を指定する必要があります。

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

   {"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 になります。

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"}]}

手順

1. /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 を指定しない場合、Apicurio Registry は UUID として自動的に生成します。
   • MY-REGISTRY-URL は、Apicurio Registry がデプロイされているホスト名です。例: my-cluster-service-registry-myproject.example.com
   • この例では、API パスで my-group のグループ ID を指定します。一意のグループ ID を指定しない場合は、API パスで ../groups/default を指定する必要があります。

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

   {"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":[]}

3. /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 のカスタムコンテンツタイプを指定する必要があります。

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

   {"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":[{"artifactId":"ItemId","groupId":"my-group","name":"ItemId","version":"1"}] }

5. 参照を含むアーティファクトのグローバル ID を指定して、Apicurio Registry からアーティファクト参照を取得します。この例では、指定されたグローバル ID は 2 です。

   $ curl -H "Authorization: Bearer $ACCESS_TOKEN" MY-REGISTRY-URL/apis/registry/v2/ids/globalIds/2/references

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

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

手順

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

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

   MY-REGISTRY-URL は、ソース Apicurio Registry がデプロイされているホスト名です。例: my-cluster-source-registry-myproject.example.com。

2. レジストリーデータをターゲット Apicurio 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 は、ターゲットの Apicurio Registry がデプロイされているホスト名です。例: my-cluster-target-registry-myproject.example.com。

手順

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/v2</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
                       <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>

   1

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

   2

   ../apis/registry/v2 エンドポイントで 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/v2</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>

   1

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

   2

   ../apis/registry/v2 エンドポイントで 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/v2</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>

   1

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

   2

   ../apis/registry/v2 エンドポイントで 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/v2</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>
                           <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>

   1

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

   2

   ../apis/registry/v2 エンドポイントを使用して 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/v2</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>
                           <type>AVRO</type>
                           <file>
                               ${project.basedir}/src/main/resources/schemas/TradeKey.avsc 5
                           </file>
                           <ifExists>RETURN_OR_UPDATE</ifExists>
                           <canonicalize>true</canonicalize>
                           <autoRefs>true</autoRefs> 6
                       </artifact>
                   </artifacts>
               </configuration>
           </execution>
       </executions>
   </plugin>

   1

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

   2

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

   3

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

   4

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

   5

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

   6

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

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

手順

1. 以下の依存関係を Maven プロジェクトに追加します。

   <dependency>
       <groupId>io.apicurio</groupId>
       <artifactId>apicurio-registry-client</artifactId>
       <version>${apicurio-registry.version}</version>
   </dependency>

2. 次のように Apicurio Registry クライアントを作成します。

   public class ClientExample {
   
       public static void main(String[] args) throws Exception {
          // Create a registry client
          String registryUrl = "https://my-registry.my-domain.com/apis/registry/v2"; 1
          RegistryClient client = RegistryClientFactory.create(registryUrl); 2
       }
   }

   1

   https://my-registry.my-domain.com の例の Apicurio Registry URL を指定すると、クライアントは自動的に /apis/registry/v2 を追加します。

   2

   Apicurio Registry クライアント作成時の他のオプションは、次のセクションの Java クライアント設定を参照してください。

手順

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

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

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

   1

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

   2

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

手順

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

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

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

   1

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

   2

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

   3

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

手順

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

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

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

   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)
   );

1. Apicurio Registry の必須 URL。
2. ID 処理を拡張することで、他の ID 形式をサポートし、その形式に Apicurio Registry SerDes サービスとの互換性を持たせます。たとえば、ID 形式を Long から Integer に変更すると Confluent ID 形式がサポートされます。
3. Confluent ID の処理を簡素化します。true に設定すると、Integer がグローバル ID の検索に使用されます。この設定は、ID_HANDLER オプションと一緒に使用しないでください。

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