Identity and Access Management (IAM) 提供多種政策,可協助您控管主體可存取的資源。本指南說明如何使用存取權政策,在將事件訊息發布至 Eventarc Advanced 匯流排時控管存取權。
IAM 存取權政策可允許及拒絕存取資源。 不過,與 IAM 允許和拒絕政策不同,存取政策可根據特定事件內容屬性 (例如事件訊息優先順序),授予或拒絕存取權。
每項存取權政策都是一組規則,可讓您識別主體、定義決定規則適用性的條件,以及啟用精細的存取控管。舉例來說,您可以根據套用至事件內容屬性的一般運算語言 (CEL) 運算式評估結果,允許或拒絕將部分事件訊息發布至 Eventarc 進階匯流排的權限。
本指南說明如何建立及套用存取權政策,方法是先建立存取權政策,然後建立政策繫結,將該政策連結至 Google Cloud 專案。
事前準備
建立及套用存取權政策前,您應已建立 Eventarc Advanced 匯流排,以便發布事件訊息。
請務必考量下列事項:
存取權政策必須套用至 Google Cloud 專案或與專案繫結。每個存取權政策最多可附加至 5 個專案,每個專案最多可附加 5 個存取權政策。每個Google Cloud 專案中,一個支援的區域可建立一個匯流排。附加至專案的存取權政策會控管該專案中任何 Eventarc Advanced 匯流排的發布存取權。
您可以使用存取權政策控管 Eventarc Advanced 匯流排的發布存取權,但無法控管特定匯流排訊息的訂閱存取權。支援的權限為
eventarc.messageBuses.publish。存取控管只能根據事件情境屬性,不能根據事件酬載內容。
系統會捨棄從 Google 來源發布且遭到拒絕的事件訊息。如果主體直接發布事件訊息,
Event published successfully記錄訊息會指出這點。不過,如果存取政策中的條件拒絕事件訊息,就會發生類似下列內容的錯誤:ERROR: (gcloud.beta.eventarc.message-buses.publish) PERMISSION_DENIED: Permission 'eventarc.googleapis.com/messageBuses.publish' denied on resource due to an IAM Access Policy. This command is authenticated as user@example.com which is the active account specified by the [core/account] property. '@type': type.googleapis.com/google.rpc.ErrorInfo domain: iam.googleapis.com metadata: permission: eventarc.googleapis.com/messageBuses.publish reason: IAM_PERMISSION_DENIED
如果尚未啟用 Eventarc 和 IAM API,請執行下列操作:
gcloud services enable eventarc.googleapis.com \ eventarcpublishing.googleapis.com \ iam.googleapis.com
設定驗證方法:
gcloud
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
REST API
如要在本機開發環境中使用本頁的 REST API 範例,請使用您提供給 gcloud CLI 的憑證。
Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command:
gcloud initIf you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
詳情請參閱 Google Cloud 驗證說明文件中的「使用 REST 進行驗證」。
必要的角色
IAM 角色包含一組權限,可讓您對 Google Cloud 資源執行特定動作。
如要取得控管發布存取權所需的權限,請要求管理員在專案中授予您下列 IAM 角色:
-
建立存取權政策:
存取權政策管理員 (
roles/iam.accessPolicyAdmin) -
套用存取權政策:
專案 IAM 管理員 (
roles/resourcemanager.projectIamAdmin)
如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。
這些預先定義的角色具備控管發布存取權所需的權限。如要查看確切的必要權限,請展開「Required permissions」(必要權限) 部分:
所需權限
如要控管發布存取權,必須具備下列權限:
-
建立存取權政策:
iam.accessPolicies.create -
套用存取政策:
-
iam.accessPolicies.bind -
resourcemanager.projects.createPolicyBinding
-
建立存取權政策
建立存取權政策,在專案中發布至 Eventarc Advanced 匯流排時控管存取權。
您可以透過 Google Cloud CLI 建立存取權政策,也可以直接向 IAM v3 API 發出要求。
gcloud
您可以執行 gcloud beta iam access-policies create 指令,建立存取權政策。
gcloud beta iam access-policies create POLICY_ID \ --project=POLICY_PROJECT_ID \ --location=global \ --details-rules=description="POLICY_DESCRIPTION",effect=EFFECT, \ principals=[PRINCIPALS],excludedPrincipals=[EXCLUDED_PRINCIPALS], \ permissions=[eventarc.googleapis.com/messageBuses.publish], \ activationConditions={eventarc.googleapis.com={celCondition={expression="CEL_EXPRESSION"}}}
更改下列內容:
POLICY_ID:存取權政策的專屬名稱,例如my-access-policy。POLICY_PROJECT_ID:要在當中建立政策的專案 ID。 Google CloudPOLICY_DESCRIPTION:政策的選用說明 (最多 256 個半形字元)。EFFECT:規則的影響 (ALLOW或DENY)。PRINCIPALS:適用這項規則的身分。識別碼的格式取決於您要參照的主體類型。詳情請參閱「存取權政策的主體類型」。EXCLUDED_PRINCIPALS:即使列在principals中,也會從規則套用範圍中排除的身分。舉例來說,您可以將 Google 群組新增至principals,然後排除屬於該群組的特定使用者。CEL_EXPRESSION:系統會評估 CEL 運算式,判斷是否適用規則,例如message.version != \"v1\"。詳情請參閱「使用一般運算式語言」。
注意事項:
--location標記會指定存取權政策的位置,且必須為global。--details-rules旗標可指定存取權政策檔案的路徑,該檔案可採用 JSON 或 YAML 格式編寫,例如--details-rules=path_to_file.json。設定多項規則時,也可以重複使用這個標記。系統會分別評估各項規則。
存取政策採用下列格式:
{ "displayName": "POLICY_DISPLAY_NAME", "details": { "rules": [ { "description": "POLICY_DESCRIPTION", "effect": "EFFECT", "principals": [ "PRINCIPALS" ], "excludedPrincipals": [ "EXCLUDED_PRINCIPALS" ], "permissions": [ "eventarc.googleapis.com/messageBuses.publish" ], "activationConditions": { "eventarc.googleapis.com": { "celCondition": { "expression": "CEL_EXPRESSION" } } } } ] } }
回應會包含代表您要求的一項長時間執行作業。如要瞭解如何取得長時間執行作業的狀態,請參閱本文的「檢查長時間執行作業的狀態」。
範例
下列指令會建立存取權政策,允許指定主體將事件訊息發布至匯流排,但如果資料媒體類型為 JSON,則會拒絕發布。
gcloud beta iam access-policies create my-access-policy \ --project=my-project-id \ --location=global \ --details-rules=description="Allow publishing to bus",effect=ALLOW,principals=[principal://goog/subject/user@example.com],permissions=[eventarc.googleapis.com/messageBuses.publish] \ --details-rules=description="Deny publishing to bus if media type is JSON",effect=DENY,principals=[principal://goog/subject/user@example.com],permissions=[eventarc.googleapis.com/messageBuses.publish],activationConditions={eventarc.googleapis.com={celCondition={expression="message.datacontenttype=='application/json'"}}}
REST API
您可以使用
projects.locations.accessPolicies.create method建立存取權政策。使用任何要求資料之前,請先替換以下項目:
POLICY_DISPLAY_NAME:選用。 存取權政策的人類可讀名稱,例如「Example policy」。顯示名稱長度上限為 63 個字元。POLICY_DESCRIPTION:選用。 存取政策的說明,例如「說明範例」。說明長度上限為 256 個字元。EFFECT:規則的影響,可以是ALLOW或DENY。PRINCIPALS:這項規則適用的身分。識別碼的格式取決於您要參照的主體類型。詳情請參閱「存取權政策的主體類型」。EXCLUDED_PRINCIPALS:從規則套用程序中排除的身分,即使列在principals中也一樣。舉例來說,您可以將 Google 群組新增至principals,然後排除該群組中的特定使用者。CEL_EXPRESSION:要評估的 CEL 運算式,用於判斷規則是否適用。詳情請參閱「使用一般運算式語言」。POLICY_PROJECT_ID:要在當中建立政策的專案 ID。 Google CloudPOLICY_ID:存取權政策的專屬名稱,例如my-access-policy。
您可以列出多項規則。系統會分別評估各項規則。如果某項規則不適用, 其他規則可能適用。
JSON 要求主體:
{ "displayName": "POLICY_DISPLAY_NAME", "details": { "rules": [ { "description": "POLICY_DESCRIPTION", "effect": "EFFECT", "principals": [ "PRINCIPALS" ], "excludedPrincipals": [ "EXCLUDED_PRINCIPALS" ], "permissions": [ "eventarc.googleapis.com/messageBuses.publish" ], "activationConditions": { "eventarc.googleapis.com": { "celCondition": { "expression": "CEL_EXPRESSION" } } } } ] } }請展開以下其中一個選項,以傳送要求:
回應會包含代表您要求的一項長時間執行作業。如要瞭解如何取得長時間執行作業的狀態,請參閱本文的「在本頁面檢查長時間執行作業的狀態」。
{ "name": "projects/POLICY_PROJECT_ID/locations/global/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.iam.v3.OperationMetadata", "createTime": "2025-01-25T17:17:45.782370139Z", "target": "projects/POLICY_PROJECT_ID/locations/global/accessPolicies/POLICY_ID", "verb": "create", "requestedCancellation": false, "apiVersion": "v3" }, "done": false }範例
下列存取權政策允許指定主體將事件訊息發布至匯流排,但如果訊息優先順序為
HIGH,則會拒絕發布。cat > request.json << 'EOF' { "displayName": "Eventarc Advanced access policy", "details": { "rules": [ { "description": "Allow publishing to bus", "effect": "ALLOW", "principals": [ "principal://goog/subject/user@example.com" ], "permissions": [ "eventarc.googleapis.com/messageBuses.publish" ] }, { "description": "Deny publishing to bus if message priority is HIGH", "effect": "DENY", "principals": [ "principal://goog/subject/user@example.com" ], "permissions": [ "eventarc.googleapis.com/messageBuses.publish" ], "activationConditions": { "eventarc.googleapis.com": { "celCondition": { "expression": "message.priority == \"HIGH\"" } } } } ] } } EOF curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ -d @request.json \ "https://iam.googleapis.com/v3/projects/POLICY_PROJECT_ID/locations/global/accessPolicies?access_policy_id=POLICY_ID"
套用存取權政策
建立政策繫結,將存取權政策套用至專案。 Google Cloud 每個政策繫結都會將一項存取權政策繫結至一項資源。
您可以透過 Google Cloud CLI 或直接向 IAM v3 API 提出要求,套用存取權政策。
gcloud
您可以執行 gcloud beta iam policy-bindings create 指令,建立政策繫結並套用存取權政策。
gcloud beta iam policy-bindings create BINDING_ID \ --project=BINDING_PROJECT_ID \ --location=global \ --policy=projects/POLICY_PROJECT_ID/locations/global/accessPolicies/POLICY_ID \ --target-resource=//cloudresourcemanager.googleapis.com/projects/BINDING_PROJECT_ID
更改下列內容:
BINDING_ID:政策繫結的專屬名稱,例如my-access-policy-binding。BINDING_PROJECT_ID:要建立繫結的專案 Google Cloud 專案 ID。這應與建立 Eventarc Advanced 匯流排的專案 ID 相同,並指出繫結的目標。
--location旗標會指定政策繫結的位置,且必須為global。回應會包含代表您要求的一項長時間執行作業。如要瞭解如何取得長時間執行作業的狀態,請參閱本文的「檢查長時間執行作業的狀態」。
範例
下列指令會建立政策繫結,將指定的存取權政策套用至 Google Cloud 專案:
gcloud beta iam policy-bindings create my-access-policy-binding \ --project=my-project-id \ --location=global \ --policy=projects/my-project-id/locations/global/accessPolicies/my-access-policy \ --target-resource=//cloudresourcemanager.googleapis.com/projects/my-project-id
REST API
您可以使用
projects.locations.policyBindings.create method建立政策繫結並套用存取權政策。使用任何要求資料之前,請先替換以下項目:
BINDING_DISPLAY_NAME: 選用。政策繫結的使用者可解讀名稱,例如「Example binding」。顯示名稱長度上限為 63 個字元。BINDING_PROJECT_ID:要在當中建立繫結的專案 ID。 Google Cloud 這應與建立 Eventarc Advanced 匯流排的專案 ID 相同,並指出繫結的目標。POLICY_PROJECT_ID:建立政策的專案專案 ID。 Google CloudPOLICY_ID:要繫結的存取權政策名稱,例如my-access-policy。
JSON 要求主體:
{ "display_name": "BINDING_DISPLAY_NAME", "target": {"resource": "//cloudresourcemanager.googleapis.com/projects/BINDING_PROJECT_ID"}, "policy_kind": "ACCESS", "policy": "projects/POLICY_PROJECT_ID/locations/global/accessPolicies/POLICY_ID" }請展開以下其中一個選項,以傳送要求:
回應會包含代表您要求的一項長時間執行作業。如要瞭解如何取得長時間執行作業的狀態,請參閱本文的「在本頁面檢查長時間執行作業的狀態」。
{ "name": "projects/BINDING_PROJECT_ID/locations/global/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.iam.v3.OperationMetadata", "createTime": "2025-01-25T17:17:45.782370139Z", "target": "projects/BINDING_PROJECT_ID/locations/global/policyBindings/POLICY_ID-binding", "verb": "create", "requestedCancellation": false, "apiVersion": "v3" }, "done": false }檢查長時間執行的作業狀態
使用 IAM REST API 時,凡是會變更存取權政策或繫結的方法,都會傳回長時間執行的作業 (LRO)。長期作業會追蹤要求狀態,並指出政策或繫結的變更是否完成。
operations.get方法會傳回長時間執行作業的狀態。使用任何要求資料之前,請先替換以下項目:
OPERATION_NAME:作業的完整名稱。您會在原始要求的相關回覆中收到這個名稱。作業名稱的格式如下:
projects/PROJECT_ID/locations/global/operations/OPERATION_ID
PROJECT_ID:作業傳回所在專案的 Google Cloud 專案 ID。
請展開以下其中一個選項,以傳送要求:
您應該會收到如下的 JSON 回覆:
{ "name": "projects/PROJECT_ID/locations/global/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.iam.v3.OperationMetadata", "createTime": "2025-01-28T00:05:12.006289686Z", "endTime": "2025-01-28T00:05:12.192141801Z", "target": "projects/PROJECT_ID/locations/global/accessPolicies/POLICY_ID", "verb": "create", "requestedCancellation": false, "apiVersion": "v3" }, "done": true, "response": { ACCESS_POLICY } }如果作業沒有
done欄位,請重複取得作業,持續監控作業狀態。使用「部分指數輪詢」,在每次要求之間加入延遲。done欄位設為true時,即代表作業完成,您可以停止取得作業。後續步驟
除非另有註明,否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權,程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間:2025-12-04 (世界標準時間)。
[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["難以理解","hardToUnderstand","thumb-down"],["資訊或程式碼範例有誤","incorrectInformationOrSampleCode","thumb-down"],["缺少我需要的資訊/範例","missingTheInformationSamplesINeed","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間:2025-12-04 (世界標準時間)。"],[],[]]-
建立存取權政策:
存取權政策管理員 (