Transferencias controladas por eventos

Las transferencias controladas por eventos en el Servicio de transferencia de datos de BigQuery te permiten cargar datos de forma automática en BigQuery en respuesta a las notificaciones de eventos. Puedes usar este enfoque para la transferencia por lotes incremental y rentable cuando tu carga de trabajo pueda tolerar un retraso de unos minutos entre las ejecuciones de transferencia. Si necesitas que los datos estén disponibles en tiempo real con una latencia más baja, usa la API de Storage Write para transmitir datos directamente a BigQuery.

Fuentes de datos compatibles con las transferencias basadas en eventos

El Servicio de transferencia de datos de BigQuery puede usar transferencias controladas por eventos con las siguientes fuentes de datos:

Limitaciones

Las transferencias controladas por eventos a BigQuery están sujetas a las siguientes limitaciones:

  • Después de que se activa una transferencia controlada por eventos, el Servicio de transferencia de datos de BigQuery espera hasta 10 minutos antes de activar la siguiente ejecución de transferencia, sin importar si llega un evento dentro de ese tiempo.
  • Las transferencias controladas por eventos no admiten parámetros de entorno de ejecución para el URI de origen o la ruta de acceso de datos.
  • No se puede volver a usar la misma suscripción a Pub/Sub en varias configuraciones de transferencia controladas por eventos.

Configura una transferencia controlada por eventos de Cloud Storage

Las transferencias controladas por eventos de Cloud Storage usan notificaciones de Pub/Sub para saber cuándo se modificaron o agregaron objetos en el bucket de origen. Cuando usas el modo de transferencia incremental, borrar un objeto en el bucket de origen no borra los datos asociados en la tabla de BigQuery de destino.

Antes de comenzar

Antes de configurar una transferencia controlada por eventos de Cloud Storage, debes realizar los siguientes pasos:

  1. Habilitar la API de Pub/Sub para el proyecto que recibe notificaciones.

    Habilitar la API

  2. Si eres administrador de Cloud Storage (roles/storage.admin) y administrador de Pub/Sub (roles/pubsub.admin), puedes continuar con el paso Crea una configuración de transferencia basada en eventos.

  3. Si no eres el administrador de Cloud Storage (roles/storage.admin) ni el administrador de Pub/Sub (roles/pubsub.admin), pídele a tu administrador que te otorgue los roles roles/storage.admin y roles/pubsub.admin, o que complete la configuración de Pub/Sub y la configuración de los permisos del agente de servicio en las siguientes secciones y que use la suscripción preconfigurada de Pub/Sub para crear una configuración de transferencia controlada por eventos.

  4. Estos son los permisos detallados que se requieren para configurar las notificaciones de configuración de transferencias basadas en eventos:

Configura notificaciones de Pub/Sub en Cloud Storage

  1. Asegúrate de cumplir con los requisitos previos para usar Pub/Sub con Cloud Storage.

  2. Aplica una configuración de notificaciones a tu bucket de Cloud Storage:

    gcloud storage buckets notifications create gs://BUCKET_NAME --topic=TOPIC_NAME --event-types=OBJECT_FINALIZE

    Reemplaza lo siguiente:

    • BUCKET_NAME: Es el nombre del bucket de Cloud Storage en el que quieres activar los eventos de notificación de archivos.
    • TOPIC_NAME: Es el nombre del tema de Pub/Sub en el que deseas recibir los eventos de notificación de archivos.

    También puedes agregar una configuración de notificaciones con otros métodos además de gcloud CLI. Para obtener más información, consulta Aplica una configuración de notificación.

  3. Verifica que la notificación de Pub/Sub esté configurada correctamente para Cloud Storage. Usa el comando gcloud storage buckets notifications list:

    gcloud storage buckets notifications list gs://BUCKET_NAME

    Si se ejecuta de forma correcta, la respuesta se verá como el ejemplo siguiente:

    etag: '132'
id: '132'
kind: storage#notification
payload_format: JSON_API_V1
selfLink: https://www.googleapis.com/storage/v1/b/my-bucket/notificationConfigs/132
topic: //pubsub.googleapis.com/projects/my-project/topics/my-bucket

  4. Crea una suscripción de extracción para el tema:

    gcloud pubsub subscriptions create SUBSCRIPTION_ID --topic=TOPIC_NAME

    Reemplaza SUBSCRIPTION_ID por el nombre o el ID de tu nueva suscripción de extracción de Pub/Sub.

    Puedes crear una suscripción de extracción con otros métodos.

Configura los permisos del agente de servicio

  1. Busca el nombre del agente del Servicio de transferencia de datos de BigQuery para tu proyecto:

    1. Ir a la página IAM y administración

      Ir a IAM y administración

    2. Selecciona la casilla de verificación Incluir asignaciones de funciones proporcionadas por Google.

    3. El agente del Servicio de transferencia de datos de BigQuery aparece con el nombre service-<project_number>@gcp-sa-bigquerydatatransfer.iam.gserviceaccount.com y se le otorga el rol de agente del Servicio de transferencia de datos de BigQuery (roles/bigquerydatatransfer.serviceAgent).

      Verifica si la cuenta de servicio tiene el rol de agente de servicio.

    Para obtener más información sobre los agentes de servicio, consulta Agentes de servicio.

  2. Otorga el rol de suscriptor de Pub/Sub (pubsub.subscriber) al agente del Servicio de transferencia de datos de BigQuery.

    Consola de Cloud

    Sigue las instrucciones que se indican en Controla el acceso a través de la consola de Google Cloud para otorgar el rol Pub/Sub Subscriber al agente del Servicio de transferencia de datos de BigQuery. El rol se puede otorgar a nivel de tema, suscripción o proyecto.

    gcloud CLI

    Sigue las instrucciones que se indican en Configura una política para agregar la siguiente vinculación:

    {
  "role": "roles/pubsub.subscriber",
  "members": [
    "serviceAccount:project-PROJECT_NUMBER@gcp-sa-bigquerydatatransfer.iam.gserviceaccount.com"
}

    Reemplaza PROJECT_NUMBER por el ID del proyecto que aloja los recursos de transferencia que se crean y facturan.

    Atribución de uso de cuota: Cuando el agente del Servicio de transferencia de datos de BigQuery accede a la suscripción a Pub/Sub, el uso de la cuota se cobra al proyecto del usuario.

  3. Verifica que el agente del Servicio de transferencia de datos de BigQuery tenga otorgado el rol de suscriptor de Pub/Sub (pubsub.subscriber).

    1. En la consola de Google Cloud , ve a la página Pub/Sub.

      Ir a Pub/Sub

    2. Selecciona la suscripción a Pub/Sub que usaste en la transferencia basada en eventos.

    3. Si el panel de información está oculto, haz clic en Mostrar panel de información en la esquina superior derecha.

    4. En la pestaña Permisos, verifica que el agente de servicio del Servicio de transferencia de datos de BigQuery tenga el rol de suscriptor de Pub/Sub (pubsub.subscriber).

    Verifica si el agente de servicio tiene pubsub.subscriber en la suscripción.

Comandos resumidos para configurar las notificaciones y los permisos

Los siguientes comandos de Google Cloud CLI incluyen todos los comandos necesarios para configurar las notificaciones y los permisos, como se detalla en las secciones anteriores.

gcloud

PROJECT_ID=project_id
CONFIG_NAME=config_name
RESOURCE_NAME="bqdts-event-driven-${CONFIG_NAME}"
# Create a Pub/Sub topic.
gcloud pubsub topics create "${RESOURCE_NAME}" --project="${PROJECT_ID}"
# Create a Pub/Sub subscription.
gcloud pubsub subscriptions create "${RESOURCE_NAME}" --project="${PROJECT_ID}" --topic="projects/${PROJECT_ID}/topics/${RESOURCE_NAME}"
# Create a Pub/Sub notification.
gcloud storage buckets notifications create gs://"${RESOURCE_NAME}" --topic="projects/${PROJECT_ID}/topics/${RESOURCE_NAME}" --event-types=OBJECT_FINALIZE
# Grant roles/pubsub.subscriber permission to the DTS service agent.
PROJECT_NUMBER=$(gcloud projects describe "${PROJECT_ID}" --format='value(projectNumber)')
gcloud pubsub subscriptions add-iam-policy-binding "${RESOURCE_NAME}"  --project="${PROJECT_ID}"  --member=serviceAccount:service-"${PROJECT_NUMBER}"@gcp-sa-bigquerydatatransfer.iam.gserviceaccount.com  --role=roles/pubsub.subscriber

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto
  • CONFIG_NAME: Es un nombre para identificar esta configuración de transferencia.

Crea una configuración de transferencia

Para crear una transferencia de Cloud Storage controlada por eventos, crea una transferencia de Cloud Storage y selecciona Controlada por eventos como el Tipo de programa. Como administrador de Cloud Storage (roles/storage.admin) y administrador de Pub/Sub (roles/pubsub.admin), tienes permisos suficientes para que el Servicio de transferencia de datos de BigQuery configure Cloud Storage de forma automática para enviar notificaciones.

Si no eres administrador de Cloud Storage (roles/storage.admin) ni de Pub/Sub (roles/pubsub.admin), debes pedirle a tu administrador que te otorgue los roles o que complete las notificaciones de Pub/Sub requeridas en las configuraciones de Cloud Storage y las configuraciones de permisos del agente de servicio antes de que puedas crear la transferencia controlada por eventos.