Con Cloud Run Functions y Eventarc, puedes implementar código en Administrar eventos activados por cambios en tu base de datos de Firestore en modo Datastore Esta te permite agregar funcionalidad del lado del servidor sin ejecutar tus propios servidores.
Activadores del modo Datastore
Eventarc admite el siguiente evento de Firestore en modo Datastore para crear controladores de funciones de Cloud Run (2ª gen..) vinculados Eventos de Firestore en modo Datastore:
Tipo de evento | Activador |
---|---|
google.cloud.datastore.entity.v1.created |
Se activa cuando se escribe una entidad por primera vez. |
google.cloud.datastore.entity.v1.updated |
Se activa cuando una entidad ya existe y cambia algún valor. |
google.cloud.datastore.entity.v1.deleted |
Se activa cuando se borra una entidad. |
google.cloud.datastore.entity.v1.written |
Se activa con created , updated o deleted . |
google.cloud.datastore.entity.v1.created.withAuthContext |
Es igual que created , pero agrega información de autenticación. |
google.cloud.datastore.entity.v1.updated.withAuthContext |
Es igual que updated , pero agrega información de autenticación. |
google.cloud.datastore.entity.v1.deleted.withAuthContext |
Es igual que deleted , pero agrega información de autenticación. |
google.cloud.datastore.entity.v1.written.withAuthContext |
Es igual que written , pero agrega información de autenticación. |
Los activadores de eventos del modo Datastore solo responden a los cambios de entidad. Una actualización de una entidad del modo Datastore en la que los datos no cambia (una escritura no-op) no genera un evento de actualización ni de escritura. Tú no puede generar eventos solo para propiedades específicas.
Incluye el contexto de autenticación en el evento
Para incluir información de autenticación adicional sobre el evento, usa un
activador con la extensión withAuthContext
. Esta extensión agrega funciones adicionales
información sobre la principal que activó el evento. Agrega la
los atributos authtype
y authid
, además de la información que se muestra en
el evento base. Consulta la
Consulta la referencia de authcontext
para obtener más información sobre los valores de los atributos.
Escribe una función activada por entidad
Para escribir una función que responda a los eventos de Firestore en modo Datastore, sigue estos pasos: prepare para especificar lo siguiente durante la implementación:
- un tipo de evento activador
- Un filtro de evento activador para seleccionar las entidades asociadas con la función
- el código de la función para ejecutar
Filtros de eventos del activador
Cuando especificas un filtro de eventos, puedes indicar una entidad exacta
coincidencia o un patrón de ruta de acceso. Usa un patrón de ruta de acceso para hacer coincidir varias entidades con
los comodines *
o **
.
Por ejemplo, puedes especificar una coincidencia de entidad exacta para responder a los cambios en el siguiente entidad:
users/marie
Usa comodines, *
o **
, para responder a los cambios en las entidades
que coinciden con un patrón. El comodín *
coincide con un solo segmento.
El comodín de varios segmentos **
coincide con cero o más segmentos en el patrón.
Para las coincidencias de segmento único (*
), también puedes usar un grupo de captura con nombre, como
como users/{userId}
.
En la siguiente tabla, se muestran patrones de ruta de acceso válidos:
Patrón | Descripción |
---|---|
users/* o users/{userId} |
Coincide con todas las entidades de tipo users . No coincide con el nivel de entidades subordinadas, como /users/marie/messages/33e2IxYBD9enzS50SJ68 |
users/** |
Coincide con todas las entidades de tipo users y con todas las entidades subordinadas, como
/users/marie/messages/33e2IxYBD9enzS50SJ68 |
Para obtener más información sobre los patrones de ruta, consulta Patrones de ruta de Eventarc.
Los activadores siempre deben apuntar a una entidad, incluso si usas un comodín. Consulta los ejemplos siguientes:
users/{userId=*}/{messages=*}
no es válido porque{messages=*}
es un ID de tipo.users/{userId=*}/{messages}/{messageId=*}
es válido porque{messageId=*}
siempre apunta a una entidad.
Escapa de caracteres
En esta sección, se describen situaciones que requieren escapar caracteres en los IDs de tipos y de entidades. El escape de un carácter permite que el evento se filtre correctamente interpretar el ID.
Si un ID de tipo o de entidad incluye un carácter
~
o/
, debes el ID en el filtro de eventos. Para escapar un ID, usa el formato__escENCODED_ID__
Reemplaza ENCODED_ID por un ID de tipo o de entidad que tenga todos los~
y Se reemplazaron los caracteres/
por sus ID de codificación, que son los siguientes:~
:~0
/
:~1
Por ejemplo, el ID de tipo
user/profile
se convierte en__escusers~1profile__
. Los ejemplo de patrón de ruta de acceso con este ID de tipo es__escusers~1profile__/{userId}
Si usas el ID de tipo o de entidad de
.
o..
en tu filtro de eventos, debes escapar el ID de la siguiente manera:.
:__esc~2__
..
:__esc~2~2__
Debes escapar el carácter
.
solo si el ID es exactamente.
o..
. Por ejemplo, el ID de tipocustomers.info
no requiere escape.Si tu tipo o ID de entidad es un valor numérico en lugar de un valor de cadena, debes escapar el ID con
__idNUMERIC_VALUE__
. Por ejemplo, el patrón de ruta de acceso para una entidad de tipo111
y el ID de entidad222
es__id111__/__id222__
.Si migraste desde Cloud Datastore heredado a Firestore en modo Datastore, es posible que tu base de datos contenga IDs heredados con una codificación que no sea UTF8. Debes escapar estos ID con
__bytesBASE64_ENCODING__
. Reemplaza BASE64_ENCODING por la codificación en base64 del ID. Para Por ejemplo, el patrón de rutaTask/{task}
con escape para un ID de tipo que no sea UTF8.Task
se convierte en__bytesVGFzaw==__/{task}
.
Funciones de ejemplo
En el siguiente ejemplo, se muestra cómo recibir eventos del modo Datastore.
Para trabajar con los datos involucrados en un evento, consulta value
y
old_value
campos.
value
: Es un objetoEntityResult
que contiene una instantánea de la entidad posterior a la operación. Este campo no se completa para los eventos de eliminación.old_value
: Es un objetoEntityResult
que contiene una entidad de operación previa. instantánea. Este campo solo se propaga para los eventos de actualización y eliminación.
Java
Para obtener información sobre cómo instalar y usar la biblioteca cliente del modo Datastore, consulta Bibliotecas cliente del modo Datastore Para obtener más información, consulta la API de Java modo Datastore documentación de referencia.
Para autenticarte en el modo Datastore, 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 proto en tu código fuente
Debes incluir el modo Datastoredata.proto
en el directorio del código fuente de tu función. Este archivo importa lo siguiente
.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
en google/protobuf
.
Estos archivos son necesarios para decodificar los datos de eventos. Si la fuente de tu función no si no incluyes estos archivos, se muestra un error cuando se ejecuta.
Atributos del evento
Cada evento incluye atributos de datos. que incluyen información sobre el evento, como la hora en que se activó. Firestore en modo Datastore agrega datos adicionales sobre la base de datos y la entidad. participan en el evento. Puedes acceder a estos atributos de la siguiente manera:
Java
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 namespace: " + event.getExtension("namespace")); logger.info("Database entity: " + event.getExtension("entity")); // For withAuthContext events logger.info("Auth information: " + event.getExtension("authid")); logger.info("Auth information: " + event.getExtension("authtype"));
Implementa una función
Los usuarios que implementan Cloud Run Functions deben tener las Desarrollador de funciones de Cloud Run un rol de IAM o uno 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 con gcloud CLI. Para más detalles sobre la implementación con la consola de Google Cloud, consulta Implementa funciones de Cloud Run.
-
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.
Usa el comando
gcloud functions deploy
para implementar una función:gcloud functions deploy FUNCTION_NAME \ --gen2 \ --region=FUNCTION_LOCATION \ --trigger-location=TRIGGER_LOCATION \ --runtime=RUNTIME \ --source=SOURCE_LOCATION \ --entry-point=CODE_ENTRYPOINT \ --trigger-event-filters="type=EVENT_FILTER_TYPE" \ --trigger-event-filters="database=DATABASE" \ --trigger-event-filters="namespace=NAMESPACE" \ --trigger-event-filters-path-pattern="entity=ENTITY_OR_PATH" \
El primer argumento, 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. Reemplaza FUNCTION_NAME por un valor válido el nombre de la función. Luego, agrega las siguientes marcas:
La marca
--gen2
especifica que quieres implementar las funciones de Cloud Run (2ª gen..). Omitir esta marca da como resultado la implementación en Cloud Run Functions (1a gen.).La marca
--region=FUNCTION_LOCATION
especifica la región en la que se implementará la función.Para maximizar la proximidad, establece FUNCTION_LOCATION en una región cercana tu base de datos de Firestore. Si tu base de datos de Firestore está en una ubicación multirregional, establece el valor en
us-central1
para las bases de datos ennam5
y aeurope-west4
para las bases de datos eneur3
. Para regiones Ubicaciones de Firestore, configuradas en la misma región.La
--trigger-location=TRIGGER_LOCATION
marca especifica la ubicación del activador. Debes configurar TRIGGER_LOCATION en la ubicación de tu base de datos en modo Datastore.La marca
--runtime=RUNTIME
especifica el entorno de ejecución de lenguaje que usa tu función. Funciones de Cloud Run admite varios entornos de ejecución. Consulta Entornos de ejecución para obtener más información. Configura RUNTIME en un entorno de ejecución compatible.La marca
--source=SOURCE_LOCATION
especifica la ubicación del código fuente de tu función. Consulta lo siguiente para conocer los detalles:- Implementa desde tu máquina local
- Implementa desde Cloud Storage
- Implementa desde un repositorio de código fuente
Establece SOURCE_LOCATION en la ubicación del código fuente de la función.
La marca
--entry-point=CODE_ENTRYPOINT
especifica el punto de entrada a tu función en tu código fuente. Este es el código que tu función ejecuta cuando se ejecuta. Debes establecer CODE_ENTRYPOINT por un nombre de función o una clase completamente calificada que existe en tu código fuente. Consulta Punto de entrada de función para más información.La
--trigger-event-filters
Las marcas definen el filtro de eventos, que incluye el tipo de activador y la entidad. o la ruta de acceso que activa los eventos. Configura los siguientes valores de atributos para definir tu filtro de eventos:type=EVENT_FILTER_TYPE
: Firestore admite los siguientes tipos de eventos:google.cloud.datastore.entity.v1.created
: El evento se envía cuando un se escribe por primera vez.google.cloud.datastore.entity.v1.updated
: El evento se envía cuando un ya existe y su valor cambió.google.cloud.datastore.entity.v1.deleted
: El evento se envía cuando un el estado de la entidad.google.cloud.datastore.entity.v1.written
: El evento se envía cuando un se crea, actualiza o borra la entidad.google.cloud.datastore.entity.v1.created.withAuthContext
: el evento se envió. Cuando se escribe un documento por primera vez y el evento incluye información de autenticación adicionalgoogle.cloud.datastore.entity.v1.updated.withAuthContext
: el evento se envió. Cuando un documento ya existe y se modifica uno de sus valores. Incluye información de autenticación adicionalgoogle.cloud.datastore.entity.v1.deleted.withAuthContext
: el evento se envió. cuando se borra un documento. Incluye información de autenticación adicionalgoogle.cloud.datastore.entity.v1.written.withAuthContext
: el evento se envió. cuando se crea, actualiza o borra un documento. Incluye información de autenticación adicional
Establece EVENT_FILTER_TYPE en uno de estos tipos de eventos.
database=DATABASE
: la base de datos de Firestore. Para el nombre predeterminado de la base de datos, establece DATABASE en(default)
.namespace=NAMESPACE
: Es la base de datos. namespace. Para la configuración predeterminada nombre de la base de datos, establece NAMESPACE en(default)
. Quitar la bandera para que coincida con cualquier espacio de nombres.entity=ENTITY_OR_PATH
: Es la ruta de acceso de la base de datos que activa eventos cuando se crean, actualizan o borrar. Los valores aceptados para ENTITY_OR_PATH son los siguientes:- Iguales; por ejemplo,
--trigger-event-filters="entity='users/marie'"
- Patrón de ruta de acceso; por ejemplo,
--trigger-event-filters-path-pattern="entity='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-datastore-node \
--gen2 \
--region=us-west2 \
--trigger-location=us-west2 \
--runtime=nodejs18 \
--source=gs://example_bucket-1/datastoreEventFunction.zip \
--entry-point=makeUpperCase \
--trigger-event-filters=type=google.cloud.datastore.entity.v1.written \
--trigger-event-filters=database='(default)' \
--trigger-event-filters-path-pattern="entity='messages/{pushId}'"
Implementa una función para una base de datos en la multirregión nam5
:
gcloud functions deploy gcfv2-trigger-datastore-python \
--gen2 \
--region=us-central1 \
--trigger-location=nam5 \
--runtime=python311 \
--source=gs://example_bucket-1/datastoreEventFunction.zip \
--entry-point=make_upper_case \
--trigger-event-filters=type=google.cloud.datastore.entity.v1.written.withAuthContext \
--trigger-event-filters=database='(default)' \
--trigger-event-filters-path-pattern="entity='messages/{pushId}'"
Limitaciones
Ten en cuenta las siguientes limitaciones de los activadores de Firestore para las funciones de Cloud Run:
- Las funciones de Cloud Run (1a gen.) son requisitos previos de una instancia “(predeterminada) existente en modo nativo de Firestore. No admite bases de datos con nombre de Firestore ni modo Datastore. Usa Cloud Run Functions (2ª gen..) para configurar eventos en esos casos.
- 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 exactamente una vez y escribe funciones idempotentes.
- Firestore en modo Datastore requiere Cloud Run Functions (2ª gen..). Cloud Run Functions (1a gen.) no admite el modo Datastore.
- 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 supera el tamaño máximo de solicitud, el
es posible que no se entregue a las funciones de Cloud Run (1a gen.).
- Los eventos que no se entregaron debido al tamaño de la solicitud se registran en los registros de la plataforma y se consideran en 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
todavía está dentro de una hora a partir de ahora, puedes inferir el contenido real del evento si lees 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 Run Functions (2ª gen..)
- Reducir el tamaño del documento
- Borrar las funciones de Cloud Run en cuestión
- Puedes desactivar el registro con exclusiones, pero ten en cuenta que los eventos problemáticos aún no se entregarán.
Ubicaciones de Eventarc y Firestore en modo Datastore
Eventarc no es compatible con multirregiones para eventos de Firestore pero aún puedes crear activadores para las bases de datos de Firestore en ubicaciones multirregionales. Eventarc asigna Firestore ubicaciones multirregionales a las siguientes regiones de Eventarc:
Firestore multirregional | Región de Eventarc |
---|---|
nam5 |
us-central1 |
eur3 |
europe-west4 |
¿Qué sigue?
- Obtén más información sobre las arquitecturas controladas por eventos.
- Consulta las muestras de código para el modo Datastore.