Crea activadores a partir de eventos de Firestore

En esta guía, se incluyen las instrucciones para crear activadores para servicios y funciones de Cloud Run a partir de eventos de Firestore.

Puedes configurar tus servicios de Cloud Run para que se activen con eventos en una base de datos de Firestore. Cuando se activa, tu servicio lee y actualiza una base de datos de Firestore en respuesta a estos eventos a través de las APIs de Firestore y las bibliotecas cliente.

En un ciclo de vida típico, sucede lo siguiente cuando los eventos de Firestore activan un servicio de Cloud Run:

  1. El servicio espera cambios en un documento específico.

  2. Cuando se produce un cambio, se activa el servicio y realiza sus tareas.

  3. El servicio recibe un objeto de datos con una instantánea del documento afectado. En el caso de los eventos write o update, 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

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
google.cloud.firestore.document.v1.created (predeterminada) 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 con datos.
google.cloud.firestore.document.v1.written Se activa cuando se crea, actualiza o borra un documento.

Los comodines se escriben en los activadores con llaves, por ejemplo: projects/YOUR_PROJECT_ID/databases/(default)/documents/collection/{document_wildcard}

Especifica la ruta del documento

Para activar tu servicio, especifica la ruta de acceso del documento que deseas escuchar. La ruta de acceso al documento debe estar en el mismo proyecto Google Cloud que el servicio.

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ón addresses, 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.

  • users/{user=**}: Activador válido. Supervisa todos los documentos del usuario y los documentos de las subcolecciones de cada documento del usuario, como /users/userID/address/home o /users/userID/phone/work.

Comodines y parámetros

Si no conoces el documento específico que quieres 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}. Si tu objetivo es responder también a los eventos en las subcolecciones, usa el comodín de varios segmentos {username=**}.

Las coincidencias de comodines se extraen de las rutas de acceso de documentos. Puedes definir tantos comodines como desees para sustituir los IDs explícitos de colección o documento. Puedes usar hasta un comodín de varios segmentos, como {username=**}.

Estructuras de eventos

Este activador invoca tu servicio con un evento similar al siguiente: 

{
    "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.

Antes de comenzar

  1. Asegúrate de haber configurado un proyecto nuevo para Cloud Run, como se describe en la página de configuración.

  2. Habilita las APIs de Artifact Registry, Cloud Build, Cloud Run Admin, Eventarc, Firestore Cloud Logging y Pub/Sub:

    Habilita las APIs

  3. Otorga los roles y permisos de IAM necesarios.

Roles necesarios para la cuenta del implementador

Para obtener los permisos que necesitas para activar desde eventos de Firestore, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Ten en cuenta que, de forma predeterminada, los permisos de Cloud Build incluyen permisos para subir y descargar artefactos de Artifact Registry.

Configura la base de datos de Firestore

Antes de implementar tu servicio, debes crear una base de datos de Firestore:

  1. Ir a la página Datos de Firestore

  2. Selecciona Crear base de datos.

  3. Haz clic en Modo nativo y, luego, selecciona Continuar.

  4. En el campo Asigna un nombre a tu base de datos, ingresa un ID de base de datos, como firestore-db.

  5. En Tipo de ubicación, selecciona Región y elige la región en la que residirá tu base de datos. Esta elección es permanente.

  6. Deja la sección Reglas seguras tal como está.

  7. Haz clic en Crear base de datos.

El modelo de datos de Firestore consta de colecciones que contienen documentos. Cada documento contiene un conjunto de pares clave-valor.

Crear activadores

Según el tipo de servicio que implementes, puedes hacer lo siguiente:

Crea un activador para los servicios

Después de implementar un servicio, puedes configurar un activador con la consola de Google Cloud , Google Cloud CLI o Terraform.

Console

  1. Implementa tu servicio de Cloud Run con contenedores o desde código fuente.

  2. En la consola de Google Cloud , ve a Cloud Run:

    Ir a Cloud Run

  3. En la lista de servicios, haz clic en un servicio existente.

  4. En la página de detalles del servicio, navega a la pestaña Activadores.

  5. Haz clic en Agregar activador y selecciona Activador de Firestore.

  6. En el panel Activador de Eventarc, modifica los detalles del activador de la siguiente manera:

    1. En el campo Nombre del activador, ingresa un nombre para el activador o usa el nombre predeterminado.

    2. Selecciona un Tipo de activador en la lista para especificar uno de los siguientes tipos de activadores:

      • Fuentes de Google para especificar activadores para Pub/Sub, Cloud Storage, Firestore y otros proveedores de eventos de Google

      • Terceros para integrarte a proveedores externos a Google que ofrecen una fuente de Eventarc. Para obtener más información, consulta Eventos de terceros en Eventarc.

    3. Selecciona Firestore en la lista Proveedor de eventos para seleccionar un producto que proporcione el tipo de evento para activar tu servicio. Para obtener la lista de proveedores de eventos, consulta Proveedores y destinos de eventos.

    4. Selecciona type=google.cloud.firestore.document.v1.created en la lista Tipo de evento. La configuración del activador varía según el tipo de evento compatible. Para obtener más información, consulta Tipos de eventos.

    5. En la sección Filtros, selecciona una base de datos, valores de operación y atributos, o usa las selecciones predeterminadas.

    6. Si el campo Región está habilitado, selecciona una ubicación para el activador de Eventarc. En general, la ubicación de un activador de Eventarc debe coincidir con la ubicación del recurso de Google Cloud que deseas supervisar para detectar eventos. En la mayoría de los casos, también debes implementar tu servicio en la misma región. Consulta Información sobre las ubicaciones de Eventarc para obtener más detalles sobre las ubicaciones de activadores de Eventarc.

    7. En el campo Cuenta de servicio, selecciona una cuenta de servicio. Los activadores de Eventarc están vinculados a cuentas de servicio para usarlos como identidad cuando se invoca el servicio. La cuenta de servicio del activador de Eventarc debe tener permiso para invocar tu servicio. De forma predeterminada, Cloud Run usa la cuenta de servicio predeterminada de Compute Engine.

    8. De manera opcional, especifica la ruta de URL del servicio a la que se enviará la solicitud entrante. Esta es la ruta de acceso relativa en el servicio de destino al que se deben enviar los eventos del activador. Por ejemplo, /, /route, route y route/subroute.

    9. De manera opcional, para habilitar los reintentos si falla el intento de entrega, selecciona la casilla de verificación Habilitar reintento en caso de error. De lo contrario, el comportamiento predeterminado es un solo intento de entrega sin reintentos. Para obtener más información, consulta Eventos de reintento.

    10. Una vez que hayas completado los campos obligatorios, haz clic en Guardar activador.

  7. Después de crear el activador, verifica su estado. Para esto, asegúrate de que haya una marca de verificación en la pestaña Activadores.

gcloud

  1. Implementa tu servicio de Cloud Run con contenedores o desde código fuente.

  2. Ejecuta el siguiente comando para crear un activador que filtre y enrute eventos:

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=LOCATION \
    --destination-run-service=DESTINATION_RUN_SERVICE  \
    --destination-run-region=DESTINATION_RUN_REGION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

    Reemplaza lo siguiente:

    • TRIGGER_NAME: ID del activador o un identificador completamente calificado.
    • LOCATION: la ubicación del activador de Eventarc. De forma alternativa, puedes establecer la propiedad eventarc/location; por ejemplo, gcloud config set eventarc/location us-central1.

      Para evitar problemas de rendimiento y residencia de datos, la ubicación debe coincidir con la ubicación del servicio Google Cloud que genera eventos. Para obtener más información, consulta Ubicaciones de Eventarc.

    • DESTINATION_RUN_SERVICE: el nombre del servicio de Cloud Run que recibe los eventos para el activador. El servicio puede estar en cualquiera de las ubicaciones admitidas de Cloud Run y no es necesario que esté en la misma ubicación que el activador. Sin embargo, el servicio debe estar en el mismo proyecto que el activador y recibirá eventos como solicitudes POST HTTP enviadas a su ruta de URL raíz (/) cada vez que se genere el evento.
    • DESTINATION_RUN_REGION: (opcional) la ubicación de Cloud Run en la que se puede encontrar el servicio de Cloud Run de destino. Si no se especifica, se supone que el servicio se encuentra en la misma región que el activador.
    • EVENT_FILTER_TYPE: el identificador del evento. Se genera un evento cuando una llamada a la API para el método se hace de forma correcta. Para las operaciones de larga duración, el evento solo se genera al final de la operación, y únicamente si la acción se lleva a cabo correctamente. Para obtener una lista de los tipos de eventos compatibles, consulta Tipos de eventos de Google compatibles con Eventarc.
    • SERVICE_ACCOUNT_NAME: el nombre de la cuenta de servicio administrada por el usuario.
    • PROJECT_ID: Es el ID del proyecto de Google Cloud .

    Notas:

    • Después de crear un activador, no se puede cambiar el tipo de filtro de eventos. Para un tipo de evento diferente, debes crear un activador nuevo.
    • --event-filters=type=google.cloud.firestore.document.v1.written especifica que la función se activa cuando se crea, actualiza o borra un documento, según el tipo de evento.
    • --event-filters=database='(default)' especifica la base de datos de Firebase. Para ver el nombre de la base de datos predeterminada, usa (default).
    • --event-filters-path-pattern=document='users/{username}' proporciona el patrón de ruta de acceso de los documentos que deben supervisarse para detectar cambios relevantes. En este patrón de ruta de acceso, se indica que se deben supervisar todos los documentos de la colección users. Para obtener más información, consulta Información sobre los patrones de ruta de acceso.
    • De manera opcional, para especificar un solo intento de entrega de eventos sin reintentos, usa la marca --max-retry-attempts. El único valor válido es 1. Si omites la marca, se aplica el comportamiento de reintento estándar. Para obtener más información, consulta Eventos de reintento.
    • Hay otras marcas disponibles. Para obtener más información, consulta gcloud eventarc triggers create

Terraform

Para crear un activador de Eventarc para un servicio de Cloud Run, consulta Crea un activador con Terraform.

Crea un activador para funciones

Después de implementar una función, puedes configurar un activador con la consola de Google Cloud , Google Cloud CLI o Terraform.

Console

Cuando usas la consola de Google Cloud para crear una función, también puedes agregar un activador a tu función. Sigue estos pasos para crear un activador para tu función:

  1. En la consola Google Cloud , ve a Cloud Run:

    Ir a Cloud Run

  2. Haz clic en Escribir una función y, luego, ingresa los detalles de la función. Para obtener más información sobre la configuración de funciones durante la implementación, consulta Implementa funciones.

  3. En la sección Activador, haz clic en Agregar activador.

  4. Selecciona Activador de Firestore.

  5. En el panel Activador de Eventarc, modifica los detalles del activador de la siguiente manera:

    1. Ingresa un nombre para el activador en el campo Nombre del activador o usa el nombre predeterminado.

    2. Selecciona un tipo de activador de la lista:

      • Fuentes de Google para especificar activadores para Pub/Sub, Cloud Storage, Firestore y otros proveedores de eventos de Google

      • Terceros para integrarte a proveedores externos a Google que ofrecen una fuente de Eventarc. Para obtener más información, consulta Eventos de terceros en Eventarc.

    3. Selecciona Firestore en la lista Proveedor de eventos para seleccionar un producto que proporcione el tipo de evento para activar tu función. Para obtener la lista de proveedores de eventos, consulta Proveedores y destinos de eventos.

    4. Selecciona type=google.cloud.firestore.document.v1.created en la lista Tipo de evento. La configuración del activador varía según el tipo de evento compatible. Para obtener más información, consulta Tipos de eventos.

    5. En la sección Filtros, selecciona una base de datos, valores de operación y atributos, o usa las selecciones predeterminadas.

    6. Si el campo Región está habilitado, selecciona una ubicación para el activador de Eventarc. En general, la ubicación de un activador de Eventarc debe coincidir con la ubicación del recurso deGoogle Cloud que deseas supervisar para detectar eventos. En la mayoría de los casos, también debes implementar tu función en la misma región. Consulta Información sobre las ubicaciones de Eventarc para obtener más detalles sobre las ubicaciones de activadores de Eventarc.

    7. En el campo Cuenta de servicio, selecciona una cuenta de servicio. Los activadores de Eventarc están vinculados a cuentas de servicio para usarlos como identidad cuando se invoca la función. La cuenta de servicio del activador de Eventarc debe tener permiso para invocar tu función. De forma predeterminada, Cloud Run usa la cuenta de servicio predeterminada de Compute Engine.

    8. De manera opcional, especifica la ruta de URL del servicio a la que se enviará la solicitud entrante. Esta es la ruta de acceso relativa en el servicio de destino al que se deben enviar los eventos del activador. Por ejemplo, /, /route, route y route/subroute.

    9. De manera opcional, para habilitar los reintentos si falla el intento de entrega, selecciona la casilla de verificación Habilitar reintento en caso de error. De lo contrario, el comportamiento predeterminado es un solo intento de entrega sin reintentos. Para obtener más información, consulta Eventos de reintento.

  6. Una vez que hayas completado los campos obligatorios, haz clic en Guardar activador.

  7. Haz clic en Crear.

  8. En la pestaña Fuente, edita el código fuente si es necesario y, luego, selecciona Guardar y volver a implementar.

gcloud

Cuando creas una función con la gcloud CLI, primero debes implementarla y, luego, crear un activador. Sigue estos pasos para crear un activador para tu función:

  1. Ejecuta el siguiente comando en el directorio que contiene el código de muestra para implementar tu función:

    gcloud run deploy FUNCTION \
    --source . \
    --function FUNCTION_ENTRYPOINT \
    --base-image BASE_IMAGE_ID \
    --region REGION

    Reemplaza lo siguiente:

    • FUNCTION: Es el nombre de la función que implementas. Puedes omitir este parámetro por completo, pero se te solicitará el nombre si lo haces.

    • FUNCTION_ENTRYPOINT: el punto de entrada a tu función en tu código fuente. Este es el código que ejecuta Cloud Run cuando se ejecuta 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.

    • BASE_IMAGE_ID: Es el entorno de imagen base para tu función. Para obtener más detalles sobre las imágenes base y los paquetes incluidos en cada imagen, consulta Imágenes base de los tiempos de ejecución.

    • REGION: la Google Cloud región en la que deseas implementar tu función. Por ejemplo, europe-west1.

  2. Ejecuta el siguiente comando para crear un activador que filtre y enrute eventos:

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=LOCATION \
    --destination-run-service=FUNCTION  \
    --destination-run-region=DESTINATION_RUN_REGION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

    Reemplaza lo siguiente:

    • TRIGGER_NAME: ID del activador o un identificador completamente calificado.
    • LOCATION: la ubicación del activador de Eventarc. De forma alternativa, puedes establecer la propiedad eventarc/location; por ejemplo, gcloud config set eventarc/location us-central1.

      Para evitar problemas de rendimiento y residencia de datos, la ubicación debe coincidir con la ubicación del servicio Google Cloud que genera eventos. Para obtener más información, consulta Ubicaciones de Eventarc.

    • FUNCTION: Es el nombre de la función de Cloud Run implementada que recibe los eventos para el activador.
    • DESTINATION_RUN_REGION: (opcional) la ubicación de Cloud Run en la que se puede encontrar la función de Cloud Run de destino. Si no se especifica, se supone que la función se encuentra en la misma región que el activador.
    • EVENT_FILTER_TYPE: el identificador del evento. Se genera un evento cuando una llamada a la API para el método se hace de forma correcta. Para las operaciones de larga duración, el evento solo se genera al final de la operación, y únicamente si la acción se lleva a cabo correctamente. Para obtener una lista de los tipos de eventos compatibles, consulta Tipos de eventos de Google compatibles con Eventarc.
    • SERVICE_ACCOUNT_NAME: el nombre de la cuenta de servicio administrada por el usuario.
    • PROJECT_ID: Es el ID del proyecto de Google Cloud .

    Notas:

    • Después de crear un activador, no se puede cambiar el tipo de filtro de eventos. Para un tipo de evento diferente, debes crear un activador nuevo.
    • --event-filters=type=google.cloud.firestore.document.v1.written especifica que la función se activa cuando se crea, actualiza o borra un documento, según el tipo de evento.
    • --event-filters=database='(default)' especifica la base de datos de Firebase. Para ver el nombre de la base de datos predeterminada, usa (default).
    • --event-filters-path-pattern=document='users/{username}' proporciona el patrón de ruta de acceso de los documentos que deben supervisarse para detectar cambios relevantes. En este patrón de ruta de acceso, se indica que se deben supervisar todos los documentos de la colección users. Para obtener más información, consulta Información sobre los patrones de ruta de acceso.
    • De manera opcional, para especificar un solo intento de entrega de eventos sin reintentos, usa la marca --max-retry-attempts. El único valor válido es 1. Si omites la marca, se aplica el comportamiento de reintento estándar. Para obtener más información, consulta Eventos de reintento.
    • Hay otras marcas disponibles. Para obtener más información, consulta gcloud eventarc triggers create

Terraform

Para crear un activador de Eventarc para una función de Cloud Run, consulta Crea un activador con Terraform.

Consulta Extiende Firestore con activadores de eventos usando Cloud Run Functions para obtener más información.

¿Qué sigue?

  • Consulta ejemplos de funciones que se activan cuando realizas cambios en un documento dentro de una colección especificada.