将 Cloud Storage 事件路由到 Cloud Run

Eventarc 触发器声明您对某个事件或一系列事件感兴趣。如需配置事件路由，您可以为触发器指定过滤条件，包括事件来源和目标 Cloud Run 服务。

Eventarc 通过 HTTP 请求以 CloudEvents 格式将事件传送到事件接收器。

以下说明介绍如何配置到 Cloud Run 服务的事件路由（由直接 Cloud Storage 事件触发）。如需了解详情，请参阅支持的直接事件列表。

准备创建触发器

在创建触发器之前，请先完成以下前提条件：

控制台

  1. 在 Google Cloud 控制台的“项目选择器”页面上，选择或创建 Google Cloud 项目。

    转到“项目选择器”

  2. 启用 Cloud Logging、Eventarc 和 Eventarc Publishing API。

    启用 API

  3. 如果适用，请启用与直接事件相关的 API。例如，对于 Cloud Storage 事件，请启用 Cloud Storage API。

  4. 如果您还没有用户管理的服务账号，请创建一个，然后为其授予必要的角色和权限，以便 Eventarc 可以管理目标服务的事件。

    1. 在 Google Cloud 控制台中，进入创建服务账号页面。

      转到“创建服务账号”

    2. 选择您的项目。

    3. 在服务账号名称字段中，输入一个名称。Google Cloud 控制台会根据此名称填充服务账号 ID 字段。

      在服务账号说明字段中，输入说明。例如 Service account for event trigger。

    4. 点击创建并继续。

    5. 如需提供适当的访问权限，请在选择角色列表中，针对经过身份验证或未经身份验证的调用选择要向服务账号授予的所需 Identity and Access Management (IAM) 角色。如需了解详情，请参阅 Cloud Run 目标的角色和权限。

      如需添加其他角色，请点击 添加其他角色，然后添加其他各个角色。

    6. 点击继续。

    7. 如需完成账号的创建过程，请点击完成。

  5. 向 Cloud Storage 服务代理授予 Pub/Sub Publisher 角色。通常，此服务代理为 service-PROJECT_NUMBER@gs-project-accounts.iam.gserviceaccount.com。您可以检索 Cloud Storage 服务代理的电子邮件地址。

    1. 在 Google Cloud 控制台中，转到 IAM 页面。

      进入 IAM

    2. 在 Cloud Storage 服务代理对应的行中，点击 修改主账号。（如果未列出服务代理，请继续执行下一步。）此时会打开修改访问权限窗格。

      1. 点击 添加其他角色，然后搜索 Pub/Sub Publisher 角色。
      2. 选择角色。
      3. 点击保存。

    3. 如果未列出服务代理，请点击 授予访问权限。此时会打开授予访问权限窗格。

      1. 在新的主账号字段中，输入服务代理的电子邮件地址。
      2. 在选择角色列表中，搜索 Pub/Sub Publisher 角色。
      3. 选择角色。
      4. 点击保存。

gcloud

  1. 在 Google Cloud 控制台中，激活 Cloud Shell。

    激活 Cloud Shell

    Cloud Shell 会话随即会在 Google Cloud 控制台的底部启动，并显示命令行提示符。Cloud Shell 是一个已安装 Google Cloud CLI 且已为当前项目设置值的 Shell 环境。该会话可能需要几秒钟时间来完成初始化。

  2. 启用 Cloud Logging、Eventarc 和 Eventarc Publishing API。

    gcloud services enable logging.googleapis.com \
  eventarc.googleapis.com \
  eventarcpublishing.googleapis.com

  3. 如果适用，请启用与直接事件相关的 API。例如，对于 Cloud Storage 事件，请启用 storage.googleapis.com。

  4. 如果您还没有用户管理的服务账号，请创建一个，然后为其授予必要的角色和权限，以便 Eventarc 可以管理目标服务的事件。

    1. 创建服务账号：

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      将 SERVICE_ACCOUNT_NAME 替换为服务账号的名称。该名称必须介于 6 到 30 个字符之间，且可以包含小写字母数字字符和短划线。在服务账号创建完毕后，无法再更改其名称。

    2. 为经过身份验证或未经身份验证的调用授予所需的 Identity and Access Management (IAM) 角色或权限。如需了解详情，请参阅 Cloud Run 目标的角色和权限。

  5. 将 pubsub.publisher 角色授予 Cloud Storage 服务账号：

    SERVICE_ACCOUNT="$(gsutil kms serviceaccount -p PROJECT_ID)"

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/pubsub.publisher"

创建触发器

您可以使用 Google Cloud CLI 或通过 Google Cloud 控制台创建 Eventarc 触发器。

控制台

  1. 在 Google Cloud 控制台中，进入 Eventarc 触发器页面。

    转到“触发器”

  2. 点击 创建触发器。
  3. 输入触发器名称。

    这是触发器的 ID，必须以字母开头。最多可包含 63 个小写字母、数字或连字符。

  4. 在触发器类型部分，选择 Google 来源。
  5. 在事件提供方列表中，选择 Cloud Storage。

    请注意，关联的 Google Cloud 文档中使用的事件提供方名称可能没有 Cloud 或 Google Cloud 前缀。例如，在控制台中，Memorystore for Redis 称为 Google Cloud Memorystore for Redis。

  6. 在事件类型列表中，从“直接”事件中选择一种事件类型：
    • google.cloud.storage.object.v1.archived：当对象的当前版本被归档或删除时，系统会发送事件。系统仅针对启用了版本控制的存储桶发送此事件。
    • google.cloud.storage.object.v1.delete：当对象被永久删除时，系统会发送事件。根据存储桶的对象版本控制设置，这意味着：
      • 对于启用了版本控制的存储桶，只有当某个版本被永久删除时（而不是在对象被归档时），系统才会发送此事件。
      • 对于未启用版本控制的存储分区，当某个对象被删除或覆盖时，系统会发送此事件。
    • google.cloud.storage.object.v1.finalized：当存储桶中创建了新对象（或者现有对象被覆盖，以及创建了该对象的新实例）时，系统将发送此事件。
    • google.cloud.storage.object.v1.metadataUpdated：在现有对象的[元数据](/storage/docs/metadata)发生更改时，系统将发送此事件。
  7. 在事件数据内容类型列表中，选择事件载荷的编码。

    对于来自 Cloud Storage 的直接事件，编码必须是 application/json。

  8. 指定或浏览 Cloud Storage 存储桶的全局唯一标识符。

    Cloud Storage 存储桶必须与 Eventarc 触发器位于同一 Google Cloud 项目以及同一区域或多区域中。

  9. 选择区域。

    Eventarc 的 Cloud Storage 触发器适用于单区域、双区域和多区域位置]。请注意，Cloud Storage 存储桶必须与 Eventarc 触发器位于同一 Google Cloud 项目和区域或多区域中。

    事件是通过来自 Cloud Storage 的 Pub/Sub 通知传送的。针对同一存储桶设置过多的注册通知可能会耗尽存储桶的通知限额，如错误 Cloud Storage bucket ...: Pub/Sub notification limit reached 所示。存储桶最多可将 10 个通知配置设置为针对特定事件触发。请参阅 Cloud Storage 配额和限制页面，详细了解配额和限制。

  10. 选择将调用您的服务或工作流的服务账号。

    或者，您可以创建新的服务账号。

    这用于指定与触发器相关联且您之前向其授予 Eventarc 所需的特定角色的 Identity and Access Management (IAM) 服务账号电子邮件。

  11. 在事件目的地列表中，选择 Cloud Run。
  12. 选择一项服务。

    这是接收触发器事件的服务的名称。该服务必须与触发器位于同一项目中，并在事件生成时，接收作为 HTTP POST 请求发送到其根网址路径 (/) 的事件。

  13. （可选）您可以指定将传入请求发送到的服务网址路径。

    这是触发器的事件应该发送到的目的地服务上的相对路径。例如：/、/route、route、route/subroute。

  14. 点击创建。

    15. 创建触发器之后，您便无法修改事件来源过滤条件。请创建新触发器，并删除旧触发器。 如需了解详情，请参阅管理触发器。

gcloud

您可以通过运行包含必需和可选标志的 gcloud eventarc triggers create 命令来创建触发器。

gcloud eventarc triggers create TRIGGER \
    --location=LOCATION \
    --destination-run-service=DESTINATION_RUN_SERVICE \
    --destination-run-region=DESTINATION_RUN_REGION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --event-filters="bucket=BUCKET" \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

替换以下内容：

  • TRIGGER：触发器的 ID 或完全限定标识符。
  • LOCATION：Eventarc 触发器的位置。或者，您可以设置 eventarc/location 属性；例如 gcloud config set eventarc/location us-central1。

    Cloud Storage 存储桶必须与 Eventarc 触发器位于同一 Google Cloud 项目以及同一区域或多区域中。如需了解详情，请参阅 Eventarc 位置。

  • DESTINATION_RUN_SERVICE：为触发器接收事件的 Cloud Run 服务的名称。该服务可以位于任何 Cloud Run 支持位置，无需与触发器位于同一位置。但是，该服务必须与触发器位于同一项目中，并在事件生成时，接收作为 HTTP POST 请求发送到其根网址路径 (/) 的事件。
  • DESTINATION_RUN_REGION：（可选）目标 Cloud Run 服务所在的区域。如果未指定，系统将假定服务与触发器位于同一区域。
  • EVENT_FILTER_TYPE：Cloud Storage 事件的标识符，可以是以下各项之一：
    • google.cloud.storage.object.v1.finalized：当存储桶中创建了新对象（或者现有对象被覆盖，以及创建了该对象的新实例）时发送事件
    • google.cloud.storage.object.v1.archived：当对象的现行版本被归档或被删除时，系统会发送此事件。系统仅针对启用了版本控制的存储桶发送此事件。
    • google.cloud.storage.object.v1.deleted：当某个对象被永久删除时，系统将发送此事件。根据存储桶的对象版本控制设置，这意味着：
      • 对于启用了版本控制的存储桶，只有当某个版本被永久删除时（而不是在对象被归档时），系统才会发送此事件。
      • 对于未启用版本控制的存储桶，当某个对象被删除或覆盖时，系统会发送此事件。
    • google.cloud.storage.object.v1.metadataUpdated：当现有对象的元数据发生更改时，系统会发送此事件。
  • BUCKET 是 Cloud Storage 存储桶的全球唯一标识符。
  • SERVICE_ACCOUNT_NAME：用户管理的服务账号的名称。
  • PROJECT_ID：您的 Google Cloud 项目 ID。

备注：

  • 对于来自 Cloud Storage 的直接事件，事件载荷的编码为 application/json。
  • 这些标志是必需的：
    • --event-filters="type=EVENT_FILTER_TYPE"
    • --event-filters="bucket=BUCKET"
  • 每个触发器可以有多个事件过滤条件，在一个 --event-filters=[ATTRIBUTE=VALUE,...] 标志内以英文逗号分隔，您也可以重复使用该标志来添加更多过滤条件。只有符合所有过滤条件的事件会被发送到目的地。不支持通配符和正则表达式。
  • 触发器创建后，事件过滤条件类型便无法更改。对于其他事件类型，您必须创建新的触发器。
  • 事件是通过来自 Cloud Storage 的 Pub/Sub 通知传送的。 针对同一存储桶设置过多的注册通知可能会耗尽存储桶的通知限额，如错误 Cloud Storage bucket ...: Pub/Sub notification limit reached 所示。存储桶最多可将 10 个通知配置设定为针对特定事件触发。请参阅 Cloud Storage 配额和限制页面，详细了解配额和限制。
  • --service-account 标志用于指定与触发器关联的 Identity and Access Management (IAM) 服务账号电子邮件。
  • （可选）您可以使用 --destination-run-path 标志指定触发器的事件应发送到的目标 Cloud Run 服务的相对路径。

示例：

gcloud eventarc triggers create helloworld-trigger \
    --location=us-central1 \
    --destination-run-service=helloworld-events \
    --destination-run-region=us-central1 \
    --event-filters="type=google.cloud.storage.object.v1.finalized" \
    --event-filters="bucket=my-bucket" \
    --service-account=${SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com

此命令会为 Cloud Storage 存储桶 my-bucket 和标识为 google.cloud.storage.object.v1.finalized 的事件创建一个名为 helloworld-trigger 的触发器。

Terraform

您可以使用 Terraform 为 Cloud Run 目标创建触发器。如需了解详情，请参阅使用 Terraform 创建触发器。

列出触发器

如需确认触发器已创建，您可以使用 Google Cloud CLI 或通过 Google Cloud 控制台列出 Eventarc 触发器。

控制台

  1. 在 Google Cloud 控制台中，进入 Eventarc 触发器页面。

    转到“触发器”

    此页面会列出所有位置的触发器，并包含名称、区域、事件提供方、目标位置等详细信息。

  2. 如需过滤触发器，请执行以下操作：

    1. 点击 过滤或过滤触发器字段。
    2. 在属性列表中，选择要作为触发器过滤条件的选项。

    您可以选择单个属性，或使用逻辑运算符 OR 添加更多属性。

  3. 如需对触发器进行排序，请点击任意受支持的列标题旁边的 排序。

gcloud

运行以下命令可列出触发器：

gcloud eventarc triggers list --location=-

此命令会列出所有位置的触发器，并包含名称、类型、目标位置和状态等详细信息。

后续步骤