結構定義註冊資料庫總覽

架構登錄檔提供多個應用程式共用的架構存放區。先前，如果沒有結構定義登錄檔，團隊可能需要依賴非正式協議 (例如口頭共識、未以程式碼強制執行的共用文件或 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 版本 (將 orderDate 新增至 V1)

什麼是結構定義

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 中結構定義儲存庫的典型工作流程：

使用指定為 Avro 產生類別的特定結構定義，初始化生產者應用程式，並設定該應用程式以使用特定結構定義登錄和序列化程式庫。
設定消費者端用戶端，使用對應的還原序列化程式庫和相同的結構定義登錄。
在執行階段，用戶端會將訊息物件傳遞至 producer.send 方法，而 Kafka 用戶端程式庫會使用設定的序列化程式，將這項記錄轉換為 Avro 編碼的位元組。
序列化器會根據用戶端程式庫中設定的主體名稱策略，判斷結構定義的主體名稱。然後在對結構定義登錄的要求中使用這個主體名稱，擷取結構定義的 ID。詳情請參閱「主體命名策略」。
如果該主體名稱下的登錄中沒有結構定義，可以設定用戶端來登錄結構定義，這樣用戶端就會收到新指派的 ID。

請勿在正式環境中進行這項設定。
生產者會將序列化訊息連同結構定義 ID，傳送至 Kafka 代理程式的適當主題。
Kafka 代理程式會將訊息的位元組陣列表示法儲存在主題中。
取用端應用程式會收到訊息。
還原序列化工具會從結構定義登錄檔中，擷取具有這個 ID 的結構定義。
還原序列化工具會剖析消費者應用程式的訊息。

限制

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

架構格式：
- 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 參數。

後續步驟

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