Se usó la API de Cloud Translation para traducir esta página.
Switch to English

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:

  • Por ahora, la parte del bucket en el URI de Amazon S3 no admite el uso de parámetros.
  • Las transferencias de Amazon S3 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 de carga para obtener más detalles.
  • Según el formato de los datos de origen de Amazon S3, puede haber limitaciones adicionales. Para obtener más información, consulta:

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 de IAM predefinida bigquery.admin incluye permisos bigquery.transfers.update, bigquery.datasets.update y bigquery.datasets.get. Para obtener más información sobre las funciones de IAM en el Servicio de transferencia de datos de BigQuery, consulta Referencia de 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:

Console

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

    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 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. Incluye las siguientes opciones:

        • Diariamente (Daily) (predeterminada)
        • Semanal
        • Mensual
        • Personalizada
        • Según demanda (On demand)

        Si eliges una opción que no sea Diaria (Daily), tendrás opciones adicionales. Por ejemplo, si eliges Semanal, aparece una opción para que selecciones el día.

      • 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):

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

        Detalles de la fuente de S3

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

      • En Cantidad de errores permitidos (Number of errors allowed), ingresa un valor entero para la cantidad máxima de registros erróneos que se pueden ignorar.
      • (Opcional) En Tipos de objetivo decimales, ingresa una lista separada por comas de tipos de datos SQL posibles en los que se podrían 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 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 predeterminado será “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.

      Formato de opciones de transferencia

    • 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

    • 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 \
--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 fácilmente si es necesario hacerle modificaciones más tarde.
  • dataset: obligatorio. El conjunto de datos de destino para la configuración de transferencia.
  • 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.

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

    • decimal_target_types: Opcional Una lista separada por comas de tipos de datos de SQL posibles en los que se podrían 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.

    • 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_template 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_template":"s3://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=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

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

Consulta tus datos

Cuando tus datos se transfieren a BigQuery, se escriben en tablas particionadas por tiempo de transferencia. Para obtener más información, consulta Introducción a tablas con particiones.

Si consultas tus tablas directamente en lugar de usar las vistas generadas de manera automática, debes usar la seudocolumna _PARTITIONTIME en tu consulta. Para obtener más información, visita Consulta tablas particionadas.

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 salida 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

A continuación, se proporciona información sobre errores comunes y recomendaciones para su resolución.

Errores PERMISSION_DENIED de Amazon S3

Error Acción recomendada
El ID de clave de acceso de AWS que proporcionaste no existe en nuestros registros. Asegúrate de que la clave de acceso exista y que el ID sea correcto.
La firma de la solicitud que calculamos no coincide con la firma que proporcionaste. Comprueba la clave y el método de registro de firma. Asegúrate de que la configuración de transferencia tenga la clave de acceso secreta correspondiente.
No se pudo obtener la ubicación del bucket fuente de S3. Detalles adicionales: Acceso denegado

No se pudo obtener la ubicación del depósito fuente de S3. Detalles adicionales: HTTP/1.1 403 Forbidden

Mensaje de error de S3: Acceso denegado
Asegúrate de que el usuario de IAM de AWS tenga permiso para realizar lo siguiente:
  • Enumera el bucket de Amazon S3.
  • Obtén la ubicación del bucket.
  • Lee los objetos del bucket.
El servidor no puede inicializar la carga de objetos. InvalidObjectState: La operación no es válida para la clase de almacenamiento del objeto

No se pudo obtener la ubicación del depósito fuente de S3. Detalles adicionales: Se inhabilitó el acceso a este objeto
Restablece los objetos que estén archivados en Amazon Glacier. No se podrá acceder a los objetos en Amazon S3 que estén archivados en Amazon Glacier hasta que se los restablezca.
Se inhabilitó el acceso a este objeto Confirma que el URI de Amazon S3 en la configuración de transferencia sea correcto

Errores de límite de transferencia de Amazon S3

Error Acción recomendada
La cantidad de archivos en transferencia excede el límite de 10,000. Evalúa si la cantidad de comodines en el URI de Amazon S3 puede reducirse a solo uno. Si esto es posible, vuelve a intentar con una nueva configuración de transferencia, ya que el número máximo de archivos por ejecución de transferencia será mayor.

Evalúa si la configuración de transferencia puede dividirse en varias, y que cada una transfiera una parte de los datos de origen.
El tamaño de los archivos en transferencia supera el límite de 16492674416640 bytes. Evalúa si la configuración de transferencia se puede dividir en varias, y que cada una transfiera una parte de los datos de origen.

Problemas generales

Error Acción recomendada
Los archivos se transfieren desde Amazon S3, pero no se cargan en BigQuery. Los registros de transferencia pueden tener un aspecto similar a este:

Se movieron los datos de Amazon S3 a Google Cloud: Se movieron los objetos <NNN< .
No se encontraron archivos nuevos que coincidan con <Amazon S3 URI>.
Confirma que el URI de Amazon S3 en la configuración de la transferencia sea correcto.

Si la configuración de transferencia debía cargar todos los archivos con un prefijo común, asegúrate de que el URI de Amazon S3 finalice con un comodín.
Por ejemplo, para cargar todos los archivos en s3://my-bucket/my-folder/, el URI de Amazon S3 en la configuración de transferencia debe ser s3://my-bucket/my-folder/*, no solo s3://my-bucket/my-folder/.
Otros problemas Consulta la página sobre cómo solucionar problemas relacionados con las configuraciones de transferencia.

¿Qué sigue?