サブジェクトを作成する

このドキュメントでは、スキーマレジストリにサブジェクトを作成する方法について説明します。サブジェクトは、スキーマのさまざまなバージョンの論理コンテナです。サブジェクトを初めて作成するときに、そのサブジェクトのスキーマの最初のバージョンも作成します。

サブジェクトは、次のいずれかの方法で作成できます。

暗黙的（デフォルト）: 多くのプロデューサークライアントとコンシューマークライアントのデフォルトの動作は、クライアントが接続したときに存在しないスキーマを自動的に作成することです。スキーマを参照するサブジェクトとバージョンも自動的に作成されます。これは便利ですが、複数のクライアントが同時にバージョンを作成すると、データに不整合が生じる可能性があります。
明示的（推奨）: この方法では、プロデューサーまたはコンシューマークライアントがスキーマを使用する前に、各スキーマをレジストリに作成する必要があります。これを行うには、 Google Cloud コンソールまたは Managed Kafka API を使用します。

この動作はクライアント設定で構成する必要があります。詳細については、シリアライザーまたはデシリアライザーのクライアントライブラリのドキュメントをご覧ください。

始める前に

スキーマの概要について学習する。
スキーマレジストリがまだない場合は、スキーマレジストリを作成します。
スキーマリファレンスについて理解する。

必要なロールと権限

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

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

必要な権限

サブジェクトを作成するには、次の権限が必要です。

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

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

上位レベルの マネージド Kafka スキーマレジストリ管理者（roles/managedkafka.schemaRegistryAdmin）ロールには、サブジェクトバージョンを作成および管理する権限も含まれています。

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

サブジェクトまたはスキーマの最初のバージョンを作成する

サブジェクトを作成すると、最初のバージョンも作成されます。この最初のバージョンでは、新しいスキーマを作成するか、既存のスキーマへの参照を作成します。

コンソール

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

スキーマレジストリに移動
サブジェクトを作成するスキーマレジストリの名前をクリックします。
[ 件名を作成] をクリックします。
[サブジェクト名] に、サブジェクトの一意の名前を入力します。

名前は文字で始まり、文字、数字、特殊文字（ダッシュ（-）、ピリオド（.）、アンダースコア（_）、チルダ（~）、パーセント（%）、プラス記号（+））のみを含める必要があります。サブジェクトの名前は変更できません。

サブジェクト名の選択の詳細については、サブジェクトの命名戦略をご覧ください。
[コンテキスト] で、コンテキストを選択するか、新しいコンテキストを作成します。コンテキストは、サブジェクトとスキーマを整理する名前空間のように機能し、異なるグループ間の分離を提供します。
- 既存のコンテキストを使用するには、[コンテキスト] リストからコンテキストを選択します。デフォルトのコンテキストは (default context) と表示されます。
- 新しいコンテキストを作成する手順は次のとおりです。
  1. [コンテキスト] リストから [コンテキストを作成] を選択します。
  2. [コンテキスト名] フィールドに、コンテキストの名前を入力します。
    
    名前の先頭は英字にする必要があります。使用できる文字は、英字、数字、および特殊文字としてダッシュ（-）、ピリオド（.）、アンダースコア（_）、チルダ（~）、パーセント（%）、プラス記号（+）のみです。コンテキストの名前は変更できません。
  3. [保存] をクリックします。
[スキーマタイプ] で、[Avro] または [プロトコルバッファ] を選択します。
[スキーマ定義] フィールドにスキーマ定義を入力します。スキーマの形式は、スキーマタイプと一致する必要があります。スキーマフィールド名に、個人を特定できる情報（PII）やセキュリティデータなどの機密情報を含めないでください。
スキーマがスキーマレジストリの他のスキーマで定義されたデータ構造を使用または依存している場合は、次の手順を行います。
1. [Add Schema reference] をクリックします。
2. [Reference name] フィールドに、参照されるスキーマの参照名を入力します。
3. [サブジェクト] リストで、参照されるスキーマを含むサブジェクトを選択します。
4. [バージョン] リストで、参照されるスキーマのバージョン番号を選択します。
5. [OK] をクリックします。
参照されるスキーマごとに、上記の手順を繰り返します。
[作成] をクリックします。

REST

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

次の REST API サンプルは、サブジェクトの最初のバージョンを作成します。

デフォルトコンテキスト内にサブジェクトを作成するには、projects.locations.schemaRegistries.subjects.versions.create メソッドを使用して、指定された URI に POST リクエストを送信します。

POST https://managedkafka.googleapis.com/v1main/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

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

POST https://managedkafka.googleapis.com/v1main/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", // 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（必須）: 実際のスキーマ定義ペイロードを含む文字列。

スキーマフィールド名に、個人を特定できる情報（PII）やセキュリティデータなどの機密情報を含めないでください。
schemaType（省略可）: スキーマのタイプ。AVRO または PROTOBUF のいずれかです。省略した場合のデフォルトは AVRO です。
references（省略可）: このスキーマで参照されるスキーマを定義するオブジェクトの配列。
- REFERENCE_NAME: このスキーマの定義内で他のスキーマを参照するために使用される名前。
- REFERENCED_SUBJECT_ID: 参照されるスキーマのサブジェクト ID。
- REFERENCED_VERSION_NUMBER: 参照されるサブジェクトのスキーマの特定のバージョン番号。
versionId、schemaId: 通常はサービスによって処理されるオプションのフィールド。科目の最初のバージョンでは、versionId は「1」になります。

リクエストが成功し、スキーマが有効で、互換性チェックが構成されている場合は、そのチェックに合格すると、API は 200 OK ステータスコードを返します。レスポンス本文には、作成されたバージョンで使用されるスキーマ ID が含まれます。これはバージョン ID とは異なります。

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

次のステップ

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