Dirigir eventos de Cloud Firestore a Cloud Run

Consola

1. En la Google Cloud consola, en la página del selector de proyectos, selecciona o crea un Google Cloud proyecto.

   Ir al selector de proyectos

2. Habilita las APIs Cloud Logging, Eventarc y Eventarc Publishing.

   Habilita las APIs

3. Si procede, habilita la API relacionada con los eventos directos. Por ejemplo, para los eventos de Cloud Firestore , habilita la APICloud Firestore .

4. Si aún no tienes una, crea una cuenta de servicio gestionada por el usuario y, a continuación, concédele los roles y permisos necesarios para que Eventarc pueda gestionar eventos de tu servicio de destino.

   1. En la Google Cloud consola, ve a la página Crear cuenta de servicio.

      Ir a Crear cuenta de servicio

   2. Selecciona el proyecto.

   3. En el campo Nombre de cuenta de servicio, escribe un nombre. La Google Cloud consola rellena el campo ID de cuenta de servicio con este nombre.

      En el campo Descripción de la cuenta de servicio, escribe una descripción. Por ejemplo, Service account for event trigger.

   4. Haz clic en Crear y continuar.

   5. Para proporcionar el acceso adecuado, en la lista Selecciona un rol, elige los roles de gestión de identidades y accesos (IAM) que quieras asignar a tu cuenta de servicio para las invocaciones autenticadas o no autenticadas. Para obtener más información, consulta Roles y permisos para destinos de Cloud Run.

      Para añadir más roles, haz clic en add Añadir otro rol y añade cada rol adicional.

   6. Haz clic en Continuar.

   7. Para terminar de crear la cuenta, haga clic en Hecho.

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   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.

2. Habilita las APIs Cloud Logging, Eventarc y Eventarc Publishing.

   gcloud services enable logging.googleapis.com \
     eventarc.googleapis.com \
     eventarcpublishing.googleapis.com

3. Si procede, habilita la API relacionada con los eventos directos. Por ejemplo, para los eventos, habilita Cloud Firestore .firestore.googleapis.com

4. Si aún no tienes una, crea una cuenta de servicio gestionada por el usuario y, a continuación, concédele los roles y permisos necesarios para que Eventarc pueda gestionar eventos de tu servicio de destino.

   1. Crea la cuenta de servicio:

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      Sustituye SERVICE_ACCOUNT_NAME por el nombre de la cuenta de servicio. Debe tener entre 6 y 30 caracteres, y puede contener caracteres alfanuméricos en minúscula y guiones. Una vez que hayas creado una cuenta de servicio, no podrás cambiar su nombre.

   2. Concede los roles o permisos de gestión de identidades y accesos necesarios para las invocaciones autenticadas o no autenticadas. Para obtener más información, consulta Roles y permisos para destinos de Cloud Run.

Consola

1. En la Google Cloud consola, ve a la página Triggers (Activadores) de Eventarc.

   Ir a Activadores

2. Haz clic en add_box Crear activador.
3. Escribe un Nombre del activador.

   Es el ID del activador y debe empezar por una letra. Puede contener hasta 63 letras minúsculas, números o guiones.

4. En Tipo de activador, selecciona Fuentes de Google.
5. En la lista Event provider (Proveedor de eventos), seleccione Cloud Firestore.

   Tenga en cuenta que el nombre del proveedor de eventos que se usa en la documentaciónGoogle Cloud asociada puede no tener el prefijo Cloud o Google Cloud. Por ejemplo, en la consola, Memorystore para Redis se denomina Google Cloud Memorystore para Redis.

6. En la lista Tipo de evento, en los eventos Direct (Directos), selecciona un tipo de evento.
7. En la lista Tipo de contenido de datos de evento, seleccione la codificación de la carga útil del evento.

   En el caso de los eventos directos de Cloud Firestore, el valor debe ser application/protobuf y los datos del evento deben ser una matriz de bytes. Para obtener más información sobre los mensajes protobuf de los eventos de Cloud Firestore, consulte Eventos comunes.

8. En la lista Región, selecciona la misma región que el Google Cloud servicio que genera eventos.

   Para obtener más información, consulta Ubicaciones de Eventarc.

9. Si procede, haga clic en Añadir filtro y especifique lo siguiente:
   1. En el campo Atributo 1, en función del evento directo que haya elegido, seleccione un ID de recurso que pueda actuar como filtro de eventos.
   2. Selecciona un operador:
      • Igual
      • Patrón de ruta: aplicable a los recursos document (modo nativo) y entity (modo de Datastore). Usa comodines para responder a los cambios 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 del patrón. No especifiques una barra inicial. Por ejemplo:

        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 con los documentos de las subcolecciones, como /users/marie/messages/33e2IxYBD9enzS50SJ68.

        Para obtener más información, consulta Información sobre los patrones de ruta.

   3. En el campo Valor del atributo 1, en función del operador que haya elegido, escriba el valor exacto o aplique un patrón de ruta.
   4. Si se pueden aplicar más filtros de atributos, haz clic en Añadir filtro y especifica los valores correspondientes.
10. Selecciona la cuenta de servicio que invocará tu servicio o flujo de trabajo.

    También puedes crear una cuenta de servicio.

    Especifica la dirección de correo de la cuenta de servicio de Gestión de Identidades y Accesos (IAM) asociada al activador y a la que has concedido roles específicos necesarios para Eventarc.

11. En la lista Destino del evento, selecciona Cloud Run.
12. Selecciona un servicio.
    

    Es el nombre del servicio que recibe los eventos del activador. El servicio debe estar en el mismo proyecto que el activador y recibirá eventos como solicitudes HTTP POST enviadas a la ruta de la URL raíz (/) cada vez que se genere el evento.

13. También puede especificar la ruta de URL del servicio a la que se enviará la solicitud entrante.

    Es la ruta relativa del servicio de destino al que se deben enviar los eventos del activador. Por ejemplo: /, /route, route, route/subroute.

14. Si quieres añadir una etiqueta, puedes hacer clic en add Añadir etiqueta. Las etiquetas son pares clave-valor que te ayudan a organizar tus recursosGoogle Cloud . Para obtener más información, consulta ¿Qué son las etiquetas?
15. Haz clic en Crear.

Una vez creado un activador, no se pueden modificar los filtros de origen de eventos. En su lugar, cree un nuevo activador y elimine el antiguo. Para obtener más información, consulta Gestionar activadores.

gcloud

Para crear un activador, ejecuta un comando gcloud eventarc triggers create junto con las marcas obligatorias y opcionales.

Las marcas varían en función de si usas Firestore en modo nativo o en modo de almacén de datos. Para obtener más información, consulta Escoger el modo nativo o el de Datastore.

Modo nativo

gcloud eventarc triggers create TRIGGER \
    --location=LOCATION \
    --destination-run-service=DESTINATION_RUN_SERVICE \
    --destination-run-region=DESTINATION_RUN_REGION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --event-filters="database=DATABASE" \
    --event-filters="namespace=NAMESPACE" \
    --event-filters-path-pattern="document=DOCUMENT" \
    --event-data-content-type="EVENT_DATA_CONTENT_TYPE" \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com"

Modo de Datastore

gcloud eventarc triggers create TRIGGER \
    --location=LOCATION \
    --destination-run-service=DESTINATION_RUN_SERVICE \
    --destination-run-region=DESTINATION_RUN_REGION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --event-filters="database=DATABASE" \
    --event-filters="namespace=NAMESPACE" \
    --event-filters-path-pattern="entity=ENTITY" \
    --event-data-content-type="EVENT_DATA_CONTENT_TYPE" \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com"

Haz los cambios siguientes:

• TRIGGER: el ID del activador o un identificador completo.

• LOCATION: la ubicación del activador de Eventarc. También puedes definir la propiedad eventarc/location; por ejemplo, gcloud config set eventarc/location us-central1.

  Los activadores de Cloud Firestore para Eventarc solo están disponibles en determinadas ubicaciones y el activador debe estar en la misma ubicación que la base de datos de Cloud Firestore. Para obtener más información, consulta las ubicaciones de Eventarc y las ubicaciones de Cloud Firestore.

• DESTINATION_RUN_SERVICE: el nombre del servicio de Cloud Run que recibe los eventos del activador. El servicio puede estar en cualquiera de las ubicaciones admitidas de Cloud Run y no tiene por qué estar 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 HTTP POST enviadas a la ruta de URL raíz (/) cada vez que se genere el evento.
• DESTINATION_RUN_REGION: (opcional) la región en la que se puede encontrar el servicio de Cloud Run de destino. Si no se especifica, se presupone que el servicio está en la misma región que el activador.
• EVENT_FILTER_TYPE: identificador del evento. Se genera un evento cuando se realiza correctamente una llamada a la API del método. En el caso de las operaciones de larga duración, el evento solo se genera al final de la operación y solo si la acción se realiza correctamente. Para ver una lista de los tipos de eventos admitidos, consulta Tipos de eventos de Google compatibles con Eventarc.
Cloud Firestore admite los siguientes tipos de eventos solo en modo nativo.
• google.cloud.firestore.document.v1.created: el evento se envía cuando se escribe en un documento por primera vez.
• google.cloud.firestore.document.v1.created.withAuthContext: event con atributos de información de autenticación se envía cuando se escribe en un documento por primera vez.
• google.cloud.firestore.document.v1.updated: el evento se envía cuando ya existe un documento y se cambia algún valor.
• google.cloud.firestore.document.v1.updated.withAuthContext: evento con atributos de información de autenticación que se envía cuando ya existe un documento y se ha cambiado algún valor.
• google.cloud.firestore.document.v1.deleted: evento que se envía cuando se elimina un documento.
• google.cloud.firestore.document.v1.deleted.withAuthContext: event with authentication information attributes is sent when a document is deleted
• google.cloud.firestore.document.v1.written: el evento se envía cuando se crea, actualiza o elimina un documento.
• google.cloud.firestore.document.v1.written.withAuthContext: el evento con atributos de información de autenticación se envía cuando se crea, actualiza o elimina un documento.

Cloud Firestore admite los siguientes tipos de eventos solo en el modo Datastore. Los objetos de datos de Firestore en modo Datastore se conocen como entidades.

• google.cloud.datastore.entity.v1.created: el evento se envía cuando se escribe en una entidad por primera vez.
• google.cloud.datastore.entity.v1.created.withAuthContext: evento con atributos de información de autenticación que se envía cuando se escribe en una entidad por primera vez.
• google.cloud.datastore.entity.v1.updated: el evento se envía cuando ya existe una entidad y se ha cambiado algún valor.
• google.cloud.datastore.entity.v1.updated.withAuthContext: evento con atributos de información de autenticación que se envía cuando una entidad ya existe y se ha cambiado algún valor.
• google.cloud.datastore.entity.v1.deleted: el evento se envía cuando se elimina una entidad.
• google.cloud.datastore.entity.v1.deleted.withAuthContext: evento con atributos de información de autenticación que se envía cuando se elimina una entidad
• google.cloud.datastore.entity.v1.written: el evento se envía cuando se crea, actualiza o elimina una entidad.
• google.cloud.datastore.entity.v1.written.withAuthContext: evento con atributos de información de autenticación que se envía cuando se crea, actualiza o elimina una entidad.

• DATABASE: la base de datos de Firestore. Para el nombre de la base de datos predeterminado, usa (default).
• NAMESPACE (opcional): el espacio de nombres de la base de datos de Firestore. Para el espacio de nombres predeterminado en el modo Datastore, usa (default). Si no se especifica ningún valor, se utiliza un comodín (*) para buscar coincidencias.
• DOCUMENT (opcional): se aplica a las instancias de bases de datos que se ejecutan solo en modo nativo. La ruta de la base de datos de la que quieres recibir eventos cuando se creen, actualicen o eliminen datos en esa ruta. No especifiques una barra inicial. El operador puede ser uno de los siguientes:
  • Igual; por ejemplo: --event-filters="document=DOCUMENT"
  • Patrón de ruta. Por ejemplo, --event-filters-path-pattern="document=DOCUMENT".

    Usa comodines 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 del patrón. Por ejemplo:

    users/* o users/{userId}	Coincide con todos los documentos de la colección /users. No coincide con los documentos de las subcolecciones, como /users/marie/messages/33e2IxYBD9enzS50SJ68
    users/**	Coincide con todos los documentos de la colección /users y con los documentos de las subcolecciones, como /users/marie/messages/33e2IxYBD9enzS50SJ68.

    Para obtener más información, consulta Información sobre los patrones de ruta.
• ENTITY (opcional): se aplica a las instancias de base de datos que se ejecutan solo en el modo de Datastore. La ruta de la base de datos de la que quieres recibir eventos cuando se creen, actualicen o eliminen datos en esa ruta. No especifiques una barra inicial. El operador puede ser uno de los siguientes:
  • Igual; por ejemplo: --event-filters="document=ENTITY"
  • Patrón de ruta. Por ejemplo: --event-filters-path-pattern="ENTITY=ENTITY"

    Para obtener más información, consulta Información sobre los patrones de ruta.

    Ten en cuenta que es posible que tengas que usar caracteres de escape en los IDs de tipo y de entidad. Si se escapa un carácter, el filtro de eventos podrá interpretar correctamente el ID. Para obtener más información, consulta la sección sobre secuencias de escape de caracteres.

• EVENT_DATA_CONTENT_TYPE: la codificación de la carga útil del evento. En el caso de los eventos directos de Firestore, debe ser application/protobuf y los datos del evento son una matriz de bytes. Para obtener más información sobre los mensajes protobuf de los eventos de Cloud Firestore, consulta Eventos comunes.
• SERVICE_ACCOUNT_NAME: el nombre de tu cuenta de servicio gestionada por el usuario.
• PROJECT_ID: tu ID de proyecto Google Cloud .

Notas:

• En el caso de los eventos directos de Cloud Firestore, la codificación de la carga útil del evento es application/protobuf.
• Es obligatorio usar la marca --event-filters="type=EVENT_FILTER_TYPE". Si no se define ningún otro filtro de eventos, se buscarán coincidencias de eventos de todos los recursos.
• EVENT_FILTER_TYPE no se puede cambiar después de crearse. Para cambiar EVENT_FILTER_TYPE, crea un nuevo activador y elimina el antiguo.
• Cada activador puede tener varios filtros de eventos separados por comas en una --event-filters=[ATTRIBUTE=VALUE,...] marca, o bien puede repetir la marca para añadir más filtros. Solo se envían al destino los eventos que coinciden con todos los filtros. No se admiten comodines ni expresiones regulares. Sin embargo, cuando se usa la marca --event-filters-path-pattern, se puede definir un patrón de ruta de recurso.
• La marca --service-account se usa para especificar la dirección de correo de la cuenta de servicio de gestión de identidades y accesos (IAM) asociada al activador.
• También puede especificar una ruta relativa en el servicio Cloud Run de destino al que se deben enviar los eventos del activador mediante la marca --destination-run-path.

Ejemplo:

gcloud eventarc triggers create helloworld-trigger \
    --location=us-east1 \
    --destination-run-service=helloworld-events \
    --destination-run-region=us-east1 \
    --event-filters="type=google.cloud.firestore.document.v1.updated" \
    --event-filters="database=my-database" \
    --event-filters-path-pattern="document=users/my-document-*" \
    --event-data-content-type="application/protobuf" \
    --service-account=${SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com

Este comando crea un activador llamado helloworld-trigger para el evento identificado como google.cloud.firestore.document.v1.updated en la instancia de la base de datos my-database que se ejecuta en modo nativo y filtra los eventos de las rutas document que coinciden con users/my-document-.

Consola

1. En la Google Cloud consola, ve a la página Triggers (Activadores) de Eventarc.

   Ir a Activadores

   En esta página se muestran todos tus activadores de todas las ubicaciones, así como detalles como nombres, regiones, proveedores de eventos, destinos y más.

2. Para filtrar tus activadores, sigue estos pasos:

   1. Haz clic en filter_list Filtrar o en el campo Activar filtros.
   2. En la lista Propiedades, seleccione una opción para filtrar los activadores.

   Puede seleccionar una sola propiedad o usar el operador lógico OR para añadir más propiedades.

3. Para ordenar los activadores, junto al encabezado de cualquier columna admitida, haz clic en arrow_upward Ordenar.

gcloud

Ejecuta el siguiente comando para ver una lista de tus activadores:

gcloud eventarc triggers list --location=-

Este comando muestra los activadores de todas las ubicaciones e incluye detalles como nombres, tipos, destinos y estados.