Crea una inscripción para recibir eventos

Una inscripción identifica una suscripción a un bus en particular. La inscripción define los criterios de coincidencia que determinan qué mensajes se enrutan a un destino. También especifica la canalización a través de la cual se deben enrutar los mensajes coincidentes. Una canalización te permite configurar un destino de destino y también te brinda la opción de transformar los eventos coincidentes antes de entregarlos al destino.

Ten en cuenta lo siguiente:

  • Una canalización y una inscripción deben estar en el mismo proyecto de Google Cloud. (El bus puede estar en el mismo proyecto o en uno diferente).
  • Se puede usar una canalización para varias inscripciones.
  • Solo un destino puede ser el objetivo de los mensajes que enruta una canalización.
  • Antes de configurar una canalización o una inscripción, ya deberías haber creado un bus avanzado de Eventarc.

Roles obligatorios

Un rol de Identity and Access Management (IAM) contiene un conjunto de permisos que te permite realizar acciones específicas en los recursos de Google Cloud. Se requieren los siguientes roles y permisos cuando se crea una canalización y una inscripción para enrutar mensajes:

  • Para obtener el permiso que necesitas para crear una canalización, pídele a tu administrador que te otorgue el rol de IAM de Desarrollador de Eventarc (roles/eventarc.developer) en tu proyecto de canalización. Este rol predefinido contiene el permiso eventarc.pipelines.create, que se requiere para crear una canalización.
  • Para obtener el permiso que necesitas para crear una inscripción, pídele a tu administrador que te otorgue el rol de IAM Desarrollador de Eventarc (roles/eventarc.developer) en tu proyecto de inscripción. Este rol predefinido contiene el permiso eventarc.enrollments.create, que se requiere para crear una inscripción.
  • Para obtener el permiso que necesitas para usar un bus, pídele a tu administrador que te otorgue el rol de IAM Usuario de bus de mensajes de Eventarc (roles/eventarc.messageBusUser) en tu proyecto de bus. Este rol predefinido contiene el permiso eventarc.buses.use, que se requiere para usar un bus.

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso. También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Inscríbete para recibir eventos

Puedes crear una canalización y una inscripción en la consola de Google Cloud o con Google Cloud CLI.

Console

En la consola de Google Cloud, puedes crear la canalización y la inscripción al mismo tiempo desde la página Canalizaciones.

  1. Para crear una inscripción, en la consola de Google Cloud, ve a la página Eventarc > Canales.

    Ir a Canalizaciones

  2. Haz clic en Crear canalización.

  3. En el panel Detalles de la canalización, haz lo siguiente:

    1. Ingresa un Nombre de la canalización. Este es el ID de tu canalización.
    2. En la lista Región, selecciona una región para implementar tu canalización. La canalización se debe crear en la misma región que el bus. Para obtener más información, consulta Ubicaciones avanzadas de Eventarc.
    3. Opcional: Puedes modificar la configuración predeterminada para reintentar eventos.
    4. En Encriptación, acepta la clave de encriptación administrada por Google predeterminada o selecciona la clave de Cloud KMS. Para obtener más información, consulta Usa claves de encriptación administradas por el cliente (CMEK).

    5. Si seleccionas Clave de Cloud KMS, haz lo siguiente:

      1. En la lista Tipo de clave, selecciona un método para administrar tus claves.

        Puedes administrar tus claves de forma manual o usar Autokey, que te permite generar llaveros y claves a pedido. Si la opción Autokey está inhabilitada, aún no está integrada en el tipo de recurso actual.

      2. En Selecciona una clave administrada por el cliente, selecciona una clave.

        Ten en cuenta que debes seleccionar una región para poder ver tus claves administradas por el cliente.

      3. Opcional: Para ingresar de forma manual el nombre del recurso de la clave, en la lista Selecciona una clave administrada por el cliente, haz clic en Ingresar clave de forma manual y, luego, escribe el nombre de la clave en el formato especificado.

      4. Si se te solicita, otorga el rol cloudkms.cryptoKeyEncrypterDecrypter al agente de servicio de Eventarc.

    6. Opcional: Para agregar etiquetas, haz clic en Agregar etiqueta. Las etiquetas son pares clave-valor que te ayudan a organizar tus recursos de Google Cloud. Para obtener más información, consulta ¿Qué son las etiquetas?

    7. Haga clic en Continuar.

  4. En el panel Matrículas, haz lo siguiente:

    1. Haz clic en Agregar una inscripción.
    2. Ingresa un nombre de inscripción.
    3. En la lista Bus, selecciona un bus al que suscribirte.

    4. En el campo CEL expression, escribe una expresión de evaluación con CEL. Por ejemplo:

      message.type == "google.cloud.dataflow.job.v1beta3.statusChanged"

      Ten en cuenta que la expresión predeterminada, true, indica que todos los mensajes se enrutan sin filtrar.

    5. Haz clic en Listo.

    6. Puedes agregar otra inscripción o hacer clic en Continuar.

  5. Opcional: En el panel Mediación de eventos, haz lo siguiente o haz clic en Continuar:

    1. Selecciona la casilla de verificación Aplicar una transformación.

    2. En la lista Formato entrante, selecciona el formato aplicable.

      Ten en cuenta que, cuando aplicas una transformación, debes especificar un formato de datos entrantes para una canalización y que todos los eventos deben coincidir con ese formato.

    3. Para los formatos Avro o Protobuf, debes especificar un esquema entrante. De manera opcional, puedes subir un esquema entrante. Para obtener más información, consulta Cómo formatear los eventos recibidos.

    4. En el campo CEL expression, escribe una expresión de transformación con CEL.

    5. Haga clic en Continuar.

  6. En el panel Destino, haz lo siguiente:

    1. En la lista Tipo de destino, selecciona un tipo de destino al que se enrutelen los mensajes. Según el tipo de destino, haz lo siguiente:

      • Extremo HTTP: Especifica el URI de destino. El host puede ser una IP estática a la que se puede asignar una dirección desde una red de nube privada virtual (VPC) o el nombre de host interno del sistema de nombres de dominio (DNS) de un servicio que se puede resolver con Cloud DNS.

        Ten en cuenta que puedes usar este tipo de destino para segmentar una función de Cloud Run.

      • Bus de Eventarc Advanced: Selecciona un bus de Eventarc Advanced.

      • Flujo de trabajo de Workflows: Selecciona un flujo de trabajo de Workflows.

      • Tema de Pub/Sub: Selecciona o crea un tema de Pub/Sub.

      • Servicio de Cloud Run (a través de HTTP): Selecciona un servicio de Cloud Run que recibirá eventos como solicitudes HTTP POST que se envían a su ruta de URL raiz (/). De manera opcional, puedes especificar una ruta de URL relativa en el servicio de destino al que se deben enviar los eventos.

      • Trabajo de Cloud Run (a través de HTTP): Selecciona un trabajo de Cloud Run que reciba eventos como solicitudes HTTP POST.

    2. Especifica un adjunto de red.

      Un adjunto de red es un recurso que permite que una red de VPC del productor inicie conexiones a una red de VPC del consumidor. Para publicar eventos, Eventarc Advanced usa el adjunto de red para establecer una conexión con el extremo alojado en una red de VPC.

      Puedes crear un adjunto de red que acepte conexiones de forma automática desde cualquier interfaz de Private Service Connect que haga referencia al adjunto de red. Crea el adjunto de red en la misma red y región que contiene el extremo de destino.

      Si enrutas mensajes a un destino de Google con una dirección DNS (por ejemplo, Cloud Run, Pub/Sub, Workflows o cualquier otro bus avanzado de Eventarc), asegúrate de que el Acceso privado a Google esté habilitado en la subred que se usa en el adjunto de red. De lo contrario, no se podrá resolver la dirección DNS.

    3. Si corresponde, selecciona un formato en la lista Formato de salida.

      Ten en cuenta que, si no se especifica un formato de datos entrantes para una canalización, no se puede establecer un formato saliente.

    4. Si corresponde, aplica una vinculación de mensajes. Para obtener más información, consulta Define una vinculación de mensajes.

    5. Para habilitar la autenticación, selecciona la casilla de verificación Habilitar autenticación.

      1. En la lista Encabezado de autenticación, selecciona el tipo de token que se generará y adjúntalo como encabezado Authorization en la solicitud HTTP:

        • Por lo general, un token de OAuth solo debe usarse cuando se llama a las APIs de Google alojadas en *.googleapis.com. De manera opcional, especifica el alcance de este token. De lo contrario, el valor predeterminado será https://www.googleapis.com/auth/cloud-platform. Para los servicios de Google Cloud, se recomienda usar el permiso https://www.googleapis.com/auth/cloud-platform, que incluye todas las APIs de Google Cloud, junto con Identity and Access Management (IAM), que proporciona un control de acceso detallado.

          Ten en cuenta que todas las solicitudes a otro bus avanzado de Eventarc, Pub/Sub o Workflows deben tener un encabezado de autorización HTTP que contenga un token de OAuth firmado por Google para una de las cuentas de servicio autorizadas.

        • Un token de OIDC se puede usar en muchas situaciones, incluidos los extremos en los que deseas validar el token por tu cuenta. Además, especifica el Público al que está destinado este token. Por lo general, debe coincidir con la URL de la canalización de destino. Si no se especifica, se usa la URL completa, incluidos los parámetros de solicitud.

          Ten en cuenta que Cloud Run realiza una verificación de IAM en cada solicitud y puedes usar el permiso run.routes.invoke para configurar quién puede acceder a tu servicio de Cloud Run de cualquiera de las siguientes maneras:

          • Otorga el permiso para seleccionar cuentas de servicio o grupos para permitir el acceso al servicio. Todas las solicitudes deben tener un encabezado de autorización HTTP que contenga un token de OpenID Connect firmado por Google para una de las cuentas de servicio autorizadas.

          • Otorga el permiso a allUsers para permitir el acceso no autenticado.

          Para obtener más información, consulta Control de acceso de Cloud Run.

        Obtén más información sobre los tipos de tokens.

      2. En la lista Cuenta de servicio, selecciona la cuenta de servicio que invocará tu servicio de destino. También puedes crear una cuenta de servicio nueva.

        Esto especifica el correo electrónico de la cuenta de servicio de IAM asociado con la canalización y al que otorgaste antes roles específicos que requiere Eventarc Advanced.

  7. Haz clic en Crear.

gcloud

Cuando uses gcloud CLI, primero crea la canalización y, luego, crea la inscripción con los comandos adecuados.

Canalización

  1. Abre una terminal.

  2. Crea una canalización con el comando gcloud beta eventarc pipelines create:

    gcloud beta eventarc pipelines create PIPELINE_NAME \
    --destinations=DESTINATION_KEY \
    --location=REGION

    Reemplaza lo siguiente:

    • PIPELINE_NAME: El ID de la canalización o un nombre completamente calificado

    • DESTINATION_KEY: Uno o más pares clave-valor para configurar un destino para la canalización

      Debes establecer solo una de las siguientes claves:

      Debes establecer la siguiente clave:

      • network_attachment: Es un recurso que permite que una red de VPC del productor inicie conexiones a una red de VPC del consumidor. Para publicar eventos, Eventarc Advanced usa el adjunto de red para establecer una conexión con el extremo alojado en una red de VPC.

        Puedes crear un adjunto de red que acepte conexiones de forma automática desde cualquier interfaz de Private Service Connect que haga referencia al adjunto de red. Crea el adjunto de red en la misma red y región que contiene el recurso de destino.

        Si enrutas mensajes a un destino de Google con una dirección DNS (por ejemplo, Cloud Run, Pub/Sub, Workflows o cualquier otro bus avanzado de Eventarc), asegúrate de que el Acceso privado a Google esté habilitado en la subred que se usa en el adjunto de red. De lo contrario, no se podrá resolver la dirección DNS.

      Para habilitar la autenticación, puedes establecer una de las siguientes claves:

      • google_oidc_authentication_service_account: Es el correo electrónico de la cuenta de servicio que se usa para generar un token de OIDC que se puede usar en muchas situaciones, incluidos los extremos en los que deseas validar el token por tu cuenta. De manera opcional, puedes configurar google_oidc_authentication_audience para especificar el público al que está destinado este token. Por lo general, debe coincidir con la URL de la canalización de destino. Si no se especifica, se usa la URL completa, incluidos los parámetros de solicitud.

        Ten en cuenta que Cloud Run realiza una verificación de IAM en cada solicitud y puedes usar el permiso run.routes.invoke para configurar quién puede acceder a tu servicio de Cloud Run de cualquiera de las siguientes maneras:

        • Otorga el permiso para seleccionar cuentas de servicio o grupos para permitir el acceso al servicio. Todas las solicitudes deben tener un encabezado de autorización HTTP que contenga un token de OpenID Connect firmado por Google para una de las cuentas de servicio autorizadas.

        • Otorga el permiso a allUsers para permitir el acceso no autenticado.

        Para obtener más información, consulta Control de acceso de Cloud Run .

      • oauth_token_authentication_service_account: Es el correo electrónico de la cuenta de servicio que se usa para generar un token de OAuth, que, por lo general, solo se debe usar cuando se llama a las APIs de Google alojadas en *.googleapis.com. De manera opcional, puedes configurar oauth_token_authentication_scope para especificar el alcance de este token. De lo contrario, el valor predeterminado será https://www.googleapis.com/auth/cloud-platform. Para los servicios de Google Cloud, se recomienda usar el permiso https://www.googleapis.com/auth/cloud-platform, que incluye todas las APIs de Google Cloud, junto con Identity and Access Management (IAM), que proporciona un control de acceso detallado.

        Ten en cuenta que todas las solicitudes a otro bus avanzado de Eventarc, Pub/Sub o Workflows deben tener un encabezado de autorización HTTP que contenga un token de OAuth firmado por Google para una de las cuentas de servicio autorizadas.

        Obtén más información sobre los tipos de tokens.

      Opcional: Puedes establecer una de las siguientes claves:

      • output_payload_format_avro_schema_definition
      • output_payload_format_json

      • output_payload_format_protobuf_schema_definition

        Ten en cuenta que, si estableces un formato de salida, también debes especificar un formato de entrada (consulta las siguientes marcas input-payload-format-*).

      Opcional: Si http_endpoint_uri no se usa como clave de destino, puedes establecer las siguientes claves:

      • project: Es el ID del proyecto de Google Cloud del recurso de destino. De forma predeterminada, se usa el ID del proyecto de la canalización.
      • location: Es la ubicación del recurso de destino. De forma predeterminada, se usa la ubicación de la canalización.

    • REGION: Una ubicación de Eventarc Advanced compatible

      Como alternativa, puedes configurar la propiedad de ubicación de gcloud CLI:

      gcloud config set eventarc/location REGION

    Opcional: Puedes usar las siguientes marcas:

    • --async para mostrar el comando de inmediato, sin esperar a que se complete la operación en curso.
    • --crypto-key para especificar el nombre completamente calificado de una clave de encriptación administrada por el cliente. Si no se especifica, se usan claves administradas por Google.
    • --logging-config para configurar el nivel de registro, que debe ser una de las siguientes opciones: NONE, DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT, EMERGENCY.

    • --mediations para aplicar una transformación. transformation_template es la única plantilla compatible y solo se admite una mediación por canalización. Por ejemplo:

      --mediations=transformation_template='message.removeFields(["id\ ","credit_card_number","age"])'

      Ten en cuenta que, si aplicas una transformación, debes usar una de las siguientes marcas para especificar un formato de entrada.

    • Uno de los siguientes para especificar un formato de entrada:

      • --input-payload-format-avro-schema-definition
      • --input-payload-format-json
      • --input-payload-format-protobuf-schema-definition

    • --max-retry-attempts, --max-retry-delay y --min-retry-delay para volver a intentar eventos

    Por ejemplo:

    gcloud beta eventarc pipelines create my-pipeline \
    --destinations=http_endpoint_uri='https://example-endpoint.com',network_attachment=my-network-attachment,oauth_token_authentication_service_account=example-service-account@example-project.gserviceaccount.iam.com,oauth_token_authentication_scope='https://www.googleapis.com/auth/cloud-platform',output_payload_format_avro_schema_definition='{"type": "record","name": "my_record", "fields": [{"name": "my_field", "type":"string"}]}' \
    --input-payload-format-avro-schema-definition='{"type":"record", "name": "my_record", "fields": [{"name": "my_field","type": "string"}]}' \
    --location=us-central1 \
    --async

    Para obtener más detalles y ejemplos, consulta la documentación de la CLI de gcloud.

Inscripción

  1. Abre una terminal.

  2. Crea una inscripción con el comando gcloud beta eventarc enrollments create:

    gcloud beta eventarc enrollments create ENROLLMENT_NAME \
    --cel-match=MATCH_EXPRESSION \
    --destination-pipeline=PIPELINE_NAME \
    --message-bus=BUS_NAME \
    --message-bus-project=PROJECT_ID \
    --location=REGION

    Reemplaza lo siguiente:

    • ENROLLMENT_NAME: El ID de la inscripción o un nombre completamente calificado
    • MATCH_EXPRESSION: Es la expresión de coincidencia para esta inscripción con CEL, por ejemplo, "message.type == 'google.cloud.dataflow.job.v1beta3.statusChanged'".
    • PIPELINE_NAME: El ID de la canalización de destino o su nombre completamente calificado para esta inscripción
    • BUS_NAME: El ID del bus avanzado de Eventarc o su nombre completamente calificado
    • PROJECT_ID: El ID del proyecto de Google Cloud del bus

    • REGION: Una ubicación de Eventarc Advanced compatible

      Como alternativa, puedes configurar la propiedad de ubicación de gcloud CLI:

      gcloud config set eventarc/location REGION

    Opcional: Puedes usar la siguiente marca:

    • --async para mostrar el comando de inmediato, sin esperar a que se complete la operación en curso

    Por ejemplo:

    gcloud beta eventarc enrollments create my-enrollment \
    --cel-match="message.type == 'google.cloud.dataflow.job.v1beta3.statusChanged'" \
    --destination-pipeline=my-pipeline \
    --message-bus=my-message-bus \
    --message-bus-project=another-google-cloud-project \
    --location=us-central1 \
    --async

Cómo borrar una inscripción

Puedes borrar una inscripción en la consola de Google Cloud o con Google Cloud CLI.

Console

  1. Para borrar una inscripción, en la consola de Google Cloud, ve a la página Eventarc > Canalizaciones.

    Ir a Canalizaciones

  2. Haz clic en el nombre de la canalización de la que deseas borrar la inscripción.

    Se abrirá el panel Detalles de la canalización.

  3. Haga clic en Continuar.

    Se abrirá el panel Matrículas.

  4. En la inscripción que deseas borrar, haz clic en el ícono de borrar .

  5. Haz clic en Guardar.

gcloud

  1. Abre una terminal.

  2. Borra una inscripción con el comando gcloud beta eventarc enrollments delete:

    gcloud beta eventarc enrollments delete ENROLLMENT_NAME \
      --location=REGION

    Reemplaza lo siguiente:

Cómo borrar una canalización

Puedes borrar una canalización en la consola de Google Cloud o con Google Cloud CLI.

Ten en cuenta que borrar una canalización puede tardar más de 10 minutos.

Console

  1. Para borrar una canalización, en la consola de Google Cloud, ve a la página Eventarc > Canalizaciones.

    Ir a Canalizaciones

  2. En la lista de canalización, selecciona la casilla de verificación junto al nombre de la canalización que deseas borrar.

  3. Haz clic en Borrar.

  4. Ingresa Delete para confirmar la eliminación.

  5. Haz clic en Borrar.

gcloud

  1. Abre una terminal.

  2. Borra una canalización con el comando gcloud beta eventarc pipelines delete:

    gcloud beta eventarc pipelines delete PIPELINE_NAME \
      --location=REGION

    Reemplaza lo siguiente:

¿Qué sigue?