Transferencias de Blob Storage

El conector del Servicio de transferencia de datos de BigQuery para Azure Blob Storage te permite administrar y programar de manera automática trabajos de carga recurrentes de Blob Storage en BigQuery.

Antes de comenzar

Antes de crear una transferencia de datos de Blob Storage, haz lo siguiente:

Permisos necesarios

Para crear una transferencia de datos de Blob Storage, necesitas el permiso bigquery.transfers.update de Identity and Access Management (IAM). También necesitas los permisos bigquery.datasets.get y bigquery.datasets.update en el conjunto de datos de destino.

El rol predefinido de IAM bigquery.admin incluye los permisos que necesitas para crear una transferencia de datos de Blob Storage.

Para obtener más información sobre IAM de BigQuery, consulta Control de acceso con IAM.

Para confirmar que tienes los permisos correctos en Blob Storage a fin de habilitar la transferencia de datos, consulta Firma de acceso compartido (SAS).

Si quieres configurar las notificaciones de ejecución de transferencias para Pub/Sub, debes tener el permiso pubsub.topics.setIamPolicy. Los permisos de Pub/Sub solo son necesarios para las notificaciones por correo electrónico. Para obtener más información, consulta la sección sobre notificaciones de ejecución del Servicio de transferencia de datos de BigQuery.

Limitaciones

Las transferencias de datos de Blob Storage están sujetas a las siguientes limitaciones:

Configura una transferencia de datos de Blob Storage

Selecciona una de las opciones siguientes:

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 Crear transferencia.

  3. En la página Crear transferencia, haz lo siguiente:

    • En la sección Tipo de fuente, en Fuente, elige Azure Blob Storage.

      Tipo de fuente de transferencia

    • En la sección Nombre de configuración de la transferencia (Transfer config name), en Nombre visible (Display name), ingresa el nombre de la transferencia de datos.

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

    • En la sección Configuración de destino, en Conjunto de datos de destino, selecciona el conjunto de datos que creaste para almacenar tus datos.

    • En la sección Detalles de fuente de datos, haz lo siguiente:

      • En Tabla de destino, 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 Nombre de la cuenta de almacenamiento de Azure, ingresa el nombre de la cuenta de Blob Storage.
      • En Nombre del contenedor, ingresa el nombre del contenedor de Blob Storage.
      • En Ruta de acceso a los datos, ingresa la ruta para filtrar los archivos que se transferirán. Ve ejemplos.
      • En Token SAS, ingresa el token SAS de Azure.
      • En Formato de archivo, elige el formato de datos de origen.
      • En Disposición de escritura, selecciona WRITE_APPEND para agregar datos nuevos de forma incremental a la tabla de destino o WRITE_TRUNCATE para reemplazar datos en la tabla de destino durante cada ejecución de transferencia. WRITE_APPEND es el valor predeterminado para la disposición de escritura.

      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 Azure Blob Para obtener más información sobre el campo writeDisposition, consulta JobConfigurationLoad.

      Detalles de la fuente de datos

    • En la sección Opciones de transferencia, haz lo siguiente:

      • En Cantidad de errores permitidos, ingresa un valor entero para la cantidad máxima de registros erróneos que se pueden ignorar. El valor predeterminado es 0.
      • (Opcional) En Tipos de destino decimales, ingresa una lista separada por comas de tipos de datos de SQL posibles en los que se conviertan los valores decimales en los datos de origen. El tipo de datos SQL que se selecciona para la conversión depende de las siguientes condiciones:
        • En el orden de NUMERIC, BIGNUMERIC y STRING, se elige un tipo si está en la lista especificada y si admite la precisión y el escalamiento.
        • Si ninguno de los tipos de datos enumerados admite la precisión y el escalamiento, se selecciona el tipo de datos que admite el rango más amplio en la lista que especificaste. Se muestra 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 es NUMERIC,STRING para ORC y NUMERIC para otros formatos de archivo.
        • Este campo no puede contener tipos de datos duplicados.
        • Se ignora el orden de los tipos de datos que enumeras.

    • Si eliges los formatos de archivo CSV o JSON, en la sección JSON, CSV, marca Ignorar valores desconocidos para aceptar las filas con valores que no coinciden con el esquema.

    • 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 la sección Opciones de notificación, puedes elegir habilitar las notificaciones por correo electrónico y las notificaciones de Pub/Sub.

      • Si habilitas las notificaciones por correo electrónico, el administrador de transferencias recibirá una notificación por correo electrónico cuando falle la ejecución de una transferencia.
      • Cuando habilitas Notificaciones de Pub/Sub, elige un nombre de tema para publicar o haz clic en Cree un tema para crear uno.

    • Si usas CMEKs, en la sección Opciones avanzadas, selecciona Clave administrada por el cliente. Aparecerá una lista de las CMEKs disponibles para que elijas. Para obtener información del funcionamiento las CMEKs con el Servicio de transferencia de datos de BigQuery, consulta Especifica la clave de encriptación con transferencias.

  4. Haz clic en Guardar.

bq

Usa el comando bq mk --transfer_config para crear una transferencia de Blob Storage:

bq mk \
  --transfer_config \
  --project_id=PROJECT_ID \
  --data_source=DATA_SOURCE \
  --display_name=DISPLAY_NAME \
  --target_dataset=DATASET \
  --destination_kms_key=DESTINATION_KEY \
  --params=PARAMETERS

Reemplaza lo siguiente:

  • PROJECT_ID: (Opcional) el ID del proyecto que contiene tu conjunto de datos de destino. Si no se especifica, se usa el proyecto predeterminado.
  • DATA_SOURCE: azure_blob_storage.
  • DISPLAY_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 con facilidad si es necesario hacerle modificaciones más tarde.
  • DATASET: el conjunto de datos de destino para la configuración de transferencia de datos.
  • DESTINATION_KEY: (Opcional) el ID de recurso clave de Cloud KMS, por ejemplo, projects/project_name/locations/us/keyRings/key_ring_name/cryptoKeys/key_name.
  • PARAMETERS son los parámetros de la configuración de la transferencia de datos en formato JSON. Por ejemplo, --params={"param1":"value1", "param2":"value2"} Los siguientes son los parámetros para una transferencia de datos de Blob Storage:
    • destination_table_name_template: Obligatorio. El nombre de la tabla de destino.
    • storage_account: Obligatorio. El nombre de la cuenta de Blob Storage.
    • container: Obligatorio. El nombre del contenedor de Blob Storage.
    • data_path: Opcional La ruta para filtrar los archivos que se transferirán. Ve ejemplos.
    • sas_token: Obligatorio. El token SAS de Azure.
    • file_format: Opcional El tipo de archivos que deseas transferir: CSV, JSON, AVRO, PARQUET o ORC. El valor predeterminado es CSV.
    • write_disposition: Opcional Selecciona WRITE_APPEND para agregar datos a la tabla de destino, o WRITE_TRUNCATE, si quieres reemplazar datos en la tabla de destino. El valor predeterminado es WRITE_APPEND.
    • max_bad_records: Opcional La cantidad de registros erróneos permitidos. El valor predeterminado es 0.
    • decimal_target_types: Opcional Una lista separada por comas de tipos de datos de SQL posibles en los que se convierten los valores decimales en los datos 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: Opcional y, también, ignorado si file_format no es JSON ni CSV. Configúralo como true para aceptar filas que contengan valores que no coincidan con el esquema.
    • field_delimiter: Opcional y solo se aplica cuando file_format es CSV. El carácter que separa los campos. El valor predeterminado es ,.
    • 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 faltantes se completan con NULL.

Por ejemplo, lo siguiente crea una transferencia de datos de Blob Storage llamada mytransfer:

bq mk \
  --transfer_config \
  --data_source=azure_blob_storage \
  --display_name=mytransfer \
  --target_dataset=mydataset \
  --destination_kms_key=projects/myproject/locations/us/keyRings/mykeyring/cryptoKeys/key1
  --params={"destination_table_name_template":"mytable",
      "storage_account":"myaccount",
      "container":"mycontainer",
      "data_path":"myfolder/*.csv",
      "sas_token":"my_sas_token_value",
      "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"}

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 azure blob storage transfer config.
public class CreateAzureBlobStorageTransfer {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    final String displayName = "MY_TRANSFER_DISPLAY_NAME";
    final String datasetId = "MY_DATASET_ID";
    String tableId = "MY_TABLE_ID";
    String storageAccount = "MY_AZURE_STORAGE_ACCOUNT_NAME";
    String containerName = "MY_AZURE_CONTAINER_NAME";
    String dataPath = "MY_AZURE_FILE_NAME_OR_PREFIX";
    String sasToken = "MY_AZURE_SAS_TOKEN";
    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("storage_account", Value.newBuilder().setStringValue(storageAccount).build());
    params.put("container", Value.newBuilder().setStringValue(containerName).build());
    params.put("data_path", Value.newBuilder().setStringValue(dataPath).build());
    params.put("sas_token", Value.newBuilder().setStringValue(sasToken).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());
    createAzureBlobStorageTransfer(projectId, displayName, datasetId, params);
  }

  public static void createAzureBlobStorageTransfer(
      String projectId, String displayName, String datasetId, Map<String, Value> params)
      throws IOException {
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName(displayName)
            .setDataSourceId("azure_blob_storage")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .setSchedule("every 24 hours")
            .build();
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    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("Azure Blob Storage transfer created successfully: " + config.getName());
    } catch (ApiException ex) {
      System.out.print("Azure Blob Storage transfer was not created." + ex.toString());
    }
  }
}

Especifica la clave de encriptación con transferencias

Puedes especificar claves de encriptación administradas por el cliente (CMEKs) para encriptar los datos de una ejecución de transferencia. Puedes usar una CMEK para admitir transferencias de Azure Blob Storage.

Cuando especificas una CMEK con una transferencia, el Servicio de transferencia de datos de BigQuery aplica la CMEK a cualquier memoria caché del disco intermedia de datos transferidos para que todo el flujo de trabajo de transferencia de datos cumpla con la CMEK.

No puedes actualizar una transferencia existente para agregar una CMEK si la transferencia no se creó en un principio con una CMEK. Por ejemplo, no puedes cambiar una tabla de destino que se encriptó de forma predeterminada para que ahora se encripte con CMEK. Por el contrario, tampoco puedes cambiar una tabla de destino encriptada con CMEK para que tenga un tipo de encriptación diferente.

Puedes actualizar una CMEK para una transferencia si la configuración de la transferencia se creó en un principio con una encriptación de CMEK. Cuando actualizas una CMEK para una configuración de transferencia, el Servicio de transferencia de datos de BigQuery propaga la CMEK a las tablas de destino en la siguiente ejecución de la transferencia, en la que el Servicio de transferencia de datos de BigQuery reemplaza cualquier CMEK desactualizada por la CMEK nueva durante la ejecución de la transferencia. Para obtener más información, consulta Actualiza una transferencia.

También puedes usar las claves predeterminadas del proyecto. Cuando especificas una clave predeterminada de proyecto con una transferencia, el Servicio de transferencia de datos de BigQuery usa la clave predeterminada del proyecto como la clave predeterminada para cualquier configuración de transferencia nueva.

Soluciona problemas con la configuración de una transferencia

Si tienes problemas para configurar tu transferencia datos, consulta Problemas de transferencia de Blob Storage.

¿Qué sigue?