新しいスキーマ バージョンを登録する

サブジェクトを作成したら、新しいバージョンを追加できます。このプロセスは、新しいスキーマ バージョンの登録と呼ばれます。新しいバージョンは、そのサブジェクトに関連付けられたスキーマの進化を表します。

サブジェクトには複数のバージョンが存在する場合があります。サブジェクト内のバージョンは、構成可能な互換性ルールに従って、安全なスキーマの進化を保証します。たとえば、サブジェクトはすべての変更に後方互換性があることを要求できます。下位互換性のある変更の例としては、オプション フィールドの追加があります。必須フィールドの追加は下位互換性のない変更と見なされます。サブジェクトが下位互換性用に構成されている場合、この変更は許可されません。ただし、サブジェクトが前方互換性用に構成されている場合は、必須フィールドを追加しても問題ありません。

互換性チェックは遡って適用されません。サブジェクトまたはスキーマ レジストリの互換性ルールが変更されても、サブジェクト内にすでに存在するバージョンが新しいルールに照らし合わせて再検証されることはありません。互換性の詳細については、互換性タイプについてをご覧ください。

必要なロールと権限

サブジェクトのスキーマ バージョンを登録するために必要な権限を取得するには、プロジェクトまたは特定のスキーマ レジストリとサブジェクトに対する Managed Kafka Schema Registry 編集者 （roles/managedkafka.schemaRegistryEditor）IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

この事前定義ロールには、サブジェクトのスキーマ バージョンを登録するために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

サブジェクトのスキーマ バージョンを登録するには、次の権限が必要です。

  • 親コンテキストまたはデフォルト コンテキストにこの権限を付与します。 managedkafka.versions.create

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

上位の Managed Kafka Schema Registry 管理者（roles/managedkafka.schemaRegistryAdmin）ロールにも、これらの権限が含まれています。

Managed Service for Apache Kafka で使用できる事前定義ロールの詳細については、アクセス制御のドキュメントをご覧ください。

新しいスキーマ バージョンを登録する

新しいスキーマ バージョンを登録するには、次の操作を行います。

コンソール

  1. Google Cloud コンソールで、[スキーマ レジストリ] ページに移動します。

    スキーマ レジストリに移動

  2. 新しいスキーマ バージョンを登録するスキーマ レジストリの名前をクリックします。

  3. [このスキーマ レジストリのサブジェクト] で、サブジェクトの名前をクリックします。

  4. [サブジェクトの詳細] ページで、 [バージョンを作成] をクリックします。

  5. [スキーマ定義] フィールドに、最新バージョンの定義が表示されます。このフィールドの定義を新しいバージョンに更新します。スキーマ フィールド名に、個人を特定できる情報（PII）やセキュリティ データなどの機密情報を含めないでください。

  6. スキーマがスキーマ レジストリの他のスキーマで定義されたデータ構造を使用または依存している場合は、次の手順を行います。

    1. [Add Schema reference] をクリックします。
    2. [Reference name] フィールドに、参照されるスキーマの参照名を入力します。
    3. [サブジェクト] リストで、参照されるスキーマを含むサブジェクトを選択します。
    4. [バージョン] リストで、参照されるスキーマのバージョン番号を選択します。
    5. [OK] をクリックします。

    参照されるスキーマごとに、上記の手順を繰り返します。

  7. 省略可: 新しいスキーマが以前のバージョンと互換性があるかどうかを確認するには、[互換性を確認] をクリックします。

    スキーマに互換性がある場合は、 チェックマークが表示されます。それ以外の場合は、エラー メッセージが表示されます。その場合は、エラーを修正して [互換性を確認] をもう一度クリックします。

    実行される互換性チェックは、サブジェクトの互換性タイプによって異なります。

  8. [作成] をクリックします。スキーマ定義が有効で、サブジェクトの互換性チェックに合格すると、新しいバージョンが [すべてのバージョン] に表示されます。

REST

リクエストは、Authorization ヘッダー内のアクセス トークンにより認証を受ける必要があります。現在のアプリケーションのデフォルト認証情報のアクセス トークンを取得する場合は、gcloud auth application-default print-access-token を使用します。

デフォルト コンテキスト内のサブジェクトの新しいスキーマ バージョンを登録するには、projects.locations.schemaRegistries.subjects.versions.create メソッドを使用して特定の URI に POST リクエストを送信します。

POST https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/subjects/SUBJECT_ID/versions
Authorization: Bearer $(gcloud auth application-default print-access-token)
Content-Type: application/json

特定のコンテキストを使用する場合は、バージョン コレクション URI にコンテキストを含め、projects.locations.schemaRegistries.contexts.subjects.versions.create メソッドを使用します。

POST https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/contexts/CONTEXT_ID/subjects/SUBJECT_ID/versions
Authorization: Bearer $(gcloud auth application-default print-access-token)
Content-Type: application/json

次のように置き換えます。

  • PROJECT_ID（必須）: Google Cloudプロジェクト ID。
  • LOCATION（必須）: スキーマ レジストリが存在する Google Cloud リージョン。
  • REGISTRY_ID（必須）: ターゲット スキーマ レジストリの ID。
  • CONTEXT_ID（省略可）: サブジェクトを含むコンテキストの ID。明示的に指定する場合は、デフォルトのコンテキストに .（単一のピリオド）を使用します。それ以外の場合は、/contexts/CONTEXT_ID を省略して、デフォルトのコンテキストを暗黙的に使用します。
  • SUBJECT_ID（必須）: 新しいバージョンを作成するサブジェクトの ID。

リクエストの本文:

リクエストの本文に、スキーマの詳細を指定する JSON オブジェクトを含めます。

{
  "schema": "YOUR_SCHEMA_DEFINITION_STRING",
  "schema_type": "AVRO" | "PROTOBUF" | "JSON", // Optional, defaults to AVRO
  "references": [ // Optional
    {
      "name": "REFERENCE_NAME",
      "subject": "REFERENCED_SUBJECT_ID",
      "version": REFERENCED_VERSION_NUMBER
    }
    // ... more references
  ]
  // "version": VERSION_NUMBER, // Optional: Usually omitted, let service assign next
  // "id": SCHEMA_ID, // Optional: Usually omitted, let service assign or reuse
}

次のように置き換えます。

  • YOUR_SCHEMA_DEFINITION_STRING（必須）: 実際のスキーマ定義ペイロードを含む文字列。

  • schemaType（省略可、schema オブジェクト内）: スキーマのタイプ。AVRO または PROTOBUF のいずれかです。省略した場合のデフォルトは AVRO です。

  • references（省略可、schema オブジェクト内）: このスキーマで参照されるスキーマを定義するオブジェクトの配列。

    • REFERENCE_NAME: このスキーマの定義内で他のスキーマを参照するために使用される名前。

    • REFERENCED_SUBJECT_ID: 参照されるスキーマの完全修飾サブジェクト名。projects/test-project/locations/us-central1/schemaRegistries/test-registry/subjects/test-referenced-subject

    • REFERENCED_VERSION_NUMBER: 参照されるサブジェクトのスキーマの特定のバージョン番号（整数）。

  • versionId、schemaId: 通常はサービスによって処理される省略可能なフィールド。スキーマ バージョンを登録すると、サービスは次に使用可能なバージョン番号を割り当てます。

リクエストが成功すると、API は 200 OK ステータス コードとスキーマ ID を含むレスポンス本文を返します。

詳細については、REST API のドキュメントをご覧ください。

次のステップ

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