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 depuis Cloud Storage définissent le paramètre Préférence d'écriture sur APPEND par défaut. Dans ce mode, un fichier non modifié ne peut être chargé dans BigQuery qu'une seule fois. Si la propriété last modification time du fichier est mise à jour, celui-ci est actualisé.
  • 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 la zone de votre ensemble de données est définie 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.
  • 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.
  • BigQuery n'est pas compatible avec la gestion des versions d'objets Cloud Storage. Si vous incluez un numéro de génération dans l'URI Cloud Storage, la tâche de chargement échoue.

  • 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 sont immédiatement prélevés pour transfert, aucun âge minimal de fichier n'est requis.
  • L'intervalle minimum entre deux 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
    • 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 associés au 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)
        • Monthly (Tous les mois)
        • Custom (personnalisée) Pour Custom Schedule (Programmation personnalisée), saisissez une fréquence personnalisée. Par exemple, every day 00:00. Consultez la section Mettre en forme l'élément schedule.
        • À 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 :

        • APPEND pour ajouter de nouvelles données à votre table de destination existante. Les tâches de chargement BigQuery sont déclenchées avec la préférence WRITE_APPEND. Pour en savoir plus, consultez les détails du champ writeDisposition de l'objet JobConfigurationLoad. La valeur par défaut pour le paramètre Write preference (Préférence d'écriture) est APPEND.
        • 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écimaux, saisissez une liste de types de données SQL possibles (séparés par des virgules) vers lesquels les valeurs décimales sources 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 sera le premier type de données de la liste suivante qui accepte la précision et l'échelle des données sources, dans cet ordre : 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 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 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 des virgules, vers lesquels les valeurs décimales sources peuvent être converties. Si ce champ n'est pas fourni, le type de données par défaut est "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

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

Si la configuration du transfert est paramétrée au moment de l'exécution, vous devez spécifier une plage de dates pour laquelle des transferts supplémentaires seront démarrés.

Pour déclencher manuellement un transfert :

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 maintenant ou Programmer le remplissage (pour les configurations de transfert paramétrées au moment de l'exécution).

  5. Le cas échéant, choisissez une date de début et une date de fin, puis cliquez sur OK pour confirmer.

    Exécuter le transfert maintenant

    Pour les configurations de transfert paramétrées au moment de l'exécution, des options de date s'affichent lorsque vous cliquez sur Programmer le remplissage.

    Programmer le remplissage

Étape suivante