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 fichiers sources dans Cloud Storage doivent dater d'au moins une heure pour être récupérés lors 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 en cours. 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 section relative à configuration.load.writeDisposition sous la propriété configuration.load.
  • 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.

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 :

Autorisations requises

Pour charger des données dans BigQuery, vous devez disposer, au niveau du projet ou de l'ensemble de données, des autorisations requises pour charger des données dans des tables et des 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 : vous devez disposer des autorisations bigquery.transfers.update pour créer le transfert planifié. Le rôle IAM bigquery.admin prédéfini au niveau du projet inclut les autorisations bigquery.transfers.update. Pour en savoir plus sur les rôles IAM dans BigQuery, consultez la page Contrôle des accès.
  • Cloud Storage : vous devez disposer des autorisations storage.objects.get au niveau du projet ou du bucket individuel. 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 IAM storage.objectAdmin prédéfini au niveau du projet 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 :

UI classique

  1. Accédez à l'UI Web de BigQuery.

    Accéder à l'interface utilisateur Web de BigQuery

  2. Cliquez sur Transferts.

  3. Cliquez sur Ajouter un transfert.

  4. Sur la page Nouveau transfert :

    • Comme Source, choisissez Cloud Storage.
    • Dans le champ Display name (Nom à afficher), saisissez un nom pour la requête programmée, tel que My Transfer. Le nom à afficher peut être n'importe quelle valeur permettant d'identifier facilement le transfert si vous devez le modifier par la suite.
    • (Facultatif) Pour Schedule (Programmation), vous pouvez conserver la valeur par défaut Daily (toutes les 24 heures, en fonction de l'heure de création) ou cliquer sur Edit (Modifier) pour modifier l'heure d'exécution. Vous pouvez également modifier l'intervalle d'exécution en Hebdomadaire, Mensuel ou Personnalisé. Lorsque vous sélectionnez "Custom" (valeur personnalisée), vous devez ajouter une spécification temporelle de type Cron, par exemple every 12 hours. La période la plus courte autorisée est de 12 heures. Reportez-vous à la section concernant le champ schedule sur la page relative à TransferConfig pour découvrir d'autres valeurs d'API valides.

      Exécution programmée de la requête

    • Pour Ensemble de données de destination, sélectionnez l'ensemble de données approprié.

    • Sous 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ètres sont acceptés.

    • Cochez la case située en regard de 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 la plus conseillée. Elles ne sont pas relancées si la première tentative de suppression des fichiers sources échoue.

    • Pour la valeur File format (format de fichier), sélectionnez le type de fichiers que vous souhaitez transférer.

    • Sous la section Options de transfert – 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.
    • Sous la section Options de transfert – JSON, CSV :

      • Cochez la case située en regard de 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 la section Options de transfert – CSV :

      • Sous 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 située en regard de 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 située en regard de Allow jagged rows (Autoriser les lignes irrégulières) si vous souhaitez autoriser le transfert de lignes dont certaines colonnes NULLABLE sont manquantes.

      Nouveau transfert Cloud Storage

    • (Facultatif) Développez la section Advanced (Avancé), puis configurez les notifications d'exécution pour votre transfert. Les notifications d'exécution de transfert sont actuellement en version alpha.

    • Sous Cloud Pub/Sub topic (Sujet Cloud Pub/Sub), saisissez le nom de votre sujet Cloud Pub/Sub, par exemple projects/myproject/topics/mytopic.

    • Cochez la case Send email notifications (Envoyer des notifications par e-mail) pour autoriser les notifications par e-mail en cas d'échec de l'exécution des transferts.

      Sujet Cloud Pub/Sub

  5. Cliquez sur Ajouter.

Ligne de commande

Saisissez la commande bq mk, puis spécifiez l'indicateur de création de transfert --transfer_config. Les indicateurs 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'identifiant 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 est la source de données (google_cloud_storage).
  • --display_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.
  • --target_dataset est l'ensemble de données cible de la configuration de transfert.
  • --params contient les paramètres de la configuration de transfert créée au format JSON. Par 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 correspond au 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.
    • Si vous utilisez la valeur JSON ou CSV en tant que "file_format", vous pouvez inclure le paramètre facultatif ignore_unknown_values. Ce paramètre sera ignoré si vous n'avez pas sélectionné CSV ou JSON pour file_format.
    • 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. Ce paramètre sera ignoré si vous n'avez pas sélectionné la valeur CSV pour file_format.
    • 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. Ce paramètre sera ignoré si vous n'avez pas sélectionné la valeur CSV pour file_format.
    • 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. Ce paramètre sera ignoré si vous n'avez pas sélectionné la valeur CSV pour file_format.
    • 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". Ce paramètre sera ignoré si vous n'avez pas sélectionné la valeur CSV pour file_format.
    • 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 de delete_source_files est "false" (faux).

Par exemple, la commande suivante crée un transfert Cloud Storage nommé My Transfer. La valeur gs://mybucket/myfile/*.csv est définie pour data_path_template, l'ensemble de données cible est nommé mydataset et le type de fichiers (file_format) à transférer 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

Exécutez la méthode projects.locations.transferConfigs.create et indiquez une instance de la ressource TransferConfig.

Configurer une opération d'actualisation d'un transfert

Outre le fait de configurer un transfert récurrent à partir de Cloud Storage, vous pouvez également configurer une opération d'actualisation afin de récupérer des fichiers de données supplémentaires.

Si la configuration du transfert est liée à la date (paramétrée), si l'URI Cloud Storage est paramétré, ou si les deux cas s'appliquent, vous pouvez exécuter l'opération d'actualisation pour des dates spécifiques.

Pour configurer un transfert d'actualisation, procédez comme suit :

UI classique

  1. Accédez à l'UI Web de BigQuery.

    Accéder à l'interface utilisateur Web de BigQuery

  2. Cliquez sur Transferts.

  3. Cliquez sur le transfert.

  4. Cliquez sur Actualiser le transfert.

    Actualiser le transfert

  5. Dans la boîte de dialogue Démarrer les exécutions de transfert, sélectionnez l'heure de début et l'heure de fin.

    définir des dates dans l'historique

    Si votre configuration de transfert Cloud Storage n'est pas paramétrée, aucune option de date ne s'affiche lorsque vous cliquez sur Actualiser le transfert. Au lieu de cela, l'actualisation a lieu immédiatement. Les fichiers doivent dater au moins d'une heure pour être récupérés lors du transfert.

    Actualiser immédiatement

  6. Cliquez sur OK.

Étape suivante

Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

Besoin d'aide ? Consultez notre page d'assistance.