Transferencias de Cloud Storage

El Servicio de transferencia de datos de BigQuery para Cloud Storage te permite programar cargas de datos recurrentes de Cloud Storage a BigQuery.

Antes de comenzar

Antes de crear una transferencia de Cloud Storage, sigue estos pasos:

Verifica si completaste todas las acciones requeridas en la página sobre cómo habilitar el Servicio de transferencia de datos de BigQuery.
Recupera tu URI de Cloud Storage.
Permite las ventanas emergentes en tu navegador desde bigquery.cloud.google.com para que puedas ver la ventana de permisos. Debes otorgar permiso al Servicio de transferencia de datos de BigQuery para que controle tu transferencia.
Crea un conjunto de datos de BigQuery para almacenar tus datos.
Crea la tabla de destino para tu transferencia y especifica la definición de esquema.

Limitaciones

Las transferencias recurrentes de Cloud Storage a BigQuery están sujetas a las siguientes limitaciones:

Todos los archivos que coincidan con los patrones que define un comodín o los parámetros del entorno de ejecución de tu transferencia deben compartir el mismo esquema que definiste para la tabla de destino, de lo contrario, la transferencia fallará. Los cambios en el esquema de tabla entre ejecuciones también hacen que la transferencia falle.
Debido a que se pueden crear versiones de los objetos de Cloud Storage, es importante que tengas en cuenta que las transferencias de BigQuery no admiten objetos archivados de Cloud Storage. Los objetos deben estar activos para que se puedan transferir.
A diferencia de las cargas individuales de datos de Cloud Storage a BigQuery, para las transferencias en curso, debes crear la tabla de destino y el esquema antes de configurar la transferencia. BigQuery no puede crear la tabla como parte del proceso de transferencia de datos recurrentes.
Las transferencias de Cloud Storage siempre se activan con la preferencia WRITE_APPEND que agrega datos a la tabla de destino. Consulta configuration.load.writeDisposition en la configuración del trabajo load para obtener detalles adicionales.
El Servicio de transferencia de datos de BigQuery no garantiza que todos los archivos se transfieran o transfieran solo una vez si se manipulan los archivos de Cloud Storage durante la transferencia.
Si la ubicación de tu conjunto de datos está configurada en un valor diferente a US, el depósito de Cloud Storage regional o multirregional debe estar en la misma región que el conjunto de datos.
El Servicio de transferencia de datos de BigQuery no garantiza la coherencia de los datos para las fuentes de datos externas. Los cambios en los datos subyacentes mientras se ejecuta una consulta pueden dar como resultado un comportamiento inesperado.
Según el formato de tus datos de origen de Cloud Storage, puede haber limitaciones adicionales. Para obtener más información, consulta:
Tu depósito de Cloud Storage debe estar en una región o multirregión compatible con la región o multirregión del conjunto de datos de destino en BigQuery. Esto se conoce como colocación. Consulta las ubicaciones de datos de transferencia de Cloud Storage para obtener más información.

Intervalos mínimos

Los archivos de origen en Cloud Storage deben tener al menos una hora de antigüedad para que la transferencia los recopile.
El tiempo de intervalo mínimo entre transferencias recurrentes es de 1 hora. El intervalo predeterminado para una transferencia recurrente es cada 24 horas.

Permisos necesarios

Cuando cargas datos en BigQuery, necesitas permisos para cargar datos en tablas y particiones de BigQuery nuevas o existentes. Si cargas datos de Cloud Storage, también necesitarás acceso al depósito que contiene tus datos. Asegúrate de que tienes los siguientes permisos necesarios:

BigQuery: Se requieren permisos bigquery.transfers.update para crear la transferencia programada. La función de IAM predefinida bigquery.admin incluye los permisos bigquery.transfers.update. Para obtener más información sobre las funciones de IAM en el Servicio de transferencia de datos de BigQuery, consulta la referencia del control de acceso.
Cloud Storage: Se requieren permisos storage.objects.get en el depósito individual o superior. Si usas un comodín de URI, también debes tener permisos storage.objects.list. Si deseas borrar los archivos de origen después de cada transferencia exitosa, también necesitas permisos storage.objects.delete. La función predefinida IAM de storage.objectAdmin incluye todos estos permisos.

Configura una transferencia de Cloud Storage

Para crear una transferencia de Cloud Storage en el Servicio de transferencia de datos de BigQuery, sigue estos pasos:

Console

Ve a la página de BigQuery en Cloud Console.

Ir a la página de BigQuery
Haz clic en Transfers.
Haz clic en Crear.
En la página Crear transferencia, sigue estos pasos:
- En la sección Tipo de fuente (Source type), para Fuente (Source), elige Cloud Storage.
- En la sección Nombre de la configuración de transferencia (Transfer config name), en Nombre visible (Display name), ingresa el nombre de la transferencia, como My Transfer. El nombre de la transferencia puede ser cualquier valor que te permita identificarla con facilidad si es necesario hacerle modificaciones más tarde.
- En la sección Opciones de programa (Schedule options), en Programa, deja el valor predeterminado, Comenzar ahora (Start now), o haz clic en Comenzar a una hora determinada (Start at a set time).
  - En Repeticiones (Repeats), selecciona una opción para la frecuencia con la que se ejecutará la transferencia. El intervalo mínimo es de 1 hora.
    - Diaria (predeterminada)
    - Semanal
    - Mensual
    - Personalizada
    - A pedido
  - En Fecha de inicio y hora de ejecución (Start date and run time), ingresa la fecha y hora para iniciar la transferencia. Si seleccionas Comenzar ahora (Start now), esta opción se inhabilitará.
- En la sección Configuración de destino (Destination settings), en Conjunto de datos de destino (Destination dataset), selecciona el conjunto de datos que creaste para almacenar tus datos.
- En la sección Detalles de fuente de datos (Data source details), haz lo siguiente:
  - En Tabla de destino (Destination table), ingresa el nombre de tu tabla de destino. 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.
  - En el URI de Cloud Storage (Cloud Storage URI), ingresa los URI de Cloud Storage. Se admiten comodines y parámetros.
  - En Preferencia de escritura (Write preference), elige una de las siguientes opciones:
    - ADJUNTAR (APPEND) para agregar datos nuevos a tu tabla de destino existente o
    - DUPLICAR para actualizar los datos dentro de la tabla de destino y reflejar los datos modificados en la fuente. DUPLICAR reemplaza una copia nueva de los datos en la tabla de destino.
    Nota: Si lo que ingresó en el campo URI de Cloud Storage no coincide con ningún archivo, no actualizaremos (reemplazar) datos en la tabla de destino.
  - En Borrar archivos de origen después de la transferencia (Delete source files after transfer), marca la casilla si quieres borrar los archivos de origen después de cada transferencia exitosa. Los trabajos de borrado son el mejor esfuerzo. Los trabajos de borrado no se vuelven a intentar si el primer esfuerzo para borrar los archivos de origen falló.
  - En la sección Opciones de transferencia (Transfer Options), sigue estos pasos:
    - En Todos los formatos (All Formats), haz lo siguiente:
      - En Cantidad de errores permitidos (Number of errors allowed), ingresa la cantidad máxima de registros erróneos que BigQuery puede ignorar cuando ejecute el trabajo. Si la cantidad de registros erróneos supera este valor, el trabajo falla y se muestra un error de validez en el resultado. El valor predeterminado es 0.
    - En JSON, CSV, haz lo siguiente:
      - En Ignorar valores desconocidos (Ignore unknown values), marca la casilla si quieres que la transferencia descarte los datos que no coincidan con el esquema de la tabla de destino.
    - En CSV, haz lo siguiente:
      - En Delimitador de campo (Field delimiter), ingresa el carácter que separa los campos. El valor predeterminado es una coma.
      - En Filas de encabezado para omitir (Header rows to skip), ingresa la cantidad de filas de encabezado de los archivos de origen si no quieres importarlas. El valor predeterminado es 0.
      - En Permitir saltos de línea con comillas (Allow quoted newlines), marca la casilla si quieres permitir saltos de línea en campos entrecomillados.
      - En Permitir filas irregulares (Allow jagged rows), marca la casilla de verificación si quieres permitir que se transfieran filas con columnas NULLABLE faltantes.
      Nota: Consulta las opciones exclusivas de CSV para obtener más información.
- De forma opcional, en la sección Opciones de notificación (Notifications options), haz lo siguiente:
  - Haz clic en el botón de activación para habilitar las notificaciones por correo electrónico. Cuando habilitas esta opción, el administrador de transferencias recibe una notificación por correo electrónico cuando falla una ejecución de transferencia.
  - En Seleccionar un tema de Cloud Pub/Sub (Select a Cloud Pub/Sub topic), elige el nombre de tu tema o haz clic en Crear un tema (Create a topic). Con esta opción, se configuran las notificaciones de ejecución de Pub/Sub para tu transferencia.
Haz clic en Guardar (Save).

IU clásica

Ve a la IU web de BigQuery.

Ir a IU web de BigQuery
Haz clic en Transferencias.
Haz clic en Agregar transferencia.
En la página Transferencia nueva (New Transfer), sigue estos pasos:
- En Fuente (Source), selecciona Cloud Storage.
- En Nombre visible (Display name), ingresa un nombre para la transferencia, como My Transfer. El nombre visible puede ser cualquier valor que te permita identificar con facilidad la transferencia si necesitas modificarla más tarde.
- De forma opcional, en Programa (Schedule), puedes dejar el valor predeterminado de Diaria (cada 24 horas, según el tiempo de creación) o puedes hacer clic en Editar para cambiar la hora. También puedes cambiar el intervalo a Semanal, Mensual o Personalizada. Cuando seleccionas Personalizada, se espera una especificación de tiempo similar a Cron, por ejemplo, every 12 hours. El intervalo mínimo es de 1 hora. Consulta el campo schedule en TransferConfig para obtener más valores de API válidos.
- En Conjunto de datos de destino (Destination dataset), selecciona el conjunto de datos que corresponda.
- En Tabla de destino (Destination table), ingresa el nombre de tu tabla de destino. 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.
- En URI de Cloud Storage (Cloud Storage URI), ingresa los URI de Cloud Storage. Se admiten comodines y parámetros.
- En Borrar archivos de origen después de la transferencia (Delete source files after transfer), marca la casilla si quieres borrar los archivos de origen después de cada transferencia exitosa. Los trabajos de borrado son el mejor esfuerzo. Los trabajos de borrado no se vuelven a intentar si el primer esfuerzo para borrar los archivos de origen falló.
- En Formato de archivo (File format), selecciona los tipos de archivos que deseas transferir.
- En la sección Transfer Options - All Formats (Opciones de transferencia: todos los formatos), realiza lo siguiente:
  - En Cantidad de errores permitidos (Number of errors allowed), ingresa la cantidad máxima de registros erróneos que BigQuery puede ignorar cuando ejecute el trabajo. Si la cantidad de registros erróneos supera este valor, el trabajo falla y se muestra un error de validez en el resultado. El valor predeterminado es 0.
- En la sección Opciones de transferencia: JSON, CSV (Transfer Options - JSON, CSV), realiza lo siguiente:
  - En Ignorar valores desconocidos, marca la casilla si quieres que la transferencia descarte los datos que no coincidan con el esquema de la tabla de destino.
- En la sección Opciones de transferencia: CSV (Transfer Options - CSV), realiza lo siguiente:
  - En Field delimiter (Delimitador de campo), ingresa el carácter que separa los campos. El valor predeterminado es una coma.
  - En Filas de encabezado para omitir (Header rows to skip), ingresa la cantidad de filas de encabezado de los archivos de origen si no quieres importarlas. El valor predeterminado es 0.
  - En Permitir saltos de línea con comillas (Allow quoted newlines), marca la casilla si quieres permitir saltos de línea en campos entrecomillados.
  - En Permitir filas irregulares (Allow jagged rows), marca la casilla si quieres permitir que se transfieran filas con columnas NULLABLE faltantes.
  Nota: Consulta las opciones exclusivas de CSV para obtener más información.
- De forma opcional, expande la sección Avanzado (Advanced) y configura las notificaciones de ejecución para tu transferencia.
- En Tema de Cloud Pub/Sub (Cloud Pub/Sub topic), ingresa el nombre de tu tema de Cloud Pub/Sub, por ejemplo, projects/myproject/topics/mytopic.
- Marca Enviar notificaciones por correo electrónico (Send email notifications) para activar las notificaciones por correo de las ejecuciones de transferencia con errores.
Haga clic en Add.

bq

Ingresa el comando bq mk y suministra la marca de creación de transferencias --transfer_config. También se requieren las siguientes marcas:

--data_source
--display_name
--target_dataset
--params

bq mk \
--transfer_config \
--project_id=project_id \
--data_source=data_source \
--display_name=name \
--target_dataset=dataset \
--params='parameters'

Aquí:

project_id es el ID del proyecto. Si no proporcionas --project_id para especificar un proyecto en particular, se usa el proyecto predeterminado.
data_source es la fuente de datos: google_cloud_storage.
name es el nombre visible de la configuración de transferencia. El nombre de la transferencia puede ser cualquier valor que te permita identificarla con facilidad si necesitas modificarla más tarde.
dataset es el conjunto de datos de destino para la configuración de la transferencia.
parameters contiene los parámetros para la configuración de la transferencia creada en formato JSON. Por ejemplo: --params='{"param":"param_value"}'
- Para Cloud Storage, debes proporcionar los parámetros data_path_template, destination_table_name_template y file_format. data_path_template es el URI de Cloud Storage que contiene los archivos que se van a transferir, que puede incluir un comodín. destination_table_name_template es el nombre de tu tabla de destino Para file_format, indica el tipo de archivos que deseas transferir: CSV, JSON, AVRO, PARQUET o ORC. El valor predeterminado es CSV.
- Para todos los valores file_format, puedes incluir el parámetro opcional max_bad_records. El valor predeterminado es 0.
- Para los valores JSON o CSV en file_format, puedes incluir el parámetro opcional ignore_unknown_values. Este parámetro se ignorará si no has seleccionado CSV o JSON para file_format.
- Para file_format de CSV, puedes incluir el parámetro opcional field_delimiter del carácter que separa los campos. El valor predeterminado es una coma. Este parámetro se ignorará si no has seleccionado CSV para file_format.
- Para el file_format de CSV, puedes incluir el parámetro skip_leading_rows opcional a fin de indicar las filas de encabezado que no deseas importar. El valor predeterminado es 0. Este parámetro se ignorará si no has seleccionado CSV para file_format.
- Para file_format de CSV, puedes incluir el parámetro opcional allow_quoted_newlines si deseas permitir saltos de línea dentro de los campos entre comillas. Este parámetro se ignorará si no has seleccionado CSV para file_format.
- Para file_format de CVS, puedes incluir el parámetro opcional allow_jagged_rows si deseas aceptar filas a las que les faltan columnas opcionales finales. Los valores que faltan se llenarán con valores NULL. Este parámetro se ignorará si no has seleccionado CSV para file_format.
- El parámetro opcional delete_source_files borrará los archivos de origen después de cada transferencia exitosa. Los trabajos de borrado no se vuelven a intentar si el primer esfuerzo para borrar los archivos de origen falló. El valor predeterminado de delete_source_files es falso.

Por ejemplo, con el siguiente comando se crea una transferencia de Cloud Storage llamada My Transfer mediante un valor data_path_template de gs://mybucket/myfile/*.csv, el conjunto de datos de destino mydataset y el CSV como file_format. En este ejemplo, se incluyen valores no predeterminados para los parámetros opcionales asociados con el file_format CSV.

La transferencia se crea en el proyecto predeterminado:

bq mk --transfer_config \
--target_dataset=mydataset \
--display_name='My Transfer' \
--params='{"data_path_template":"gs://mybucket/myfile/*.csv",
"destination_table_name_template":"MyTable",
"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",
"delete_source_files":"true"}' \
--data_source=google_cloud_storage

Después de ejecutar el comando, recibirás un mensaje como el siguiente:

[URL omitted] Please copy and paste the above URL into your web browser and follow the instructions to retrieve an authentication code.

Sigue las instrucciones y pega el código de autenticación en la línea de comandos.

API

Usa el método projects.locations.transferConfigs.create y proporciona una instancia del recurso TransferConfig.

Configura una ejecución de actualización de una transferencia

Además de configurar una transferencia recurrente desde Cloud Storage, también puedes configurar una ejecución de actualización para recopilar archivos de datos adicionales.

Si la configuración de la transferencia está relacionada con la fecha (parametrizada), el URI de Cloud Storage está parametrizado o ambos lo están, puedes ejecutar la actualización para fechas específicas.

Para configurar una actualización de transferencia, sigue estos pasos:

Console

Ve a la página de BigQuery en Cloud Console.

Ir a la página de BigQuery
Haz clic en Transfers.
Haz clic en tu transferencia.
Haz clic en el menú Más y, luego, selecciona Actualizar transferencia.
En el cuadro de diálogo Programar la ejecución de un reabastecimiento (Schedule a backfill run), elige la Fecha de inicio (Start date) y la Fecha de finalización (End date). Puedes usar la IU web clásica de BigQuery para establecer límites de tiempo más precisos.

Nota: Si la configuración de la transferencia de Cloud Storage no está parametrizada, no verás las opciones de fecha cuando hagas clic en Actualizar transferencia. En cambio, la actualización se realizará de inmediato cuando hagas clic en Programar (Schedule).

Los archivos deben tener una hora de antigüedad como mínimo para que se puedan recopilar en una actualización de la transferencia.

IU clásica

Ve a la IU web de BigQuery.

Ir a IU web de BigQuery
Haz clic en Transfers.
Haz clic en tu transferencia.
Haz clic en Actualizar transferencia (Refresh Transfer).
En el cuadro de diálogo Iniciar ejecuciones de transferencias (Start Transfer Runs), elige la Hora de inicio (Start Time) y Hora de finalización (End Time).

Si la configuración de tu transferencia de Cloud Storage no está parametrizada, no tendrás opciones de fechas cuando hagas clic en Actualizar transferencia. En cambio, la actualización sucederá de inmediato.

Nota: Los archivos deben tener al menos una hora de antigüedad para que se recopilen en una transferencia de actualización.
Haz clic en Aceptar (OK).

Próximos pasos

Obtén información sobre cómo usar los parámetros del entorno de ejecución en las transferencias de Cloud Storage
Obtén más información sobre el Servicio de transferencia de datos de BigQuery