このドキュメントでは、スキーマ レジストリでサブジェクトを作成する方法について説明します。サブジェクトは、スキーマのさまざまなバージョンを格納する論理コンテナです。 サブジェクトを初めて作成するときに、そのサブジェクトのスキーマの最初のバージョンも作成します。
サブジェクトは、次のいずれかの方法で作成できます。
暗黙的（デフォルト）: 多くのプロデューサー クライアントとコンシューマー クライアントのデフォルトの動作では、クライアントが接続したときに存在しないスキーマが自動的に作成されます。スキーマを参照するサブジェクトとバージョンも自動的に作成されます。これは便利ですが、複数のクライアントが同時にバージョンを作成すると、データの不整合が生じる可能性があります。
明示的（推奨）: この方法では、プロデューサー クライアントまたはコンシューマー クライアントが使用する前に、各スキーマをレジストリに作成する必要があります。これを行うには、 コンソールまたは Managed Kafka API Google Cloud を使用します。
この動作は、クライアント設定で構成する必要があります。詳細については、シリアライザまたはデシリアライザ クライアント ライブラリのドキュメントをご覧ください。
始める前に
スキーマの概要について学習します。
スキーマ レジストリを作成します （まだ作成していない場合）。
スキーマ参照について理解します。
必要なロールと権限
サブジェクトの作成に必要な権限を取得するには、プロジェクトまたはスキーマ レジストリに対するManaged Kafka スキーマ レジストリ編集者 （roles/managedkafka.schemaRegistryEditor）IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。
この事前定義ロールには サブジェクトの作成に必要な権限が含まれています。必要とされる正確な権限については、必要な権限セクションを開いてご確認ください。
必要な権限
サブジェクトを作成するには、次の権限が必要です。
-
親コンテキストまたはデフォルト コンテキストに次の権限を付与します。
managedkafka.versions.create
カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。
サブジェクトまたはスキーマの最初のバージョンを作成する
サブジェクトを作成すると、その最初のバージョンも作成されます。この最初のバージョンでは、新しいスキーマが作成されるか、既存のスキーマが参照されます。
コンソール
コンソールで、[**スキーマ レジストリ**] ページに移動します。 Google Cloud
サブジェクトを作成するスキーマ レジストリの名前をクリックします。
[ [サブジェクトを作成]] をクリックします。
[**サブジェクト名**] に、サブジェクトの一意の名前を入力します。
名前は文字で始まり、文字、数字、次の特殊文字のみを含める必要があります。ダッシュ（
-）、ピリオド（.）、アンダースコア（_）、チルダ（~）、パーセント（%）、プラス記号（+）。サブジェクトの名前は変更できません。サブジェクト名の選択の詳細については、 サブジェクトの命名戦略をご覧ください。
For [Context] で、コンテキストを選択するか、新しいコンテキストを作成します。コンテキストは名前空間のように機能して、サブジェクトとスキーマを整理し、異なるグループ間の分離を提供します。
既存のコンテキストを使用するには、[コンテキスト] リストからコンテキストを選択します。 デフォルト コンテキストは
(default context)と表示されます。新しいコンテキストを作成するには、次の操作を行います。
[コンテキスト] リストから [コンテキストを作成] を選択します。
[コンテキスト名] フィールドに、コンテキストの名前を入力します。
名前は文字で始まり、文字、数字、次の特殊文字のみを含める必要があります。ダッシュ（
-）、ピリオド（.）、アンダースコア（_）、チルダ（~）、パーセント（%）、プラス記号（+）。コンテキストの名前は変更できません。[保存] をクリックします。
[**スキーマタイプ**] で [**Avro**] または [**プロトコル バッファ**] を選択します。
[スキーマ定義] フィールドに、スキーマ定義を入力します。スキーマの形式は、スキーマタイプと一致している必要があります。スキーマ フィールド名に、個人を特定できる情報（PII）やセキュリティ データなどの機密情報を含めないでください。
スキーマがスキーマ レジストリの他のスキーマで定義されたデータ構造を使用または依存している場合は、次の操作を行います。
- [スキーマ参照を追加] をクリックします。
- [参照名] フィールドに、参照されるスキーマの参照名を入力します。
- [サブジェクト] リストで、参照されるスキーマを含むサブジェクトを選択します。
- [バージョン] リストで、参照されるスキーマのバージョン番号を選択します。
- [OK] をクリックします。
参照されるスキーマごとに、上記の手順を繰り返します。
[作成] をクリックします。
REST
リクエストは、Authorization ヘッダー内のアクセス トークンにより認証を受ける必要があります。現在のアプリケーションのデフォルト認証情報
のアクセス トークンを取得する場合は、
gcloud auth application-default print-access-token を使用します。
次の REST API サンプルでは、サブジェクトの最初のバージョンを作成します。
デフォルト コンテキスト内にサブジェクトを作成するには、POST リクエストを
指定された URI に
projects.locations.schemaRegistries.subjects.versions.create
メソッドを使用して送信します。
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
または、特定のコンテキストを使用する場合は、サブジェクト
コレクション URI を使用して
projects.locations.schemaRegistries.contexts.subjects.versions.create
メソッド:
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 のドキュメントをご覧ください。