本文說明如何在結構定義登錄中建立主體。主題是結構定義不同版本的邏輯容器。首次建立主體時，您也會建立該主體的第一個結構定義版本。
您可以透過下列任一方式建立主旨：
隱含 (預設)：許多生產者和消費者用戶端的預設行為是，在用戶端連線時自動建立不存在的結構定義。系統也會自動建立參照結構定義的主體和版本。這很方便，但如果多個用戶端同時建立版本，可能會導致資料不一致。
明確 (建議)：在這個方法中，每個結構定義都必須在登錄中建立，生產者或消費者用戶端才能使用。您可以使用 Google Cloud 控制台或 Managed Kafka API 執行這項操作。
您必須在用戶端設定中設定這項行為。詳情請參閱序列化程式或還原序列化程式用戶端程式庫說明文件。
事前準備
必要角色和權限
如要取得建立主題所需的權限，請要求管理員在專案或結構定義儲存庫中，授予您「Managed Kafka 結構定義儲存庫編輯者」 (roles/managedkafka.schemaRegistryEditor) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。
這個預先定義的角色具備建立主體所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：
所需權限
如要建立主體，必須具備下列權限：
-
在父項或預設環境中授予這項權限：
managedkafka.versions.create
較高層級的「代管 Kafka 結構定義註冊資料庫管理員」(roles/managedkafka.schemaRegistryAdmin) 角色也包含建立及管理主體版本的權限。
如要進一步瞭解 Managed Service for Apache Kafka 適用的預先定義角色，請參閱存取權控管說明文件。
建立主體或結構定義的第一個版本
建立主體時，系統也會建立第一個版本。第一個版本會建立新結構定義，或參照現有結構定義。
控制台
前往 Google Cloud 控制台的「Schema registries」頁面。
按一下要建立主體的結構定義登錄名稱。
按一下 「建立科目」。
在「Subject name」中，輸入主體的專屬名稱。
名稱開頭必須是英文字母，後面只能接上英文字母、數字和下列特殊字元：連字號 (
-)、半形句號 (.)、底線 (_)、波浪號 (~)、百分比符號 (%) 或加號 (+)。主體名稱設定後即無法變更。如要進一步瞭解如何選擇主體名稱，請參閱主體命名策略。
在「情境」中，選擇情境或建立新情境。脈絡的作用類似於命名空間，可整理主體和結構定義，在不同群組之間提供隔離功能。
如要使用現有結構定義，請從「Context」清單中選取結構定義。 預設環境會顯示為
(default context)。如要建立新內容，請按照下列步驟操作：
從「Context」清單中選取「Create context」。
在「Context name」(內容名稱) 欄位中，輸入內容名稱。
名稱開頭必須是英文字母，後面只能接上英文字母、數字和下列特殊字元：連字號 (
-)、半形句號 (.)、底線 (_)、波浪號 (~)、百分比符號 (%) 或加號 (+)。背景資訊名稱設定後即無法變更。按一下 [儲存]。
在「結構定義類型」中，選取「Avro」或「通訊協定緩衝區」。
在「Schema definition」(結構定義) 欄位中，輸入結構定義。結構定義的格式必須與結構定義類型相符。請勿在結構定義欄位名稱中加入敏感資訊，例如個人識別資訊 (PII) 或安全性資料。
如果您的結構定義使用或依附於結構定義登錄中其他結構定義所定義的資料結構，請執行下列步驟：
- 按一下「新增架構參照」。
- 在「Reference name」(參照名稱) 欄位中，輸入所參照結構定義的參照名稱。
- 在「Subject」(主體) 清單中，選取含有參照結構定義的主體。
- 在「Version」清單中，選取參照結構定義的版本號碼。
- 按一下 [確定]。
針對每個參照的結構定義重複這些步驟。
點選「建立」。
REST
要求必須使用 Authorization 標頭中的存取權杖進行驗證。如要取得目前應用程式預設憑證的存取權杖，請執行：gcloud auth application-default print-access-token。
下列 REST API 範例會建立主體的初始版本。
如要在預設環境中建立主體，請使用 projects.locations.schemaRegistries.subjects.versions.create 方法，對指定 URI 發出 POST 要求：
POST https://managedkafka.googleapis.com/v1main/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
或者，如果使用特定背景資訊，請使用 projects.locations.schemaRegistries.contexts.subjects.versions.create 方法，將背景資訊納入主體集合 URI 中：
POST https://managedkafka.googleapis.com/v1main/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", // 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(必要)：包含實際結構定義酬載的字串。請勿在結構定義欄位名稱中加入敏感資訊，例如個人識別資訊 (PII) 或安全性資料。
schemaType(選用)：架構類型。可以是AVRO或PROTOBUF。如果省略，則預設值為AVRO。references(選用)：定義這個結構定義所參照任何結構定義的物件陣列。REFERENCE_NAME：用於參照這個結構定義中其他結構定義的名稱。REFERENCED_SUBJECT_ID：所參照架構的主體 ID。REFERENCED_VERSION_NUMBER：參照主體架構的特定版本號碼。
versionId、schemaId：通常由服務處理的選填欄位。主題的第一個版本為「1」。versionId
如果要求成功，且結構定義有效並通過相容性檢查 (如有設定)，API 會傳回 200 OK 狀態碼。回應主體包含所建立版本使用的結構定義 ID，與版本 ID 不同。
詳情請參閱 REST API 說明文件。