Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

控制发布权限

Advanced

Identity and Access Management (IAM) 提供了多种类型的政策，可帮助您控制主账号可以访问哪些资源。本指南介绍了如何在将事件消息发布到 Eventarc Advanced 总线时使用 访问权限政策来控制访问权限。

IAM 访问权限政策可同时允许和拒绝访问资源。不过，与 IAM 允许和拒绝政策不同，访问权限政策可以根据特定的事件上下文属性（例如事件消息优先级）授予或拒绝访问权限。

每项访问权限政策都是一组规则，可让您识别主账号并定义确定规则适用性的条件，并让您能够实现精细的访问权限控制。例如，根据对应用于事件上下文属性的通用表达式语言 (CEL) 表达式的评估，您可以允许或拒绝将一部分事件消息发布到 Eventarc Advanced 总线的权限。

本指南介绍了如何创建和应用访问权限政策，方法是先创建访问权限政策，然后创建政策绑定以将该政策关联到 a Google Cloud 项目。

准备工作

在创建和应用访问权限政策之前，您应该已经创建了可以发布事件消息的 Eventarc Advanced 总线。

您必须针对禁止将访问权限政策绑定到资源 (constraints/iam.managed.disableAccessPolicyBindings) 受管限制条件关闭强制执行。默认情况下，此布尔值限制条件针对新组织启用，并阻止您将 IAM v3 API 访问权限政策绑定到资源。如需了解详情，请参阅使用布尔值规则更新政策。
请务必考虑以下事项：

重要提示：我们建议您在控制对 Eventarc Advanced 总线的发布访问权限时仅使用 IAM v3 API （而不是同时使用 v1 和 v3 API）。在预览期间，如果在评估 IAM v3 API 访问权限政策时遇到问题或错误，IAM v1 API 允许政策仍将有效。这可能会导致意想不到的后果。
- 访问权限政策必须应用于项目或绑定到 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

安装 Google Cloud CLI，然后使用联合身份登录 gcloud CLI。登录后，运行以下命令来初始化 Google Cloud CLI：
gcloud init
REST API

如需在本地开发环境中使用本页面上的 REST API 示例，请使用您提供给 gcloud CLI 的凭证。
如需了解详情，请参阅身份验证文档中的使用 REST 时进行身份验证 Google Cloud 。

所需的角色

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 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], \
    operation={permissions=[eventarc.googleapis.com/messageBuses.publish]}, \
    conditions={eventarc.googleapis.com={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"
        ],
        "operation": {
          "permissions": ["eventarc.googleapis.com/messageBuses.publish"]
        },
        "conditions": {
          "eventarc.googleapis.com": {
              "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],operation={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],operation={permissions=[eventarc.googleapis.com/messageBuses.publish]},conditions={eventarc.googleapis.com={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"
        ],
        "operation": {
          "permissions": [
            "eventarc.googleapis.com/messageBuses.publish"
          ]
        },
        "conditions": {
          "eventarc.googleapis.com": {
            "expression": "CEL_EXPRESSION"
          }
        }
      }
    ]
  }
}

如需发送您的请求，请展开以下选项之一：

curl（Linux、macOS 或 Cloud Shell）

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以通过运行 gcloud auth list 来检查当前的活跃账号。

将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令，在当前目录中创建或覆盖此文件：

cat > request.json << 'EOF'
{
  "displayName": "POLICY_DISPLAY_NAME",
  "details": {
    "rules": [
      {
        "description": "POLICY_DESCRIPTION",
        "effect": "EFFECT",
        "principals": [
          "PRINCIPALS"
        ],
        "excludedPrincipals": [
        "EXCLUDED_PRINCIPALS"
        ],
        "operation": {
          "permissions": [
            "eventarc.googleapis.com/messageBuses.publish"
          ]
        },
        "conditions": {
          "eventarc.googleapis.com": {
            "expression": "CEL_EXPRESSION"
          }
        }
      }
    ]
  }
}
EOF

然后，执行以下命令以发送 REST 请求：

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"

PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以通过运行 gcloud auth list 来检查当前的活跃账号。

将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令，在当前目录中创建或覆盖此文件：

@'
{
  "displayName": "POLICY_DISPLAY_NAME",
  "details": {
    "rules": [
      {
        "description": "POLICY_DESCRIPTION",
        "effect": "EFFECT",
        "principals": [
          "PRINCIPALS"
        ],
        "excludedPrincipals": [
        "EXCLUDED_PRINCIPALS"
        ],
        "operation": {
          "permissions": [
            "eventarc.googleapis.com/messageBuses.publish"
          ]
        },
        "conditions": {
          "eventarc.googleapis.com": {
            "expression": "CEL_EXPRESSION"
          }
        }
      }
    ]
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

然后，执行以下命令以发送 REST 请求：

$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://iam.googleapis.com/v3/projects/POLICY_PROJECT_ID/locations/global/accessPolicies?access_policy_id=POLICY_ID" | Select-Object -Expand Content

APIs Explorer（浏览器）

复制请求正文并打开方法参考页面。APIs Explorer 面板会在页面右侧打开。您可以与此工具进行交互以发送请求。将请求正文粘贴到此工具中，填写任何其他必填字段，然后点击执行。

响应包含表示请求的长时间运行的操作。如需了解如何获取长时间运行的操作的状态，请参阅本文档中的本页面上的检查长时间运行的操作的状态。

{
  "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"
    ],
    "operation": {
      "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"
      ],
      "operation": {
        "permissions": [
          "eventarc.googleapis.com/messageBuses.publish"
        ]
      },
      "conditions": {
        "eventarc.googleapis.com": {
          "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"
}

如需发送您的请求，请展开以下选项之一：

curl（Linux、macOS 或 Cloud Shell）

将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令，在当前目录中创建或覆盖此文件：

cat > request.json << 'EOF'
{
  "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"
}
EOF

然后，执行以下命令以发送 REST 请求：

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/BINDING_PROJECT_ID/locations/global/policyBindings?policy_binding_id=POLICY_ID-binding"

PowerShell (Windows)

将请求正文保存在名为 request.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"
}
'@  | Out-File -FilePath request.json -Encoding utf8

然后，执行以下命令以发送 REST 请求：

$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://iam.googleapis.com/v3/projects/BINDING_PROJECT_ID/locations/global/policyBindings?policy_binding_id=POLICY_ID-binding" | Select-Object -Expand Content

APIs Explorer（浏览器）

响应包含表示请求的长时间运行的操作。如需了解如何获取长时间运行的操作的状态，请参阅本文档中的本页面上的检查长时间运行的操作的状态。

{
  "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。

如需发送您的请求，请展开以下选项之一：

curl（Linux、macOS 或 Cloud Shell）

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

执行以下命令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://iam.googleapis.com/v3/OPERATION_NAME"

PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

执行以下命令：

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://iam.googleapis.com/v3/OPERATION_NAME" | Select-Object -Expand Content

APIs Explorer（浏览器）

打开方法参考页面。APIs Explorer 面板会在页面右侧打开。您可以与此工具进行交互以发送请求。填写所有必填字段，然后点击执行。

您应该收到类似以下内容的 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 时，操作已完成，您可以停止获取操作。

控制发布权限 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

gcloud

REST API

所需的角色

所需权限

创建访问权限政策

gcloud

示例

REST API

curl（Linux、macOS 或 Cloud Shell）

PowerShell (Windows)

APIs Explorer（浏览器）

示例

应用访问权限政策

gcloud

示例

REST API

curl（Linux、macOS 或 Cloud Shell）

PowerShell (Windows)

APIs Explorer（浏览器）

检查长时间运行的操作的状态

curl（Linux、macOS 或 Cloud Shell）

PowerShell (Windows)

APIs Explorer（浏览器）

后续步骤

控制发布权限