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 de datos incremental que optimice la eficiencia de costos.

Cuando configuras transferencias basadas en eventos, puede haber una demora de unos minutos entre cada transferencia de datos. Si necesitas disponibilidad inmediata de datos, te recomendamos que uses la API de Storage Write, que transmite datos directamente a BigQuery con la menor latencia 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 por lotes incremental rentable 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 basadas en eventos no admiten parámetros de tiempo de ejecución para el URI de origen o la ruta de datos.
  • Varias configuraciones de transferencia basadas en eventos no pueden reutilizar la misma suscripción de Pub/Sub.

Configura una transferencia basada en eventos de Cloud Storage

Las transferencias basadas en eventos de 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 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 de 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 basadas en eventos:

Configura las 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 en el que deseas activar eventos de notificación de archivos
    • TOPIC_NAME: 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 notificación 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 realiza de forma correcta, la respuesta se verá como 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. Busca el nombre del agente de Servicio de transferencia de datos de BigQuery para tu proyecto:

    1. Ve 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 de 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 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 de 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 Google Cloud consola para otorgar el Pub/Sub Subscriber rol al agente de servicio de Servicio de transferencia de datos de BigQuery. El rol se puede otorgar a nivel del tema, la suscripción o el proyecto.

    CLI de gcloud

    Sigue las instrucciones que se indican en Establece 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 la transferencia y en el que se crean y facturan los recursos.

    Atribución del uso de la cuota: Cuando el agente de 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 otorgue el rol de suscriptor de Pub/Sub (pubsub.subscriber).

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

      Ir a Pub/Sub

    2. Selecciona la suscripción de 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 de 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: Un nombre para identificar esta configuración de transferencia

Crea una configuración de transferencia

Para crear una transferencia basada en eventos de Cloud Storage, crea una transferencia de Cloud Storage y selecciona 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 notificaciones de Pub/Sub necesarias en las configuraciones de Cloud Storage y las configuraciones de permisos del agente de servicio antes de que puedas crear la transferencia basada en eventos.