您可以透過統一存取政策 (UAP),授予及拒絕主體對Google Cloud 資源的存取權。本文說明如何編輯現有的 UAP,以及修改 UAP 適用的資源。
事前準備
設定驗證方法。
請根據您打算如何使用本頁範例,選取對應的分頁標籤:
控制台
使用 Google Cloud 控制台存取 Google Cloud 服務和 API 時,不需要設定驗證機制。
gcloud
在 Google Cloud 控制台啟用 Cloud Shell。
Google Cloud 控制台底部會開啟 Cloud Shell 工作階段,並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境,並已設定適用於您目前專案的值。工作階段可能要幾秒鐘的時間才能初始化。
REST
如要在本機開發環境中使用本頁的 REST API 範例,請使用您提供給 gcloud CLI 的憑證。
安裝 Google Cloud CLI。
若您採用的是外部識別資訊提供者 (IdP),請先使用聯合身分登入 gcloud CLI。
詳情請參閱 Google Cloud 驗證說明文件中的「使用 REST 進行驗證」一節。
選用。請參閱 UAP 總覽。
必要的角色
如要取得編輯 UAP 所需的權限,請要求管理員在擁有您要編輯的 UAP 的專案、資料夾或組織中,授予您存取權政策管理員 (roles/iam.accessPolicyAdmin) IAM 角色。如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。
這個預先定義的角色具備編輯 UAP 所需的權限。如要查看確切的必要權限,請展開「Required permissions」(必要權限) 部分:
所需權限
必須具備下列權限,才能編輯 UAP:
-
iam.accesspolicies.update -
在 Google Cloud 控制台中編輯 UAP:
-
iam.accesspolicies.get -
iam.accessPolicies.list
-
編輯現有的統一存取政策
您可以編輯 UAP,更新顯示名稱或規則。
您可以使用 Google Cloud 控制台、gcloud CLI 或 IAM REST API 編輯 UAP。
控制台
-
在 Google Cloud 控制台中,前往「統一存取政策」 頁面。
前往「Unified Access Policies」(統一存取政策) 頁面 - 選取要編輯的 UAP 所屬的專案、資料夾或組織。
- 按一下要編輯的 UAP 政策 ID。
-
如要新增規則,請按一下「 新增 規則」,然後新增規則詳細資料。如要儲存規則,請按一下「新增規則」。
如要進一步瞭解規則的欄位,請參閱「建立 UAP」。
- 如要編輯 UAP 的其他欄位,請按一下「 編輯政策」。
-
編輯下列任一欄位:
- 政策名稱:輸入 UAP 的新顯示名稱。
- 規則:在 UAP 中更新、新增或移除規則。
- 完成 UAP 編輯後,按一下「Update policy」(更新政策)。
gcloud
gcloud iam access-policies update 指令會更新現有的 UAP。
使用下列任何指令資料前,請先替換以下項目:
-
UAP_ID:要更新的 UAP ID,例如example-policy。 -
UAP_PARENT_RESOURCE_TYPE:Resource Manager 資源 (專案、資料夾或組織) 的類型,該資源擁有您要更新的 UAP。請使用project、folder或organization值。 -
UAP_PARENT_RESOURCE_ID:專案、資料夾或組織的 ID,該實體擁有您要更新的 UAP。專案 ID 是英數字串,例如my-project。資料夾和組織 ID 則為數字,例如123456789012。 -
FIELD_TO_UPDATE=UPDATED_VALUE:要更新的欄位和對應的更新值。以下列舉幾個可用來更新政策欄位的旗標:
-
--display-name=DISPLAY_NAME:將 UAP 的顯示名稱替換為指定名稱。 -
--details-rules=RULES_FILE:將 UAP 規則替換為指定檔案中的規則。檔案中的每項規則都應採用下列格式:{ "description": "DESCRIPTION", "effect": "EFFECT", "principals": [ INCLUDED_PRINCIPALS ], "excludedPrincipals": [ EXCLUDED_PRINCIPALS ], "operation": { "permissions": [ INCLUDED_PERMISSIONS ], "excludedPermissions": [ EXCLUDED_PERMISSIONS ] }, CONDITIONS }
替換下列值:
-
DESCRIPTION:規則的人類可讀說明。 -
EFFECT:規則對存取權的影響。支援的值為ALLOW和DENY:-
ALLOW:將指定權限授予指定主體。 -
DENY:禁止指定的主體使用指定權限。
-
-
替換下列值,指定規則中包含的主體:
-
INCLUDED_PRINCIPALS:要納入規則的主體。 -
EXCLUDED_PRINCIPALS:選用。要從規則中排除的主體,即使這些主體位於納入的主體清單中也一樣。舉例來說,您可以將 Google 群組新增至納入的主體清單,然後排除屬於該群組的特定使用者。
如需支援的主體 ID 清單,請參閱「UAP 的主體類型」。
-
-
替換下列值,指定要納入規則的權限:
-
INCLUDED_PERMISSIONS:要納入規則的權限。 -
EXCLUDED_PERMISSIONS:選用。要從規則中排除的權限,即使這些權限位於納入的權限清單中。舉例來說,您可以將某個角色新增至納入的權限清單,然後排除該角色中的特定權限。
建立這些權限清單時,您可以參照權限名稱、角色名稱和權限群組。詳情請參閱「UAP 規則中的角色和權限」。
-
-
CONDITIONS:選用。規則的適用條件。請使用下列格式:"conditions": { "SERVICE": { "title": "CONDITION_TITLE", "description": "CONDITION_DESCRIPTION", "expression": "CONDITION_EXPRESSION" } }
替換下列值:
-
SERVICE:提供條件運算式所用屬性的服務。 -
CONDITION_TITLE:選用。條件用途的簡短摘要。 -
CONDITION_DESCRIPTION:選用。條件的詳細說明。 -
CONDITION_EXPRESSION:參照存取嘗試屬性的布林運算式,例如存取嘗試中附加至資源的標記。如果運算式評估結果為true,則規則會套用至存取嘗試。如果評估結果為false,則規則不適用於存取嘗試。
如需支援屬性及其服務清單,請參閱「支援的條件屬性」。
-
-
-
--add-details-rules=RULES_FILE:將指定檔案中的規則附加至 UAP 中的現有規則。 -
--remove-details-rules=RULES_FILE:從 UAP 的現有規則中移除指定檔案中的規則。只有與指定檔案中的規則完全相符的規則才會遭到移除。 -
--clear-details-rules:清除 UAP 中的所有規則。
如需可用於更新 UAP 的完整旗標清單,請參閱
gcloud iam access-policies update指令參考資料。部分旗標互斥。 -
FORMAT:回覆格式。使用json或yaml。
執行下列指令:
Linux、macOS 或 Cloud Shell
gcloud iam access-policies update UAP_ID \ --UAP_PARENT_RESOURCE_TYPE=UAP_PARENT_RESOURCE_ID \ --location=global --FIELD_TO_UPDATE=UPDATED_VALUE \ --format=FORMAT
Windows (PowerShell)
gcloud iam access-policies update UAP_ID ` --UAP_PARENT_RESOURCE_TYPE=UAP_PARENT_RESOURCE_ID ` --location=global --FIELD_TO_UPDATE=UPDATED_VALUE ` --format=FORMAT
Windows (cmd.exe)
gcloud iam access-policies update UAP_ID ^ --UAP_PARENT_RESOURCE_TYPE=UAP_PARENT_RESOURCE_ID ^ --location=global --FIELD_TO_UPDATE=UPDATED_VALUE ^ --format=FORMAT
回應會包含代表要求的長時間執行的作業。作業完成後,回應會顯示更新後的 UAP。
Request issued for: [example-policy]
Waiting for operation [organizations/123456789012/locations/global/operations/operation-1715374208720-6181fae5e2034-2d8a712b-5c92e5b9] to complete...done.
Updated accessPolicy [example-policy].
{
"createTime": "2026-08-31T21:43:39.822441Z",
"details": {
"rules": [
{
"conditions": {
"iam.googleapis.com": {
"expression": "resource.matchTag('environment', 'prod')"
}
},
"description": "Grant non-delete compute permissions to compute admins in prod",
"effect": "ALLOW",
"excludedPrincipals": [
"principal://goog/subject/access-restricted@example.com"
],
"operation": {
"excludedPermissions": [
"*/*.delete"
],
"permissions": [
"role:roles/compute.admin"
]
},
"principals": [
"principalSet://goog/group/compute-admins@example.com"
]
}
]
},
"displayName": "Updated display name",
"etag": "W/\"YZtdQgtulCVzvTwlBTFjPQ==\"",
"name": "projects/0123456789012/locations/global/accessPolicies/example-policy",
"uid": "puid_0123456789012345678",
"updateTime": "2026-08-31T21:43:39.822441Z"
}
REST
accessPolicies.patch 方法會更新現有的 UAP。
使用任何要求資料之前,請先修改下列項目的值:
-
UAP_PARENT_RESOURCE_TYPE:Resource Manager 資源 (專案、資料夾或組織) 的類型,該資源擁有您要更新的 UAP。請使用projects、folders或organizations值。 -
UAP_PARENT_RESOURCE_ID:專案、資料夾或組織的 ID,該實體擁有您要更新的 UAP。專案 ID 是英數字串,例如my-project。資料夾和組織 ID 則為數字,例如123456789012。 -
UAP_ID:要更新的 UAP ID,例如example-policy。 DISPLAY_NAME:選用。UAP 的人類可讀說明,例如Example policy。顯示名稱長度上限為 63 個字元。-
UAP_RULES:UAP 規則清單,定義要授予或拒絕的存取權,以及要授予或拒絕存取權的主體。一項 UAP 最多可有 100 項規則。每項規則的格式如下:{ "description": "DESCRIPTION", "effect": "EFFECT", "principals": [ INCLUDED_PRINCIPALS ], "excludedPrincipals": [ EXCLUDED_PRINCIPALS ], "operation": { "permissions": [ INCLUDED_PERMISSIONS ], "excludedPermissions": [ EXCLUDED_PERMISSIONS ] }, CONDITIONS }
替換下列值:
-
DESCRIPTION:規則的人類可讀說明。 -
EFFECT:規則對存取權的影響。支援的值為ALLOW和DENY:-
ALLOW:將指定權限授予指定主體。 -
DENY:禁止指定的主體使用指定權限。
-
-
替換下列值,指定規則中包含的主體:
-
INCLUDED_PRINCIPALS:要納入規則的主體。 -
EXCLUDED_PRINCIPALS:選用。要從規則中排除的主體,即使這些主體位於納入的主體清單中也一樣。舉例來說,您可以將 Google 群組新增至納入的主體清單,然後排除屬於該群組的特定使用者。
如需支援的主體 ID 清單,請參閱「UAP 的主體類型」。
-
-
替換下列值,指定要納入規則的權限:
-
INCLUDED_PERMISSIONS:要納入規則的權限。 -
EXCLUDED_PERMISSIONS:選用。要從規則中排除的權限,即使這些權限位於納入的權限清單中。舉例來說,您可以將某個角色新增至納入的權限清單,然後排除該角色中的特定權限。
建立這些權限清單時,您可以參照權限名稱、角色名稱和權限群組。詳情請參閱「UAP 規則中的角色和權限」。
-
-
CONDITIONS:選用。規則的適用條件。請使用下列格式:"conditions": { "SERVICE": { "title": "CONDITION_TITLE", "description": "CONDITION_DESCRIPTION", "expression": "CONDITION_EXPRESSION" } }
替換下列值:
-
SERVICE:提供條件運算式所用屬性的服務。 -
CONDITION_TITLE:選用。條件用途的簡短摘要。 -
CONDITION_DESCRIPTION:選用。條件的詳細說明。 -
CONDITION_EXPRESSION:參照存取嘗試屬性的布林運算式,例如存取嘗試中附加至資源的標記。如果運算式評估結果為true,則規則會套用至存取嘗試。如果評估結果為false,則規則不適用於存取嘗試。
如需支援屬性及其服務清單,請參閱「支援的條件屬性」。
-
-
HTTP 方法和網址:
PATCH https://iam.googleapis.com/v3/UAP_PARENT_RESOURCE_TYPE/UAP_PARENT_RESOURCE_ID/locations/global/accessPolicies/UAP_ID
JSON 要求主體:
{
"displayName": "DISPLAY_NAME",
"details": {
"rules": [
UAP_RULES
]
}
}
請展開以下其中一個選項,以傳送要求:
回應會包含代表要求的長時間執行的作業。如要瞭解如何取得長時間執行的作業狀態,請參閱本頁的「查看長時間執行的作業狀態」一節。
{
"name": "organizations/123456789012/locations/global/operations/operation-1715626721931-6185a7953ef76-76f80ee4-19cd1bf7",
"metadata": {
"@type": "type.googleapis.com/google.iam.v3.OperationMetadata",
"createTime": "2026-05-13T18:58:43.721277235Z",
"target": "organizations/123456789012/locations/global/accessPolicies/example-policy",
"verb": "update",
"requestedCancellation": false,
"apiVersion": "v3"
},
"done": false
}
變更政策適用的資源
建立 UAP 繫結後,您無法變更繫結中的政策 ID 或資源。因此,如要變更 UAP 套用的資源,必須執行下列其中一項操作:
- 如要將 UAP 套用至其他資源,請建立新的繫結,將 UAP 繫結至該資源。
- 如要從資源中移除 UAP,請刪除將 UAP 繫結至資源的繫結。
查看長時間執行的作業狀態
使用 REST API 或用戶端程式庫時,任何變更政策或繫結的方法都會傳回長時間執行的作業 (LRO)。長時間執行的作業會追蹤要求狀態,並指出政策或繫結的變更是否已完成。
REST
operations.get 方法會傳回長時間執行的作業的狀態。
使用任何要求資料之前,請先修改下列項目的值:
-
OPERATION_NAME::作業的全名。您會在原始要求的 回應中收到這個名稱。作業名稱的格式如下:
RESOURCE_TYPE/RESOURCE_ID/locations/global/operations/OPERATION_ID
HTTP 方法和網址:
GET https://iam.googleapis.com/v3/OPERATION_NAME
請展開以下其中一個選項,以傳送要求:
您應該會收到如下的 JSON 回覆:
{
"name": "organizations/314340013352/locations/global/operations/operation-1732752311821-627edd607a3df-9a62cdea-2a7d9f07",
"metadata": {
"@type": "type.googleapis.com/google.iam.v3.OperationMetadata",
"createTime": "2024-11-28T00:05:12.006289686Z",
"endTime": "2024-11-28T00:05:12.192141801Z",
"target": "organizations/314340013352/locations/global/POLICY_TYPE/POLICY_ID",
"verb": "create",
"requestedCancellation": false,
"apiVersion": "v3"
},
"done": true,
"response": {
POLICY
}
}
如果作業沒有 done 欄位,請重複取得作業,繼續監控其狀態。使用部分指數輪詢,在每次要求之間加入延遲時間。當 done 欄位設為 true 時,代表作業已完成,您可以停止取得作業。