Transferencias basadas en eventos

Puedes usar el Servicio de transferencia de datos de BigQuery para crear transferencias basadas en eventos que carguen datos automáticamente según las notificaciones de eventos. Te recomendamos que uses transferencias basadas en eventos si necesitas una transferencia incremental de datos que optimice la eficiencia de los costos.

Cuando configuras transferencias basadas en eventos, puede haber una demora de unos minutos entre cada transferencia de datos. Si necesitas que los datos estén disponibles de inmediato, te recomendamos que uses la API de Storage Write, que transmite datos directamente a BigQuery con la latencia más baja posible. La API de Storage Write proporciona actualizaciones en tiempo real para los casos de uso más exigentes.

Cuando elijas entre las dos opciones, considera si necesitas priorizar la transferencia incremental y rentable de lotes con transferencias basadas en eventos o si prefieres la flexibilidad de la API de Storage Write.

Fuentes de datos compatibles con transferencias basadas en eventos

El Servicio de transferencia de datos de BigQuery puede usar transferencias basadas en eventos con las siguientes fuentes de datos:

Limitaciones

Las transferencias basadas en eventos a BigQuery están sujetas a las siguientes limitaciones:

  • Después de que se activa una transferencia basada en eventos, el Servicio de transferencia de datos de BigQuery espera hasta 10 minutos antes de activar la siguiente ejecución de transferencia, independientemente de si llega un evento dentro de ese período.
  • Las transferencias controladas por eventos no admiten parámetros de tiempo de ejecución para la ruta de acceso de datos o el URI de la fuente.
  • Varias configuraciones de transferencia basadas en eventos no pueden reutilizar la misma suscripción de Pub/Sub.

Configura una transferencia controlada por eventos de Cloud Storage

Las transferencias controladas por eventos desde Cloud Storage usan notificaciones de Pub/Sub para saber cuándo se modificaron o agregaron objetos en el bucket de origen. Cuando se usa 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 basada en eventos de Cloud Storage, debes realizar los siguientes pasos:

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

    Habilitar la API

  2. Si eres el administrador de Cloud Storage (roles/storage.admin) y el administrador de Pub/Sub (roles/pubsub.admin), puedes continuar con Cómo crear 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 de roles/storage.admin y roles/pubsub.admin, o que complete la configuración de Pub/Sub y la configuración de permisos del agente de servicio en las siguientes secciones, y que use la suscripción a Pub/Sub preconfigurada para crear una configuración de transferencia basada en eventos.

  4. Permisos detallados necesarios para configurar las notificaciones de configuración de transferencia basada 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 notificación 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: El nombre del bucket de Cloud Storage para el que deseas activar 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 Cómo aplicar una configuración de notificaciones.

  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á similar a la 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. Para encontrar el nombre del agente del Servicio de transferencia de datos de BigQuery de tu proyecto, haz lo siguiente:

    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. Se muestra el agente de Servicio de transferencia de datos de BigQuery con el nombre service-<project_number>@gcp-sa-bigquerydatatransfer.iam.gserviceaccount.com y se le otorga el rol de agente de 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 Cómo controlar el acceso a través de la consola de Google Cloud para otorgar el rol de 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 Cómo establecer 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 del uso de la cuota: Cuando el agente del Servicio de transferencia de datos de BigQuery accede a la suscripción de Pub/Sub, el uso de la cuota se cobra en el proyecto del usuario.

  3. Verifica que al agente de Servicio de transferencia de datos de BigQuery se le haya 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 notificaciones y 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

Puedes crear una transferencia de Cloud Storage basada en eventos creando una transferencia de Cloud Storage y seleccionando Basada en eventos como el Tipo de programación. 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 automáticamente Cloud Storage para enviar notificaciones.

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