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.
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. Para obtener más información, consulta la descripción del campo writeDisposition del objeto JobConfigurationLoad.
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

Se recogen los archivos de origen para su transferencia inmediatamente, sin una edad de archivo mínima.
El tiempo mínimo de intervalo entre transferencias recurrentes es de 15 minutos. 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 bucket 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 de IAM predefinida 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 15 minutos.
    - Diariamente (predeterminada)
    - Semanal
    - Mensual
    - Personalizada. En Programación personalizada, ingresa una frecuencia personalizada. por ejemplo, every day 00:00. Consulta Da formato a la programación.
    - 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):
  - En Tabla de destino, 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.
      - (Opcional) En Tipos de objetivo decimal, ingresa una lista separada por comas de tipos de datos SQL posibles en los que se puedan convertir los valores decimales de origen. El tipo de datos de SQL que se selecciona para la conversión depende de las siguientes condiciones:
        
        El tipo de datos seleccionado para la conversión será el primer tipo de datos de la siguiente lista que admite la precisión y la escala de los datos de origen, en este orden: NUMERIC, BIGNUMERIC (Vista previa) y STRING.
        
        Si ninguno de los tipos de datos enumerados admite la precisión y la escala, se selecciona el tipo de datos que admite el rango más amplio en la lista especificada. Si un valor excede el rango admitido cuando se leen los datos de origen, se mostrará un error.
        
        El tipo de datos STRING admite todos los valores de precisión y escala.
        
        Si este campo se deja vacío, el tipo de datos se establecerá de manera predeterminada en “NUMERIC,STRING” para ORC y “NUMERIC” para los otros formatos de archivos.
        
        Este campo no puede contener tipos de datos duplicados.
        
        El orden de los tipos de datos que enumeras en este campo se ignora.
    - 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.
Haga clic en Save.

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 todos los valores file_format, puedes incluir el parámetro opcional decimal_target_types. decimal_target_types es una lista separada por comas de posibles tipos de datos de SQL en los que se pueden convertir los valores decimales de origen. Si no se proporciona este campo, el tipo de datos se establecerá de forma predeterminada como “NUMERIC,STRING” para ORC y “NUMERIC” para los otros formatos de archivos.
- 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 suministra una instancia del recurso TransferConfig.

Java

Ver en GitHub Comentarios

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.CreateTransferConfigRequest;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ProjectName;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

// Sample to create google cloud storage transfer config
public class CreateCloudStorageTransfer {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    String datasetId = "MY_DATASET_ID";
    String tableId = "MY_TABLE_ID";
    // GCS Uri
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv";
    String fileFormat = "CSV";
    String fieldDelimiter = ",";
    String skipLeadingRows = "1";
    Map<String, Value> params = new HashMap<>();
    params.put(
        "destination_table_name_template", Value.newBuilder().setStringValue(tableId).build());
    params.put("data_path_template", Value.newBuilder().setStringValue(sourceUri).build());
    params.put("write_disposition", Value.newBuilder().setStringValue("APPEND").build());
    params.put("file_format", Value.newBuilder().setStringValue(fileFormat).build());
    params.put("field_delimiter", Value.newBuilder().setStringValue(fieldDelimiter).build());
    params.put("skip_leading_rows", Value.newBuilder().setStringValue(skipLeadingRows).build());
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName("Your Google Cloud Storage Config Name")
            .setDataSourceId("google_cloud_storage")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .setSchedule("every 24 hours")
            .build();
    createCloudStorageTransfer(projectId, transferConfig);
  }

  public static void createCloudStorageTransfer(String projectId, TransferConfig transferConfig)
      throws IOException {
    try (DataTransferServiceClient client = DataTransferServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      CreateTransferConfigRequest request =
          CreateTransferConfigRequest.newBuilder()
              .setParent(parent.toString())
              .setTransferConfig(transferConfig)
              .build();
      TransferConfig config = client.createTransferConfig(request);
      System.out.println("Cloud storage transfer created successfully :" + config.getName());
    } catch (ApiException ex) {
      System.out.print("Cloud storage transfer was not created." + ex.toString());
    }
  }
}

Activa una transferencia de forma manual

Además de las transferencias programadas de forma automática desde Cloud Storage, puedes activar de forma manual una transferencia para cargar archivos de datos adicionales.

Si la configuración de la transferencia está parametrizada, deberás especificar un rango de fechas para el que se iniciarán las transferencias adicionales.

Para activar una transferencia de forma manual, haz lo siguiente:

Console

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

Ir a la página de BigQuery
Haz clic en Transferencias de datos.
Haz clic en tu transferencia.
Haz clic en EJECUTAR TRANSFER NOW o SCHEDULE BACKFILL (para las configuraciones de transferencia parametrizadas del entorno de ejecución).
Si corresponde, selecciona la Fecha de inicio y la Fecha de finalización y, luego, haz clic en Aceptar para confirmar.

En las configuraciones de transferencia parametrizadas del entorno de ejecución, verás las opciones de fecha cuando hagas clic en SCHEDULE BACKFILL.

¿Qué sigue?

Obtén información sobre el Uso de 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