本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # AWS Glue 結構描述登錄檔 **注意** AWS Glue AWS Glue 主控台中的下列區域不支援結構描述登錄檔：中東 （阿拉伯聯合大公國）。 AWS Glue 結構描述登錄檔可讓您集中探索、控制和發展資料串流結構描述。*結構描述*定義資料記錄的結構和格式。搭配 AWS Glue 結構描述登錄檔，您可以使用方便的 Apache Kafka、[Amazon Managed Streaming for Apache Kafka](https://aws.amazon.com/msk/)、[Amazon Kinesis Data Streams](https://aws.amazon.com/kinesis/data-streams/)、[Amazon Managed Service for Apache Flink](https://aws.amazon.com/kinesis/data-analytics/) 和 [AWS Lambda](https://aws.amazon.com/lambda/) 整合，在資料串流應用程式上管理和強制執行結構描述。 [結構描述登錄檔支援 AVRO (v1.11.4) 資料格式、JSON 資料格式 (具有 ](https://json-schema.org/)JSON 結構描述格式[ (適用於結構描述 (規格 Draft-04、Draft-06 和 Draft-07)) 並使用 ](https://github.com/everit-org/json-schema)Everit 程式庫`extensions`進行 JSON 結構描述驗證)，Protocol Buffers (Protobuf) 版本 proto2 和 proto3 不支援 或 `groups`，支援 Java 語言，且即將推出對其他資料格式和語言的支援。支援的功能包括相容性、透過中繼資料取得結構描述、自動註冊結構描述、IAM 相容性，以及選用的 ZLIB 壓縮，以減少儲存和資料傳輸。結構描述登錄檔是無伺服器且可免費使用。 使用結構描述作為生產者與消費者之間的資料格式合約，可改善資料控管、更高品質的資料，並讓資料消費者能夠彈性相容上游變更。 結構描述登錄檔允許不同的系統共用序列化和還原序列化的結構描述。例如，假設您擁有資料的生產者和消費者。生產者在發佈資料時知道結構描述。結構描述登錄檔提供某些系統，如 Amazon MSK 或 Apache Kafka 的序列化程式和還原序列化程式。 如需詳細資訊，請參閱[結構描述登錄檔的運作方式](schema-registry-works.md)。 **Topics** + [結構描述](#schema-registry-schemas) + [登錄檔](#schema-registry-registries) + [結構描述版本控制和相容性](#schema-registry-compatibility) + [開源 Serde 程式庫](#schema-registry-serde-libraries) + [結構描述登錄檔的配額](#schema-registry-quotas) + [結構描述登錄檔的運作方式](schema-registry-works.md) + [結構描述登錄檔入門](schema-registry-gs.md) ## 結構描述 *結構描述*定義資料記錄的結構和格式。結構描述是可靠的資料發佈、耗用或儲存的版本化規格。 在 Avro 的這個範例結構描述中，格式和結構由配置和欄位名稱定義，欄位名稱的格式由資料類型定義 (例如，`string`、`int`)。 ``` { "type": "record", "namespace": "ABC_Organization", "name": "Employee", "fields": [ { "name": "Name", "type": "string" }, { "name": "Age", "type": "int" }, { "name": "address", "type": { "type": "record", "name": "addressRecord", "fields": [ { "name": "street", "type": "string" }, { "name": "zipcode", "type": "int" } ] } } ] } ``` 在 JSON Schema Draft-07 for JSON 此範例中，格式是由 [JSON 結構描述組織](https://json-schema.org/)所定義。 ``` { "$id": "https://example.com/person.schema.json", "$schema": "http://json-schema.org/draft-07/schema#", "title": "Person", "type": "object", "properties": { "firstName": { "type": "string", "description": "The person's first name." }, "lastName": { "type": "string", "description": "The person's last name." }, "age": { "description": "Age in years which must be equal to or greater than zero.", "type": "integer", "minimum": 0 } } } ``` 在這個 Protobuf 範例中，格式由[協定緩衝區語言的版本 2 (proto2)](https://developers.google.com/protocol-buffers/docs/reference/proto2-spec) 定義。 ``` syntax = "proto2"; package tutorial; option java_multiple_files = true; option java_package = "com.example.tutorial.protos"; option java_outer_classname = "AddressBookProtos"; message Person { optional string name = 1; optional int32 id = 2; optional string email = 3; enum PhoneType { MOBILE = 0; HOME = 1; WORK = 2; } message PhoneNumber { optional string number = 1; optional PhoneType type = 2 [default = HOME]; } repeated PhoneNumber phones = 4; } message AddressBook { repeated Person people = 1; } ``` ## 登錄檔 *登錄檔*是結構描述的邏輯容器。登錄檔允許您組織您的結構描述，以及管理應用程式的存取控制。登錄檔具有 Amazon Resource Name (ARN)，可讓您組織和設定登錄檔中結構描述操作的不同存取許可。 您可以使用預設登錄檔，或視需要建立許多新的登錄檔。 **AWS Glue 結構描述登錄檔階層** | | | --- | | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/schema-registry.html) | | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/schema-registry.html) | | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/schema-registry.html) | | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/schema-registry.html) | ## 結構描述版本控制和相容性 每個結構描述可以有多個版本。版本控制是由套用在結構描述上的相容性規則所控制。結構描述登錄檔會根據此規則檢查登錄新結構描述版本的要求，然後才能成功。 標示為檢查點的結構描述版本是用來判斷註冊新結構描述版本的相容性。第一次建立結構描述時，預設檢查點將是第一個版本。當結構描述隨著更多版本發展，您可以使用 CLI/SDK 將檢查點變更為使用 `UpdateSchema` API，它遵循一組約束。在主控台中，編輯結構描述定義或相容性模式預設會將檢查點變更為最新版本。 相容性模式可讓您控制結構描述可以或不可以隨著時間變化的方式。這些模式形成應用程式產生和使用資料之間的合約。當新版的結構描述提交至登錄檔時，會使用套用至結構描述名稱的相容性規則來判斷是否可以接受新版本。共有 8 種相容性模式：NONE、DISABLED、BACKWARD、BACKWARD\_ALL、FORWARD、FORWARD\_ALL、FULL、FULL\_ALL。 在 Avro 資料格式中，欄位可以是選用的或必要的。選用欄位是其中 `Type` 包含 null。必要欄位的 `Type` 沒有 null。 在 Protobuf 資料格式中，proto2 語法中的欄位可以是選用 (包括重複) 或必要欄位，而 proto3 語法中的所有欄位均是選用 (包括重複) 欄位。所有相容性規則均是根據對協定緩衝區規範的理解以及 [Google 協定緩衝區文件](https://developers.google.com/protocol-buffers/docs/overview#updating)中的指導所決定。 + *NONE*：未套用相容性模式。您可以在開發案例中使用此選項，或者如果您不知道要套用至結構描述的相容性模式。任何新增的版本都會被接受，而不經過相容性檢查。 + *DISABLED*：此相容性選項可防止特定結構描述的版本控制。無法新增新版本。 + *BACKWARD*：建議使用此相容性選項，因為它允許消費者讀取目前和先前的結構描述版本。當您刪除欄位或新增選用欄位時，您可以使用此選項來檢查與先前結構描述版本的相容性。一個典型的 BACKWARD 使用案例是，當您的應用程式為最新的結構描述而建立時。 **AVRO** 例如，假設您有一個由名字 (必要)、姓氏 (必要)、電子郵件 (必要) 和電話號碼 (選用) 所定義的結構描述。 如果您的下一個結構描述版本移除必要的電子郵件欄位，將可成功註冊。BACKWARD 相容性要求消費者能夠讀取目前和先前的結構描述版本。您的消費者將能夠讀取新的結構描述，因為舊訊息中的額外電子郵件欄位被忽略。 如果您有新增必要欄位 (例如郵遞區號) 的提議新結構描述版本，則不會成功註冊 BACKWARD 相容性。新版本的消費者將無法在結構描述變更之前讀取舊訊息，因為他們缺少必要的郵遞區號欄位。但是，如果在新的結構描述中將郵遞區號欄位設定為選用，則提議的版本將成功註冊，因為消費者可以在沒有選用郵遞區碼欄位的情況下讀取舊的結構描述。 **JSON** 例如，假設您有一個由名字 (選用)、姓氏 (選用)、電子郵件 (選用) 和電話號碼 (選用) 所定義的結構描述版本。 如果您的下一個結構描述版本新增了選用的電話號碼屬性，只要原始結構描述版本不允許透過將 `additionalProperties` 欄位設定為 false 的任何其他屬性，這就會成功註冊。BACKWARD 相容性要求消費者能夠讀取目前和先前的結構描述版本。您的消費者將能夠讀取電話號碼屬性不存在的原始結構描述產生的資料。 如果您有新增選用電話號碼屬性的提議新結構描述版本，當原始結構描述版本將 `additionalProperties` 欄位設定為 true 時 (即允許任何其他屬性)，這將無法成功註冊 BACKWARD 相容性。新版本的消費者將無法在結構描述變更之前讀取舊訊息，因為他們無法讀取具有不同類型 (例如是字串而不是數字) 之電話號碼屬性的資料。 **PROTOBUF** 例如，假設您有一個由訊息 `Person` 與 proto2 語法下的 `first name` (必要)、`last name` (必要)、`email` (必要) 和 `phone number` (選用) 等欄位所定義的結構描述版本。 與 AVRO 案例類似，如果您的下一個結構描述版本移除必要的 `email` 欄位，該版本可成功註冊。BACKWARD 相容性要求消費者能夠讀取目前和先前的結構描述版本。舊訊息中的額外 `email` 欄位會被忽略，您的消費者將能夠讀取新的結構描述。 如果您有新增了必要欄位 (例如 `zip code`) 的提議新結構描述版本，根據 BACKWARD 相容性規則，該版本無法成功註冊。新版本的消費者將無法讀取結構描述變更之前的舊訊息，因為它們缺少必要的 `zip code` 欄位。但是，如果在新的結構描述中將 `zip code` 欄位設定為選用，則提議的版本可成功註冊，因為消費者可以讀取不含 `zip code` 選用欄位的結構描述。 在 GrPC 使用案例中，新增新 RPC 服務或 RPC 方法是向後相容的變更。例如，假設您有一個由 RPC 服務 `MyService` 使用 `Foo` 和 `Bar` 兩種 RPC 方法所定義的結構描述版本。 如果您的下一個結構描述版本新增了名為 `Baz` 的新 RPC 方法，該版本可成功註冊。因為新加入的 RPC 方法 `Baz` 為可選方法，根據 BACKWARD 相容性規則，您的消費者將能夠讀取原始結構描述產生的資料。 如果您有移除了現有 RPC 方法 `Foo` 的提議新結構描述版本，根據 BACKWARD 相容性規則，該版本無法成功註冊。新版本的消費者將無法讀取結構描述變更之前的舊訊息，因為他們無法使用 gRPC 應用程式中不存在的 RPC 方法 `Foo` 來理解和讀取資料。 + *BACKWARD\_ALL*：此相容性選項可讓消費者同時讀取目前和所有先前的結構描述版本。當您刪除欄位或新增選用欄位時，您可以使用此選項來檢查所有先前結構描述版本的相容性。 + *FORWARD*：此相容性選項可讓消費者同時讀取目前和後續的結構描述版本，但不一定是較新的版本。當您新增欄位或刪除選用欄位時，您可以使用此選項來檢查與上一個結構描述版本的相容性。FORWARD 的典型使用案例是您的應用程式已經為之前的結構描述建立，並且應該能夠處理更新的結構描述。 **AVRO** 例如，假設您有一個由名字 (必要)、姓氏 (必要)、電子郵件 (選用) 定義的結構描述版本。 如果您有一個新的結構描述版本新增了必要欄位，例如電話號碼，該版本可成功註冊。FORWARD 相容性要求消費者能夠使用舊版本來讀取以新結構描述產生的資料。 如果您有刪除了必要名字欄位的提議結構描述版本，根據 FORWARD 相容性規則，該版本無法成功註冊。您在以前版本上的消費者將無法讀取提議的結構描述，因為他們缺少必要的名字欄位。但是，如果名字欄位最初是選用的，那麼提議的新結構描述將成功註冊，因為消費者可以根據沒有選用名字欄位的新結構描述讀取資料。 **JSON** 例如，假設您有一個由名字 (選用)、姓氏 (選用)、電子郵件 (選用) 和電話號碼 (選用) 所定義的結構描述版本。 如果您有移除選用電話號碼屬性的新結構描述版本，只要新結構描述版本不允許透過將 `additionalProperties` 欄位設定為 false 的任何其他屬性，這就會成功註冊。FORWARD 相容性要求消費者能夠使用舊版本來讀取以新結構描述產生的資料。 如果您有刪除選用電話號碼屬性的提議結構描述版本，則當新的結構描述版本將 `additionalProperties` 欄位設定為 true，即允許任何額外的屬性，這不會成功註冊 FORWARD 相容性。舊版本的消費者將無法讀取提議的結構描述，因為他們可能具有不同類型的電話號碼屬性，例如是字串而不是數字。 **PROTOBUF** 例如，假設您有一個由訊息 `Person` 與 proto2 語法下的 `first name` (必要)、`last name` (必要) 和 `email` (選用) 等欄位所定義的結構描述版本。 與 AVRO 案例類似，如果您有一個新的結構描述版本新增了必要欄位，例如 `phone number`，該版本可成功註冊。FORWARD 相容性要求消費者能夠使用舊版本來讀取以新結構描述產生的資料。 如果您有刪除了必要 `first name` 欄位的提議結構描述版本，根據 FORWARD 相容性規則，該版本無法成功註冊。您在以前版本上的消費者將無法讀取提議的結構描述，因為它們缺少必要的 `first name` 欄位。但是，如果 `first name` 欄位最初是選用欄位，則提議的新結構描述可成功註冊，因為消費者可以讀取沒有 `first name` 選用欄位的新結構描述資料。 在 gRPC 使用案例中，移除 RPC 服務或 RPC 方法是向前相容的變更。例如，假設您有一個由 RPC 服務 `MyService` 使用 `Foo` 和 `Bar` 兩種 RPC 方法所定義的結構描述版本。 如果您的下一個結構描述版本刪除了名為 `Foo` 的現有 RPC 方法，根據 FORWARD 相容性規則，該版本可成功註冊，因為消費者可以使用舊版本來讀取新結構描述產生的資料。如果您有新增了 RPC 方法 `Baz` 的提議新結構描述版本，根據 FORWARD 相容性規則，該版本無法成功註冊。您以前版本上的消費者將無法讀取提議的結構描述，因為它們缺少 RPC 方法 `Baz`。 + *FORWARD\_ALL*：此相容性選項可讓消費者讀取任何新註冊結構描述的生產者所寫入的資料。當您需要新增欄位或刪除選用欄位，並檢查與所有先前結構描述版本的相容性時，您可以使用此選項。 + *FULL*：此相容性選項可讓消費者讀取使用前一個或下一個版本的結構描述，但不能讀取更舊或更新版本的生產者所寫入的資料。當您新增或移除選用欄位時，您可以使用此選項來檢查與上一個結構描述版本的相容性。 + *FULL\_ALL*：此相容性選項可讓消費者讀取生產者使用所有先前的結構描述版本所寫入的資料。當您新增或移除選用欄位時，您可以使用此選項來檢查所有先前結構描述版本的相容性。 ## 開源 Serde 程式庫 AWS 提供開放原始碼 Serde 程式庫做為序列化和還原序列化資料的架構。這些程式庫的開源設計允許通用的開源應用程式和架構在他們的專案中支援這些程式庫。 如需 Serde 函式庫如何運作的詳細資訊，請參閱[結構描述登錄檔的運作方式](schema-registry-works.md)。 ## 結構描述登錄檔的配額 配額也稱為 中的限制 AWS，是 AWS 帳戶中資源、動作和項目的最大值。下列是 AWS Glue 中結構描述登錄檔的軟性限制。 **結構描述版本中繼資料索引鍵-值對** 每個 AWS 區域每個 SchemaVersion 最多可以有 10 個鍵值對。 您可以使用 [QuerySchemaVersionMetadata 動作 (Python: query\_schema\_version\_metadata)](aws-glue-api-schema-registry-api.md#aws-glue-api-schema-registry-api-QuerySchemaVersionMetadata) 或 [PutSchemaVersionMetadata 動作 (Python: put\_schema\_version\_metadata)](aws-glue-api-schema-registry-api.md#aws-glue-api-schema-registry-api-PutSchemaVersionMetadata) API 檢視或設定索引鍵值中繼資料配對。 下列是 AWS Glue 中結構描述登錄檔的硬性限制。 **登錄檔** 此帳戶每個 AWS 區域最多可以有 100 個登錄檔。 **SchemaVersion** 此帳戶每個 AWS 區域最多可以有 10000 個結構描述版本。 每個新結構描述都會建立新的結構描述版本，因此如果每個結構描述只有一個版本，理論上每個區域每個帳戶最多可以有 10000 個結構描述。 **結構描述承載** 結構描述裝載的大小限制為 170 KB。