Transferts de stockage de blobs

Le service de transfert de données BigQuery pour Azure Blob Storage vous permet de planifier et de gérer automatiquement les tâches de chargement récurrentes de Blob Storage dans BigQuery.

Avant de commencer

Avant de créer un transfert de stockage de blobs, procédez comme suit :

Autorisations requises

Pour créer un transfert de stockage de blobs, vous devez disposer de l'autorisation IAM (Identity and Access Management) bigquery.transfers.update. Vous devez également disposer des autorisations bigquery.datasets.get et bigquery.datasets.update sur l'ensemble de données cible.

Le rôle IAM prédéfini bigquery.admin inclut les autorisations dont vous avez besoin pour créer un transfert de stockage de blobs.

Pour plus d'informations sur BigQuery IAM, consultez la page Contrôle des accès avec IAM.

Pour vérifier que vous disposez des autorisations nécessaires dans Blob Storage pour activer le transfert, consultez la section Signature d'accès partagé (SAP).

Si vous avez l'intention de configurer des notifications d'exécution de transfert pour Pub/Sub, vous devez disposer de l'autorisation pubsub.topics.setIamPolicy. Les autorisations Pub/Sub ne sont pas nécessaires pour les notifications par e-mail. Pour en savoir plus, consultez la page Notifications d'exécution du service de transfert de données BigQuery.

Limites

Les transferts du stockage de blobs sont soumis aux limitations suivantes :

Configurer un transfert de données de stockage de blobs

Sélectionnez l'une des options suivantes :

Console

  1. Dans la console Google Cloud, accédez à la page BigQuery.

    Accéder à BigQuery

  2. Dans le menu de navigation de BigQuery, cliquez sur Transferts de données.

  3. Cliquez sur Créer un transfert.

  4. Sur la page Créer un transfert, procédez comme suit :

    • Dans la section Type de source, choisissez Azure Blob Storage pour Source.

      Type de source de transfert

    • Dans la section Nom de la configuration de transfert, sous Nom à afficher, saisissez le nom du transfert.

    • Dans la section Schedule options (Options de programmation) :

      • Sélectionnez une fréquence de répétition. Si vous sélectionnez Heures, Jours, Semaines ou Mois, vous devez également spécifier une fréquence. Vous pouvez également sélectionner Personnalisé pour spécifier une fréquence de répétition personnalisée. Si vous sélectionnez À la demande, ce transfert s'exécute lorsque vous déclenchez manuellement le transfert.

      • Le cas échéant, sélectionnez Commencer ou Démarrer à l'heure définie, puis indiquez une date de début et une heure d'exécution.

    • Dans la section Paramètres de destination, pour le champ Ensemble de données de destination, choisissez l'ensemble de données que vous avez créé pour stocker vos données.

    • Dans la section Data source details (Détails de la source de données), procédez comme suit :

      • Pour le champ Destination table (Table de destination), saisissez le nom de la table que vous avez créée pour stocker les données dans BigQuery. Les noms de table de destination sont compatibles avec les paramètres.
      • Dans le champ Nom du compte de stockage Azure, saisissez le nom du compte Blob Storage.
      • Dans le champ Nom du conteneur, saisissez le nom du conteneur Blob Storage.
      • Pour Chemin d'accès aux données, saisissez le chemin d'accès permettant de filtrer les fichiers à transférer. Affichez des exemples.
      • Dans le champ Jeton SAP, saisissez le jeton Azure SAP.
      • Dans le champ Format de fichier, choisissez le format des données source.
      • Pour Disposition d'écriture, sélectionnez WRITE_APPEND pour ajouter de nouvelles données de manière incrémentielle à la table de destination, ou WRITE_TRUNCATE pour écraser les données dans la table de destination à chaque exécution de transfert. WRITE_APPEND est la valeur par défaut pour la disposition d'écriture.

      Pour en savoir plus sur la manière dont le service de transfert de données BigQuery ingère des données à l'aide de WRITE_APPEND ou de WRITE_TRUNCATE, consultez la page Ingestion de données pour Azure Blob Transfers. Pour en savoir plus sur le champ writeDisposition, consultez la section JobConfigurationLoad.

      Détails de la source de données

    • Dans la section Options de transfert, procédez comme suit :

      • Dans le champ Number of errors allowed (Nombre d'erreurs autorisées), saisissez une valeur entière pour le nombre maximal d'enregistrements incorrects pouvant être ignorés. La valeur par défaut est 0.
      • (Facultatif) Pour les types de cibles décimaux, saisissez une liste de types de données SQL possibles (séparés par des virgules) vers lesquels les valeurs décimales des données sources sont converties. Le type de données SQL sélectionné pour la conversion dépend des conditions suivantes :
        • Dans l'ordre NUMERIC, BIGNUMERIC et STRING, un type est choisi s'il figure dans votre liste spécifiée et s'il est compatible avec la précision et l'échelle.
        • Si aucun des types de données répertoriés n'accepte la précision et l'échelle, le type de données acceptant la plus large plage parmi la liste spécifiée est sélectionné. Si une valeur dépasse la plage acceptée lors de la lecture des données sources, une erreur est renvoyée.
        • Le type de données STRING accepte toutes les valeurs de précision et d'échelle.
        • Si ce champ n'est pas renseigné, le type de données est défini par défaut sur NUMERIC,STRING pour ORC et NUMERIC pour les autres formats de fichiers.
        • Ce champ ne peut pas contenir de types de données en double.
        • L'ordre dans lequel vous répertoriez les types de données est ignoré.

    • Si vous avez choisi CSV ou JSON comme format de fichier, dans la section JSON, CSV, cochez Ignorer les valeurs inconnues pour accepter les lignes contenant des valeurs qui ne correspondent pas au schéma.

    • Si vous avez choisi CSV comme format de fichier, dans la section CSV, saisissez les options CSV supplémentaires pour le chargement des données.

      Options CSV

    • Dans la section Options de notification, vous pouvez choisir d'activer les notifications par e-mail et les notifications Pub/Sub.

      • Lorsque vous activez les notifications par e-mail, l'administrateur de transfert reçoit une notification par e-mail en cas d'échec de l'exécution du transfert.
      • Lorsque vous activez les notifications Pub/Sub, choisissez un nom de sujet pour publier ou cliquez sur Créer un sujet pour en créer un.

    • Si vous utilisez des clés CMEK, dans la section Options avancées, sélectionnez Clé gérée par le client. La liste des clés CMEK disponibles s'affiche. Pour en savoir plus sur le fonctionnement des clés CMEK avec le service de transfert de données BigQuery, consultez la page Spécifier une clé de chiffrement avec des transferts.

  5. Cliquez sur Enregistrer.

bq

Exécutez la commande bq mk --transfer_config pour créer un transfert de stockage de blobs :

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

Remplacez les éléments suivants :

  • PROJECT_ID : (facultatif) ID du projet contenant votre ensemble de données cible. Si non spécifié, votre projet par défaut est utilisé.
  • DATA_SOURCE : azure_blob_storage.
  • DISPLAY_NAME : nom à afficher de la configuration de transfert. Ce nom peut correspondre à n'importe quelle valeur permettant d'identifier facilement le transfert si vous devez le modifier ultérieurement.
  • DATASET : ensemble de données cible de la configuration de transfert.
  • DESTINATION_KEY : (facultatif) ID de ressource de la clé Cloud KMS (par exemple, projects/project_name/locations/us/keyRings/key_ring_name/cryptoKeys/key_name).
  • PARAMETERS : paramètres de la configuration de transfert, répertoriés au format JSON. Exemple : --params={"param1":"value1", "param2":"value2"}. Voici les paramètres d'un transfert de stockage de blobs :
    • destination_table_name_template : valeur obligatoire. Le nom de votre table de destination.
    • storage_account : valeur obligatoire. Nom du compte Blob Storage.
    • container : valeur obligatoire. Nom du conteneur Blob Storage.
    • data_path : facultatif. Chemin d'accès pour filtrer les fichiers à transférer. Affichez des exemples.
    • sas_token : valeur obligatoire. Le jeton Azure SAS.
    • file_format : facultatif. Le type de fichiers que vous souhaitez transférer : CSV, JSON, AVRO, PARQUET ou ORC. La valeur par défaut est CSV.
    • write_disposition : facultatif. Sélectionnez WRITE_APPEND pour ajouter des données à la table de destination, ou WRITE_TRUNCATE pour écraser les données de la table de destination. La valeur par défaut est WRITE_APPEND.
    • max_bad_records : facultatif. Le nombre d'enregistrements incorrects autorisés. La valeur par défaut est 0.
    • decimal_target_types : facultatif. Liste de types de données SQL possibles, séparés par des virgules, vers lesquels les valeurs décimales des données sources sont converties. Si ce champ n'est pas renseigné, le type de données par défaut est NUMERIC,STRING pour ORC et NUMERIC pour les autres formats de fichiers.
    • ignore_unknown_values : facultatif. Cette valeur est ignorée si file_format n'est pas défini sur JSON ou CSV. Définissez la valeur sur true pour accepter les lignes contenant des valeurs qui ne correspondent pas au schéma.
    • field_delimiter : facultatif. Cette valeur s'applique uniquement lorsque file_format est défini sur CSV. Le caractère de séparation des champs. La valeur par défaut est ,.
    • skip_leading_rows : facultatif. Cette valeur s'applique uniquement lorsque file_format est défini sur CSV. Indique le nombre de lignes d'en-tête que vous ne souhaitez pas importer. La valeur par défaut est 0.
    • allow_quoted_newlines : facultatif. Cette valeur s'applique uniquement lorsque file_format est défini sur CSV. Indique si les sauts de ligne doivent être autorisés dans les champs entre guillemets.
    • allow_jagged_rows : facultatif. Cette valeur s'applique uniquement lorsque file_format est défini sur CSV. Indique s'il faut accepter les lignes pour lesquelles il manque des colonnes facultatives finales. Les valeurs manquantes sont renseignées avec NULL.

Par exemple, la commande suivante crée un transfert de stockage de blobs appelé 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"}

Java

Avant d'essayer cet exemple, suivez les instructions de configuration pour Java du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Java.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes. 


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

Spécifier une clé de chiffrement avec les transferts

Vous pouvez spécifier des clés de chiffrement gérées par le client (CMEK) pour chiffrer les données d'une exécution de transfert. Vous pouvez utiliser une clé CMEK pour assurer le transfert depuis Azure Blob Storage.

Lorsque vous spécifiez une clé CMEK avec un transfert, le service de transfert de données BigQuery l'applique à tous les caches sur disque intermédiaires des données ingérées afin que l'intégralité du workflow de transfert de données soit compatible avec CMEK.

Vous ne pouvez pas mettre à jour un transfert existant pour ajouter une clé CMEK si le transfert n'a pas été initialement créé avec une clé CMEK. Par exemple, vous ne pouvez pas modifier une table de destination initialement chiffrée par défaut pour être chiffrée avec des clés CMEK. À l'inverse, vous ne pouvez pas modifier une table de destination chiffrée par CMEK pour obtenir un type de chiffrement différent.

Vous pouvez mettre à jour une clé CMEK pour un transfert si la configuration de celui-ci a été initialement créée avec un chiffrement CMEK. Lorsque vous mettez à jour une clé CMEK pour une configuration de transfert, le service de transfert de données BigQuery propage cette clé aux tables de destination à la prochaine exécution du transfert, où le service de transfert de données BigQuery remplace toutes les clés CMEK obsolètes par la nouvelle clé lors de l'exécution du transfert. Pour en savoir plus, consultez Mettre à jour un transfert.

Vous pouvez également utiliser les clés par défaut d'un projet. Lorsque vous spécifiez une clé de projet par défaut avec un transfert, le service de transfert de données BigQuery utilise cette clé pour toutes les nouvelles configurations de transfert.

Résoudre les problèmes liés à la configuration d'un transfert

Si vous rencontrez des problèmes lors de la configuration de votre transfert, consultez la section Problèmes de transfert avec le stockage de blobs.

Étapes suivantes