使用 Cloud Storage 创建触发器

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

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

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

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

设置所需角色

  1. 如果您是项目创建者，则会被授予基本 Owner 角色 (roles/owner)。默认情况下，此 Identity and Access Management (IAM) 角色可提供完全访问大多数 Google Cloud 资源所需的权限，您可以跳过此步骤。

    如果您不是项目创建者，则必须向主账号授予项目的必需权限。例如，主账号可以是 Google 账号（针对最终用户）或服务账号（针对应用和计算工作负载）。如需了解详情，请参阅事件目标位置的角色和权限页面。

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

    所需权限

    如需获得配置 Cloud Storage 触发器所需的权限，请让管理员向您授予项目的以下 IAM 角色：

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

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

  2. 记下 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 角色，这些角色包含所需的最小权限并遵循最小权限原则。

  3. 默认情况下，只有 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.
  4. 将项目的 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
  5. 如果您在 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 区域。

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

    • event-filters 标志用于指定触发器监控的事件过滤条件。与所有 event-filters 过滤条件匹配的事件会触发对服务的调用。每个触发器都必须具有受支持的事件类型。创建后，您无法更改事件过滤条件类型。如需更改事件过滤条件类型，您必须创建新的触发器并删除旧触发器。您可以酌情使用格式为 ATTRIBUTE=VALUE 的受支持过滤条件重复 --event-filters 标志来添加更多过滤条件。

为函数创建触发器

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

控制台

使用 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 创建函数时，您必须先deploy函数，然后再创建触发器。请按照以下步骤为函数创建触发器：

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

    gcloud beta 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 区域。例如 us-central1。

  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 过滤条件匹配的事件会触发对函数的调用。每个触发器都必须具有受支持的事件类型。创建后，您无法更改事件过滤条件类型。如需更改事件过滤条件类型，您必须创建新的触发器并删除旧触发器。您可以酌情使用格式为 ATTRIBUTE=VALUE 的受支持过滤条件重复 --event-filters 标志来添加更多过滤条件。

事件交付

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

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

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

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

后续步骤