Transferencias de Amazon S3

El Servicio de transferencia de datos de BigQuery para Amazon S3 te permite programar y administrar automáticamente los trabajos de carga recurrentes de Amazon S3 en BigQuery.

Antes de comenzar

Antes de crear una transferencia de Amazon S3:

Limitaciones

Las transferencias de Amazon S3 están sujetas a las siguientes limitaciones:

  • La parte del bucket en el URI de Amazon S3 no admite el uso de parámetros.
  • Las transferencias de Amazon S3 con el parámetro disposición de escritura establecido en WRITE_TRUNCATE transferirán todos los archivos coincidentes a Google Cloud durante cada ejecución. Esto puede generar costos adicionales de transferencia de datos salientes de Amazon S3. Para obtener más información sobre qué archivos se transfieren durante una ejecución, consulta Impacto de la coincidencia de prefijos frente a la coincidencia de comodines.
  • No se admiten las transferencias de las regiones de AWS GovCloud (us-gov).
  • No se admiten las transferencias a ubicaciones de BigQuery Omni.

  • Según el formato de los datos de origen de Amazon S3, puede haber limitaciones adicionales. Para obtener más información, consulta:

  • El tiempo de intervalo mínimo entre transferencias recurrentes es de 24 horas. El intervalo predeterminado para una transferencia recurrente es de 24 horas.

Permisos necesarios

Antes de crear una transferencia de Amazon S3, haz lo siguiente:

  • Asegúrate de que la persona que crea la transferencia tenga los siguientes permisos obligatorios en BigQuery:

    • permisos bigquery.transfers.update para crear la transferencia
    • Los permisos bigquery.datasets.get y bigquery.datasets.update en el conjunto de datos de destino

    La función predefinida de IAM bigquery.admin incluye los permisos bigquery.transfers.update, bigquery.datasets.update y bigquery.datasets.get. Para obtener más información sobre los roles de IAM en el Servicio de transferencia de datos de BigQuery, consulta Control de acceso.

  • Consulta la documentación de Amazon S3 y asegúrate de tener configurados los permisos necesarios para habilitar la transferencia. Como mínimo, los datos de origen de Amazon S3 deben estar sujetos a la política administrada de AWS AmazonS3ReadOnlyAccess.

Configura una transferencia de datos de Amazon S3

Para crear una transferencia de datos de Amazon S3:

Consola

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

  3. Haz clic en Crear una transferencia.

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

    • En la sección Tipo de fuente (Source type), elige Amazon S3 como Fuente (Source).

      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 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 crear una frecuencia de repetición más específica. Si seleccionas A pedido, esta transferencia solo se ejecutará cuando actives 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 (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):

      • En Tabla de destino (Destination table), 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 el URI de Amazon S3 (Amazon S3 URI), ingresa el URI en el siguiente formato: s3://mybucket/myfolder/.... Los URI también admiten parámetros.
      • En ID de clave de acceso (Access key ID), ingresa el ID de tu clave de acceso.
      • En Clave de acceso secreta, ingresa tu clave de acceso secreta.
      • En Formato de archivo (File format), elige el formato de datos: CSV, Avro, Parquet, ORC o JSON delimitados por saltos de línea.

      • Para la Disposición de escritura, elige:

        • WRITE_APPEND para agregar datos nuevos a tu tabla de destino existente de forma incremental. WRITE_APPEND es el valor predeterminado para la preferencia de escritura.
        • WRITE_TRUNCATE para reemplazar los datos de la tabla de destino durante cada ejecución de transferencia.

        Si deseas obtener más información sobre cómo el Servicio de transferencia de datos de BigQuery transfiere datos mediante WRITE_APPEND o WRITE_TRUNCATE, consulta Transferencia de datos para Transferencias de Amazon S3 Para obtener más información sobre el campo writeDisposition, consulta JobConfigurationLoad.

        Detalles de la fuente de S3

    • En la sección Opciones de transferencia: todos los formatos, sigue estos pasos:

      • En Cantidad de errores permitidos, ingresa un valor entero para la cantidad máxima de registros erróneos que se pueden ignorar.
      • 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.

      Opciones de transferencia en todos los formatos

    • Si eliges los formatos de archivo CSV o JSON, en la sección JSON, CSV, marca Ignorar valores desconocidos (Ignore unknown values) para aceptar las filas con valores que no coinciden con el esquema. Los valores desconocidos se ignoran. En los archivos CSV, esta opción ignora los valores adicionales al final de una línea.

      Ignorar valores desconocidos

    • Si elegiste CSV como formato de archivo, en la sección CSV ingresa cualquier opción de CSV adicional para cargar datos.

      Opciones de CSV

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

    • De forma opcional, en la sección Opciones de notificación, 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 Selecciona un tema de Pub/Sub, elige el nombre de tu tema o haz clic en Crear un tema para crear uno. Con esta opción, se configuran las notificaciones de ejecución de Pub/Sub para tu transferencia.

  5. Haga clic en Save.

bq

Ingresa el comando bq mk y suministra la marca de creación de transferencias --transfer_config.

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

Aquí:

  • project_id: Opcional Tu ID del proyecto de Google Cloud. Si no se proporciona --project_id para especificar un proyecto en particular, se usa el proyecto predeterminado.
  • data_source: obligatorio. La fuente de datos, amazon_s3.
  • display_name: obligatorio. 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 es necesario hacerle modificaciones más tarde.
  • dataset: Obligatorio. El conjunto de datos de destino para la configuración de transferencia.
  • service_account: 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.

  • parameters: Obligatorio. Los parámetros de la configuración de transferencia creada en formato JSON. Por ejemplo: --params='{"param":"param_value"}' Los siguientes son los parámetros para una transferencia de Amazon S3:

    • destination_table_name_template: obligatorio. El nombre de la tabla de destino.

    • data_path: obligatorio. El URI de Amazon S3, en el siguiente formato:

      s3://mybucket/myfolder/...

      Los URI también admiten parámetros.

    • access_key_id: obligatorio. Tu ID de clave de acceso.

    • secret_access_key: obligatorio. Tu clave de acceso secreta.

    • file_format: Opcional Indica el tipo de archivos que deseas transferir: CSV, JSON, AVRO, PARQUET o ORC. El valor predeterminado es CSV.

    • write_disposition: Opcional WRITE_APPEND transferirá solo los archivos que se modificaron desde la ejecución correcta anterior. WRITE_TRUNCATE transferirá todos los archivos coincidentes, incluidos los que se transfirieron en una ejecución anterior. El valor predeterminado es WRITE_APPEND.

    • max_bad_records: Opcional La cantidad de registros erróneos permitidos. El predeterminado es 0.

    • decimal_target_types: Opcional 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 será "NUMERIC,STRING" para ORC y "NUMERIC" para los otros formatos de archivo.

    • ignore_unknown_values: Opcional y, también, ignorado si file_format no es JSON ni CSV. Indica si se deben ignorar los valores desconocidos en tus datos.

    • field_delimiter: Opcional y solo se aplica cuando file_format es CSV. El carácter que separa los campos. El valor predeterminado es una coma.

    • skip_leading_rows: Opcional y solo se aplica cuando file_format es CSV. Indica la cantidad de filas de encabezado que no deseas importar. El valor predeterminado es 0.

    • allow_quoted_newlines: Opcional y solo se aplica cuando file_format es CSV. Indica si se permiten saltos de líneas dentro de los campos entre comillas.

    • allow_jagged_rows: Opcional y solo se aplica cuando file_format es CSV. Indica si se aceptan filas a las que les faltan columnas opcionales finales. Los valores que faltan se completarán con valores NULL.

Por ejemplo, con el siguiente comando se crea una transferencia de Amazon S3 llamada My Transfer mediante un valor data_path de s3://mybucket/myfile/*.csv, el conjunto de datos de destino mydataset y el file_format como CSV. Este ejemplo incluye 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":"s3://mybucket/myfile/*.csv",
"destination_table_name_template":"MyTable",
"file_format":"CSV",
"write_disposition":"WRITE_APPEND",
"max_bad_records":"1",
"ignore_unknown_values":"true",
"field_delimiter":"|",
"skip_leading_rows":"1",
"allow_quoted_newlines":"true",
"allow_jagged_rows":"false"}' \
--data_source=amazon_s3

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

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. 

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 amazon s3 transfer config.
public class CreateAmazonS3Transfer {

  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";
    // Amazon S3 Bucket Uri with read role permission
    String sourceUri = "s3://your-bucket-name/*";
    String awsAccessKeyId = "MY_AWS_ACCESS_KEY_ID";
    String awsSecretAccessId = "AWS_SECRET_ACCESS_ID";
    String sourceFormat = "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", Value.newBuilder().setStringValue(sourceUri).build());
    params.put("access_key_id", Value.newBuilder().setStringValue(awsAccessKeyId).build());
    params.put("secret_access_key", Value.newBuilder().setStringValue(awsSecretAccessId).build());
    params.put("source_format", Value.newBuilder().setStringValue(sourceFormat).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 Aws S3 Config Name")
            .setDataSourceId("amazon_s3")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .setSchedule("every 24 hours")
            .build();
    createAmazonS3Transfer(projectId, transferConfig);
  }

  public static void createAmazonS3Transfer(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("Amazon s3 transfer created successfully :" + config.getName());
    } catch (ApiException ex) {
      System.out.print("Amazon s3 transfer was not created." + ex.toString());
    }
  }
}

Impacto de la coincidencia de prefijos frente a la coincidencia de comodines

La API de Amazon S3 admite la coincidencia de prefijos, pero no la coincidencia de comodines. Todos los archivos de Amazon S3 que coincidan con un prefijo se transferirán a Google Cloud. Sin embargo, solo los que coincidan con el URI de Amazon S3 en la configuración de transferencia se cargarán en BigQuery. Esto podría provocar un exceso en los costos de transferencia de datos salientes de Amazon S3 para los archivos que se transfieren pero no se cargan en BigQuery.

A modo de ejemplo, considera esta ruta de datos:

s3://bucket/folder/*/subfolder/*.csv

Junto con estos archivos en la ubicación de origen:

s3://bucket/folder/any/subfolder/file1.csv
s3://bucket/folder/file2.csv

Esto hará que todos los archivos de Amazon S3 con el prefijo s3://bucket/folder/ se transfieran a Google Cloud. En este ejemplo, se transferirán file1.csv y file2.csv.

Sin embargo, solo los archivos que coincidan con s3://bucket/folder/*/subfolder/*.csv se cargarán en BigQuery. En este ejemplo, solo se cargarán file1.csv en BigQuery.

Soluciona problemas con la configuración de una transferencia

Si tienes problemas para configurar tu transferencia, consulta la sección sobre problemas de transferencias de Amazon S3.

¿Qué sigue?