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 transferencias incrementales de datos que optimicen 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 de datos inmediata, 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, considera si necesitas priorizar la transferencia incremental de lotes rentable con transferencias basadas en eventos o si prefieres la flexibilidad de la API de Storage Write.

Fuentes de datos compatibles con las transferencias centradas 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 que llegue un evento dentro de ese tiempo.
  • Las transferencias controladas por eventos no admiten parámetros de tiempo de ejecución para el URI de origen o la ruta de acceso de datos.
  • Varias configuraciones de transferencia basadas en eventos no pueden reutilizar la misma suscripción a Pub/Sub.

Configura una transferencia basada en eventos de Cloud Storage

Las transferencias impulsadas 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 usas el modo de transferencia incremental, borrar un objeto del 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 seguir estos 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 al administrador que te otorgue los roles roles/storage.admin y roles/pubsub.admin, o pídele 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 preconfigurada de Pub/Sub para crear una configuración de transferencia basada en eventos.

  4. Permisos detallados necesarios para configurar notificaciones de configuración de transferencia basada en eventos:

Cómo configurar 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: Es el nombre del bucket de Cloud Storage en 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 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 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 en la lista 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.

      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 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 Google Cloud consola 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 del tema, la suscripción o el proyecto.

    gcloud CLI

    Sigue las instrucciones que se indican en Cómo configurar 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 del Servicio de transferencia de datos de BigQuery se le otorgue el rol 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 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 notificaciones y 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 basada en eventos, crea una transferencia de Cloud Storage y selecciona Basada en eventos como Tipo de programación. Como administrador de Cloud Storage (roles/storage.admin) y 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 que envíe 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.