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-value 或 topicName-key，主題名稱為 topicName。

例如：

• 主題名稱：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

這項策略結合了「盡量爭取轉換」和「盡量爭取轉換價值」的要素。TopicNameStrategyRecordNameStrategy

主體名稱由 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

注意： com.example.events.PageView 在 user-events 和 product-interactions 中的演變方式可能不同。

使用 TopicRecordNameStrategy 的優點如下：

• 與 RecordNameStrategy 類似，您可以將不同類型的記錄傳送至相同主題。

• 與 RecordNameStrategy 不同，這項策略可讓您在每個主題中，獨立演進特定記錄類型的結構定義。這表示 my-topic-com.example.project.MyRecord 的演變方式可能與 another-topic-com.example.project.MyRecord 不同。

使用 TopicRecordNameStrategy 的缺點如下：

• 由於主體名稱是由主題名稱和完整記錄名稱組合而成，因此可能會相當長。

Apache Kafka® 是 The Apache Software Foundation 或其關聯企業在美國與/或其他國家/地區的註冊商標。