更新代管 Kafka ACL

建立 Managed Service for Apache Kafka ACL 資源後，您可以編輯其設定，更新 ACL 項目清單。

更新 Managed Service for Apache Kafka ACL 資源的方式有兩種：

完整取代：如本頁所述，覆寫整個 ACL 項目清單。
增量更新：新增或移除單一 ACL 項目，如「新增 ACL 項目」和「移除 ACL 項目」頁面所述。

您無法使用更新作業，將 ACL 項目清單修改為空白。如要移除資源模式的所有項目，請改為刪除 Managed Service for Apache Kafka ACL 資源。

必要角色和權限

如要取得更新 Managed Service for Apache Kafka ACL 所需的權限，請要求管理員授予您專案的「Managed Kafka ACL 編輯者」 (roles/managedkafka.aclEditor) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這個預先定義的角色具備更新 Managed Service for Apache Kafka ACL 所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要更新 Managed Service for Apache Kafka ACL，您必須具備下列權限：

在要求的 ACL 上授予這項權限，即可使用完整取代 (UpdateAcl API) 進行更新： managedkafka.acls.update
在要求的 ACL 上授予這項權限，即可使用累加變更 (AddAclEntry 或 RemoveAclEntry API) 更新： managedkafka.acls.updateEntries

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

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

etag 屬性

etag 欄位用於開放式並行控制。系統會在 GetAcl 和 CreateAcl 作業的回應中傳回 ETag。您必須在 UpdateAcl 要求中加入這個 etag，確保變更會套用至您擷取的 Managed Service for Apache Kafka ACL 資源相同版本。如果資源同時遭到修改，這項機制可防止更新遺失。

etag 中的終端 T 字元表示 ACL 項目清單在回應中遭到截斷，因為超過可重複欄位項目的數量上限。Kafka 叢集上直接存在這個資源模式的更多項目，但無法在 Managed Service for Apache Kafka ACL 資源中表示。如果資源的 ACL 項目遭到截斷，則不支援完整取代更新。在此情境下，請使用標準 Apache Kafka API (例如 kafka-acls.sh) 或 AdminClient 直接管理 ACL。

完整取代 ACL 項目

您可以使用 UpdateAcl API 方法或 gcloud managed-kafka acls update 指令，完整取代 ACL 項目清單。資源中的整個 acl_entries 欄位會遭到更新要求中傳送的清單覆寫。

如要使用這個方法修改清單 (例如新增或移除單一 ACL 項目，同時保留其他項目)，請按照下列步驟操作：

使用describe 指令擷取目前的 ACL 項目清單和 etag。
建構新的 ACL 項目清單。
執行 gcloud managed-kafka acls update 指令，並提供擷取的 etag。

以下章節說明如何使用 gcloud managed-kafka acls update 指令，完整取代 ACL 項目清單。

Install the Google Cloud CLI.
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
To initialize the gcloud CLI, run the following command:
```
gcloud init
```
執行 gcloud managed-kafka acls update 指令，將所有現有 ACL 項目替換為指定項目：

gcloud managed-kafka acls update ACL_ID \
    --cluster=CLUSTER_ID \
    --location=LOCATION \
    --etag=ETAG_VALUE \
    --acl-entry=principal='PRINCIPAL',operation=OPERATION_TYPE,permission_type=PERMISSION_TYPE,host='*' \

更改下列內容：

ACL_ID (必要)：要更新的 Managed Service for Apache Kafka ACL 資源 ID。如要進一步瞭解 ACL ID，請參閱「ACL ID」。
CLUSTER_ID (必要)：包含 ACL 資源的叢集 ID。
LOCATION (必要)：叢集所在的區域。如要進一步瞭解地區，請參閱「支援的地區」。
ETAG_VALUE (必要)：從這個 ACL 資源先前的說明或建立作業取得的 etag 值。
--acl-entry (必要)：指定要納入新清單的 ACL 項目。您可以重複使用這個旗標，以加入多個項目。現有清單會完全遭到取代，改為指令中指定的項目。

PRINCIPAL (必要)：這個 ACL 項目的主體。使用 User:{google_service_account_email} 格式或萬用字元 User:*。
OPERATION_TYPE (必要)：這個 ACL 項目適用的作業類型。允許的值包括 ALL、READ、WRITE、CREATE、DELETE、ALTER、DESCRIBE、CLUSTER_ACTION、DESCRIBE_CONFIGS、ALTER_CONFIGS 和 IDEMPOTENT_WRITE。
PERMISSION_TYPE (必要)：要更新的權限類型：ALLOW 或 DENY。
HOST (必要)：要更新的 ACL 項目用戶端主機。如果是 Google Cloud Managed Service for Apache Kafka，這個值必須設為萬用字元 '*'。

完整更換範例

這個指令會將 us-central1 中 test-kafka-cluster 內 topic/orders 資源模式的所有現有 ACL 項目，替換為單一新項目。這個新項目會將 WRITE 權限授予服務帳戶 producer-app@test-project.iam.gserviceaccount.com。這項指令需要 ACL 資源的目前 etag，在本例中為 "AYk=Ags="。

gcloud managed-kafka acls update topic/orders \
    --cluster=test-kafka-cluster \
    --location=us-central1 \
    --project=test-project \
    --etag='"AYk=Ags="' \
    --acl-entry=principal='User:producer-app@test-project.iam.gserviceaccount.com',operation=WRITE,permission_type=ALLOW,host='*'

如果指令成功執行，輸出內容會顯示更新後的 ACL 資源設定，包括新的 aclEntries 清單和新的 etag。系統會移除這個 ACL 資源先前存在的所有項目。

aclEntries:
-   host: '*'
  operation: WRITE
  permissionType: ALLOW
  principal: User:producer-app@test-project.iam.gserviceaccount.com
etag: '"Bcn=Def="'  # Note: The etag value changes after a successful update.
name: projects/test-project/locations/us-central1/clusters/my-kafka-cluster/acls/topic/orders
resourcePatternType: TOPIC

分批更新 ACL 項目

您可以使用 AddAclEntry 和 RemoveAclEntry API 方法，或對應的 gcloud managed-kafka acls add-acl-entry 和 gcloud managed-kafka acls remove-acl-entry 指令，新增或移除個別 ACL 項目，不必替換整個清單。這些方法不需要 etag。

使用 AddAclEntry 會在 Managed Service for Apache Kafka ACL 資源中新增單一 ACL 項目。這類似於建立單一新的 Apache Kafka AclBinding。詳情請參閱「新增 ACL 項目」。
使用 RemoveAclEntry 會從 Managed Service for Apache Kafka ACL 資源中移除單一現有 ACL 項目。這相當於刪除單一 Apache Kafka AclBinding。詳情請參閱「移除 ACL 項目」。

後續步驟

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