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：英文字母 (大寫或小寫)、數字和下列特殊字元：破折號 -、半形句號 .、底線 _、波浪號 ~、百分比符號 % 或加號 +。

特殊字元

您可以在資源 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

這項策略結合了「盡量爭取轉換」和「盡量爭取轉換價值」的要素。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

使用 TopicRecordNameStrategy 的優點如下：

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

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

使用 TopicRecordNameStrategy 的缺點如下：

  • 由於主題名稱和完整記錄名稱的組合，主體名稱可能會相當長。
Apache Kafka® 是 The Apache Software Foundation 或其關聯企業在美國與/或其他國家/地區的註冊商標。