Transferencias de Amazon S3

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

Antes de comenzar

Antes de crear una transferencia de Amazon S3, sigue estos pasos:

Limitaciones

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

  • Por ahora, la parte del depósito 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 estos vínculos:

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:

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

    La función de Cloud IAM bigquery.admin predefinida incluye los permisos bigquery.transfers.update y bigquery.datasets.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.

  • 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 IU web de BigQuery en Cloud Console.

    Ir a la Cloud Console

  2. Haz clic en Transferencias.

  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), haz lo siguiente:

      • 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 (Secret access key), 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 (Transfer options), 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.

      Cantidad de errores permitidos

    • 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. Si 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. Haz clic en Guardar.

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

    • En Fuente, elige Amazon S3.
    • En Nombre visible, 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 manera opcional, en Programa, puedes dejar el valor predeterminado Diaria (cada 24 horas, según la hora 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 período más corto permitido es de 12 horas. Consulta el campo schedule en TransferConfig para obtener más valores de API válidos.
    • En Conjunto de datos de destino, selecciona el conjunto de datos que corresponda.
    • 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 URI de Amazon S3 ingresa el URI de Amazon S3. Se admiten comodines y parámetros.
    • En ID de clave de acceso, ingresa el ID de tu clave de acceso.
    • En Clave de acceso secreta, ingresa tu clave de acceso secreta.
    • En Formato de archivo, elige el formato de datos: CSV, Avro, Parquet, ORC o JSON delimitados por saltos de línea.
    • En la sección Opciones de transferencia: todos los formatos, sigue estos pasos:
      • En Cantidad de errores permitidos, 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.
    • Si eliges los formatos de datos CSV o JSON, en la sección Opciones de transferencia: JSON, CSV, haz 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.
    • Si eliges el formato de datos CSV, en la sección Opciones de transferencia: CSV, sigue estos pasos:

      • En Delimitador de campo, ingresa el carácter que separa los campos. El valor predeterminado es una coma.
      • En Filas de encabezado para omitir, 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, marca la casilla si quieres permitir saltos de línea en campos entrecomillados.
      • En Permitir filas irregulares, marca la casilla si quieres permitir que se transfieran las filas con columnas NULLABLE faltantes.
    • 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.

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: 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 la 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.

    • 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 proporciona una instancia del recurso TransferConfig.

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, visita Consulta tablas particionadas.

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 depósito 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 depósito de Amazon S3.
  • Obtén la ubicación del depósito.
  • Lee los objetos del depósito.
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 transferencias pueden tener un aspecto similar al siguiente:

Traslado de datos de Amazon  S3 a Google Cloud completo: Se movieron <NNN> objetos.
No se encontraron archivos nuevos que coincidan con <URI de Amazon  S3>.
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.

Próximos pasos