Transferts Cloud Storage

Le service de transfert de données BigQuery pour Cloud Storage vous permet de planifier des chargements de données récurrents depuis Cloud Storage vers BigQuery.

Avant de commencer

Avant de créer un transfert Cloud Storage, procédez comme suit :

Limites

Les transferts récurrents de Cloud Storage vers BigQuery sont soumis aux limitations suivantes :

  • Tous les fichiers correspondant aux schémas définis par un caractère générique ou par des paramètres d'exécution relatifs au transfert doivent partager le même schéma que celui défini pour la table de destination. Si ce n'est pas le cas, le transfert échoue. Les modifications de schéma de table entre les exécutions entraînent également l'échec du transfert.
  • Les objets Cloud Storage peuvent comporter des versions gérées ; il est donc important de noter que les objets Cloud Storage archivés ne sont pas acceptés pour les transferts BigQuery. Les objets doivent être publiés pour être transférés.
  • Contrairement aux chargements de données individuels de Cloud Storage vers BigQuery, vous devez créer la table de destination et son schéma avant de configurer le transfert pour les transferts continus. BigQuery ne peut pas créer la table dans le cadre du processus de transfert de données récurrent.
  • Les transferts à partir de Cloud Storage sont toujours déclenchés avec la préférence WRITE_APPEND, qui ajoute des données à la table de destination. Pour plus d'informations, consultez la description du champ writeDisposition de l'objet JobConfigurationLoad.
  • Si des fichiers Cloud Storage sont modifiés en cours de transfert, le service de transfert de données BigQuery ne garantit pas que tous les fichiers seront transférés, ou qu'ils ne seront transférés qu'une seule fois.
  • Si l'emplacement de votre ensemble de données est défini sur une valeur autre que US, le bucket Cloud Storage régional ou multirégional doit se trouver dans la même région que cet ensemble de données.
  • Le service de transfert de données BigQuery ne garantit pas la cohérence des données pour les sources de données externes. Les modifications apportées aux données sous-jacentes lors de l'exécution d'une requête peuvent entraîner un comportement inattendu.

  • Selon le format de vos données sources Cloud Storage, des limitations supplémentaires peuvent s'appliquer. Pour en savoir plus, consultez les pages suivantes :

  • Votre bucket Cloud Storage doit se trouver dans une région ou un emplacement multirégional compatible avec la région ou l'emplacement multirégional de l'ensemble de données de destination dans BigQuery. C'est ce qu'on appelle la colocation. Pour en savoir plus, consultez les emplacements de données de transfert de Cloud Storage.

Intervalles minimum

  • Les fichiers sources peuvent être transférés immédiatement, sans ancienneté minimale du fichier.
  • L'intervalle minimal entre les transferts récurrents est de 15 minutes. L'intervalle par défaut entre transferts récurrents est de 24 heures.

Autorisations requises

Lorsque vous chargez des données dans BigQuery, vous avez besoin d'autorisations qui vous permettent de charger des données dans des tables et partitions BigQuery nouvelles ou existantes. Si vous chargez des données depuis Cloud Storage, vous devez également avoir accès au bucket contenant vos données. Assurez-vous que vous disposez des autorisations requises suivantes :

  • BigQuery : assurez-vous que la personne qui crée le transfert dispose des autorisations suivantes dans BigQuery :

    • Autorisations bigquery.transfers.update pour créer le transfert
    • Les 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 bigquery.transfers.update, bigquery.datasets.update et bigquery.datasets.get. Pour en savoir plus sur les rôles IAM dans le cadre du service de transfert de données BigQuery, consultez la documentation de référence sur le Contrôle des accès.

  • Cloud Storage : vous devez disposer des autorisations storage.objects.get au niveau du bucket individuel ou à un niveau supérieur. Si vous utilisez un caractère générique dans l'URI, vous devez également disposer des autorisations storage.objects.list. Si vous souhaitez supprimer les fichiers sources après chaque transfert réussi, vous devez également disposer des autorisations storage.objects.delete. Le rôle Cloud IAM prédéfini storage.objectAdmin inclut toutes ces autorisations.

Configurer un transfert Cloud Storage

Pour créer un transfert Cloud Storage dans le service de transfert de données BigQuery :

Console

  1. Accédez à la page "BigQuery" de Cloud Console.

    Accéder à BigQuery

  2. Cliquez sur Transferts.

  3. Cliquez sur Create (Créer).

  4. Sur la page Créer un transfert :

    • Dans la section Source type (Type de source), choisissez Cloud Storage comme Source.

      Source de transfert

    • Dans la section Transfer config name (Nom de la configuration de transfert), sousDisplay name (Nom à afficher), saisissez un nom pour le transfert, tel que My Transfer. Ce nom peut correspondre à n'importe quelle valeur permettant d'identifier facilement le transfert si vous devez le modifier ultérieurement.

      Nom du transfert

    • Dans la section Schedule options (Options de programmation), pour le champ Custom Schedule (Programmation personnalisée), laissez la valeur par défaut Start now (Commencer), ou cliquez sur Start at a set time (Démarrer à l'heure définie).

      • Pour le champ Repeats (Périodicité), choisissez l'une des options suivantes pour la fréquence d'exécution du transfert. L'intervalle minimal est de 15 minutes.
        • Daily (Tous les jours) (par défaut)
        • Weekly (Toutes les semaines)
        • Tous les mois
        • Personnalisé : Pour Custom Schedule (Programmation personnalisée), saisissez une fréquence personnalisée. par exemple, every day 00:00. Consultez la section Mettre en forme le planning.
        • À la demande
      • Pour le champ Start date and run time (Date de début et heure d'exécution), saisissez la date et l'heure de début du transfert. Cette option est désactivée si vous choisissez Start now (Commencer maintenant).

        Programmation de transfert

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

      Transférer un ensemble de données

    • Dans la section Data source details (Détails de la source de données) :

      • Sous Destination table (Table de destination), saisissez le nom de votre table de destination. Le nom de la table de destination doit respecter les règles de dénomination des tables. Les noms de table de destination acceptent également les paramètres.
      • Dans le champ Cloud Storage URI (URI Cloud Storage), saisissez l'URI Cloud Storage. Les caractères génériques et les paramètressont acceptés.
      • Pour Préférences en écriture, sélectionnez :

        • AJOUTER pour ajouter de nouvelles données à votre table de destination existante ; ou
        • METTRE EN MIROIR pour actualiser les données dans la table de destination, afin de refléter les données modifiées dans la source. METTRE EN MIROIR écrase une nouvelle copie des données de la table de destination.
      • Cochez la case Delete source files after transfer (Supprimer les fichiers sources après le transfert) si vous souhaitez supprimer les fichiers sources après chaque transfert réussi. Les tâches de suppression représentent l'approche conseillée. Elles ne sont pas relancées si la première tentative de suppression des fichiers sources échoue.

      • Dans la section Transfer Options (Options de transfert) :

        • Sous All formats (Tous les formats) :
          • Dans le champ Number of errors allowed (Nombre d'erreurs autorisées), saisissez le nombre maximal d'enregistrements incorrects pouvant être ignorés par BigQuery lors de l'exécution de la tâche. Si cette valeur maximale est dépassée, une erreur de type "non valide" est renvoyée dans le résultat de la tâche, et cette dernière échoue. La valeur par défaut est 0.
          • (Facultatif) Pour les types de cibles décimal, saisissez une liste de types de données SQL possibles, séparés par une virgule, dans lequel les valeurs décimales source peuvent être converties. Le type de données SQL sélectionné pour la conversion dépend des conditions suivantes :
            • Le type de données sélectionné pour la conversion est le premier type de données de la liste suivante, qui accepte la précision et l'échelle des données sources dans l'ordre suivant: NUMERIC,BIGNUMERIC et STRING.
            • Si aucun des types de données répertoriés n'accepte la précision et l'échelle, le type de données compatible avec la plage la plus large de 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 est vide, le type de données par défaut est "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 des types de données que vous répertoriez dans ce champ est ignoré.
        • Sous JSON, CSV :
          • Cochez la case Ignore unknown values (Ignorer les valeurs inconnues) si vous souhaitez que les données ne correspondant pas au schéma de la table de destination ne soient pas prises en compte lors du transfert.
        • Sous CSV :

          • Dans le champ Field delimiter (Délimiteur de champ), saisissez le caractère qui sépare les champs. La valeur par défaut est une virgule.
          • Dans le champ Header rows to skip (Lignes d'en-tête à ignorer), saisissez le nombre de lignes d'en-tête contenues dans le ou les fichiers sources si vous ne souhaitez pas importer ces lignes. La valeur par défaut est 0.
          • Cochez la case Allow quoted newlines (Autoriser les nouvelles lignes entre guillemets) si vous souhaitez autoriser l'ajout de lignes dans les champs entre guillemets.
          • Cochez la case Allow jagged rows (Autoriser les lignes irrégulières) si vous souhaitez autoriser le transfert de lignes dont certaines colonnes NULLABLE sont manquantes.

      Détails de la source Cloud Storage

    • (Facultatif) Dans la section Notification options (Options de notification) :

      • Cliquez sur le bouton pour activer les notifications par e-mail. Lorsque vous activez cette option, l'administrateur de transfert reçoit une notification par e-mail en cas d'échec de l'exécution du transfert.
      • Pour le champ Select a Pub/Sub topic (Sélectionner un sujet Pub/Sub), choisissez le nom de votre sujet ou cliquez sur Create a topic (Créer un sujet). Cette option configure les notifications d'exécution Cloud Pub/Sub pour votre transfert.
  5. Cliquez sur Save (Enregistrer).

bq

Saisissez la commande bq mk, puis spécifiez l'indicateur de création de transfert --transfer_config. Les paramètres suivants sont également requis :

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

Où :

  • project_id est l'ID de votre projet. Si vous ne fournissez pas de --project_id afin de spécifier un projet particulier, le projet par défaut est utilisé.
  • data_source correspond à la source de données : google_cloud_storage.
  • name est le nom à afficher pour la configuration de transfert. Ce nom peut correspondre à toute valeur permettant d'identifier facilement le transfert si vous devez le modifier ultérieurement.
  • dataset est l'ensemble de données cible de la configuration de transfert.
  • parameters contient les paramètres de la configuration de transfert créée au format JSON. Exemple : --params='{"param":"param_value"}'.
    • Pour Cloud Storage, vous devez fournir les paramètres data_path_template, destination_table_name_template et file_format. Le paramètre data_path_template correspond à l'URI Cloud Storage contenant les fichiers à transférer (ce paramètre peut comporter un caractère générique). Le paramètre destination_table_name_template est le nom de votre table de destination. Pour le paramètre file_format, indiquez le type de fichiers que vous souhaitez transférer : CSV, JSON, AVRO, PARQUET ou ORC. La valeur par défaut est CSV.
    • Pour toutes les valeurs "file_format", vous pouvez inclure le paramètre facultatif max_bad_records. La valeur par défaut est 0.
    • Pour toutes les valeurs "file_format", vous pouvez inclure le paramètre facultatif decimal_target_types. decimal_target_types est une liste de types de données SQL possibles, séparés par une virgule, dans lequel les valeurs décimales source peuvent être converties. Si ce champ n'est pas fourni, le type de données par défaut sera "NUMERIC,STRING" pour ORC et "NUMERIC" pour les autres formats de fichiers.
    • Si vous utilisez la valeur JSON ou CSV en tant que "file_format", vous pouvez inclure le paramètre facultatif ignore_unknown_values. Si vous n'avez pas sélectionné CSV ou JSON pour file_format, ce paramètre sera ignoré.
    • Si vous utilisez la valeur CSV en tant que "file_format", vous pouvez inclure le paramètre facultatif field_delimiter pour le caractère séparant les champs. La valeur par défaut est une virgule. Si vous n'avez pas sélectionné CSV pour file_format, ce paramètre sera ignoré.
    • Si vous utilisez la valeur CSV en tant que "file_format", vous pouvez inclure le paramètre facultatif skip_leading_rows pour indiquer les lignes d'en-tête que vous ne souhaitez pas importer. La valeur par défaut est 0. Si vous n'avez pas sélectionné CSV pour file_format, ce paramètre sera ignoré.
    • Si vous utilisez la valeur CSV en tant que "file_format", vous pouvez inclure le paramètre facultatif allow_quoted_newlines si vous souhaitez autoriser l'ajout de lignes dans les champs entre guillemets. Si vous n'avez pas sélectionné CSV pour file_format, ce paramètre sera ignoré.
    • Si vous utilisez la valeur CSV en tant que "file_format", vous pouvez inclure le paramètre facultatif allow_jagged_rows si vous souhaitez accepter les lignes auxquelles il manque des colonnes facultatives finales. Les valeurs absentes seront remplacées par des valeurs "NULL". Si vous n'avez pas sélectionné CSV pour file_format, ce paramètre sera ignoré.
    • Le paramètre facultatif delete_source_files permet de supprimer les fichiers sources après chaque transfert réussi. Notez que les tâches de suppression ne sont pas relancées si la première tentative de suppression des fichiers sources échoue. La valeur par défaut pour delete_source_files est "false".

Par exemple, la commande suivante crée un transfert Cloud Storage nommé My Transfer. La valeur data_path_template est définie pour gs://mybucket/myfile/*.csv, l'ensemble de données cible est nommé mydataset et le type de fichiersfile_format est CSV. Cet exemple utilise des valeurs autres que celles par défaut pour les paramètres facultatifs associés au format de fichiers CSV.

Le transfert est créé dans le projet par défaut :

bq mk --transfer_config \
--target_dataset=mydataset \
--display_name='My Transfer' \
--params='{"data_path_template":"gs://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=google_cloud_storage

Après avoir exécuté la commande, vous recevez un message de ce type :

[URL omitted] Please copy and paste the above URL into your web browser and follow the instructions to retrieve an authentication code.

Suivez les instructions et collez le code d'authentification sur la ligne de commande.

API

Utilisez la méthode projects.locations.transferConfigs.create et fournissez une instance de la ressource 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 google cloud storage transfer config
public class CreateCloudStorageTransfer {

  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";
    // GCS Uri
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv";
    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("data_path_template", Value.newBuilder().setStringValue(sourceUri).build());
    params.put("write_disposition", Value.newBuilder().setStringValue("APPEND").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());
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName("Your Google Cloud Storage Config Name")
            .setDataSourceId("google_cloud_storage")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .setSchedule("every 24 hours")
            .build();
    createCloudStorageTransfer(projectId, transferConfig);
  }

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

Déclencher manuellement un transfert

En plus des transferts planifiés automatiquement depuis Cloud Storage, vous pouvez déclencher manuellement un transfert pour charger des fichiers de données supplémentaires.

Si la configuration de transfert est paramétrée par défaut, vous devez spécifier une plage de dates pour lesquelles des transferts supplémentaires seront lancés.

Pour déclencher manuellement un transfert, procédez comme suit:

Console

  1. Accédez à la page "BigQuery" de Cloud Console.

    Accéder à BigQuery

  2. Cliquez sur Transferts de données.

  3. Cliquez sur le transfert.

  4. Cliquez sur EXÉCUTER LE TRANSFERT ou RENDRE BACKFILL (pour les configurations de transfert paramétrées de l'environnement d'exécution).

  5. Le cas échéant, sélectionnez la Date de début et la Date de fin, puis cliquez sur OK pour confirmer.

    TRANSFÉRER

    Pour les configurations de transfert paramétrées d'exécution, vous verrez apparaître les options de date en cliquant sur Programmer la sauvegarde.

    PLANIFIER LA RETOUR

Étape suivante