結構定義註冊資料庫總覽

架構登錄提供多個應用程式共用的架構存放區。先前，如果沒有結構定義登錄，團隊可能需要依賴非正式協議 (例如口頭共識、未以程式碼強制執行的共用文件或 Wiki 頁面)，才能定義訊息格式，以及如何序列化和還原序列化訊息。結構定義登錄可確保訊息編碼和解碼作業一致。

本文將簡要介紹 Managed Service for Apache Kafka 的結構定義登錄功能、元件和基本工作流程。

瞭解結構定義

假設您要建構追蹤顧客訂單的應用程式。您可能會使用名為 customer_orders 的 Kafka 主題，傳輸含有各項訂單資訊的訊息。典型的訂單訊息可能包含下列資訊欄位：

• 訂單 ID

• 客戶名稱

• 產品名稱

• 數量

• 價格

如要確保這些訊息的結構一致，可以定義結構定義。 以下是 Apache Avro 格式的範例：

{
  "type": "record",
  "name": "Order",
  "namespace": "com.example",
  "fields": [
    {"name": "orderId", "type": "string"},
    {"name": "customerName", "type": "string"},
    {"name": "productName", "type": "string"},
    {"name": "quantity", "type": "int"},
    {"name": "price", "type": "double"}
  ]
}

以下是通訊協定緩衝區格式的相同範例。

syntax = "proto3";

package com.example;

option java_multiple_files = true; // Optional: Recommended for Java users
option java_package = "com.example"; // Optional: Explicit Java package

message Order {
  string orderId = 1;
  string customerName = 2;
  string productName = 3;
  int32 quantity = 4; // Avro int maps to Protobuf int32
  double price = 5;
}

這個結構定義是訊息的藍圖，這表示order訊息有五個欄位：訂單 ID、顧客姓名、產品名稱、數量和價格。並指定每個欄位的資料類型。

如果消費者端用戶端收到以這個結構定義編碼的二進位訊息，就必須確切瞭解如何解讀。為此，生產者會將 order 結構定義儲存在結構定義登錄中，並連同訊息傳遞結構定義的 ID。只要訊息的消費者知道使用哪個登錄檔，就能擷取相同結構定義並解碼訊息。

假設您想在 order 訊息中新增 orderDate 欄位。您會建立 order 結構定義的新版本，並在相同主體下註冊。方便您追蹤結構定義隨著時間的變化。 新增欄位是向前相容的變更。也就是說，使用舊版結構定義 (不含 orderDate) 的消費者仍可讀取及處理以新結構定義產生的訊息。系統會忽略新欄位。

結構定義登錄的回溯相容性是指，設定為使用新版結構定義的消費者應用程式，可以讀取使用舊版結構定義產生的資料。

在本例中，初始 order 架構為第 1 版。新增 orderDate 欄位時，系統會建立 order 結構定義的第 2 版。兩個版本都會儲存在同一個主體下，方便您管理結構定義更新，同時避免中斷可能仍依賴版本 1 的現有應用程式。

以下是名為 schema_registry_test 的範例結構定義登錄檔，依據內容、主體和結構定義版本整理，由上而下檢視：

• customer_support context

  • order 主旨

  • V1 版本 (包括 orderId、customerName、productName、quantity、price)

  • V2 版本 (在 V1 中新增 orderDate)

什麼是結構定義

Apache Kafka 訊息是由位元組字串組成。如果沒有定義結構，消費者應用程式就必須直接與生產者應用程式協調，瞭解如何解讀這些位元組。

結構定義會正式描述訊息中的資料。可定義欄位及其資料類型，例如字串、整數或布林值，以及任何巢狀結構。

Managed Service for Apache Kafka 支援下列格式的結構定義：

• Apache Avro

• 通訊協定緩衝區 (Protobuf)

結構定義登錄 API 不支援 JSON。

Managed Service for Apache Kafka 整合的結構定義儲存庫功能，可讓您使用 Kafka 用戶端建立、管理及使用這些結構定義。結構定義儲存庫會實作 Confluent Schema Registry REST API，因此與現有的 Apache Kafka 應用程式和常見的用戶端程式庫相容。

結構定義儲存庫機構

結構定義登錄檔會使用階層式結構來整理結構定義。

• 結構定義：訊息的結構和資料型別。每個結構定義都有專屬 ID。應用程式會使用這個 ID 擷取結構定義。

• 主題：結構定義不同版本的邏輯容器。主體會使用相容性規則，管理結構定義如何隨著時間演變。每個主體通常會對應至 Kafka 主題或記錄物件。

• 版本：如果商業邏輯需要變更訊息結構，請在相關主體下建立並註冊新的結構定義版本。

  每個版本都會參照特定結構定義。如果不同主體的基礎結構定義相同，這些主體的版本可以參照同一個結構定義。

• 內容：主題的高階分組或命名空間。不同團隊或應用程式可透過內容使用相同的主體名稱，不會在相同結構定義登錄中發生衝突。

  架構登錄檔可以有多個內容。一律包含預設環境 (識別為 .)，如果未指定其他環境 ID，結構定義和主體就會放在這裡。

  一個情境可以包含多個主體。

• 登錄：整個結構定義生態系統的頂層容器。儲存及管理所有結構定義、主體、版本和內容。

結構定義儲存庫工作流程

如要按照本節所述的工作流程操作，可以試試「使用結構定義登錄產生 Avro 訊息」快速入門導覽課程。

Kafka 用戶端中的序列化器和還原序列化器會與結構定義登錄檔互動，確保訊息符合定義的結構定義。以下是 Managed Service for Apache Kafka 中結構定義儲存庫的典型工作流程：

1. 使用以 Avro 產生的類別指定特定結構定義，初始化您的生產者應用程式，並將其設定為使用特定結構定義登錄和序列化程式庫。

2. 設定消費者端用戶端，使用對應的還原序列化程式庫和相同的結構定義登錄。

3. 在執行階段，用戶端會將訊息物件傳遞至 producer.send 方法，而 Kafka 用戶端程式庫會使用設定的序列化程式，將這項記錄轉換為 Avro 編碼的位元組。

4. 序列化器會根據用戶端程式庫中設定的主體名稱策略，判斷結構定義的主體名稱。然後，它會在對結構定義登錄的要求中使用這個主體名稱，以擷取結構定義的 ID。詳情請參閱「主旨命名策略」。

5. 如果該主體名稱下的登錄中沒有結構定義，可以設定用戶端來註冊結構定義，這樣就會收到新指派的 ID。

   請避免在正式環境中進行這項設定。

6. 生產者會將含有結構定義 ID 的序列化訊息，傳送至 Kafka 代理程式的適當主題。

7. Kafka 代理程式會將訊息的位元組陣列表示法儲存在主題中。

8. 取用端應用程式會收到訊息。

9. 還原序列化器會從結構定義登錄檔中，擷取具有這個 ID 的結構定義。

10. 解構子會剖析消費者應用程式的訊息。

限制

結構定義登錄服務不支援下列功能：

• 架構格式：

  • JSON 結構定義格式。

• 結構定義模式：

  • READONLY_OVERRIDE 結構定義模式。

• 結構定義設定值：

  • Normalize 和 Alias 設定值。

• API 方法：

  • ModifySchemaTags 方法 (/subjects/{subject}/versions/{version}/tags)。
  • GetLatestWithMetadata 方法 (/subjects/{subject}/metadata)。
  • ListSchemas 方法 (/schemas)。
  • DeleteSchemaMode 方法。
  • GetVersion 方法：format、deleted 和 findTags 參數。
  • CreateVersion 方法：metadata、ruleSet、schemaTagsToAdd 和 schemaTagsToRemove 參數。
  • 針對 UpdateSchemaMode 方法：force 參數。
  • 針對 GetSchemaMode 方法：defaultToGlobal 參數。
  • GetSchema 方法：WorkspaceMaxId 和 findTags 參數。
  • 針對 ListVersions 方法：deletedOnly 參數。
  • 針對 ListSubjects 方法：deletedOnly 參數。

後續步驟

• 結構定義生命週期管理

• 建立結構定義儲存庫

• 建立主題