使用 Cloud Run 函数(第 2 代)进行扩展
借助 Cloud Run 函数,您可以部署代码来处理触发的事件 Firestore 数据库中的更改。这样,您就可以将 而无需运行您自己的服务器。
使用 Cloud Run 函数扩展 Firestore(第 2 代)
Cloud Run Functions(第 2 代)支持以下 Firestore 事件触发器,以便您创建与 Firestore 事件关联的处理程序:
事件类型 | 触发器 |
---|---|
google.cloud.firestore.document.v1.created |
首次写入某个文档时触发。 |
google.cloud.firestore.document.v1.updated |
当某文档已存在并且其任何值发生了更改时触发。 |
google.cloud.firestore.document.v1.deleted |
在有文档被删除时触发。 |
google.cloud.firestore.document.v1.written |
在触发 created 、updated 或 deleted 时触发。 |
google.cloud.firestore.document.v1.created.withAuthContext |
与 created 相同,但添加了身份验证信息。 |
google.cloud.firestore.document.v1.updated.withAuthContext |
与 updated 相同,但添加了身份验证信息。 |
google.cloud.firestore.document.v1.deleted.withAuthContext |
与 deleted 相同,但添加了身份验证信息。 |
google.cloud.firestore.document.v1.written.withAuthContext |
与 written 相同,但添加了身份验证信息。 |
仅 Firestore 事件触发 。数据未更改(无操作写入)的 Firestore 文档更新将不会生成更新或写入事件。无法将事件添加到特定字段。
在事件中添加身份验证上下文
如需包含与事件相关的其他身份验证信息,请将事件触发器与 withAuthContext
扩展程序搭配使用。此附加信息可将
触发事件的主账号的相关信息。除了基本事件中返回的信息之外,它还会添加 authtype
和 authid
属性。如需详细了解属性值,请参阅 authcontext
参考文档。
编写 Firestore 触发的函数
如需编写响应 Firestore 事件的函数,请准备在部署期间指定以下内容:
- 触发事件类型
- 一个触发器事件过滤条件,用于选择与函数关联的文档
- 要运行的函数代码
触发器事件过滤条件
指定事件过滤条件时,您可以指定文档完全匹配或路径模式。使用路径模式,通过通配符 *
或 **
匹配多个文档。
例如,您可以响应以下文档的更改:
users/marie
使用通配符 *
或 **
响应与模式匹配的文档中的更改。通配符 *
与单个分段匹配,多段通配符 **
与模式中的零个或多个分段匹配。
对于单段匹配 (*
),您还可以使用已命名的捕获组。例如 users/{userId}
。
例如:
模式 | 说明 |
---|---|
/users/* 或 /users/{userId} |
与 /users 集合中的所有文档匹配。与 /users/marie/messages/33e2IxYBD9enzS50SJ68 等子集合中的文档不匹配 |
/users/** |
匹配 /users 集合中的所有文档以及 /users/marie/messages/33e2IxYBD9enzS50SJ68 等子集合中的文档 |
如需详细了解路径模式,请参阅 Eventarc 路径模式。
即使您使用的是通配符,触发器也必须始终指向某个文档。例如,users/{userId=*}/{messageCollectionId=*}
是无效的,因为 {messageCollectionId=*}
是一个集合。不过,users/{userId=*}/{messageCollectionId}/{messageId=*}
是有效的,因为 {messageId=*}
将始终指向某个文档。
示例函数
以下示例演示了如何接收 Firestore 事件。如需处理事件涉及的文档数据,请查看 value
和 old_value
字段。
value
:一个包含操作后文档快照的Document
对象。 对于删除事件,不会填充此字段。old_value
:一个Document
对象,其中包含操作前的文档快照。系统仅为更新和删除事件填充此字段。
Go
如需向 Firestore 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Java
如需向 Firestore 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Node.js
如需向 Firestore 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
使用 protobufjs 解码事件数据。在源代码中添加google.events.cloud.firestore.v1
data.proto
。
Python
如需向 Firestore 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
C#
如需向 Firestore 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
以下示例会将添加到受影响文档的 original
字段的字符串转换为大写,并将新值写入同一文档:
Go
如需向 Firestore 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Java
如需向 Firestore 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Node.js
如需向 Firestore 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
使用 protobufjs 解码事件数据。在源代码中添加google.events.cloud.firestore.v1
data.proto
。
Python
如需向 Firestore 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
C#
如需向 Firestore 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
在源代码中添加 proto 依赖项
您必须添加 Firestore data.proto
文件(位于函数源目录中)。此文件会导入以下 proto,您也必须将其添加到源目录中:
为依赖项使用相同的目录结构。例如,将 struct.proto
放置在 google/protobuf
中。
需要使用这些文件才能对事件数据进行解码。如果函数源代码不包含这些文件,则在运行时会返回错误。
事件属性
每个事件都包含数据属性,其中包含与事件相关的信息,例如事件触发的时间。Firestore 会添加与事件中涉及的数据库和文档相关的其他数据。您可以按如下方式访问这些属性:
Java
logger.info("Function triggered by event on: " + event.getSource()); logger.info("Event type: " + event.getType()); logger.info("Event time " + event.getTime()); logger.info("Event project: " + event.getExtension("project")); logger.info("Event location: " + event.getExtension("location")); logger.info("Database name: " + event.getExtension("database")); logger.info("Database document: " + event.getExtension("document")); // For withAuthContext events logger.info("Auth information: " + event.getExtension("authid")); logger.info("Auth information: " + event.getExtension("authtype"));
Node.js
console.log(`Function triggered by event on: ${cloudEvent.source}`); console.log(`Event type: ${cloudEvent.type}`); console.log(`Event time: ${cloudEvent.time}`); console.log(`Event project: ${cloudEvent.project}`); console.log(`Event location: ${cloudEvent.location}`); console.log(`Database name: ${cloudEvent.database}`); console.log(`Document name: ${cloudEvent.document}`); // For withAuthContext events console.log(`Auth information: ${cloudEvent.authid}`); console.log(`Auth information: ${cloudEvent.authtype}`);
Python
print(f"Function triggered by change to: {cloud_event['source']}") print(f"Event type: {cloud_event['type']}") print(f"Event time: {cloud_event['time']}") print(f"Event project: {cloud_event['project']}") print(f"Location: {cloud_event['location']}") print(f"Database name: {cloud_event['database']}") print(f"Document: {cloud_event['document']}") // For withAuthContext events print(f"Auth information: {cloud_event['authid']}") print(f"Auth information: {cloud_event['authtype']}")
部署函数
部署 Cloud Run 函数的用户必须具有 Cloud Run functions Developer IAM 角色或具有提供相同权限的其他角色。另请参阅其他部署配置。
您可以使用 gcloud CLI 部署函数 或 Google Cloud 控制台以下示例演示了使用 gcloud CLI 进行部署。如需详细了解如何使用 Google Cloud 控制台进行部署,请参阅部署 Cloud Run 函数
gcloud
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
使用
gcloud functions deploy
命令部署函数:gcloud functions deploy YOUR_FUNCTION_NAME \ --gen2 \ --region=FUNCTION_LOCATION \ --trigger-location=TRIGGER_LOCATION \ --runtime=YOUR_RUNTIME \ --source=YOUR_SOURCE_LOCATION \ --entry-point=YOUR_CODE_ENTRYPOINT \ --trigger-event-filters="type=EVENT_FILTER_TYPE" \ --trigger-event-filters="database=DATABASE" \ --trigger-event-filters-path-pattern="document=DOCUMENT" \
第一个参数
YOUR_FUNCTION_NAME
是已部署函数的名称。函数名称必须以字母开头,后面最多可跟 62 个字母、数字、连字符或下划线,但必须以字母或数字结尾。--gen2
标志 指定您要部署到 Cloud Run 函数(第 2 代)。省略 此标志会导致部署到 Cloud Run 函数(第 1 代)。--region
标志 指定要部署函数的区域。为了尽可能靠近,请设置为 Firestore 附近的区域 数据库。如果您的 Firestore 数据库位于多区域位置 位置,对于
nam5
中的数据库和设置为us-central1
europe-west4
(适用于eur3
中的数据库)。对于地区性 Firestore 位置,请设置为同一区域。--trigger-location
标志用于指定触发器的位置。您必须将此标志设置为 Firestore 数据库的位置。--source
标志用于指定函数源代码的位置。请参阅以下内容 了解详情:--entry-point
标志指定源代码中函数的入口点。这是在您的函数运行时执行的代码。此标志的值必须是源代码中存在的函数名称或完全限定类名称。如需了解详情,请参阅函数入口点。EVENT_FILTER_TYPE
:Firestore 支持以下事件类型。google.cloud.firestore.document.v1.created
:首次写入文档时发送事件。google.cloud.firestore.document.v1.updated
:在发生 文档已存在,并且其任何值已更改。google.cloud.firestore.document.v1.deleted
:在发生 文档已删除。google.cloud.firestore.document.v1.written
:在发生 创建、更新或删除文档。google.cloud.firestore.document.v1.created.withAuthContext
:首次写入文档时发送事件,并且该事件包含额外的身份验证信息google.cloud.firestore.document.v1.updated.withAuthContext
:在文档已存在并且值已更改时发送事件。包含额外的身份验证信息google.cloud.firestore.document.v1.deleted.withAuthContext
:在删除文档时发送事件。包含额外的身份验证信息google.cloud.firestore.document.v1.written.withAuthContext
:在创建、更新或删除文档时发送事件。包含额外的身份验证信息
DATABASE
:Firestore 数据库。对于默认数据库名称,请使用(default)
。DOCUMENT
:您要修改此参数的数据库路径 在数据被创建、更新或触发事件时触发事件 已删除。运算符可以是下列之一:- 等于;例如
--trigger-event-filters=document='users/marie'
。 - 路径模式;例如
--trigger-event-filters-path-pattern=document='users/*'
。如需了解详情,请参阅了解路径模式。
- 等于;例如
如需查看有关部署命令及其标志的完整参考信息,请参阅
gcloud functions deploy
文档。
部署示例
以下示例演示了如何使用 Google Cloud CLI 进行部署。
在 us-west2
区域中为数据库部署函数:
gcloud functions deploy gcfv2-trigger-firestore-node \
--gen2 \
--region=us-west2 \
--trigger-location=us-west2 \
--runtime=nodejs18 \
--source=gs://CLOUD_STORAGE_BUCKET/firestoreEventFunction.zip \
--entry-point=makeUpperCase \
--trigger-event-filters=type=google.cloud.firestore.document.v1.written \
--trigger-event-filters=database='(default)' \
--trigger-event-filters-path-pattern=document='messages/{pushId}'
在 nam5
多区域中为数据库部署函数:
gcloud functions deploy gcfv2-trigger-firestore-python \
--gen2 \
--region=us-central1 \
--trigger-location=nam5 \
--runtime=python311 \
--source=gs://CLOUD_STORAGE_BUCKET/firestoreEventFunction.zip \
--entry-point=make_upper_case \
--trigger-event-filters=type=google.cloud.firestore.document.v1.written.withAuthContext \
--trigger-event-filters=database='(default)' \
--trigger-event-filters-path-pattern=document='messages/{pushId}'
限制
请注意适用于 Cloud Run 函数的 Firestore 触发器的以下限制:
- Cloud Run 函数(第 1 代)前提条件是现有的“(默认)”Firestore 原生模式下的数据库。它不会 支持 Firestore 命名数据库或 Datastore 模式。请使用 Cloud Run 函数 在这种情况下,(第 2 代)配置事件。
- 无法保证顺序。快速更改可能会以意想不到的顺序触发函数调用。
- 事件至少会被传送一次,但单个事件可能会导致多次调用函数。应该避免依赖“正好一次”机制,并编写幂等函数。
- Datastore 模式 Firestore 需要使用 Cloud Run 函数(第 2 代)。Cloud Run 函数(第 1 代)不支持 Datastore 模式。
- 一个触发器与单一数据库相关联。您无法创建与多个数据库匹配的触发器。
- 删除数据库不会自动删除该数据库的任何触发器。触发器会停止传送事件,但会继续存在,直到您删除触发器。
- 如果匹配的事件超过请求大小上限,则
事件可能不会传递给 Cloud Run 函数(第 1 代)。
- 因请求大小而未传送的事件会记录在平台日志中,并计入项目的日志使用量。
- 您可以在 Logs Explorer 中找到这些日志,其严重性为
error
且内容为“由于大小超出第 1 代的限制,因此事件无法传送到 Cloud Functions 函数”消息。您可以在functionName
字段下方找到函数名称。如果receiveTimestamp
字段仍在从现在起的一小时内,您可以利用该时间戳之前和之后的快照来读取相关文档,从而推断实际事件内容。 - 为避免这种情况发生,您可以:
- 迁移并升级到 Cloud Run 函数(第 2 代)
- 缩小文档
- 删除相关的 Cloud Run functions 函数
- 您可以使用排除功能关闭日志记录功能本身,但请注意,违规事件仍然不会传送。
Eventarc 和 Firestore 位置
Eventarc 不支持 Firestore 事件的多区域 触发器,但您仍然可以为 Firestore 数据库创建触发器 多区域位置Eventarc 映射 Firestore 多区域位置复制到以下 Eventarc 区域:
Firestore 多区域 | Eventarc 区域 |
---|---|
nam5 |
us-central1 |
eur3 |
europe-west4 |
Cloud Run functions(第 2 代)与第 1 代之间的差异
Cloud Run functions(第 2 代)针对所有运行时使用 Eventarc 事件。以前,Cloud Run 函数(第 1 代)将 Eventarc 事件用于 只有部分运行时。 Eventarc 事件与 Cloud Run functions(第 1 代)之间存在以下差异。
支持 Eventarc 的 Firestore 触发器 其他目标位置您可以通过路由
CloudEvents
多个目标平台,包括: 包括但不限于 Cloud Run、GKE Workflows。适用于 Eventarc 的 Firestore 触发器检索 触发器定义,并使用 以确定 Firestore 是否应发出事件。写入操作不会考虑触发器定义在运行期间可能发生的任何更改。
Cloud Run 函数(第 1 代)会检索触发器定义, 数据库写入的评估,以及对触发器所做的更改, 评估可能会影响 Firestore 是否发出事件。
如需了解详情,请参阅 Cloud Run 函数版本比较。