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:

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 estos vínculos:

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 predefinida bigquery.admin de Cloud IAM incluye los permisos bigquery.transfers.update. Para obtener más información sobre las funciones de Cloud IAM en el Servicio de transferencia de datos de BigQuery, consulta la página de la referencia de 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 storage.objectAdmin de Cloud IAM 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

  1. Ve a Cloud Console.

    Ir a Cloud Console

  2. Haz clic en Transferencias.

  3. Haz clic en Crear.

  4. En la página Crear transferencia, sigue estos pasos:

    • En la sección Tipo de fuente (Source type), para Fuente (Source), elige Cloud Storage.

      Fuente de transferencia

    • 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.

      Nombre de la transferencia

    • 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á.

        Programa de la transferencia

    • 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.

      Conjunto de datos de la transferencia

    • 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 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.

      Detalles de la fuente de Cloud Storage

    • 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. Si habilitas esta opción, el administrador de transferencias recibirá una notificación por correo electrónico cuando falle la ejecución de una transferencia.
      • En Selecciona un tema de Pub/Sub (Select a Pub/Sub topic), elige el nombre de tu tema o haz clic en Crear un tema. Con esta opción, se configuran las notificaciones de ejecución de Pub/Sub para tu transferencia.
  5. Haz clic en Guardar (Save).

IU clásica

  1. Ve a la IU web de BigQuery.

    Ir a la IU web de BigQuery

  2. Haz clic en Transferencias (Transfers).

  3. Haz clic en Agregar transferencia.

  4. 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.

      Programa de la transferencia

    • 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.

      Transferencia de Cloud Storage nueva

    • 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.

      Tema de Cloud Pub/Sub

  5. Haz clic en Agregar.

CLI

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'

En el ejemplo anterior, se ilustra lo siguiente:

  • 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 la 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 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

  1. Abre Cloud Console.

    Ir a Cloud Console

  2. Haz clic en Transferencias.

  3. Haz clic en tu transferencia.

  4. Haz clic en el menú Más y, luego, selecciona Actualizar transferencia.

  5. 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.

    Configurar fechas de actualización

IU clásica

  1. Ve a la IU web de BigQuery.

    Ir a la IU web de BigQuery

  2. Haz clic en Transfers.

  3. Haz clic en tu transferencia.

  4. Haz clic en Actualizar transferencia (Refresh Transfer).

    Actualizar transferencia

  5. 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).

    Configurar fechas de actualización

    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.

    Actualizar de inmediato

  6. Haz clic en Aceptar (OK).

Próximos pasos