Transferencias de Cloud Storage

Console

1. Ve a la página Transferencia de datos en la consola de Google Cloud.

   Ir a Transferencias de datos

2. Haz clic en add Crear transferencia.

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

   

4. En la sección Nombre de la configuración de transferencia (Transfer config name), en Nombre visible, ingresa el nombre de la transferencia de datos, como My Transfer. El nombre de la transferencia puede ser cualquier valor que te permita identificarla si es necesario hacerle modificaciones más tarde.

   

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

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

   

7. En la sección Detalles de fuente de datos (Data source details):

   1. 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.
   2. En el URI de Cloud Storage (Cloud Storage URI), ingresa los URI de Cloud Storage. Se admiten comodines y parámetros.
   3. En Preferencia de escritura, elige una de las siguientes opciones:
      • APPEND para agregar incrementalmente datos nuevos a tu tabla de destino existente. APPEND es el valor predeterminado para Preferencia de escritura.
      • MIRROR para reemplazar los datos en la tabla de destino durante cada ejecución de transferencia de datos.

   Si deseas obtener más información de cómo el Servicio de transferencia de datos de BigQuery transfiere datos con APPEND o MIRROR, consulta Transferencia de datos para transferencias de Cloud Storage. Para obtener más información del campo writeDisposition, consulta JobConfigurationLoad.

   1. 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 de datos 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ó.

   2. En la sección Opciones de transferencia (Transfer Options), sigue estos pasos:

      1. En Todos los formatos (All Formats), haz lo siguiente:
         1. 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.
         2. En Tipos de destino decimales, ingresa una lista separada por comas de tipos de datos de SQL posibles en los que se puedan convertir los valores decimales de origen (opcional). El tipo de datos 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 el escalamiento de los datos de origen, en este orden: NUMERIC, BIGNUMERIC y STRING.
            • Si ninguno de los tipos de datos enumerados admitirá la precisión y el escalamiento, se selecciona el tipo de datos que admite el rango más amplio en la lista especificada. Se mostrará 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 será “NUMERIC,STRING” para ORC y “NUMERIC” para los 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 este campo.
      2. En JSON, CSV, haz lo siguiente:
         • En Ignorar valores desconocidos (Ignore unknown values), marca la casilla si quieres que la transferencia de datos descarte los datos que no coincidan con el esquema de la tabla de destino.
      3. En AVRO, haz lo siguiente:
         • En Use avro logical types, marca la casilla si quieres que la transferencia de datos convierta los tipos lógicos de Avro en sus tipos de datos de BigQuery correspondientes. El comportamiento predeterminado es ignorar el atributo logicalType en la mayoría de los tipos y usar el tipo de Avro subyacente en su lugar.

      4. En CSV, haz lo siguiente:

         1. En Delimitador de campo (Field delimiter), ingresa el carácter que separa los campos. El valor predeterminado es una coma.
         2. En Carácter de comilla, ingresa el carácter que se usa para entrecomillar secciones de datos en un archivo CSV. El valor predeterminado es una comilla doble (").
         3. 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.
         4. En Permitir saltos de línea con comillas (Allow quoted newlines), marca la casilla si quieres permitir saltos de línea en campos entrecomillados.
         5. En Permitir filas irregulares (Allow jagged rows), marca la casilla de verificación si quieres permitir que se transfieran datos de filas con columnas NULLABLE faltantes.

8. En el menú Cuenta de servicio, selecciona una cuenta de servicio de las cuentas de servicio asociadas a tu proyecto de Google Cloud. Puedes asociar una cuenta de servicio con tu transferencia de datos en lugar de usar tus credenciales de usuario. Para obtener más información sobre el uso de cuentas de servicio con transferencias de datos, consulta Usa cuentas de servicio.

   • Si accediste con una identidad federada, se requiere una cuenta de servicio para crear una transferencia de datos. Si accediste con una Cuenta de Google, la cuenta de servicio para dicha transferencia de datos es opcional.
   • La cuenta de servicio debe tener los permisos necesarios para BigQuery y Cloud Storage.

9. Opcional: En la sección Opciones de notificación:

   1. Haz clic en el botón de activación para habilitar las notificaciones por correo electrónico. Cuando habilitas esta opción, el propietario de la configuración de la transferencia de datos recibe una notificación por correo electrónico cuando falla una ejecución de transferencia.
   2. 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.

10. Opcional: En la sección Opciones avanzadas, haz lo siguiente:

    • Si usas CMEKs, selecciona Clave administrada por el cliente. Aparecerá una lista de las CMEKs disponibles para que elijas.

    Para obtener información acerca de cómo funcionan las CMEKs con el Servicio de transferencia de datos de BigQuery, consulta Especifica la clave de encriptación con transferencias.

11. Haz clic en Guardar.

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

Marcas opcionales:

• --destination_kms_key: Especifica el ID de recurso de la clave para la clave de Cloud KMS si usas una clave de encriptación administrada por el cliente (CMEK) para esta transferencia de datos. Para obtener información acerca de cómo funcionan las CMEKs con el Servicio de transferencia de datos de BigQuery, consulta Especifica la clave de encriptación con transferencias.
• --service_account_name: Especifica una cuenta de servicio que se usará para la autenticación de la transferencia de Cloud Storage en lugar de tu cuenta de usuario.

bq mk \
--transfer_config \
--project_id=PROJECT_ID \
--data_source=DATA_SOURCE \
--display_name=NAME \
--target_dataset=DATASET \
--destination_kms_key="DESTINATION_KEY" \
--params='PARAMETERS' \
--service_account_name=SERVICE_ACCOUNT_NAME

Donde:

• 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, por ejemplo, google_cloud_storage.
• NAME es el nombre visible de la configuración de transferencia de datos. El nombre de la transferencia puede ser cualquier valor que te permita identificarla si es necesario hacerle modificaciones más tarde.
• DATASET es el conjunto de datos de destino para la configuración de la transferencia.
• DESTINATION_KEY: El ID de recurso de la clave de Cloud KMS, por ejemplo, projects/project_name/locations/us/keyRings/key_ring_name/cryptoKeys/key_name.
• PARAMETERS contiene los parámetros para la configuración de la transferencia creada en formato JSON. Por ejemplo: --params='{"param":"param_value"}'
  • destination_table_name_template: Es el nombre de la tabla de BigQuery de destino.
  • data_path_template es el URI de Cloud Storage que contiene los archivos que se van a transferir, que puede incluir un comodín.
  • write_disposition: Determina si los archivos coincidentes se agregan a la tabla de destino o se duplican por completo. Los valores admitidos son APPEND o MIRROR. Si quieres obtener información sobre cómo el Servicio de transferencia de datos de BigQuery agrega o duplica los datos en las transferencias de Cloud Storage, consulta Transferencia de datos para las transferencias de Cloud Storage.
  • file_format: El formato de los archivos que quieras transferir. El formato puede ser CSV, JSON, AVRO, PARQUET o ORC. El valor predeterminado es CSV.
  • max_bad_records: Para cualquier valor file_format, es la cantidad máxima de registros erróneos que se pueden ignorar. El valor predeterminado es 0.
  • decimal_target_types: Para cualquier valor file_format, es una lista separada por comas de tipos de datos de SQL posibles en los que se pueden convertir los valores decimales de origen. Si no se proporciona este campo, el tipo de datos predeterminado es "NUMERIC,STRING" para ORC y "NUMERIC" para los otros formatos de archivo.
  • ignore_unknown_values: Para cualquier valor file_format, se configura como TRUE para aceptar filas que contengan valores que no coincidan con el esquema. Para obtener más información, consulta los detalles del campo ignoreUnknownvalues en la tabla de referencia de JobConfigurationLoad.
  • use_avro_logical_types: Para valores file_format de AVRO, configúralo como TRUE de modo que puedas interpretar tipos lógicos en sus tipos correspondientes (por ejemplo, TIMESTAMP), en lugar de solo usar sus tipos sin procesar (por ejemplo, INTEGER).
  • parquet_enum_as_string: Para los valores PARQUET file_format, establecer en TRUE para inferir el tipo lógico PARQUET ENUM como STRING en lugar del valor predeterminado BYTES.
  • parquet_enable_list_inference: Para los valores PARQUET file_format, configúralo como TRUE de modo que puedas usar la inferencia de esquema específicamente para el tipo lógico PARQUET LIST.
  • reference_file_schema_uri: Es una ruta de acceso de URI a un archivo de referencia con el esquema de lector.
  • field_delimiter: para los valores CSV file_format, es un carácter que separa los campos. El valor predeterminado es una coma.
  • quote: Para los valores CSV file_format, es un carácter que se usa para entrecomillar secciones de datos en un archivo CSV. El valor predeterminado es una comilla doble (").
  • skip_leading_rows: para los valores CSV file_format, indica la cantidad de filas de encabezado iniciales que no quieres importar. El valor predeterminado es 0.
  • allow_quoted_newlines: Para los valores CSV file_format, se establece en TRUE para permitir saltos de línea dentro de los campos entre comillas.
  • allow_jagged_rows: Para los valores CSV file_format, se establece en TRUE para aceptar filas a las que les falten columnas opcionales finales. Los valores faltantes se completan con NULL.
  • preserve_ascii_control_characters: Para los valores CSV file_format, se establece en TRUE para preservar cualquier carácter de control ASCII incorporado.
  • encoding: Especifica el tipo de codificación CSV. Los valores admitidos son UTF8, ISO_8859_1, UTF16BE, UTF16LE, UTF32BE y UTF32LE.
  • delete_source_files: Se establece en TRUE para borrar los archivos de origen después de cada transferencia exitosa. Los trabajos de borrado no se vuelven a ejecutar si falla el primer intento de borrar el archivo de origen. El valor predeterminado es FALSE.
• SERVICE_ACCOUNT_NAME es el nombre de la cuenta de servicio que se usa para autenticar tu transferencia. La cuenta de servicio debe ser propiedad del mismo project_id que se usa para crear la transferencia y debe tener todos los permisos necesarios.

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

La transferencia de datos se crea en el proyecto predeterminado:

bq mk --transfer_config \
--target_dataset=mydataset \
--project_id=myProject \
--display_name='My Transfer' \
--destination_kms_key=projects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey \
--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":"|",
"quote":";",
"skip_leading_rows":"1",
"allow_quoted_newlines":"true",
"allow_jagged_rows":"false",
"delete_source_files":"true"}' \
--data_source=google_cloud_storage \
--service_account_name=abcdef-test-sa@abcdef-test.iam.gserviceaccount.com projects/862514376110/locations/us/transferConfigs/ 5dd12f26-0000-262f-bc38-089e0820fe38

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

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());
    }
  }
}

Console

1. Ve a la página de BigQuery en la consola de Google Cloud.

   Ir a la página de BigQuery

2. Haz clic en sync_alt Transferencias de datos.

3. Selecciona tu transferencia de datos en la lista.

4. Haz clic en Ejecutar transferencia ahora o Programar el reabastecimiento (para configuraciones de transferencia con parámetros de entorno de ejecución).

   • Si hiciste clic en Ejecutar transferencia ahora, selecciona Ejecutar transferencia de un solo uso o Ejecutar en una fecha específica según corresponda. Si seleccionaste Ejecutar en una fecha específica, selecciona una fecha y hora específicas:

     

   • Si hiciste clic en Programar el reabastecimiento, selecciona Ejecutar transferencia de un solo uso o Ejecutar durante un período según corresponda. Si seleccionaste Ejecutar durante un período, selecciona una fecha y hora de inicio y de finalización:

     

5. Haz clic en Aceptar.

bq

Ingresa el comando bq mk y proporciona la marca --transfer_run. Puedes usar la marca --run_time o las marcas --start_time y --end_time.

bq mk \
--transfer_run \
--start_time='START_TIME' \
--end_time='END_TIME' \
RESOURCE_NAME

bq mk \
--transfer_run \
--run_time='RUN_TIME' \
RESOURCE_NAME

Donde:

• START_TIME y END_TIME son marcas de tiempo que terminan en Z o contienen un desplazamiento de zona horaria válido. Por ejemplo:

  • 2017-08-19T12:11:35.00Z
  • 2017-05-25T00:00:00+00:00

• RUN_TIME es una marca de tiempo que especifica la hora para programar la ejecución de la transferencia de datos. Si deseas ejecutar una transferencia de un solo uso para la hora actual, puedes usar la marca --run_time.

• RESOURCE_NAME es el nombre del recurso de la transferencia (también conocido como la configuración de transferencia), por ejemplo, projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7. Si no conoces el nombre del recurso de la transferencia, ejecuta el comando bq ls --transfer_config --transfer_location=LOCATION para encontrar el nombre del recurso.

API

Usa el método projects.locations.transferConfigs.startManualRuns y proporciona el recurso de configuración de la transferencia con el parámetro parent.