1. Home
  2. Platform
  3. スキーマ管理
  4. Schema Registry 開発者ガイド

Schema Registry Maven プラグイン

Looking for Schema Management Confluent Cloud docs? You are currently viewing Confluent Platform documentation. If you are looking for Confluent Cloud docs, check out Schema Management on Confluent Cloud.

Schema Registry 向けの開発プロセス全体を支援する Maven プラグインが提供されています。構成オプションは以下のとおりです。

ちなみに

Schema Registry 向けにすぐに利用できる公式の Gradle プラグインはありません。一方、次のプラグインはいずれも、Maven pom.xml （Project Object Model ファイル）から参照することができます。

schema-registry:download

download の目的は、Schema Registry サーバーからスキーマを取得することです。リクエストされたサブジェクトの Avro スキーマをダウンロードして、ローカルファイルシステム上のフォルダーに書き込む際にこのプラグインを使用します。

schemaRegistryUrls

接続先となる Schema Registry の URL

  • 型: String[]
  • 必須: true
userInfoConfig

Schema Registry に接続するためのユーザーの資格情報（user:password 形式）。Confluent Cloud Schema Registry に接続する場合は必須となります。

  • 型: String[]
  • 必須: false
  • デフォルト: null
outputDirectory

スキーマの書き込み先となる出力ディレクトリ。

  • 型: File
  • 必須: true
schemaExtension

出力ファイル名に使用するファイル拡張子。先頭文字は「.」とする必要があります。

  • 型: File
  • 必須: false
  • デフォルト: .avsc
subjectPatterns

ダウンロードするサブジェクトのパターン。一連の正規表現を指定します。サブジェクト名全体と一致するパターンを使用してください。

  • 型: String[]
  • 必須: true
<plugin>
    <groupId>io.confluent</groupId>
    <artifactId>kafka-schema-registry-maven-plugin</artifactId>
    <version>6.1.5</version>
    <configuration>
        <schemaRegistryUrls>
            <param>http://192.168.99.100:8081</param>
        </schemaRegistryUrls>
        <outputDirectory>src/main/avro</outputDirectory>
        <subjectPatterns>
            <param>^TestSubject000-(key|value)$</param>
        </subjectPatterns>
    </configuration>
</plugin>
Copy

schema-registry:test-compatibility

ローカルファイルシステムからスキーマを読み取って、Schema Registry サーバーとの間で互換性をテストする目的に使用します。継続的なパイプラインで使用することにより、プロジェクト内のスキーマと他の環境のスキーマとの間に互換性を確保することができます。

schemaRegistryUrls

接続先となる Schema Registry の URL

  • 型: String[]
  • 必須: true
userInfoConfig

Schema Registry に接続するためのユーザーの資格情報（user:password 形式）。Confluent Cloud Schema Registry に接続する場合は必須となります。

  • 型: String[]
  • 必須: false
  • デフォルト: null
subjects

登録するサブジェクトのスキーマへのパスを格納するマップ。

  • 型: Map<String, File>
  • 必須: true

ちなみに

Confluent Platform 5.5.5 以降では、サブジェクト名にスラッシュ / などの特殊文字を指定できます。そのためには、まずサブジェクト名を URL エンコードしたうえで、その出力に含まれる無効な文字を置き換えます。たとえば、path/to/my.proto というサブジェクト名を URL エンコードすると、`%2Fpath%2Fto%2Fmy.proto` のような結果が生成されますが、XML 名では % が有効ではないため、この結果の % を _x に置き換えて _x2Fpath_x2Fto_x2Fmy.proto のように修正します。この背景には、Maven プラグインではサブジェクト名を XML 要素として指定する必要がありますが、スラッシュのような一部の文字は XML 名では無効であるという事実があります。サブジェクトに /path/to/my.proto を使用するなど、他のスキーマから参照される Protobuf スキーマ を登録する際にスラッシュを使いたい場合があります。この回避策によってそれが可能となります。

schemaTypes

スキーマタイプ を指定する文字列。

  • 型: String（AVRO （デフォルト）、JSON、PROTOBUF のいずれか）
  • 必須: false
  • デフォルト: AVRO
references

参照名とサブジェクトを格納するマップ

  • 型: Map<String, Reference[]>
  • 必須: false
verbose

スキーマが互換性テストで不合格になった場合、その理由を出力に含めます。

  • 型: Boolean
  • 必須: false
  • デフォルト: true

次の例では、プラグインを使用して 3 つのサブジェクト（order、product、customer）を構成しています。スキーマタイプとしては AVRO を使用しています。

<plugin>
    <groupId>io.confluent</groupId>
    <artifactId>kafka-schema-registry-maven-plugin</artifactId>
    <version>6.1.5</version>
    <configuration>
        <schemaRegistryUrls>
            <param>http://192.168.99.100:8081</param>
        </schemaRegistryUrls>
        <subjects>
            <order>src/main/avro/order.avsc</order>
            <product>src/main/avro/product.avsc</product>
            <customer>src/main/avro/customer.avsc</customer>
        </subjects>
        <schemaTypes>
            <order>AVRO</order>
            <product>AVRO</product>
            <customer>AVRO</customer>
        </schemaTypes>
        <references>
            <order>
              <reference>
                  <name>com.acme.Product</name>
                  <subject>product</subject>
              </reference>
              <reference>
                  <name>com.acme.Customer</name>
                  <subject>customer</subject>
              </reference>
            </order>
        </references>
    </configuration>
    <goals>
        <goal>test-compatibility</goal>
    </goals>
</plugin>
Copy

使用例

schema-registry:test-compatibility の使用例については、次の記事を参照してください。

schema-registry:validate

ローカルファイルシステムからスキーマを読み取って、それらを登録前にローカルで検証する目的に使用します。構文エラーが見つかった場合は、それらを調査して修正した後、schema-registry:register を使用してスキーマを Schema Registry に送信することができます。

schemaRegistryUrls

接続先となる Schema Registry の URL

  • 型: String[]
  • 必須: true
userInfoConfig

Schema Registry に接続するためのユーザーの資格情報（user:password 形式）。Confluent Cloud Schema Registry に接続する場合は必須となります。

  • 型: String[]
  • 必須: false
  • デフォルト: null
subjects

登録するサブジェクトのスキーマへのパスを格納するマップ。

  • 型: Map<String, File>
  • 必須: true
schemaTypes

スキーマタイプ を指定する文字列。

  • 型: String（AVRO （デフォルト）、JSON、PROTOBUF のいずれか）
  • 必須: false
  • デフォルト: AVRO
references

参照名とサブジェクトを格納するマップ

  • 型: Map<String, Reference[]>
  • 必須: false

schema-registry:register

ローカルファイルシステムからスキーマを読み取って、ターゲットの Schema Registry サーバーに登録する目的に使用します。継続的なデプロイパイプラインで使用することにより、新しい環境にスキーマをプッシュすることができます。

schemaRegistryUrls

接続先となる Schema Registry の URL

  • 型: String[]
  • 必須: true
userInfoConfig

Schema Registry に接続するためのユーザーの資格情報（user:password 形式）。Confluent Cloud Schema Registry に接続する場合は必須となります。

  • 型: String[]
  • 必須: false
  • デフォルト: null
subjects

登録するサブジェクトのスキーマへのパスを格納するマップ。

  • 型: Map<String, File>
  • 必須: true
schemaTypes

スキーマタイプ を指定する文字列。

  • 型: String（AVRO （デフォルト）、JSON、PROTOBUF のいずれか）
  • 必須: false
  • デフォルト: AVRO
references

参照名とサブジェクトを格納するマップ

  • 型: Map<String, Reference[]>
  • 必須: false

次の例では、プラグインを使用して 3 つのサブジェクト（order、product、customer）を構成しています。スキーマタイプとしては AVRO を使用しています。

<plugin>
    <groupId>io.confluent</groupId>
    <artifactId>kafka-schema-registry-maven-plugin</artifactId>
    <version>6.1.5</version>
    <configuration>
        <schemaRegistryUrls>
            <param>http://192.168.99.100:8081</param>
        </schemaRegistryUrls>
        <subjects>
            <order>src/main/avro/order.avsc</order>
            <product>src/main/avro/product.avsc</product>
            <customer>src/main/avro/customer.avsc</customer>
        </subjects>
        <schemaTypes>
            <order>AVRO</order>
            <product>AVRO</product>
            <customer>AVRO</customer>
        </schemaTypes>
        <references>
            <order>
              <reference>
                  <name>com.acme.Product</name>
                  <subject>product</subject>
              </reference>
              <reference>
                  <name>com.acme.Customer</name>
                  <subject>customer</subject>
              </reference>
            </order>
        </references>
    </configuration>
    <goals>
        <goal>register</goal>
    </goals>
</plugin>
Copy