Cloud Functions puede controlar eventos en Cloud Firestore en el mismo proyecto de Cloud que la función. Puedes leer o actualizar Cloud Firestore en respuesta a estos eventos mediante las API de Firestore y las bibliotecas cliente.
En un ciclo de vida típico, una función de Cloud Firestore hace lo siguiente:
Espera a que ocurran cambios en un documento en particular.
Se activa cuando ocurre un evento y realiza sus tareas.
Recibe un objeto de datos con una instantánea del documento afectado. En el caso de los eventos
write
oupdate
, el objeto de datos contiene instantáneas que representan el estado del documento antes y después del evento de activación.
Tipos de eventos
Cloud Firestore admite los eventos create
, update
, delete
y write
. El evento write
comprende todas las modificaciones que se realizan a un documento.
Tipo de evento | Activador |
---|---|
providers/cloud.firestore/eventTypes/document.create (predeterminado) |
Se activa cuando se escribe en un documento por primera vez. |
providers/cloud.firestore/eventTypes/document.update |
Se activa cuando un documento ya existe y se cambia uno de sus valores. |
providers/cloud.firestore/eventTypes/document.delete |
Se activa cuando se borra un documento con datos. |
providers/cloud.firestore/eventTypes/document.write |
Se activa cuando se crea, actualiza o borra un documento. |
Los comodines se escriben en los activadores con llaves, como se muestra en el siguiente ejemplo: "/projects/YOUR_PROJECT_ID/databases/(default)/documents/collection/{document_wildcard}"
Especifica la ruta de acceso del documento
Para activar la función, especifica la ruta de acceso del documento que deseas escuchar. Las funciones solo responden a los cambios del documento y no pueden supervisar colecciones o campos específicos. A continuación, se muestran algunos ejemplos de rutas de acceso de documentos válidas:
users/marie
: Activador válido. Supervisa un solo documento,/users/marie
.users/{username}
: activador válido. Supervisa todos los documentos del usuario. Los comodines se usan para supervisar todos los documentos de la colección.users/{username}/addresses
: activador no válido. Se refiere a la subcolecciónaddresses
, no a un documento.users/{username}/addresses/home
: activador válido. Supervisa el documento de dirección personal de todos los usuarios.users/{username}/addresses/{addressId}
: activador válido. Supervisa todos los documentos de dirección.
Usa comodines y parámetros
Si no conoces el documento específico que deseas supervisar, usa un {wildcard}
en lugar del ID del documento:
users/{username}
escucha cambios en todos los documentos del usuario.
En este ejemplo, cuando se cambia cualquier campo en los documentos de users
, coincide con un comodín llamado {username}
.
Si un documento de users
tiene subcolecciones y se modifica un campo de uno de los documentos en ellas, no se activará el comodín {username}
.
Las coincidencias de comodines se extraen de las rutas de acceso de documentos. Puedes definir tantos comodines como desees para sustituir los ID explícitos de colección o documento.
Estructura de eventos
Este activador invoca tu función con un evento similar al que se muestra en el siguiente ejemplo:
{ "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 } }
Cada objeto Document
contiene uno o más objetos Value
. Consulta la documentación de Value
para obtener referencias de tipo. Esto resulta muy útil si usas un lenguaje escrito (como Go) para escribir tus funciones.
Muestra de código
La siguiente muestra de Cloud Functions imprime los campos de un evento de activación de Cloud Firestore:
Node.js
Python
Go
Java
C#
Ruby
En el siguiente ejemplo, se recupera el valor que agrega el usuario, se convierte la string en esa ubicación a mayúscula y se reemplaza el valor por la string en mayúscula:
Node.js
Python
Go
Java
C#
Implementa la función
Con el siguiente comando de gcloud
, se implementa una función que se activa mediante eventos de escritura en el documento /messages/{pushId}
:
gcloud functions deploy FUNCTION_NAME \ --runtime RUNTIME \ --trigger-event "providers/cloud.firestore/eventTypes/document.write" \ --trigger-resource "projects/YOUR_PROJECT_ID/databases/(default)/documents/messages/{pushId}"
Argumento | Descripción |
---|---|
--runtime RUNTIME |
Es el nombre del entorno de ejecución que usas. Para obtener una lista completa, consulta la referencia de gcloud .
|
--trigger-event NAME |
Es el tipo de evento que supervisará la función (uno de write , create , update o delete ).
|
--trigger-resource NAME |
Es la ruta de acceso de la base de datos completamente calificada en la que escuchará la función.
Esto debe tener el siguiente formato: "projects/YOUR_PROJECT_ID/databases/(default)/documents/PATH" El texto {pushId} es un parámetro comodín, como se mencionó antes en la sección Especifica la ruta de acceso al documento.
|
Limitaciones y garantías
Los activadores de Firestore para Cloud Functions son una función Beta con algunas limitaciones conocidas, como las que se describen a continuación:
- Una función puede tardar hasta 10 segundos en responder a los cambios en Firestore.
- No se garantiza el ordenamiento. Los cambios rápidos pueden activar invocaciones de funciones en un orden inesperado.
- Los eventos se entregan al menos una vez, pero un solo evento puede dar lugar a varias invocaciones de funciones. Evita depender de la mecánica de entrega de eventos de exactamente una vez y escribe funciones idempotentes.
- Los activadores de Firestore para Cloud Functions solo están disponibles en Firestore en modo nativo. No está disponible para Firestore en el modo Datastore.