スキーマレジストリの概要

スキーマレジストリは、複数のアプリケーションで共有されるスキーマのリポジトリを提供します。以前は、スキーマレジストリがない場合、チームは口頭での理解、プログラムで強制されない共有ドキュメント、Wiki ページなどの非公式な合意に依存して、メッセージ形式とメッセージのシリアル化と逆シリアル化の方法を定義していました。スキーマレジストリにより、メッセージのエンコードとデコードの一貫性が確保されます。

このドキュメントでは、Managed Service for Apache Kafka のスキーマレジストリ機能、そのコンポーネント、基本的なワークフローの概要について説明します。

スキーマについて

顧客の注文を追跡するアプリケーションを構築しているとします。customer_orders という Kafka トピックを使用して、各注文に関する情報を含むメッセージを送信できます。一般的な注文メッセージには、次の情報フィールドが含まれます。

注文 ID
顧客名
商品名
数量
価格

これらのメッセージの構造を常に一貫させるには、スキーマを定義します。Apache Avro 形式の例を次に示します。

{
  "type": "record",
  "name": "Order",
  "namespace": "com.example",
  "fields": [
    {"name": "orderId", "type": "string"},
    {"name": "customerName", "type": "string"},
    {"name": "productName", "type": "string"},
    {"name": "quantity", "type": "int"},
    {"name": "price", "type": "double"}
  ]
}

同じ例を Protocol Buffer 形式で示します。

syntax = "proto3";

package com.example;

option java_multiple_files = true; // Optional: Recommended for Java users
option java_package = "com.example"; // Optional: Explicit Java package

message Order {
  string orderId = 1;
  string customerName = 2;
  string productName = 3;
  int32 quantity = 4; // Avro int maps to Protobuf int32
  double price = 5;
}

このスキーマはメッセージのブループリントです。これは、order メッセージに注文 ID、顧客名、商品名、数量、価格の 5 つのフィールドがあることを示しています。また、各フィールドのデータ型も指定します。

コンシューマークライアントがこのスキーマでエンコードされたバイナリメッセージを受信した場合、その解釈方法を正確に把握している必要があります。これを実現するために、プロデューサーは order スキーマをスキーマレジストリに保存し、スキーマの識別子をメッセージとともに渡します。メッセージのコンシューマーが使用されたレジストリを認識している限り、同じスキーマを取得してメッセージをデコードできます。

order メッセージに orderDate フィールドを追加するとします。order スキーマの新しいバージョンを作成し、同じサブジェクトに登録します。これにより、スキーマの経時的な変化を追跡できます。フィールドの追加は上位互換性のある変更です。つまり、古いスキーマバージョン（orderDate なし）を使用しているコンシューマーは、新しいスキーマで生成されたメッセージを読み取って処理できます。新しいフィールドは無視されます。

スキーマレジストリの下位互換性とは、新しいスキーマバージョンで構成されたコンシューマーアプリケーションが、以前のスキーマで生成されたデータを読み取ることができることを意味します。

この例では、最初の order スキーマはバージョン 1 になります。orderDate フィールドを追加すると、order スキーマのバージョン 2 が作成されます。両方のバージョンが同じサブジェクトに保存されるため、バージョン 1 を使用している既存のアプリケーションを中断することなく、スキーマの更新を管理できます。

コンテキスト、サブジェクト、スキーマバージョンで整理された schema_registry_test というサンプルスキーマレジストリのトップダウンビューを次に示します。

customer_support コンテキスト
- order subject
- V1 バージョン（orderId、customerName、productName、quantity、price を含む）
- V2 バージョン（V1 に orderDate を追加）

スキーマとは

Apache Kafka メッセージはバイト文字列で構成されています。構造が定義されていない場合、コンシューマーアプリケーションは、これらのバイトを解釈する方法を理解するために、プロデューサーアプリケーションと直接連携する必要があります。

スキーマは、メッセージ内のデータの正式な説明を提供します。フィールドとそのデータ型（文字列、整数、ブール値など）と、ネストされた構造を定義します。

Managed Service for Apache Kafka は、次の形式のスキーマをサポートしています。

Apache Avro
プロトコルバッファ（Protobuf）

スキーマレジストリ API は JSON をサポートしていません。

Managed Service for Apache Kafka に統合されたスキーマレジストリ機能を使用すると、Kafka クライアントでこれらのスキーマを作成、管理、使用できます。スキーマレジストリは、既存の Apache Kafka アプリケーションと一般的なクライアントライブラリと互換性のある Confluent Schema Registry REST API を実装しています。

スキーマレジストリの組織

スキーマレジストリは、階層構造を使用してスキーマを整理します。

図: スキーマの階層構造。

スキーマ: メッセージの構造とデータ型。各スキーマはスキーマ ID で識別されます。この ID は、アプリケーションがスキーマを取得するために使用します。
Subject: スキーマのさまざまなバージョンの論理コンテナ。サブジェクトは、互換性ルールを使用して、スキーマが時間の経過とともにどのように進化するかを管理します。通常、各サブジェクトは Kafka トピックまたはレコードオブジェクトに対応します。
バージョン: ビジネスロジックでメッセージ構造の変更が必要な場合は、関連するサブジェクトの下に新しいスキーマバージョンを作成して登録します。

各バージョンは特定のスキーマを参照します。基盤となるスキーマが同じであれば、異なるサブジェクトのバージョンが同じスキーマを参照できます。
コンテキスト: サブジェクトのハイレベルなグループまたは名前空間。コンテキストを使用すると、同じスキーマレジストリ内で競合することなく、異なるチームやアプリケーションが同じサブジェクト名を使用できます。

スキーマレジストリには複数のコンテキストを設定できます。常に . として識別されるデフォルトのコンテキストが含まれます。他のコンテキスト識別子が指定されていない場合、スキーマとサブジェクトはここに移動します。

コンテキストには複数のサブジェクトを含めることができます。
レジストリ: スキーマエコシステム全体の最上位コンテナ。すべてのスキーマ、サブジェクト、バージョン、コンテキストを保存して管理します。

スキーマレジストリのワークフロー

このセクションで説明するワークフローを試すには、スキーマレジストリを使用して Avro メッセージを生成するのクイックスタートをお試しください。

Kafka クライアントのシリアライザーとデシリアライザーは、スキーマレジストリと連携して、メッセージが定義されたスキーマに準拠していることを確認します。Managed Service for Apache Kafka のスキーマレジストリの一般的なワークフローは次のとおりです。

Avro 生成クラスとして指定された特定のスキーマを使用してプロデューサーアプリケーションを初期化し、特定のスキーマレジストリとシリアライザーライブラリを使用するように構成します。
対応するデシリアライザーライブラリと同一のスキーマレジストリを使用するようにコンシューマークライアントを構成します。
実行時に、クライアントはメッセージオブジェクトを producer.send メソッドに渡します。Kafka クライアントライブラリは、構成されたシリアライザーを使用して、このレコードを Avro エンコードされたバイトに変換します。
シリアライザーは、クライアントライブラリ内で構成されたサブジェクト名戦略に基づいて、スキーマのサブジェクト名を決定します。次に、このサブジェクト名をスキーマレジストリへのリクエストで使用して、スキーマの ID を取得します。詳細については、サブジェクトの命名戦略をご覧ください。
そのサブジェクト名でスキーマがレジストリに存在しない場合、クライアントはスキーマを登録するように構成できます。この場合、新しく割り当てられた ID が返されます。

本番環境ではこの構成は避けてください。
プロデューサーは、スキーマ ID を含むシリアル化されたメッセージを Kafka ブローカーの適切なトピックに送信します。
Kafka ブローカーは、メッセージのバイト配列表現をトピックに保存します。
コンシューマーアプリケーションがメッセージを受信します。
デシリアライザーは、この ID を持つスキーマをスキーマレジストリから取得します。
デシリアライザーは、コンシューマーアプリケーションのメッセージを解析します。

制限事項

スキーマレジストリでは、次の機能はサポートされていません。

スキーマ形式:
- JSON スキーマ形式。
スキーマモード:
- READONLY_OVERRIDE スキーマモード。
スキーマ構成値:
- Normalize と Alias の構成値。
API メソッド:
- ModifySchemaTags メソッド（/subjects/{subject}/versions/{version}/tags）。
- GetLatestWithMetadata メソッド（/subjects/{subject}/metadata）。
- ListSchemas メソッド（/schemas）。
- DeleteSchemaMode メソッド。
- GetVersion メソッドの場合: format、deleted、findTags パラメータ。
- CreateVersion メソッドの場合: metadata、ruleSet、schemaTagsToAdd、schemaTagsToRemove パラメータ。
- UpdateSchemaMode メソッドの場合: force パラメータ。
- GetSchemaMode メソッドの場合: defaultToGlobal パラメータ。
- GetSchema メソッドの場合: WorkspaceMaxId パラメータと findTags パラメータ。
- ListVersions メソッドの場合: deletedOnly パラメータ。
- ListSubjects メソッドの場合: deletedOnly パラメータ。

次のステップ

Apache Kafka® は、Apache Software Foundation または米国その他の諸国における関連会社の商標です。