リソースは、 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 ～ 255 文字の長さであること。
トピック、コンシューマー グループ 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 で使用する場合は、適切にエンコードまたはデコードする必要があります。
たとえば、mi-tópico は特定の resource ID タイプで ó が使用できない文字
の場合、無効な 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 を使用するデメリットは次のとおりです。
- トピック名とレコードの完全修飾名を組み合わせるため、サブジェクト名が非常に長くなる可能性があります。