建立主題後，即可新增版本。這個程序稱為註冊新的結構定義版本。每個新版本都代表與該主體相關聯的結構定義演進。
一個主體可以有多個版本。主體中的版本會遵循可設定的相容性規則，確保結構定義安全演變。舉例來說，主體可以要求所有變更都必須回溯相容。舉例來說，新增選用欄位就是向下相容的變更。新增必要欄位會被視為不具回溯相容性的變更；如果主體已設定為回溯相容，則不允許這項變更。不過，如果主體已設定為向前相容，則可新增必填欄位。
相容性檢查不會溯及既往。如果變更主體或結構定義儲存庫的相容性規則，系統不會依據新規則重新驗證主體中已有的版本。如要進一步瞭解相容性，請參閱「關於相容性類型」。
必要角色和權限
如要取得為主題註冊結構定義版本所需的權限，請要求管理員在專案或特定結構定義儲存庫和主題中，授予您「Managed Kafka Schema Registry Editor 」(roles/managedkafka.schemaRegistryEditor) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。
這個預先定義的角色具備為主體註冊結構定義版本所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：
所需權限
如要為主體註冊結構定義版本，必須具備下列權限：
-
在父項或預設環境中授予這項權限：
managedkafka.versions.create
較高層級的「代管 Kafka 結構定義儲存庫管理員」(roles/managedkafka.schemaRegistryAdmin) 角色也包含這些權限。
如要進一步瞭解 Managed Service for Apache Kafka 適用的預先定義角色，請參閱存取權控管說明文件。
註冊新的結構定義版本
如要註冊新的結構定義版本，請按照下列步驟操作。
控制台
前往 Google Cloud 控制台的「Schema registries」頁面。
按一下要註冊新結構定義版本的結構定義登錄名稱。
在「Subjects in this schema registry」(這個結構定義儲存庫中的主體) 下方，按一下主體名稱。
在「Subject details」(主體詳細資料) 頁面中，按一下 「Create version」(建立版本)。
「結構定義」欄位會顯示最新版本的定義。 請更新這個欄位中的定義，以符合新版本。請勿在結構定義欄位名稱中加入機密資訊，例如個人識別資訊 (PII) 或安全性資料。
如果您的結構定義使用或依附於結構定義登錄中其他結構定義所定義的資料結構，請執行下列步驟：
- 按一下「新增架構參照」。
- 在「Reference name」(參照名稱) 欄位中，輸入所參照結構定義的參照名稱。
- 在「Subject」(主體) 清單中，選取含有參照結構定義的主體。
- 在「Version」清單中，選取參照結構定義的版本號碼。
- 按一下 [確定]。
針對每個參照的結構定義重複這些步驟。
選用：如要檢查新結構定義是否與先前版本相容，請按一下「檢查相容性」。
如果結構化資料與 Google 服務相容，就會顯示 勾號。否則會顯示錯誤訊息。請修正錯誤，然後再次點選「檢查相容性」。
執行的相容性檢查取決於主體的相容性類型。
點按「Create」(建立)。如果結構定義有效，且通過主體的相容性檢查，新版本就會顯示在「所有版本」下方。
REST
要求必須使用 Authorization 標頭中的存取權杖進行驗證。如要取得目前應用程式預設憑證的存取權杖，請執行：gcloud auth application-default print-access-token。
如要在預設環境中為主體註冊新的架構版本，請使用 projects.locations.schemaRegistries.subjects.versions.create 方法，對特定 URI 發出 POST 要求：
POST https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/subjects/SUBJECT_ID/versions
Authorization: Bearer $(gcloud auth application-default print-access-token)
Content-Type: application/json
或者，如果使用特定環境，請在版本集合 URI 中加入環境，並使用 projects.locations.schemaRegistries.contexts.subjects.versions.create 方法。
POST https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/contexts/CONTEXT_ID/subjects/SUBJECT_ID/versions
Authorization: Bearer $(gcloud auth application-default print-access-token)
Content-Type: application/json
更改下列內容：
- PROJECT_ID (必填)：您的 Google Cloud專案 ID。
- LOCATION (必要)：結構定義儲存庫所在的 Google Cloud 區域。
- REGISTRY_ID (必填)：目標結構定義登錄的 ID。
- CONTEXT_ID (選用)：包含主體的內容 ID。如要明確使用預設環境，請使用
.(單一句號)，否則請省略/contexts/CONTEXT_ID，以隱含方式使用預設環境。 - SUBJECT_ID (必填)：要建立新版本的科目 ID。
要求主體：
在要求主體中加入 JSON 物件，指定結構定義詳細資料：
{
"schema": "YOUR_SCHEMA_DEFINITION_STRING",
"schema_type": "AVRO" | "PROTOBUF" | "JSON", // Optional, defaults to AVRO
"references": [ // Optional
{
"name": "REFERENCE_NAME",
"subject": "REFERENCED_SUBJECT_ID",
"version": REFERENCED_VERSION_NUMBER
}
// ... more references
]
// "version": VERSION_NUMBER, // Optional: Usually omitted, let service assign next
// "id": SCHEMA_ID, // Optional: Usually omitted, let service assign or reuse
}
更改下列內容：
YOUR_SCHEMA_DEFINITION_STRING(必要)：包含實際結構定義酬載的字串。schemaType(選用，位於schema物件中)：架構類型。可以是AVRO或PROTOBUF。如果省略，則預設值為AVRO。references(選用，位於schema物件中)：定義這個結構定義所參照任何結構定義的物件陣列。REFERENCE_NAME：用於參照這個結構定義中其他結構定義的名稱。REFERENCED_SUBJECT_ID：所參照結構定義的完整主體名稱。例如：projects/test-project/locations/us-central1/schemaRegistries/test-registry/subjects/test-referenced-subject。REFERENCED_VERSION_NUMBER：參照主體結構定義的特定版本號碼 (整數)。
versionId、schemaId：通常由服務處理的選填欄位。 註冊結構定義版本時，服務會指派下一個可用的版本號碼。
如果要求成功，API 會傳回 200 OK 狀態碼和包含結構定義 ID 的回應主體。
詳情請參閱 REST API 說明文件。