Publicar eventos en una tabla de BigQuery

Publicar eventos en una tabla de BigQuery

Avanzado

En esta guía de inicio rápido se muestra cómo publicar y recibir mensajes de eventos creando un bus avanzado de Eventarc y registrándote en tu proyecto de Google Cloud.

• Un bus te permite centralizar el flujo de mensajes a través de tu sistema y actúa como un router. Recibe mensajes de eventos de una fuente de mensajes o publicados por un proveedor y los evalúa según un registro.

• Una inscripción identifica una suscripción a un autobús concreto y define los criterios de coincidencia de los mensajes, lo que hace que se dirijan a uno o varios destinos.

En esta guía de inicio rápido, harás lo siguiente:

1. Crea una tabla de BigQuery.

2. Crea un bus avanzado de Eventarc.

3. Crea un registro avanzado de Eventarc.

4. Publica un mensaje de evento en el bus.

5. Consulte los datos de eventos en la tabla de BigQuery.

Puedes completar esta guía de inicio rápido con la CLI de gcloud y la herramienta de línea de comandos bq.

Antes de empezar

Es posible que las restricciones de seguridad definidas por tu organización te impidan completar los siguientes pasos. Para obtener información sobre cómo solucionar problemas, consulta el artículo Desarrollar aplicaciones en un entorno limitado Google Cloud .

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Install the Google Cloud CLI.

Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery and Eventarc APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable bigquery.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com

Install the Google Cloud CLI.

Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery and Eventarc APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable bigquery.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com

1. Actualiza los componentes de gcloud:

   gcloud components update

2. Inicia sesión con tu cuenta:

   gcloud auth login

3. Defina la variable de configuración que se usa en esta guía de inicio rápido:

   REGION=REGION

   Sustituye REGION por una ubicación admitida del autobús (por ejemplo, us-central1).

4. Si has creado el proyecto, se te asignará el rol básico Propietario (roles/owner). De forma predeterminada, este rol de gestión de identidades y accesos (IAM) incluye los permisos necesarios para acceder por completo a la mayoría de los recursos Google Cloud, por lo que puedes saltarte este paso.

   Si no eres el creador del proyecto, debes conceder los permisos necesarios al principal correspondiente. Por ejemplo, una entidad principal puede ser una cuenta de Google (para usuarios finales) o una cuenta de servicio (para aplicaciones y cargas de trabajo de computación).

   Permisos obligatorios

   Para obtener los permisos que necesitas para completar esta guía de inicio rápido, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos en tu proyecto:

   • Editor de datos de BigQuery (roles/bigquery.dataEditor)
   • Desarrollador de Eventarc (roles/eventarc.developer)
   • Administrador de bus de mensajes de Eventarc (roles/eventarc.messageBusAdmin)
   • Usuario con permiso para ver registros (roles/logging.viewAccessor)
   • Administrador de gestión de identidades y accesos del proyecto (roles/resourcemanager.projectIamAdmin)
   • Administrador de cuentas de servicio (roles/iam.serviceAccountAdmin)
   • Usuario de cuenta de servicio (roles/iam.serviceAccountUser)
   • Administrador de Uso de Servicio (roles/serviceusage.serviceUsageAdmin)

   Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

   También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

5. Para dar a Eventarc Advanced los permisos necesarios para actualizar las propiedades de las tablas de BigQuery, pide a tu administrador que asigne el rol de gestión de identidades y accesos Editor de datos de BigQuery (roles/bigquery.dataEditor) a una cuenta de servicio de tu proyecto Google Cloud :
   1. Crea una cuenta de servicio. Para hacer pruebas, adjuntarás esta cuenta de servicio a una canalización avanzada de Eventarc para representar la identidad de la canalización.

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      Sustituye SERVICE_ACCOUNT_NAME por el nombre de tu cuenta de servicio.
   2. Asigna el rol de roles/bigquery.dataEditor IAM a la cuenta de servicio:

      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
          --role=roles/bigquery.dataEditor

Crear una tabla de BigQuery

Crea una tabla de BigQuery como destino de los eventos. Se admiten otros destinos de eventos, como un tema de Pub/Sub, Workflows u otro endpoint HTTP. Para obtener más información, consulta Proveedores y destinos de eventos.

Antes de crear una tabla de BigQuery, crea un conjunto de datos, que actúa como contenedor de nivel superior de la tabla, y un esquema de tabla.

1. Para crear un conjunto de datos, usa el comando bq mk con la marca --dataset.

   bq --location=$REGION mk --dataset DATASET_ID

   Sustituye DATASET_ID por un nombre único para el conjunto de datos de BigQuery. Por ejemplo, my_dataset.

2. En tu terminal, crea un archivo llamado my-schema.json.

3. Copia y pega el siguiente esquema en el nuevo archivo y, a continuación, guarda el archivo.

   [
       {
           "name": "name",
           "type": "STRING",
           "mode": "REQUIRED"
       },
       {
           "name": "age",
           "type": "INTEGER",
           "mode": "NULLABLE"
       }
   ]

4. Para crear una tabla, usa el comando bq mk con la marca --table.

   bq mk --table PROJECT_ID:DATASET_ID.TABLE_ID my-schema.json

   Sustituye TABLE_ID por un nombre único para la tabla de BigQuery. Por ejemplo, my-table.

Crear un bus de Eventarc Advanced

Un bus recibe mensajes de eventos de una fuente de mensajes o publicados por un proveedor y actúa como un enrutador de mensajes.

Para obtener más información, consulta el artículo Crear un bus para enrutar mensajes.

Nota: Puedes crear un bus por Google Cloud proyecto por región admitida.

Crea un bus avanzado de Eventarc en tu proyecto con el comando gcloud eventarc message-buses create:

gcloud eventarc message-buses create BUS_NAME \
    --location=$REGION

Sustituye BUS_NAME por el ID de tu autobús o por un nombre completo, como my-bus.

Crear un registro de Eventarc Advanced

Una inscripción determina qué mensajes se enrutan a un destino y también especifica la canalización que se usa para configurar un destino para los mensajes de eventos. En este caso, el destino es un endpoint de la API de BigQuery.

Para obtener más información, consulta Crear un registro para recibir eventos.

Nota: La creación de una canalización puede tardar más de 10 minutos.

Cuando usas gcloud CLI, primero creas una canalización y, después, una inscripción:

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

   gcloud eventarc pipelines create PIPELINE_NAME \
       --destinations=http_endpoint_uri='https://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_ID/insertAll',http_endpoint_message_binding_template='{"headers": headers.merge({"content-type":"application/json"}), "body": {"rows":[{"json":message.data}]}}',oauth_token_authentication_service_account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
       --input-payload-format-json= \
       --location=$REGION

   Sustituye PIPELINE_NAME por el ID de la canalización o por un nombre completo (por ejemplo, my-pipeline).

   Ten en cuenta lo siguiente:

   • La clave http_endpoint_message_binding_template transforma el evento al formato que espera la API. Al definir un enlace de mensaje, debes configurar un formato de entrada para acceder a la carga útil.
   • La clave oauth_token_authentication_service_account especifica un correo de cuenta de servicio. Esta dirección de correo se usa para generar un token de OAuth, que normalmente solo se debe usar al llamar a las APIs de Google alojadas en *.googleapis.com.
   • La marca input-payload-format-json especifica que el formato de la carga útil de entrada de la canalización es JSON. Los mensajes que no coincidan con este formato se tratarán como errores persistentes.

2. Crea un registro con el comando gcloud eventarc enrollments create:

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

   Haz los cambios siguientes:

   • ENROLLMENT_NAME: el ID de la inscripción o un nombre completo (por ejemplo, my-enrollment).

   • MATCH_EXPRESSION: la expresión coincidente de esta inscripción con CEL. Por ejemplo:

     "message.type == 'hello-world-type'"
     

Publicar un mensaje de evento en el bus

Para publicar un mensaje directamente en tu bus, puedes usar el comando gcloud eventarc message-buses publish o enviar una solicitud a la API REST de publicación de Eventarc. Para obtener más información, consulta Publicar eventos directamente.

El mensaje debe estar en formato CloudEvents, que es una especificación para describir datos de eventos de forma común. El elemento data es la carga útil de tu evento y, en última instancia, debe coincidir con el esquema de tu tabla de BigQuery. En este campo se puede incluir cualquier JSON con el formato correcto. Para obtener más información sobre los atributos de contexto de CloudEvents, consulta el artículo Formato de evento.

A continuación, se muestran ejemplos de cómo publicar directamente un evento en un bus avanzado de Eventarc:

Ejemplo 1

Puedes publicar un evento en un bus mediante la CLI de gcloud y un --event-data, así como otros indicadores de atributos de evento:

gcloud eventarc message-buses publish BUS_NAME \
    --event-data='{"name": "my-name", "age": "20"}' \
    --event-id=hello-world-id-1234 \
    --event-source=hello-world-source \
    --event-type=hello-world-type \
    --event-attributes="datacontenttype=application/json" \
    --location=$REGION

Ejemplo 2

Puedes publicar un evento en un bus como mensaje JSON con gcloud CLI y la marca --json-message:

gcloud eventarc message-buses publish BUS_NAME \
    --location=$REGION \
    --json-message='{"id": "hello-world-id-1234", "type":
 "hello-world-type", "source":
 "hello-world-source", "specversion": "1.0", "data":
 {"name": "my-name", "age": "20"}}'

Después de publicar un evento, deberías recibir el mensaje "Evento publicado correctamente".

Ver los datos de eventos en la tabla de BigQuery

Después de publicar un evento en tu bus avanzado de Eventarc, puedes usar el comando bq query para confirmar que se ha añadido una nueva fila a tu tabla de BigQuery.

bq query \
    --use_legacy_sql=false \
    'SELECT
      *
    FROM
      `PROJECT_ID.DATASET_ID.TABLE_ID`
    LIMIT
      10;'

Has creado correctamente un bus y un registro de Eventarc Advanced, has publicado un mensaje de evento en el bus y has verificado el resultado esperado consultando la tabla de BigQuery.

Limpieza

Cuando hayas completado las tareas descritas en esta guía de inicio rápido, puedes evitar que se te siga facturando eliminando los recursos que has creado:

1. Eliminar una tabla de BigQuery.

2. Eliminar un conjunto de datos de BigQuery.

3. Elimina los recursos avanzados de Eventarc:

   1. Eliminar una inscripción.

   2. Eliminar una canalización

   3. Eliminar un autobús

También puedes eliminar tu Google Cloud proyecto para evitar que se te apliquen cargos. Al eliminar tu Google Cloud proyecto, se detendrá la facturación de todos los recursos utilizados en él.

Precaución: Eliminar un proyecto tiene los siguientes efectos:

• Se elimina todo el contenido del proyecto. Si has usado un proyecto que ya existía para las tareas de este documento, cuando lo elimines, también se eliminará cualquier otro trabajo que hayas realizado en él.
• Se pierden los IDs de proyecto personalizados. Cuando creaste este proyecto, es posible que hayas creado un ID de proyecto personalizado que quieras usar en el futuro. Para conservar las URLs que usan el ID del proyecto, como una URL appspot.com, elimina los recursos seleccionados dentro del proyecto en lugar de eliminar todo el proyecto.

Si tienes previsto consultar varias arquitecturas, tutoriales o guías de inicio rápido, reutilizar los proyectos puede ayudarte a no superar los límites de cuota de proyectos.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Siguientes pasos

• Publicar eventos de fuentes de Google
• Publicar eventos directamente
• Transformar eventos recibidos
• Dar formato a los eventos recibidos