Amplía tus productos con Cloud Functions (2nd gen)
Con Cloud Functions, puedes implementar código para controlar eventos que se activan con los cambios en la base de datos de Firestore. Esto te permite agregar funcionalidad del servidor sin ejecutar tus propios servidores.
Amplía Firestore con Cloud Functions (2nd gen)
Cloud Functions (2nd gen) admite los siguientes activadores de eventos de Firestore para que puedas crear controladores vinculados a eventos de Firestore:
Tipo de evento | Activador |
---|---|
google.cloud.firestore.document.v1.created |
Se activa cuando se escribe en un documento por primera vez. |
google.cloud.firestore.document.v1.updated |
Se activa cuando un documento ya existe y se cambia uno de sus valores. |
google.cloud.firestore.document.v1.deleted |
Se activa cuando se borra un documento. |
google.cloud.firestore.document.v1.written |
Se activa con created , updated o deleted . |
google.cloud.firestore.document.v1.created.withAuthContext |
Igual que created , pero agrega información de autenticación. |
google.cloud.firestore.document.v1.updated.withAuthContext |
Igual que updated , pero agrega información de autenticación. |
google.cloud.firestore.document.v1.deleted.withAuthContext |
Igual que deleted , pero agrega información de autenticación. |
google.cloud.firestore.document.v1.written.withAuthContext |
Igual que written , pero agrega información de autenticación. |
Los eventos de Firestore se activan solo cuando ocurren cambios en los documentos. La actualización de un documento de Firestore en la que los datos no se modifican (una escritura no-op) no genera un evento de actualización ni de escritura. No es posible agregar eventos a campos específicos.
Incluye el contexto de autenticación en el evento
Para incluir información de autenticación adicional sobre el evento, usa un activador de evento con la extensión withAuthContext
. Esta extensión agrega información
adicional sobre la principal que activó el evento. Agrega los atributos authtype
y authid
, además de la información que se muestra en el evento base. Consulta la referencia de authcontext
para obtener más información sobre los valores de atributos.
Escribe una función activada por Firestore
Para escribir una función que responda a los eventos de Firestore, prepárate para especificar lo siguiente durante la implementación:
- un tipo de evento activador
- un filtro de evento activador para seleccionar los documentos asociados con la función
- el código de la función para que se ejecute
Filtros del evento activador
Cuando especificas un filtro de eventos, puedes especificar una coincidencia exacta
de documentos o un patrón de ruta de acceso. Usa un patrón de ruta de acceso para hacer coincidir varios documentos con comodines, *
o **
.
Por ejemplo, puedes responder a los cambios realizados en el siguiente documento:
users/marie
Usa comodines, *
o **
, para responder a los cambios en documentos
que coincidan con un patrón. Un comodín *
coincide con un solo segmento, y un comodín **
de varios segmentos coincide con cero o más segmentos en el patrón.
En el caso de las coincidencias de un solo segmento (*
), también puedes usar un grupo de captura con nombre. Por ejemplo, users/{userId}
.
Por ejemplo:
Patrón | Descripción |
---|---|
/users/* o /users/{userId} |
Coincide con todos los documentos de la colección /users . No coincide con los documentos de subcolecciones como /users/marie/messages/33e2IxYBD9enzS50SJ68 |
/users/** |
Coincide con todos los documentos de la colección /users y los de las subcolecciones, como /users/marie/messages/33e2IxYBD9enzS50SJ68 |
Para obtener más información sobre los patrones de ruta, consulta Patrones de ruta de acceso de Eventarc.
Los activadores siempre deben apuntar a un documento, incluso si usas un comodín.
Por ejemplo, users/{userId=*}/{messageCollectionId=*}
no es válido porque {messageCollectionId=*}
es una colección. Sin embargo, users/{userId=*}/{messageCollectionId}/{messageId=*}
sí
es válido porque {messageId=*}
siempre apunta a un documento.
Funciones de ejemplo
En el siguiente ejemplo, se muestra cómo recibir eventos de Firestore.
Para trabajar con los datos de documentos involucrados en un evento, observa los campos value
y old_value
.
value
: Es un objetoDocument
que contiene una instantánea del documento posterior a la operación. Este campo no se propaga para borrar eventos.old_value
: Es un objetoDocument
que contiene una instantánea del documento previo a la operación. Este campo solo se propaga para los eventos de actualización y eliminación.
Go
Para autenticarte en Firestore, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Java
Para autenticarte en Firestore, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para autenticarte en Firestore, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Usa protobufjs para decodificar los datos del evento. Incluye elgoogle.events.cloud.firestore.v1
data.proto
en tu fuente.
Python
Para autenticarte en Firestore, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
C#
Para autenticarte en Firestore, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
En los siguientes ejemplos, se convierten en mayúsculas las strings agregadas al campo original
de un
documento afectado y se escribe el valor nuevo en el mismo documento:
Go
Para autenticarte en Firestore, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Java
Para autenticarte en Firestore, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para autenticarte en Firestore, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Usa protobufjs para decodificar los datos del evento. Incluye elgoogle.events.cloud.firestore.v1
data.proto
en tu fuente.
Python
Para autenticarte en Firestore, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
C#
Para autenticarte en Firestore, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Incluye las dependencias de proto en tu fuente
Debes incluir el archivo data.proto
de Firestore
en el directorio del código fuente de la función. Este archivo importa los siguientes .protos, que también debes incluir en tu directorio del código fuente:
Usa la misma estructura de directorio para las dependencias. Por ejemplo, coloca struct.proto
dentro de google/protobuf
.
Estos archivos son necesarios para decodificar los datos de eventos. Si la fuente de la función no incluye estos archivos, se mostrará un error cuando se ejecute.
Atributos del evento
Cada evento incluye atributos de datos que incluyen información sobre el evento, como la hora en que se activó. Firestore agrega datos adicionales sobre la base de datos y el documento involucrado en el evento. Puedes acceder a estos atributos de la siguiente manera:
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']}")
Implementa una función
Los usuarios que implementan Cloud Functions deben tener el rol de IAM Cloud Functions Developer o una función que incluya los mismos permisos. Consulta también Configuración adicional para la implementación.
Puedes implementar una función con gcloud CLI o la consola de Google Cloud. En el siguiente ejemplo, se muestra la implementación con gcloud CLI. Para obtener detalles sobre la implementación con la consola de Google Cloud, consulta Implementa Cloud Functions
gcloud
-
En la consola de Google Cloud, activa Cloud Shell.
En la parte inferior de la consola de Google Cloud, se inicia una sesión de Cloud Shell en la que se muestra una ventana de línea de comandos. Cloud Shell es un entorno de shell con Google Cloud CLI ya instalada y con valores ya establecidos para el proyecto actual. La sesión puede tardar unos segundos en inicializarse.
Usa el comando
gcloud functions deploy
para implementar una función: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" \
El primer argumento,
YOUR_FUNCTION_NAME
, es un nombre para tu función implementada. El nombre de la función debe comenzar con una letra seguida de un máximo de 62 letras, números, guiones o guiones bajos, y debe terminar con una letra o un número.La marca
--gen2
especifica que deseas implementar en Cloud Functions (2nd gen). Omitir esta marca da como resultado la implementación en Cloud Functions (1st gen).La marca
--region
especifica la región en la que se implementará la función.Para maximizar la proximidad, establece una región cercana a la base de datos de Firestore. Si la base de datos de Firestore está en una ubicación multirregional, configúrala como
us-central1
para las bases de datos ennam5
y comoeurope-west4
para las bases de datos eneur3
. Para las ubicaciones regionales de Firestore, configúralas en la misma región.La marca
--trigger-location
especifica la ubicación del activador. Debes configurar esta marca en la ubicación de tu base de datos de Firestore.La marca
--runtime
especifica el entorno de ejecución de lenguaje que usa tu función. Cloud Functions admite varios entornos de ejecución. Consulta Entornos de ejecución para obtener más información.La marca
--source
especifica la ubicación del código fuente de tu función. Consulta los siguientes artículos para obtener más detalles:La marca
--entry-point
especifica el punto de entrada a tu función en tu código fuente. Este es el código que se ejecutará cuando se ejecute tu función. El valor de esta marca debe ser un nombre de función o un nombre de clase completamente calificado que exista en tu código fuente. Consulta Punto de entrada de la función para obtener más información.EVENT_FILTER_TYPE
: Firestore admite los siguientes tipos de eventos.google.cloud.firestore.document.v1.created
: El evento se envía cuando se escribe un documento por primera vez.google.cloud.firestore.document.v1.updated
: El evento se envía cuando un documento ya existe y se cambia su valor.google.cloud.firestore.document.v1.deleted
: El evento se envía cuando se borra un documento.google.cloud.firestore.document.v1.written
: El evento se envía cuando se crea, actualiza o borra un documento.google.cloud.firestore.document.v1.created.withAuthContext
: El evento se envía cuando se escribe un documento por primera vez y el evento incluye información de autenticación adicional.google.cloud.firestore.document.v1.updated.withAuthContext
: El evento se envía cuando un documento ya existe y se cambia su valor. Incluye información de autenticación adicionalgoogle.cloud.firestore.document.v1.deleted.withAuthContext
: El evento se envía cuando se borra un documento. Incluye información de autenticación adicionalgoogle.cloud.firestore.document.v1.written.withAuthContext
: El evento se envía cuando se crea, actualiza o borra un documento y genera un evento. Incluye información de autenticación adicional
DATABASE
: la base de datos de Firestore. Para ver el nombre de la base de datos predeterminada, usa(default)
.DOCUMENT
: Es la ruta de la base de datos que activa eventos cuando se crean, actualizan o borran datos. El operador puede ser uno de los siguientes:- Iguales; por ejemplo,
--trigger-event-filters=document='users/marie'
- Patrón de ruta de acceso; por ejemplo,
--trigger-event-filters-path-pattern=document='users/*'
Para obtener más información, consulta Información sobre los patrones de ruta de acceso.
- Iguales; por ejemplo,
De manera opcional, puedes especificar opciones adicionales de configuración, herramientas de redes y seguridad cuando implementes una función.
Para obtener una referencia completa del comando de implementación y sus marcas, consulta la documentación de
gcloud functions deploy
.
Implementaciones de ejemplo
En los siguientes ejemplos, se muestran implementaciones con Google Cloud CLI.
Implementa una función para una base de datos en la región 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}'
Implementa una función para una base de datos en la multirregión 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}'
Limitaciones
Ten en cuenta las siguientes limitaciones para los activadores de Firestore para Cloud Functions:
- 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 mecanismos solo una vez exactos y escribe funciones idempotentes.
- Firestore en modo Datastore requiere Cloud Functions (2nd gen). Cloud Functions (1ª gen.) no es compatible con el modo Datastore.
- Cloud Functions (1st gen) solo funciona con bases de datos “(predeterminadas)” y no es compatible con las bases de datos con nombre de Firestore. Usa Cloud Functions (2nd gen) para configurar eventos para las bases de datos con nombre.
- Un activador se asocia con una sola base de datos. No puedes crear un activador que coincida con varias bases de datos.
- Cuando se borra una base de datos, no se borra automáticamente ningún activador de la base de datos. El activador deja de entregar eventos, pero sigue existiendo hasta que lo borras.
- Si un evento coincidente excede el tamaño máximo de la solicitud, es posible que el evento no se entregue a Cloud Functions (1st gen).
- Los eventos que no se entregan debido al tamaño de la solicitud se registran en los registros de la plataforma y se tienen en cuenta para el uso de registros del proyecto.
- Puedes encontrar estos registros en el Explorador de registros con el mensaje “El evento no se puede entregar a Cloud Function debido a que el tamaño supera el límite de 1ª gen... de gravedad
error
”. Puedes encontrar el nombre de la función en el campofunctionName
. Si el camporeceiveTimestamp
sigue dentro de una hora a partir de ahora, puedes inferir el contenido real del evento leyendo el documento en cuestión con una instantánea antes y después de la marca de tiempo. - Para evitar esa cadencia, puedes hacer lo siguiente:
- Migra y actualiza a Cloud Functions (2nd gen)
- Reducir el tamaño del documento
- Borra la función de Cloud Functions en cuestión
- Puedes desactivar el registro mediante las exclusiones, pero ten en cuenta que los eventos infractores aún no se entregarán.
Ubicaciones de Eventarc y Firestore
Eventarc no admite multirregiones para activadores de eventos de Firestore, pero aún puedes crear activadores para las bases de datos de Firestore en ubicaciones multirregionales. Eventarc asigna ubicaciones multirregionales de Firestore a las siguientes regiones de Eventarc:
Firestore multirregional | Región de Eventarc |
---|---|
nam5 |
us-central1 |
eur3 |
europe-west4 |
Diferencias entre Cloud Functions (2ª gen.) y 1st gen
Cloud Functions (2nd gen) usa eventos de Eventarc para todos los entornos de ejecución. Anteriormente, Cloud Functions (1a gen.) usaba eventos de Eventarc para solo algunos entornos de ejecución. Los eventos de Eventarc introducen las siguientes diferencias con respecto a Cloud Functions (1a gen.).
Los activadores de Firestore para Eventarc admiten destinos adicionales, además de Cloud Functions. Puedes enrutar
CloudEvents
a varios destinos, incluidos, entre otros, Cloud Run, GKE y Workflows.Los activadores de Firestore para Eventarc recuperan la definición del activador al comienzo de una operación de escritura de la base de datos y la usan para decidir si Firestore debe emitir un evento. La operación de escritura no tiene en cuenta ningún cambio en la definición del activador que pueda ocurrir mientras se ejecuta.
Cloud Functions (1st gen) recupera la definición del activador durante la evaluación de la escritura de la base de datos, y los cambios en el activador durante la evaluación pueden afectar si Firestore emite un evento o no.
Para obtener más información, consulta Comparación de versiones de Cloud Functions.