Crea activadores con Firestore

En esta guía, se incluyen las instrucciones para crear activadores para los servicios y las 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, ocurre lo siguiente cuando un servicio de Cloud Run se activa con eventos de Firestore:

  1. El servicio espera a que ocurran cambios en un documento en particular.

  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 una ruta de acceso al documento que deseas escuchar. La ruta de acceso al documento debe estar en el mismo proyecto de 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 particular 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, Cloud Logging de Firestore y Pub/Sub:

    Habilita las APIs

Roles obligatorios

  1. Si eres el creador del proyecto, se te otorga el rol de propietario básico (roles/owner). De forma predeterminada, este rol de Identity and Access Management (IAM) incluye los permisos necesarios para obtener acceso completo a la mayoría de los recursos de Google Cloud, pero puedes omitir este paso.

    Si no eres el creador del proyecto, se deben otorgar los permisos necesarios en el proyecto a la principal correspondiente. Por ejemplo, una principal puede ser una Cuenta de Google (para usuarios finales) o una cuenta de servicio (para aplicaciones y cargas de trabajo de procesamiento). Para obtener más información, consulta la página Roles y permisos para el destino del evento.

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

    Permisos necesarios

    Para obtener los permisos que necesitas para configurar activadores 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 mediante roles personalizados o cualquier otro rol predefinido.

  2. Toma nota del recurso Compute Engine predeterminada, ya que la conectarás a un activador de Eventarc para representar la identidad del activador con fines de prueba. Esta cuenta de servicio se crea automáticamente después de habilitar o usar un servicio de Google Cloud que use Compute Engine, y con la siguiente formato de correo electrónico:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Reemplaza PROJECT_NUMBER por el número de proyecto de Google Cloud. Para encontrar el número del proyecto, ve a la página de bienvenida de la consola de Google Cloud o ejecuta el siguiente comando:

    gcloud projects describe PROJECT_ID --format='value(projectNumber)'

    Para entornos de producción, recomendamos crear una cuenta de servicio nueva y otorgarle una o más funciones de IAM que contengan los permisos mínimos requeridos y seguir el principio de privilegio mínimo.

  3. De forma predeterminada, solo los propietarios y los editores del proyecto, y los administradores y los invocadores de Cloud Run pueden llamar a los servicios de Cloud Run. Puedes controlar el acceso según el servicio. Sin embargo, para fines de prueba, otorga el rol de invocador de Cloud Run (run.invoker) en el proyecto de Google Cloud a la cuenta de servicio de Compute Engine. Esto otorga el rol en todos los servicios y trabajos de Cloud Run en un proyecto. 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/run.invoker

    Ten en cuenta que si creas un activador para un servicio autenticado de Cloud Run sin otorgar la función de invocador de Cloud Run, el activador se crea de forma correcta y está activo. Sin embargo, el activador no funcionará como se espera y aparecerá en el registro un mensaje similar al siguiente:

    The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
  4. Otorga el rol de receptor de eventos de Eventarc (roles/eventarc.eventReceiver) en el proyecto a la cuenta de servicio predeterminada de Compute Engine para que el activador de Eventarc pueda recibir eventos de proveedores de eventos. 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/eventarc.eventReceiver
  5. Si habilitaste el agente de servicio de Cloud Pub/Sub el 8 de abril de 2021 o antes de esa fecha, para admitir las solicitudes de envío de Pub/Sub autenticadas, otorga el rol de creador de tokens de cuenta de servicio (roles/iam.serviceAccountTokenCreator) al agente de servicio. De lo contrario, este rol se otorga de forma predeterminada: 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator

Configura la base de datos de Firestore

Antes de implementar el 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

Puedes especificar un activador después de implementar un servicio.

Haz clic en la pestaña para obtener instrucciones de la herramienta que elijas.

Console

  1. Implementa tu servicio de Cloud Run con contenedores o desde la 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 de la lista para especificar uno de los siguientes tipos de activador:

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

      • Terceros para integrarse 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 elegir un producto que proporcione el tipo de evento para activar tu servicio. Para ver 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, una operación y valores de atributos, o bien 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 el 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. 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 la fuente.

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

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=EVENTARC_TRIGGER_LOCATION \
    --destination-run-service=SERVICE  \
    --destination-run-region=REGION \
    --event-filters="type=google.cloud.firestore.document.v1.created" \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Reemplaza lo siguiente:

    • TRIGGER_NAME por el nombre de tu activador.

    • EVENTARC_TRIGGER_LOCATION con la ubicación del 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. Para obtener más información, consulta Ubicaciones de Eventarc.

    • Reemplaza SERVICE por el nombre del servicio que implementas.

    • REGION por la región de Cloud Run del servicio

    • PROJECT_NUMBER por tu número de proyecto de Google Cloud Los activadores de Eventarc están vinculados a cuentas de servicio para usarlos como identidad cuando se invoca tu 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 de procesamiento predeterminada.

    • La marca event-filters especifica los filtros de eventos que supervisa el activador. Un evento que coincida con todos los filtros event-filters activa llamadas a tu servicio. Cada activador debe tener un tipo de evento compatible. No puedes cambiar el tipo de filtro de eventos después de crearlo. Para cambiar el tipo de filtro de eventos, debes crear un activador nuevo y borrar el anterior. De forma opcional, puedes repetir la marca --event-filters con un filtro compatible en el formato ATTRIBUTE=VALUE para agregar más filtros.

Crea un activador para funciones

Haz clic en la pestaña para obtener instrucciones de la herramienta que elijas.

Console

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

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

    Ir a Cloud Run

  2. Haz clic en Escribe 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 Cómo implementar 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 para especificar uno de los siguientes tipos de activador:

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

      • Terceros para integrarse 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 elegir un producto que proporcione el tipo de evento para activar tu función. Para ver 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, una operación y valores de atributos, o bien 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 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 el 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.

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

gcloud

Cuando creas una función con gcloud CLI, primero debes deploy 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 la función:

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

    Reemplaza lo siguiente:

    • Reemplaza FUNCTION por 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 por 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 por el entorno de la imagen base de 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 entornos de ejecución.

    • REGION por la región de Google Cloud en la que deseas implementar tu función. Por ejemplo, us-central1.

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

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=EVENTARC_TRIGGER_LOCATION \
    --destination-run-service=FUNCTION  \
    --destination-run-region=REGION \
    --event-filters="type=google.cloud.firestore.document.v1.created" \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Reemplaza lo siguiente:

    • TRIGGER_NAME por el nombre de tu activador.

    • EVENTARC_TRIGGER_LOCATION con la ubicación del 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 función en la misma región. Para obtener más información, consulta Ubicaciones de Eventarc.

    • Reemplaza FUNCTION por el nombre de la función que implementas.

    • REGION por la región de Cloud Run de la función.

    • PROJECT_NUMBER por tu número de proyecto de Google Cloud 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 de procesamiento predeterminada.

    • La marca event-filters especifica los filtros de eventos que supervisa el activador. Un evento que coincida con todos los filtros event-filters activa llamadas a tu función. Cada activador debe tener un tipo de evento compatible. No puedes cambiar el tipo de filtro de eventos después de crearlo. Para cambiar el tipo de filtro de eventos, debes crear un activador nuevo y borrar el anterior. De forma opcional, puedes repetir la marca --event-filters con un filtro compatible en el formato ATTRIBUTE=VALUE para agregar más filtros.

¿Qué sigue?

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