通过 Firestore 事件创建触发器

本指南介绍如何根据 Firestore 事件为 Cloud Run 服务和函数创建触发器。

您可以将 Cloud Run 服务配置为由 Firestore 数据库中的事件触发。触发后，您的服务会通过 Firestore API 和客户端库读取和更新 Firestore 数据库，以响应这些事件。

在典型的生命周期中，当 Firestore 事件触发 Cloud Run 服务时，会发生以下情况：

  1. 服务会等待特定文档发生更改。

  2. 发生更改时，服务会被触发并执行其任务。

  3. 服务会接收包含受影响文档快照的数据对象。对于 write 或 update 事件，该数据对象包含代表触发事件前后的文档状态的快照。

事件类型

Firestore 支持 create、update、delete 和 write 事件。write 事件包含对某个文档所做的所有修改。

事件类型 触发器
google.cloud.firestore.document.v1.created（默认） 首次写入某个文档时触发。
google.cloud.firestore.document.v1.updated 当某文档已存在并且其任何值发生了更改时触发。
google.cloud.firestore.document.v1.deleted 当文档的数据被删除时触发。
google.cloud.firestore.document.v1.written 在创建、更新或删除某个文档时触发。

在触发器中，通配符是使用英文大括号编写的，例如：projects/YOUR_PROJECT_ID/databases/(default)/documents/collection/{document_wildcard}

指定文档路径

如需触发服务，请指定要监听的文档路径。文档路径必须与服务位于同一 Google Cloud 项目中。

以下是一些有效和无效的文档路径示例：

  • users/marie：有效的触发器。监控单个文档 (/users/marie)。

  • users/{username}：有效的触发器。监控所有用户文档。通配符用于监控集合中的所有文档。

  • users/{username}/addresses：无效的触发器。该路径指向的是子集合 addresses，而不是某个文档。

  • users/{username}/addresses/home：有效的触发器。监控所有用户的家庭住址文档。

  • users/{username}/addresses/{addressId}：有效的触发器。监控所有地址文档。

  • users/{user=**}：有效的触发器。监控所有用户文档以及每个用户文档下子集合中的任何文档，例如 /users/userID/address/home 或 /users/userID/phone/work。

通配符和参数

如果您不知道要监控的特定文档，请使用 {wildcard} 代替文档 ID：

  • users/{username} 侦听所有用户文档的更改。

在此示例中，如果 users 中的任何文档的任何字段发生更改，都会与一个名为 {username} 的通配符相匹配。

如果 users 中的某个文档有多个子集合，并且这些子集合中一个文档内的某字段发生了更改，那么不会触发 {username} 通配符。 如果您的目标是同时也响应子集合中的事件，请使用多段通配符 {username=**}。

通配符匹配项会从文档路径中提取出来。 您可以定义任意多个通配符，以替代明确指定的集合或文档 ID。最多可以使用一个多段通配符，例如 {username=**}。

事件结构

当发生如下所示的事件时，此触发器会调用服务： 

{
    "oldValue": { // Update and Delete operations only
        A Document object containing a pre-operation document snapshot
    },
    "updateMask": { // Update operations only
        A DocumentMask object that lists changed fields.
    },
    "value": {
        // A Document object containing a post-operation document snapshot
    }
}

每个 Document 对象都包含一个或多个 Value 对象。如需查看类型参考信息，请参阅 Value 文档。

准备工作

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

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

    启用 API

所需的角色

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

部署者账号所需的角色

如需获得从 Firestore 事件触发所需的权限，请让您的管理员为您授予项目的以下 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

设置您的 Firestore 数据库

在部署服务之前，您必须先创建 Firestore 数据库：

  1. 进入 Firestore 数据页面

  2. 选择创建数据库。

  3. 点击原生模式，然后选择继续。

  4. 在为数据库命名字段中，输入数据库 ID，例如 firestore-db。

  5. 在位置类型中，选择区域，然后选择数据库位于的区域。一旦选择便无法更改。

  6. 将安全规则部分保留原样。

  7. 点击创建数据库。

Firestore 数据模型由包含文档的集合组成。每个文档包含一组键值对。

创建触发器

根据您要部署的服务类型，您可以执行以下任一操作：

为服务创建触发器

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

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

控制台

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

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

    转到 Cloud Run

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

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

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

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

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

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

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

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

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

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

    5. 在“过滤条件”部分，选择数据库、操作和属性值，或使用默认选择内容。

    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.firestore.document.v1.created" \
    --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. 选择 Firestore 触发器。

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

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

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

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

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

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

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

    5. 在“过滤条件”部分，选择数据库、操作和属性值，或使用默认选择内容。

    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.firestore.document.v1.created" \
    --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 Run functions 通过事件触发器扩展 Firestore。

后续步骤

  • 查看在您对指定集合内的文档进行更改时触发的函数示例。