Google Cloud Managed Service for Apache Kafka 资源命名指南

A Google Cloud 资源是指您在 中创建或使用的任何组件 Google Cloud。这些资源构成了在平台上运行的应用和系统的构建块。

Managed Service for Apache Kafka 中的资源包括：

  • 集群

  • 主题

  • 使用方群组

  • ACL

  • 架构注册表

  • 上下文（在架构注册表中）

  • 正文（在架构注册表或上下文中）

  • 版本（正文下的架构版本）

  • 架构（由 ID 标识，与一个或多个正文和版本相关联）

如需详细了解常规 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

该值必须是项目 ID 或项目编号，可从 控制台 Google Cloud 获取。例如，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：字母（大写或小写）、数字和以下特殊字符：短划线 -、英文句点 .、下划线 _、波形符 ~、百分号 % 或加号 +。

特殊字符

您可以在资源 ID 中使用上一部分列出的特殊字符，而无需进行网址编码。但是，您必须确保在网址中使用任何其他特殊字符时，这些字符经过正确编码或解码。

例如，如果 ó 不是该特定资源 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 的一些缺点：

  • 每个主题实际上只能处理一种基于值架构的消息类型。这是因为正文名称固定为主题名称。如果您需要向同一主题发送不同类型的记录，则此策略将不起作用。

RecordNameStrategy

此策略使用 Avro 或 Protobuf 记录的完全限定类名称作为正文名称。

下面是一些示例：

  • Avro 架构名称：com.example.data.Customer
  • Protobuf 消息名称：com.example.data.Order
  • customer 架构的正文：com.example.data.Customer
  • order 架构的正文：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 的一些缺点：

  • 由于主题名称和完全限定记录名称的组合，正文名称可能会变得很长。
Apache Kafka® 是 Apache Software Foundation 或其关联公司在美国和/或其他国家/地区的注册商标。