Transferencias de Blob Storage
El conector del Servicio de transferencia de datos de BigQuery para Azure Blob Storage te permite administrar y programar de manera automática trabajos de carga recurrentes de Blob Storage en BigQuery.
Antes de comenzar
Antes de crear una transferencia de datos de Blob Storage, haz lo siguiente:
- Verifica si completaste todas las acciones necesarias para habilitar el Servicio de transferencia de datos de BigQuery
- Elige un conjunto de datos de BigQuery existente o crea uno nuevo para almacenar tus datos.
- Elige una tabla de BigQuery existente o crea una tabla de destino nueva para tu transferencia de datos y especifica la definición de esquema. La tabla de destino debe seguir las reglas de nombres de las tablas. Los nombres de las tablas de destino también admiten parámetros.
- Recupera el nombre de la cuenta de almacenamiento de Blob Storage, el nombre del contenedor, la ruta de acceso de los datos (opcional) y el token SAS. Para obtener información sobre cómo otorgar acceso a Blob Storage con una firma de acceso compartido (SAS), consulta Firma de acceso compartido (SAS).
- Si restringes el acceso a los recursos de Azure a través de un firewall de Azure Storage, agrega trabajadores del Servicio de transferencia de datos de BigQuery a la lista de IPs permitidas.
- Si planeas especificar una clave de encriptación administrada por el cliente (CMEK), asegúrate de que tu cuenta de servicio tenga permisos para encriptar y desencriptar y de tener el ID de recurso clave de Cloud KMS necesario para usar CMEK. Para obtener información sobre cómo funciona CMEK con el Servicio de transferencia de datos de BigQuery, consulta Especifica una clave de encriptación con transferencias.
Permisos necesarios
Para crear una transferencia de datos de Blob Storage, necesitas el permiso bigquery.transfers.update
de Identity and Access Management (IAM). También necesitas los permisos bigquery.datasets.get
y bigquery.datasets.update
en el conjunto de datos de destino.
El rol predefinido de IAM bigquery.admin
incluye los permisos que necesitas para crear una transferencia de datos de Blob Storage.
Para obtener más información sobre IAM de BigQuery, consulta Control de acceso con IAM.
Para confirmar que tienes los permisos correctos en Blob Storage a fin de habilitar la transferencia de datos, consulta Firma de acceso compartido (SAS).
Si quieres configurar las notificaciones de ejecución de transferencias para Pub/Sub, debes tener el permiso pubsub.topics.setIamPolicy
.
Los permisos de Pub/Sub solo son necesarios para las notificaciones por correo electrónico. Para obtener más información, consulta la sección sobre notificaciones de ejecución del Servicio de transferencia de datos de BigQuery.
Limitaciones
Las transferencias de datos de Blob Storage están sujetas a las siguientes limitaciones:
- El tiempo de intervalo mínimo entre transferencias de datos recurrentes es de 1 hora. El intervalo predeterminado es de 24 horas.
- Según el formato de tus datos de origen de Blob Storage, puede haber limitaciones adicionales.
- No se admiten las transferencias de datos a ubicaciones de BigQuery Omni.
Configura una transferencia de datos de Blob Storage
Selecciona una de las opciones siguientes:
Console
Ve a la página Transferencia de datos en la consola de Google Cloud.
Haz clic en
Crear transferencia.En la página Crear transferencia, haz lo siguiente:
En la sección Tipo de fuente, en Fuente, elige Azure Blob Storage.
En la sección Nombre de configuración de la transferencia (Transfer config name), en Nombre visible (Display name), ingresa el nombre de la transferencia de datos.
En la sección Opciones de programación, haz lo siguiente:
Selecciona una Frecuencia de repetición. Si seleccionas Horas, Días, Semanas o Meses, también debes especificar una frecuencia. También puedes seleccionar Personalizado para especificar una frecuencia de repetición personalizada. Si seleccionas Según demanda, esta transferencia de datos se ejecuta cuando activas la transferencia de forma manual.
Si corresponde, selecciona Comenzar ahora o Comenzar a una hora determinada y proporciona una fecha de inicio y una hora de ejecución.
En la sección Configuración de destino, en Conjunto de datos de destino, selecciona el conjunto de datos que creaste para almacenar tus datos.
En la sección Detalles de fuente de datos, haz lo siguiente:
- En Tabla de destino, ingresa el nombre de la tabla que creaste para almacenar los datos en BigQuery. Los nombres de las tablas de destino admiten parámetros.
- En Nombre de la cuenta de almacenamiento de Azure, ingresa el nombre de la cuenta de Blob Storage.
- En Nombre del contenedor, ingresa el nombre del contenedor de Blob Storage.
- En Ruta de acceso a los datos, ingresa la ruta para filtrar los archivos que se transferirán. Ve ejemplos.
- En Token SAS, ingresa el token SAS de Azure.
- En Formato de archivo, elige el formato de datos de origen.
- En Disposición de escritura, selecciona
WRITE_APPEND
para agregar datos nuevos de forma incremental a la tabla de destino oWRITE_TRUNCATE
para reemplazar datos en la tabla de destino durante cada ejecución de transferencia.WRITE_APPEND
es el valor predeterminado para la disposición de escritura.
Si deseas obtener más información sobre cómo el Servicio de transferencia de datos de BigQuery transfiere datos mediante
WRITE_APPEND
oWRITE_TRUNCATE
, consulta Transferencia de datos para transferencias de Azure Blob Para obtener más información sobre el campowriteDisposition
, consultaJobConfigurationLoad
.En la sección Opciones de transferencia, haz lo siguiente:
- En Cantidad de errores permitidos, ingresa un valor entero para la cantidad máxima de registros erróneos que se pueden ignorar. El valor predeterminado es 0.
- (Opcional) En Tipos de destino decimales, ingresa una lista separada por comas de tipos de datos de SQL posibles en los que se conviertan los valores decimales en los datos de origen. El tipo de datos SQL que se selecciona para la conversión depende de las siguientes condiciones:
- En el orden de
NUMERIC
,BIGNUMERIC
ySTRING
, se elige un tipo si está en la lista especificada y si admite la precisión y el escalamiento. - Si ninguno de los tipos de datos enumerados admite la precisión y el escalamiento, se selecciona el tipo de datos que admite el rango más amplio en la lista que especificaste. Se muestra un error si un valor excede el rango admitido cuando se leen los datos de origen.
- El tipo de datos
STRING
admite todos los valores de precisión y escalamiento. - Si este campo se deja vacío, el tipo de datos predeterminado es
NUMERIC,STRING
para ORC yNUMERIC
para otros formatos de archivo. - Este campo no puede contener tipos de datos duplicados.
- Se ignora el orden de los tipos de datos que enumeras.
- En el orden de
Si eliges los formatos de archivo CSV o JSON, en la sección JSON, CSV, marca Ignorar valores desconocidos para aceptar las filas con valores que no coinciden con el esquema.
Si elegiste CSV como formato de archivo, en la sección CSV ingresa cualquier opción de CSV adicional para cargar datos.
En la sección Opciones de notificación, puedes elegir habilitar las notificaciones por correo electrónico y las notificaciones de Pub/Sub.
- Si habilitas las notificaciones por correo electrónico, el administrador de transferencias recibirá una notificación por correo electrónico cuando falle la ejecución de una transferencia.
- Cuando habilitas Notificaciones de Pub/Sub, elige un nombre de tema para publicar o haz clic en Cree un tema para crear uno.
Si usas CMEKs, en la sección Opciones avanzadas, selecciona Clave administrada por el cliente. Aparecerá una lista de las CMEKs disponibles para que elijas. Para obtener información del funcionamiento las CMEKs con el Servicio de transferencia de datos de BigQuery, consulta Especifica la clave de encriptación con transferencias.
Haz clic en Guardar.
bq
Usa el comando bq mk --transfer_config
para crear una transferencia de Blob Storage:
bq mk \ --transfer_config \ --project_id=PROJECT_ID \ --data_source=DATA_SOURCE \ --display_name=DISPLAY_NAME \ --target_dataset=DATASET \ --destination_kms_key=DESTINATION_KEY \ --params=PARAMETERS
Reemplaza lo siguiente:
PROJECT_ID
: (Opcional) el ID del proyecto que contiene tu conjunto de datos de destino. Si no se especifica, se usa el proyecto predeterminado.DATA_SOURCE
:azure_blob_storage
.DISPLAY_NAME
: el nombre visible de la configuración de transferencia de datos. El nombre de la transferencia puede ser cualquier valor que te permita identificarla con facilidad si es necesario hacerle modificaciones más tarde.DATASET
: el conjunto de datos de destino para la configuración de transferencia de datos.DESTINATION_KEY
: (Opcional) el ID de recurso clave de Cloud KMS, por ejemplo,projects/project_name/locations/us/keyRings/key_ring_name/cryptoKeys/key_name
.PARAMETERS
son los parámetros de la configuración de la transferencia de datos en formato JSON. Por ejemplo,--params={"param1":"value1", "param2":"value2"}
Los siguientes son los parámetros para una transferencia de datos de Blob Storage:destination_table_name_template
: Obligatorio. El nombre de la tabla de destino.storage_account
: Obligatorio. El nombre de la cuenta de Blob Storage.container
: Obligatorio. El nombre del contenedor de Blob Storage.data_path
: Opcional La ruta para filtrar los archivos que se transferirán. Ve ejemplos.sas_token
: Obligatorio. El token SAS de Azure.file_format
: Opcional El tipo de archivos que deseas transferir:CSV
,JSON
,AVRO
,PARQUET
oORC
. El valor predeterminado esCSV
.write_disposition
: Opcional SeleccionaWRITE_APPEND
para agregar datos a la tabla de destino, oWRITE_TRUNCATE
, si quieres reemplazar datos en la tabla de destino. El valor predeterminado esWRITE_APPEND
.max_bad_records
: Opcional La cantidad de registros erróneos permitidos. El valor predeterminado es 0.decimal_target_types
: Opcional Una lista separada por comas de tipos de datos de SQL posibles en los que se convierten los valores decimales en los datos de origen. Si no se proporciona este campo, el tipo de datos predeterminado esNUMERIC,STRING
para ORC yNUMERIC
para los otros formatos de archivo.ignore_unknown_values
: Opcional y, también, ignorado sifile_format
no esJSON
niCSV
. Configúralo comotrue
para aceptar filas que contengan valores que no coincidan con el esquema.field_delimiter
: Opcional y solo se aplica cuandofile_format
esCSV
. El carácter que separa los campos. El valor predeterminado es,
.skip_leading_rows
: Opcional y solo se aplica cuandofile_format
esCSV
. Indica la cantidad de filas de encabezado que no deseas importar. El valor predeterminado es 0.allow_quoted_newlines
: Opcional y solo se aplica cuandofile_format
esCSV
. Indica si se permiten saltos de líneas dentro de los campos entre comillas.allow_jagged_rows
: Opcional y solo se aplica cuandofile_format
esCSV
. Indica si se aceptan filas a las que les faltan columnas opcionales finales. Los valores faltantes se completan conNULL
.
Por ejemplo, lo siguiente crea una transferencia de datos de Blob Storage llamada mytransfer
:
bq mk \ --transfer_config \ --data_source=azure_blob_storage \ --display_name=mytransfer \ --target_dataset=mydataset \ --destination_kms_key=projects/myproject/locations/us/keyRings/mykeyring/cryptoKeys/key1 --params={"destination_table_name_template":"mytable", "storage_account":"myaccount", "container":"mycontainer", "data_path":"myfolder/*.csv", "sas_token":"my_sas_token_value", "file_format":"CSV", "max_bad_records":"1", "ignore_unknown_values":"true", "field_delimiter":"|", "skip_leading_rows":"1", "allow_quoted_newlines":"true", "allow_jagged_rows":"false"}
API
Usa el método projects.locations.transferConfigs.create
y suministra una instancia del recurso TransferConfig
.
Java
Antes de probar este ejemplo, sigue las instrucciones de configuración para Java incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.
Especifica la clave de encriptación con transferencias
Puedes especificar claves de encriptación administradas por el cliente (CMEKs) para encriptar los datos de una ejecución de transferencia. Puedes usar una CMEK para admitir transferencias de Azure Blob Storage.Cuando especificas una CMEK con una transferencia, el Servicio de transferencia de datos de BigQuery aplica la CMEK a cualquier memoria caché del disco intermedia de datos transferidos para que todo el flujo de trabajo de transferencia de datos cumpla con la CMEK.
No puedes actualizar una transferencia existente para agregar una CMEK si la transferencia no se creó en un principio con una CMEK. Por ejemplo, no puedes cambiar una tabla de destino que se encriptó de forma predeterminada para que ahora se encripte con CMEK. Por el contrario, tampoco puedes cambiar una tabla de destino encriptada con CMEK para que tenga un tipo de encriptación diferente.
Puedes actualizar una CMEK para una transferencia si la configuración de la transferencia se creó en un principio con una encriptación de CMEK. Cuando actualizas una CMEK para una configuración de transferencia, el Servicio de transferencia de datos de BigQuery propaga la CMEK a las tablas de destino en la siguiente ejecución de la transferencia, en la que el Servicio de transferencia de datos de BigQuery reemplaza cualquier CMEK desactualizada por la CMEK nueva durante la ejecución de la transferencia. Para obtener más información, consulta Actualiza una transferencia.
También puedes usar las claves predeterminadas del proyecto. Cuando especificas una clave predeterminada de proyecto con una transferencia, el Servicio de transferencia de datos de BigQuery usa la clave predeterminada del proyecto como la clave predeterminada para cualquier configuración de transferencia nueva.
Soluciona problemas con la configuración de una transferencia
Si tienes problemas para configurar tu transferencia datos, consulta Problemas de transferencia de Blob Storage.
¿Qué sigue?
- Obtén más información sobre los parámetros de entorno de ejecución en las transferencias.
- Obtén más información acerca del Servicio de transferencia de datos de BigQuery.
- Obtén más información sobre cómo cargar datos con operaciones entre nubes.