刪除主體

預先發布版

這項產品或功能 適用《服務專屬條款》。 正式發布前的產品和功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

本文說明如何從結構定義登錄檔刪除主體。刪除科目有兩種方式：

• 虛刪除。將主體標示為已刪除，但會保留其資訊，且可復原。系統也會虛刪除主體的所有版本。

• 永久刪除。永久移除主體及其相關資料。

您也可以從主體刪除特定結構定義版本。詳情請參閱「刪除結構定義主體版本」。

必要角色和權限

如要取得刪除主體所需的權限，請要求管理員授予您主體的「Managed Kafka Schema Registry 編輯者」 (roles/managedkafka.schemaRegistryEditor) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這個預先定義的角色具備刪除主體所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要刪除科目，必須具備下列權限：

• 對要刪除的主體授予下列權限： managedkafka.subjects.delete
• 如要在主控台中刪除主體，請授予下列權限來查看主體： managedkafka.subjects.list

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

代管 Kafka 結構定義儲存庫管理員 (roles/managedkafka.schemaRegistryAdmin) 角色也允許您刪除主體。

如要進一步瞭解預先定義的角色，請參閱「 Managed Service for Apache Kafka 預先定義的角色」。

虛刪除主體

請確認符合下列條件：

• 您要刪除的主體未由其他結構定義參照。如果主體中的任何版本遭到其他結構定義參照，刪除要求就會失敗。

• 主體所屬的結構定義儲存庫或主體本身不得處於 Read-only 模式。

如要軟刪除主體，請按照下列步驟操作。

控制台

1. 前往 Google Cloud 控制台的「Schema registries」頁面。

   前往「結構定義登錄」頁面

2. 按一下包含要刪除主體的結構定義登錄名稱。

3. 在「Subjects in this schema registry」(這個結構定義儲存庫中的主體) 下方，按一下主體名稱。

4. 在「Subject details」(主體詳細資料) 頁面中，按一下 「Delete」(刪除)。

5. 選取「軟刪除」。

6. 在「Delete schema subject」(刪除結構定義主體) 對話方塊中，在欄位中輸入 delete。

7. 按一下「Delete」(刪除)。這項動作會先虛刪除主體，再永久刪除。

REST

要求必須使用 Authorization 標頭中的存取權杖進行驗證。如要取得目前應用程式預設憑證的存取權杖：gcloud auth application-default print-access-token。

如要使用 REST API 軟刪除主體，請使用 projects.locations.schemaRegistries.contexts.subjects.delete 方法，對適當的 URI 發出 DELETE 要求。

DELETE https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/subjects/SUBJECT_ID
Authorization: Bearer $(gcloud auth application-default print-access-token)

如要使用 REST API 軟刪除特定情境下的主體，請使用 projects.locations.schemaRegistries.contexts.subjects.delete 方法，向適當的 URI 發出 DELETE 要求。

DELETE https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/contexts/CONTEXT_ID/subjects/SUBJECT_ID
Authorization: Bearer $(gcloud auth application-default print-access-token)

更改下列內容：

• PROJECT_ID (必填)：您的 Google Cloud專案 ID。
• LOCATION (必要)：結構定義登錄所在的 Google Cloud 區域。
• REGISTRY_ID (必填)：架構登錄檔的 ID。
• CONTEXT_ID (選用)：情境的 ID 或名稱，用於刪除特定情境中的主題。
• SUBJECT_ID (選用)：要刪除的主體 ID 或名稱。

舉例來說，如要從專案 test-gcp-project 和位置 us-central1 的結構定義登錄檔 test_registry 中軟刪除 orders-topic-value，請發出下列要求：

DELETE https://managedkafka.googleapis.com/v1/projects/test-gcp-project/locations/us-central1/schemaRegistries/test_registry/subjects/orders-topic-value
Authorization: Bearer $(gcloud auth application-default print-access-token)

如果要求成功，API 會傳回 200 OK 狀態碼。回應主體包含 JSON 陣列，其中列出已刪除主體所屬的結構定義版本號碼。

實刪除主體

永久刪除主體後就無法復原，且所有相關聯的結構定義版本也會一併刪除。

請確認符合下列條件：

• 您要刪除的主體未由其他結構定義參照。 如果主體中的任何版本遭到其他結構定義參照，刪除要求就會失敗。

• 主體所屬的結構定義儲存庫或主體本身不得處於 Read-only 模式。

• 請先備份所有必要的結構定義資訊，再繼續刪除。

• 如果刪除這個主旨，可能會導致中斷，因此任何有效製作人或消費者都不得依賴這個主旨中的結構定義。

控制台

1. 前往 Google Cloud 控制台的「Schema registries」頁面。

   前往「結構定義登錄」頁面

2. 按一下包含要刪除主體的結構定義登錄名稱。

3. 在「Subjects in this schema registry」(這個結構定義儲存庫中的主體) 下方，按一下主體名稱。

4. 在「Subject details」(主體詳細資料) 頁面中，按一下 「Delete」(刪除)。

5. 選取「永久刪除」。

6. 在「Delete schema subject」(刪除結構定義主體) 對話方塊中，在欄位中輸入 delete。

7. 按一下「Delete」(刪除)。這項動作會先虛刪除主體，再永久刪除。

REST

如要使用 REST API 永久刪除主體，請先暫時刪除主體。軟刪除後，即可進行硬刪除。

要求必須使用 Authorization 標頭中的存取權杖進行驗證。如要取得目前應用程式預設憑證的存取權杖，請執行：gcloud auth application-default print-access-token。

如要使用 REST API 永久刪除主體，請對適當的 URI 發出 DELETE 要求，包括 permanent=true 查詢參數，並使用 projects.locations.schemaRegistries.subjects.delete 方法。

DELETE https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/subjects/SUBJECT_ID?permanent=true
Authorization: Bearer $(gcloud auth application-default print-access-token)

如要使用 REST API 永久刪除特定情境下的主體，請向適當的 URI 發出 DELETE 要求，包括 permanent=true 查詢參數，並使用 projects.locations.schemaRegistries.contexts.subjects.delete 方法。

DELETE https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/contexts/CONTEXT_ID/subjects/SUBJECT_ID?permanent=true
Authorization: Bearer $(gcloud auth application-default print-access-token)

更改下列內容：

• PROJECT_ID (必填)：您的 Google Cloud專案 ID。
• LOCATION (必要)：結構定義登錄所在的 Google Cloud 區域。
• REGISTRY_ID (必填)：架構登錄檔的 ID。
• CONTEXT_ID (選用)：如要刪除特定情境中的主題，請提供情境 ID。
• SUBJECT_ID (選用)：要刪除的主體 ID 或名稱。

舉例來說，如要從專案 test-gcp-project 和位置 us-central1 的結構定義儲存庫 test_registry 中，實刪除先前虛刪除的主體 orders-topic-value，請發出下列要求：

DELETE https://managedkafka.googleapis.com/v1/projects/test-gcp-project/locations/us-central1/schemaRegistries/test_registry/subjects/orders-topic-value?permanent=true
Authorization: Bearer $(gcloud auth application-default print-access-token)

如果要求成功，API 會傳回 200 OK 狀態碼。回應主體包含 JSON 陣列，內含屬於已刪除主體的結構定義版本號碼。

詳情請參閱「projects.locations.schemaRegistries.contexts.subjects.delete」。

還原虛刪除的主體

如要還原已軟刪除的主體，請按照下列步驟操作。

控制台

1. 前往 Google Cloud 控制台的「Schema registries」頁面。

   前往「結構定義登錄」頁面

2. 按一下包含軟刪除主體的結構定義登錄名稱。

3. 如要 篩選，請按一下「取消」，清除「已軟刪除：否」篩選器。

4. 按一下要還原的主體名稱。

5. 在「主體詳細資料」頁面中，按一下「建立要還原的版本」。

6. 在「結構定義類型」中，選取「Avro」或「通訊協定緩衝區」。

7. 在「結構定義」欄位中，輸入結構定義。 請勿在結構定義欄位名稱中加入機密資訊，例如個人識別資訊 (PII) 或安全性資料。

8. 如果您的結構定義使用或依附於結構定義登錄中其他結構定義所定義的資料結構，請執行下列步驟：

   1. 按一下「新增架構參照」。
   2. 在「Reference name」(參照名稱) 欄位中，輸入所參照結構定義的參照名稱。
   3. 在「Subject」(主體) 清單中，選取含有參照結構定義的主體。
   4. 在「Version」清單中，選取參照結構定義的版本號碼。
   5. 按一下 [確定]。

   針對每個參照的結構定義重複這些步驟。

9. 點選「建立」。

REST

如要還原已軟刪除的主題，請使用 schemaRegistries.subjects.versions.create 方法。

使用任何要求資料之前，請先修改下列項目的值：

• PROJECT_ID：您的 Google Cloud 專案 ID
• LOCATION：結構定義登錄的位置
• REGISTRY_ID：結構定義登錄的 ID
• SUBJECT：主體名稱
• SCHEMA_DEFINITION：包含結構定義的字串。

HTTP 方法和網址：

POST https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/subjects/SUBJECT/versions

JSON 要求主體：

{
  "schema": "SCHEMA_DEFINITION"
}

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/subjects/SUBJECT/versions"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/subjects/SUBJECT/versions" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "id": SCHEMA_ID
}

後續步驟

• 進一步瞭解結構定義登錄
• 列出主題
• 列出主題版本
• 刪除結構定義主體版本

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