通过 Cloud Storage 事件创建触发器

在 Cloud Run 中，您可以使用 Eventarc 触发 Cloud Storage 中的服务，以响应 Cloud Storage 中的更改。

为服务指定 Cloud Storage 触发器时，您需要选择事件类型并指定 Cloud Storage 存储桶。由于此触发器，每当指定存储桶中的对象（文件）发生更改时，系统都会调用您的服务。

如需由 Cloud Storage 存储桶上的事件触发您的服务，该服务和存储桶必须位于同一 Google Cloud 项目中。

如需查看有关如何根据 Cloud Storage 事件创建触发器的详细说明和代码示例，请参阅以下教程：

支持的 Cloud Storage 事件类型

Cloud Run 支持以下 Cloud Storage 事件类型：

事件 事件类型 说明
对象已完成创建
  • google.cloud.storage.object.v1.finalized（通过 Eventarc）
 当您创建新对象或覆盖现有对象，并且 Cloud Storage 创建该对象的新一代实例时，会发生此事件。
删除了对象
  • google.cloud.storage.object.v1.deleted（通过 Eventarc）
 当对象被软删除时会发生此事件。如需了解详情，请参阅软删除。
对象已归档
  • google.cloud.storage.object.v1.archived（通过 Eventarc）
 当对象的当前版本变为非当前版本时会发生此事件。如需了解详情，请参阅对象版本控制。
更新了对象元数据
  • google.cloud.storage.object.v1.metadataUpdated（通过 Eventarc）
 当您更改现有对象的元数据时会发生此事件。

Google 事件代码库包含用于处理事件数据的其他资源。

准备工作

  1. 确保您已按照设置页面中的说明为 Cloud Run 设置了新项目。

  2. 启用 Artifact Registry API、Cloud Build API、Cloud Run Admin API、Eventarc API、Cloud Logging API、Pub/Sub API 和 Cloud Storage API：

    启用 API

设置所需角色

您或您的管理员必须为部署者账号、触发器身份以及可选的 Pub/Sub 服务代理授予以下 IAM 角色。

部署者账号所需的角色

如需获得从 Cloud Storage 事件触发所需的权限，请让您的管理员为您授予项目的以下 IAM 角色：

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

请注意，默认情况下，Cloud Build 权限包含上传和下载 Artifact Registry 制品的权限。

触发器身份所需的角色

  1. 记下 Compute Engine 默认服务账号，因为您将把它附加到 Eventarc 触发器以代表触发器的身份信息进行测试。启用或使用包含 Compute Engine 的 Google Cloud 服务后，系统会自动创建此服务账号，其电子邮件地址格式如下：

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    将 PROJECT_NUMBER 替换为您的 Google Cloud项目编号。您可以在 Google Cloud 控制台的欢迎页面上，或通过运行以下命令来查找项目编号：

    gcloud projects describe PROJECT_ID --format='value(projectNumber)'

    对于生产环境，我们强烈建议创建新的服务账号，并为其授予一个或多个 IAM 角色，这些角色包含所需的最小权限并遵循最小权限原则。

  2. 默认情况下，只有 Project Owner、Project Editor 以及 Cloud Run Admin 和 Invoker 才能调用 Cloud Run 服务。您可以按服务控制访问权限；但是，出于测试目的，请向 Compute Engine 服务账号授予 Google Cloud 项目的 Cloud Run Invoker 角色 (run.invoker)。此操作会授予项目中所有 Cloud Run 服务和作业的角色。
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/run.invoker

    请注意，如果您在未授予 Cloud Run Invoker 角色的情况下为经过身份验证的 Cloud Run 服务创建触发器，则触发器会成功创建且处于活动状态。但是，触发器将无法按预期运行，并且日志中会显示类似于以下内容的消息：

    The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
  3. 将项目的 Eventarc Event Receiver 角色 (roles/eventarc.eventReceiver) 授予 Compute Engine 默认服务账号，以便 Eventarc 触发器可以接收来自事件提供程序的事件。
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/eventarc.eventReceiver

Pub/Sub 服务代理所需的角色

  • 如果您在 2021 年 4 月 8 日或之前启用了 Cloud Pub/Sub 服务代理，以支持经过身份验证的 Pub/Sub 推送请求，请向该服务代理授予 Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator)。否则，系统会默认授予此角色：
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator

为服务创建触发器

您可以在部署服务后指定触发器。

点击相应标签页即可获取有关所选工具的使用说明。

控制台

  1. 使用容器或从来源部署 Cloud Run 服务。

  2. 在 Google Cloud 控制台中，前往 Cloud Run：

    转到 Cloud Run

  3. 在服务列表中，点击现有服务。

  4. 在“服务详情”页面上，找到触发器标签页。

  5. 点击添加触发器，然后选择 Cloud Storage 触发器。

  6. 在 Eventarc 触发器窗格中，修改触发器详细信息，如下所示：

    1. 在触发器名称字段中，输入触发器的名称，或使用默认名称。

    2. 从列表中选择触发器类型以指定以下触发器类型之一：

      • Google 来源，用于为 Pub/Sub、Cloud Storage、Firestore 和其他 Google 事件提供方指定触发器。

      • 第三方，用于与提供 Eventarc 来源的非 Google 提供方集成。如需了解详情，请参阅 Eventarc 中的第三方事件。

    3. 从事件提供方列表中选择 Cloud Storage，以选择提供用于触发服务的事件类型的产品。如需查看事件提供方列表，请参阅事件提供方和目的地。

    4. 从事件类型列表中选择 google.cloud.storage.object.v1.finalized。触发器配置因支持的事件类型而异。如需了解详情，请参阅事件类型。

    5. 在存储桶字段中，点击浏览，以选择触发器要监控的 Cloud Storage 存储桶。更改此存储桶中的对象会触发对函数的调用。

    6. 如果区域字段处于启用状态，请为 Eventarc 触发器选择位置。一般来说，Eventarc 触发器所在的位置应与您要监控事件的 Google Cloud 资源所在的位置一致。在大多数情况下，您还应在同一区域部署服务。如需详细了解 Eventarc 触发器位置，请参阅了解 Eventarc 位置。

    7. 在服务账号字段中，选择一个服务账号。Eventarc 触发器与调用服务时用作身份的服务账号相关联。Eventarc 触发器的服务账号必须具有调用服务的权限。默认情况下，Cloud Run 使用 Compute Engine 默认服务账号。

    8. （可选）指定要将传入请求发送到的服务网址路径。 这是触发器的事件应该发送到的目的地服务上的相对路径。例如：/、/route、route 和 route/subroute。

    9. 填写必填字段后，点击保存触发器。

  7. 创建触发器后，通过确保触发器标签上有对勾标记 来验证触发器运行状况良好。

gcloud

  1. 使用容器或从来源部署 Cloud Run 服务。

  2. 运行以下命令以创建用于过滤事件的触发器：

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=EVENTARC_TRIGGER_LOCATION \
    --destination-run-service=SERVICE  \
    --destination-run-region=REGION \
    --event-filters="type=google.cloud.storage.object.v1.finalized" \
    --event-filters="bucket=PROJECT_ID-bucket" \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    您需要进行如下替换：

    • 将 TRIGGER_NAME 替换为触发器的名称。

    • 将 EVENTARC_TRIGGER_LOCATION 替换为 Eventarc 触发器的位置。一般来说，Eventarc 触发器所在的位置应与您要监控事件的 Google Cloud 资源所在的位置一致。在大多数情况下，您还应在同一区域部署服务。如需了解详情，请参阅 Eventarc 位置。

    • 将 SERVICE 替换为您要部署的服务的名称。

    • 将 REGION 替换为服务的 Cloud Run 区域。 例如 europe-west1。

    • 将 PROJECT_NUMBER 替换为您的 Google Cloud 项目编号。Eventarc 触发器与调用服务时用作身份的服务账号相关联。Eventarc 触发器的服务账号必须具有调用服务的权限。默认情况下，Cloud Run 使用默认计算服务账号。

    每个 event-filters 标志均指定了一种事件类型，只有当事件满足其 event-filters 标志中指定的所有条件时，函数才会触发。每个触发器均必须具有一个 event-filters 标志，用于指定受支持的事件类型，例如写入 Firestore 的新文档或上传到 Cloud Storage 的文件。事件过滤条件类型在创建后便无法更改。如需更改事件过滤条件类型，您必须创建新触发器并删除旧触发器。您可以酌情使用格式为 ATTRIBUTE=VALUE 的受支持过滤条件重复 --event-filters 标志来添加更多过滤条件。

Terraform

如需为 Cloud Run 服务创建 Eventarc 触发器，请参阅使用 Terraform 创建触发器。

为函数创建触发器

点击相应标签页即可获取有关所选工具的使用说明。

控制台

使用 Google Cloud 控制台创建函数时，您还可以向函数添加触发器。请按照以下步骤为函数创建触发器：

  1. 在 Google Cloud 控制台中，前往 Cloud Run：

    转到 Cloud Run

  2. 点击编写函数，然后输入函数详细信息。如需详细了解如何在部署期间配置函数，请参阅部署函数。

  3. 在触发器部分中，点击添加触发器。

  4. 选择 Cloud Storage 触发器。

  5. 在 Eventarc 触发器窗格中，修改触发器详细信息，如下所示：

    1. 在触发器名称字段中输入触发器的名称，或使用默认名称。

    2. 从列表中选择触发器类型：

      • Google 来源，用于为 Pub/Sub、Cloud Storage、Firestore 和其他 Google 事件提供方指定触发器。

      • 第三方，用于与提供 Eventarc 来源的非 Google 提供方集成。如需了解详情，请参阅 Eventarc 中的第三方事件。

    3. 从事件提供方列表中选择 Cloud Storage，以选择提供用于触发函数的事件类型的产品。如需查看事件提供方列表，请参阅事件提供方和目的地。

    4. 从事件类型列表中选择 google.cloud.storage.object.v1.finalized。触发器配置因支持的事件类型而异。如需了解详情，请参阅事件类型。

    5. 在存储桶字段中，点击浏览，以选择触发器要监控的 Cloud Storage 存储桶。更改此存储桶中的对象会触发对函数的调用。

    6. 如果区域字段处于启用状态，请为 Eventarc 触发器选择位置。一般来说，Eventarc 触发器所在的位置应与您要监控事件的 Google Cloud 资源所在的位置一致。在大多数情况下，您还应在同一区域部署函数。如需详细了解 Eventarc 触发器位置，请参阅了解 Eventarc 位置。

    7. 在服务账号字段中，选择一个服务账号。Eventarc 触发器与调用函数时用作身份的服务账号相关联。Eventarc 触发器的服务账号必须具有调用函数的权限。默认情况下，Cloud Run 使用 Compute Engine 默认服务账号。

    8. （可选）指定要将传入请求发送到的服务网址路径。 这是触发器的事件应该发送到的目的地服务上的相对路径。例如：/、/route、route 和 route/subroute。

  6. 填写必填字段后，点击保存触发器。

gcloud

使用 gcloud CLI 创建函数时，您必须先部署函数，然后再创建触发器。请按照以下步骤为函数创建触发器：

  1. 在包含示例代码的目录中运行以下命令以部署函数：

    gcloud run deploy FUNCTION \
        --source . \
        --function FUNCTION_ENTRYPOINT \
        --base-image BASE_IMAGE_ID \
        --region REGION

    您需要进行如下替换：

    • 将 FUNCTION 替换为您要部署的函数的名称。您可以完全省略此参数，但如果省略它，系统将提示您输入名称。

    • 将 FUNCTION_ENTRYPOINT 替换为源代码中函数的入口点。这是 Cloud Run 在您的函数运行时执行的代码。此标志的值必须是源代码中存在的函数名称或完全限定类名称。

    • 将 BASE_IMAGE_ID 替换为函数的基础映像环境。如需详细了解基础映像以及每个映像中包含的软件包，请参阅运行时基础映像。

    • 将 REGION 替换为您要在其中部署函数的 Google Cloud区域。例如 europe-west1。

  2. 运行以下命令以创建用于过滤事件的触发器：

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=EVENTARC_TRIGGER_LOCATION \
    --destination-run-service=FUNCTION  \
    --destination-run-region=REGION \
    --event-filters="type=google.cloud.storage.object.v1.finalized" \
    --event-filters="bucket=PROJECT_ID-bucket" \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    您需要进行如下替换：

    • 将 TRIGGER_NAME 替换为触发器的名称。

    • 将 EVENTARC_TRIGGER_LOCATION 替换为 Eventarc 触发器的位置。一般来说，Eventarc 触发器所在的位置应与您要监控事件的 Google Cloud 资源所在的位置一致。在大多数情况下，您还应在同一区域部署函数。如需了解详情，请参阅 Eventarc 位置。

    • 将 FUNCTION 替换为您要部署的函数的名称。

    • 将 REGION 替换为函数的 Cloud Run 区域。

    • 将 PROJECT_NUMBER 替换为您的 Google Cloud 项目编号。Eventarc 触发器与调用函数时用作身份的服务账号相关联。Eventarc 触发器的服务账号必须具有调用函数的权限。默认情况下，Cloud Run 使用默认计算服务账号。

    每个 event-filters 标志均指定了一种事件类型，只有当事件满足其 event-filters 标志中指定的所有条件时，函数才会触发。每个触发器均必须具有一个 event-filters 标志，用于指定受支持的事件类型，例如写入 Firestore 的新文档或上传到 Cloud Storage 的文件。事件过滤条件类型在创建后便无法更改。如需更改事件过滤条件类型，您必须创建新触发器并删除旧触发器。您可以酌情使用格式为 ATTRIBUTE=VALUE 的受支持过滤条件重复 --event-filters 标志来添加更多过滤条件。

Terraform

如需为 Cloud Run 函数创建 Eventarc 触发器，请参阅使用 Terraform 创建触发器。

事件交付

Cloud Storage 触发器是通过适用于 Cloud Storage 的 Pub/Sub 通知实现的。事件受 Pub/Sub 通知传送保证的约束。

存储桶最多可将 10 个通知配置设定为针对特定事件触发。超出存储桶的通知限制会导致更多函数部署失败，并显示如下错误：

Cloud Storage bucket ...: Pub/Sub notification limit reached

您可以管理自己的 Pub/Sub 主题，并针对您希望函数响应的类型的 Cloud Storage 通知来注册该主题，从而规避此限制。例如，您可以将用于所选事件（例如对象创建）的单个通知配置到某个 Pub/Sub 主题。然后，让订阅该主题的所需数量的函数订阅方处理相应事件，并将其扇出到多个目标。例如：

  1. 创建您自己的 Pub/Sub 主题。
  2. 在 Cloud Storage 存储桶中创建单个通知配置，该配置会在特定事件（例如用于对象创建的 OBJECT_FINALIZE）发生时触发，并将该事件发送到单个 Pub/Sub 主题。
  3. 创建由您的 Pub/Sub 主题触发的一个或多个函数。

这样可得到一个 Cloud Storage 通知配置、一个 Pub/Sub 主题以及所需数量的函数（在 Pub/Sub 所允许的非常高的传送限制范围内）。

如需详细了解 Cloud Storage 限制，请参阅 Cloud Storage 配额和限制。

后续步骤