Identity and Access Management (IAM) 提供了多种类型的政策,可帮助您控制主账号可以访问哪些资源。本指南介绍了如何在将事件消息发布到 Eventarc 高级总线时使用访问权限政策来控制访问权限。
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 角色:
-
创建访问权限政策:
Access Policy Admin (
roles/iam.accessPolicyAdmin) -
应用访问权限政策:
Project IAM Admin (
roles/resourcemanager.projectIamAdmin)
如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。
这些预定义角色包含控制发布访问权限所需的权限。如需查看所需的确切权限,请展开所需权限部分:
所需权限
您需要具备以下权限才能控制发布访问权限:
-
创建访问权限政策:
iam.accessPolicies.create -
应用访问权限政策:
-
iam.accessPolicies.bind -
resourcemanager.projects.createPolicyBinding
-
创建访问权限政策
创建访问权限政策,以控制在发布到项目中的 Eventarc 高级总线时对资源的访问权限。
您可以使用 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:要在其中创建政策的项目的 Google Cloud 项目 ID。POLICY_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:可选。 简单易懂的访问权限政策名称,例如“示例政策”。显示名称最多可以包含 63 个字符。POLICY_DESCRIPTION:可选。 直观易懂的访问权限政策说明,例如“说明示例”。说明最多可包含 256 个字符。EFFECT:规则的效果,为ALLOW或DENY。PRINCIPALS:此规则适用的身份。标识符的格式取决于您要引用的主账号类型。如需了解详情,请参阅访问权限政策的主账号类型。EXCLUDED_PRINCIPALS:从规则应用中排除的身份,即使这些身份列在principals中也是如此。 例如,您可以将某个 Google 群组添加到principals,然后排除该群组中的特定用户。CEL_EXPRESSION:将进行评估以确定规则适用性的 CEL 表达式。如需了解详情,请参阅使用通用表达式语言。POLICY_PROJECT_ID:要在其中创建政策的项目的 Google Cloud 项目 ID。POLICY_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:可选。简单易懂的政策绑定名称,例如“示例绑定”。显示名称最多可以包含 63 个字符。BINDING_PROJECT_ID:将在其中创建绑定的项目的 Google Cloud 项目 ID。此值应与创建 Eventarc Advanced 总线的项目的 ID 相同,并指示绑定的目标。POLICY_PROJECT_ID:创建政策的项目的 Google Cloud 项目 ID。POLICY_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时,操作完成,您可以停止获取操作。后续步骤
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):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"]],["最后更新时间 (UTC):2025-12-04。"],[],[]]-
创建访问权限政策:
Access Policy Admin (