Google Cloud リソースは、 Google Cloud内で作成または使用するコンポーネントです。これらのリソースは、プラットフォームで実行されるアプリケーションとシステムの構成要素となります。
Managed Service for Apache Kafka のリソースには、次のものがあります。
クラスタ
トピック
コンシューマー グループ
ACL
スキーマ レジストリ
コンテキスト（スキーマ レジストリ内）
サブジェクト（スキーマ レジストリまたはコンテキスト内）
バージョン（サブジェクトのスキーマのバージョン）
スキーマ（ID で識別され、1 つまたは複数のサブジェクトとバージョンに関連付けられている）
一般的な Google Cloud リソースの命名について詳しくは、リソース名をご覧ください。Managed Service for Apache Kafka のスキーマ レジストリ API は、既存のオープンソース API との互換性を考慮して設計されているため、一部の命名規則が一般的な API 標準と異なる場合があります。
リソース名の形式
さまざまなリソースの形式は次のとおりです。
クラスタ:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}トピック:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}/topics/{TOPIC_ID}コンシューマー グループ:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}/consumerGroup/{CONSUMER_GROUP_ID}ACL:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}/acl/{ACL_ID}スキーマ レジストリ:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}コンテキスト:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}件名:
- デフォルトのコンテキスト内:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/subjects/{SUBJECT_ID} - 特定のコンテキスト内:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/subjects/{SUBJECT_ID}
- デフォルトのコンテキスト内:
スキーマ（ID で識別）:
- デフォルトのコンテキスト内:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/schemas/ids/{SCHEMA_ID} - 特定のコンテキスト内:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/schemas/ids/{SCHEMA_ID}
- デフォルトのコンテキスト内:
バージョン（件名のバージョン番号で識別）:
- デフォルトのコンテキスト内:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/subjects/{SUBJECT_ID}/versions/{VERSION_ID} - 特定のコンテキスト内:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/subjects/{SUBJECT_ID}/versions/{VERSION_ID}
- デフォルトのコンテキスト内:
以降のセクションでは、各コンポーネントについて詳しく説明します。
プロジェクト ID
値は、 Google Cloud コンソールから取得可能なプロジェクト ID またはプロジェクト番号にする必要があります。たとえば、my-cool-project はプロジェクト ID で、123456789123 はプロジェクト番号です。
ロケーション
値は、サポートされている Managed Service for Apache Kafka のロケーションのいずれかにする必要があります。使用可能なロケーションのリストについては、Managed Service for Apache Kafka のロケーションをご覧ください。
ID
ID は、リソースパスの最後のセグメントです。{CLUSTER_ID}、{TOPIC_ID}、{CONSUMER_GROUP_ID}、{SCHEMA_REGISTRY_ID}、{CONTEXT_ID}、{SUBJECT_ID} などの変数は、次のガイドラインに準拠する必要があります。
文字列
googで始めないこと。先頭には英字を使用してください
長さの制約:
クラスタ ID: 3 ～ 53 文字の範囲で指定します。
トピック、コンシューマー グループ ID: Apache Kafka で許可されている長さ。Apache Kafka トピック名は 249 文字に制限されています。
スキーマ レジストリ ID: 最大 255 文字。
コンテキスト ID: 255 文字以内で指定します。
サブジェクト ID: 最大 255 UTF-8 バイト。
文字の制約:
クラスタ ID: 正規表現
^[a-z]([-a-z0-9]*[a-z0-9])?に一致する必要があります。つまり、小文字、数字、ハイフンを使用できます。先頭は英小文字にする必要があり、末尾をハイフンにすることはできません。トピック、コンシューマー グループ ID: 検証は Kafka によって行われます。使用できる文字は `[a-zA-Z0-9.-]` です。これには、ASCII 英数字、ピリオド（.）、アンダースコア（）、ダッシュ（-）が含まれます。
スキーマ レジストリ ID: 文字（大文字または小文字）、数字、アンダースコア
_。コンテキスト ID: 文字（大文字または小文字）、数字、および次の特殊文字: ダッシュ
-、ピリオド.、アンダースコア_、チルダ~、パーセント%、プラス記号+。サブジェクト ID: 文字（大文字または小文字）、数字、特殊文字（ダッシュ
-、ピリオド.、アンダースコア_、チルダ~、パーセント%、プラス記号+）。
特殊文字
前のセクションに記載されている特殊文字は、URL エンコードなしでリソース ID に使用できます。ただし、URL で使用する場合、その他すべての特殊文字が適切にエンコードまたはデコードされることを確認する必要があります。
たとえば、ó が特定のリソース ID タイプの許可された文字でない場合、mi-tópico は無効な ID です。ただし、基本ラテン文字のみが許可されている場合は、mi-topico は有効になります。この形式は、REST 呼び出しを行う場合に重要です。
Kafka クライアント ライブラリからトピックを参照している場合、完全なリソースパスは使用されません。トピック名自体のみが使用されます。同様に、シリアライザーやデシリアライザーなどの Kafka クライアント統合を使用してスキーマを操作する場合は、通常、完全なリソースパスではなくサブジェクト名を使用します。
サブジェクトの命名戦略
スキーマ レジストリ、特にシリアライザーやデシリアライザーなどの Kafka クライアント統合を使用する場合は、サブジェクト名が重要になります。サブジェクト命名戦略は、スキーマ レジストリからスキーマを登録して取得する方法を決定します。戦略によって、スキーマの進化に対する柔軟性と制御のレベルが異なります。
サブジェクト命名戦略は、Kafka クライアント構成で key.subject.name.strategy プロパティまたは value.subject.name.strategy プロパティを設定することで構成できます。
TopicNameStrategy
これは、オープンソースの Kafka クライアント ライブラリのデフォルトの戦略です。
サブジェクト名は Kafka トピック名から直接派生し、メッセージキーの場合は key、メッセージ値の場合は value が付加されます。auto.register.schema が true に設定されている場合、プロデューサー クライアントは topicName という名前のトピックに topicName-value または topicName-key を使用します。
次に例を示します。
- トピック名:
orders - メッセージ値の件名:
orders-value - メッセージキーの件名:
orders-key
TopicNameStrategy を使用するメリットは次のとおりです。
これはシンプルな戦略であり、多くのユースケースに適しています。
スキーマはトピックに直接関連付けられるため、単一のトピック内のレコード タイプを個別に進化させることができます。
TopicNameStrategy を使用する際のデメリットは次のとおりです。
- 各トピックは、値スキーマに基づく 1 種類のメッセージのみを効果的に処理できます。これは、サブジェクト名がトピック名に固定されているためです。同じトピックに異なるタイプのレコードを送信する必要がある場合、この戦略は機能しません。
RecordNameStrategy
この戦略では、Avro または Protobuf レコードの完全修飾クラス名がサブジェクト名として使用されます。
次に例を示します。
- Avro スキーマ名:
com.example.data.Customer - Protobuf メッセージ名:
com.example.data.Order customerスキーマのサブジェクト:com.example.data.Customerorderスキーマのサブジェクト:com.example.data.Order
RecordNameStrategy を使用するメリットは次のとおりです。
サブジェクト名がトピックに関連付けられていないため、同じ Kafka トピックに異なるタイプのレコードを送信できます。各レコードタイプに独自の完全修飾名と、登録された対応するスキーマがある限り、これは可能です。
com.example.common.Addressなどの特定のレコード タイプのスキーマは複数のトピックで使用でき、その進化は単一のサブジェクトで一元的に管理されます。
RecordNameStrategy を使用する際のデメリットは次のとおりです。
- 特定のレコードタイプを使用するすべてのトピックで、同じサブジェクトとバージョンを使用する必要があります。異なるトピックで同じレコードタイプの異なるバージョンが必要な場合は、この制限が厳しくなる可能性があります。
TopicRecordNameStrategy
この戦略は、TopicNameStrategy と RecordNameStrategy の両方の側面を組み合わせたものです。
サブジェクト名は、Kafka トピック名とレコードの完全修飾クラス名を組み合わせたもので、TOPIC_NAME-FULLY_QUALIFIED_CLASS_NAME の形式で指定します。
次に例を示します。
トピック:
user-events完全修飾名:
com.example.events.PageViewこの組み合わせのサブジェクト名:
user-events-com.example.events.PageView別のトピック:
product-interactions完全修飾名:
com.example.events.PageViewこの組み合わせのサブジェクト名:
product-interactions-com.example.events.PageView
TopicRecordNameStrategy を使用するメリットは次のとおりです。
RecordNameStrategyと同様に、同じトピックにさまざまなタイプのレコードを送信できます。RecordNameStrategyとは異なり、この戦略では、各トピック内で特定のレコード タイプのスキーマを個別に進化させることができます。つまり、my-topic-com.example.project.MyRecordはanother-topic-com.example.project.MyRecordとは異なる進化を遂げる可能性があります。
TopicRecordNameStrategy を使用する際のデメリットは次のとおりです。
- トピック名と完全修飾されたレコード名の組み合わせにより、サブジェクト名が非常に長くなることがあります。