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

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：字母（大写或小写）、数字和以下特殊字符：短划线 -、英文句点 .、下划线 _、波形符 ~、百分号 % 或加号 +。

ACL ID

acl_id 定义了 ACL 条目所适用的资源模式。ACL 中的所有 ACL 条目都适用于 ACL ID 中编码的资源模式。

acl_id 必须采用以下结构之一：

  • 对于集群上的 ACL：

    • cluster

  • 对于集群内单个资源的 ACL：

    • topic/{RESOURCE_NAME}
    • consumerGroup/{RESOURCE_NAME}
    • transactionalId/{RESOURCE_NAME}

  • 对于与前缀匹配的所有资源的 ACL：

    • topicPrefixed/{RESOURCE_NAME}
    • consumerGroupPrefixed/{RESOURCE_NAME}
    • transactionalIdPrefixed/{RESOURCE_NAME}

  • 对于给定类型的所有资源的 ACL（通配符）：

    • allTopics（表示 topic/*）
    • allConsumerGroups（表示 consumerGroup/*）
    • allTransactionalIds（表示 transactionalId/*）

{RESOURCE_NAME}：特定资源的名称。

示例：

  • 如需授予对特定主题 my-topic 的权限，请执行以下操作：topic/my-topic
  • 如需授予以 test- 开头的所有主题的权限，请执行以下操作：topicPrefixed/test-
  • 如需授予集群本身的权限，请执行以下操作：cluster
  • 如需授予对任何群组的权限，请执行以下操作：allConsumerGroups
  • 如需授予对特定交易 ID tx-id 的权限，请执行以下操作：transactionalId/tx-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 或其关联公司在美国和/或其他国家/地区的注册商标。