Transferts Amazon S3

Le service de transfert de données BigQuery pour Amazon S3 vous permet de planifier et de gérer automatiquement les tâches de chargement récurrentes à partir d'Amazon S3 dans BigQuery.

Avant de commencer

Avant de créer un transfert Amazon S3 :

  • Vérifiez que vous avez effectué toutes les actions requises pour activer le service de transfert de données BigQuery.
  • Si vous créez le transfert à l'aide de l'interface utilisateur Web classique de BigQuery, autorisez les fenêtres pop-up de bigquery.cloud.google.com dans votre navigateur pour pouvoir afficher la fenêtre des autorisations. Vous devez autoriser le service de transfert de données BigQuery à gérer le transfert.
  • Créez un ensemble de données BigQuery pour stocker vos données.
  • Créez la table de destination pour votre transfert et spécifiez la définition du schéma. 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.
  • Récupérez votre URI Amazon S3, votre ID de clé d'accès et votre clé d'accès secrète. Pour plus d'informations sur la gestion de vos clés d'accès, consultez la documentation AWS.
  • Si vous avez l'intention de configurer des notifications d'exécution de transfert pour Pub/Sub, vous devez disposer des autorisations pubsub.topics.setIamPolicy. Les autorisations Pub/Sub ne sont pas nécessaires si vous ne configurez que des notifications par e-mail. Pour plus d'informations, consultez la page Notifications d'exécution du service de transfert de données BigQuery.

Limites

Les transferts Amazon S3 sont soumis aux limitations suivantes :

  • Actuellement, la partie compartiment de l'URI ne peut pas être paramétrée.
  • Les transferts depuis Amazon S3 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 configuration.load.writeDisposition dans la configuration de la tâche .
  • Selon le format de vos données sources Amazon S3, des limitations supplémentaires peuvent s'appliquer. Pour en savoir plus, consultez les pages suivantes :

Autorisations requises

Avant de créer un transfert Amazon S3 :

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

    • Autorisations bigquery.transfers.update pour créer le transfert
    • Autorisations bigquery.datasets.update sur l'ensemble de données cible

    Le rôle Cloud IAM prédéfini bigquery.admin inclut les autorisations bigquery.transfers.update et bigquery.datasets.update. Pour en savoir plus sur les rôles Cloud 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.

  • Consultez la documentation d'Amazon S3 pour vous assurer que vous avez configuré toutes les autorisations nécessaires pour activer le transfert. Au minimum, la stratégie AWS gérée AmazonS3ReadOnlyAccess doit être appliquée aux données sources Amazon S3.

Configuration d'un transfert de données Amazon S3

Pour créer un transfert de données Amazon S3 :

Console

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

    Accéder à Cloud Console

  2. Cliquez sur Transfers (Transferts).

  3. Cliquez sur Create a Transfer (Créer un transfert).

  4. Sur la page Create Transfer (Créer un transfert) :

    • Dans le champ Source de la section Source type (Type de source), choisissez Amazon S3.

      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. Les options incluent :

        • Daily (Tous les jours) (par défaut)
        • Weekly (Toutes les semaines)
        • Monthly (Tous les mois)
        • Custom (Personnalisé)
        • On-demand (À la demande)

        Si vous choisissez une option autre que Daily (Tous les jours), des options supplémentaires sont disponibles. Par exemple, si vous choisissez Weekly (Toutes les semaines), une option vous permet de sélectionner le jour de la semaine.

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

        Planning 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) :

      • 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.
      • Pour le champ URI Amazon S3, saisissez l'URI au format s3://mybucket/myfolder/.... Les URI sont eux aussi compatibles avec les paramètres.
      • Pour le champ Access key ID (ID de clé d’accès), saisissez votre ID de clé d’accès.
      • Pour Secret access key (Clé d'accès secrète), saisissez votre clé d'accès secrète.
      • Pour le champ File format (Format de fichier) choisissez votre format de données : JSON (délimité par une nouvelle ligne), CSV, Avro, Parquet ou Orc.

        Détails de la source S3

    • Dans la section Transfer Options (Options de transfert), sous 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.

      Nombre d'erreurs autorisées

    • Si vous avez choisi CSV ou JSON comme format de fichier, dans la section JSON, CSV, cochez Ignore unknown values (Ignorer les valeurs inconnues) pour accepter les lignes contenant des valeurs qui ne correspondent pas au schéma. Les valeurs inconnues sont ignorées. Pour les fichiers CSV, cette option ignore les valeurs supplémentaires en fin de ligne.

      Ignorer les valeurs inconnues

    • 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

    • (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 Select a Cloud Pub/Sub topic (Sélectionnez un sujet Cloud Pub/Sub), choisissez le nom de votre sujet ou cliquez sur Create a topic (Créer un sujet) pour en créer un. Cette option configure les notifications d'exécution Cloud Pub/Sub pour votre transfert.
  5. Cliquez sur Save.

Interface utilisateur classique

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

    Accéder à l'UI Web de BigQuery

  2. Cliquez sur Transfers (Transferts).

  3. Cliquez sur Add Transfer (Ajouter un transfert).

  4. Sur la page New Transfer (Nouveau transfert) :

    • Pour Source, choisissez Amazon S3.
    • Pour le champ Display name (Nom à afficher), saisissez le nom du transfert, par exemple 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 et le définir sur "Weekly" (Toutes les semaines), "Monthly" (Tous les mois) ou "Custom" (Personnalisé). Lorsque vous sélectionnez Custom (Personnalisé), 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. Consultez les informations concernant le champ schedule dans la section TransferConfig pour découvrir d'autres valeurs d'API valides.
    • Pour Destination dataset (Ensemble de données de destination), sélectionnez l'ensemble de données approprié.
    • 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.
    • Pour URI Amazon S3, saisissez l'URI Amazon S3. Les caractères génériques et les paramètres sont acceptés.
    • Pour le champ Access key ID (ID de clé d’accès), saisissez votre ID de clé d’accès.
    • Pour Secret access key (Clé d'accès secrète), saisissez votre clé d'accès secrète.
    • Pour le champ File format (Format de fichier) choisissez votre format de données : JSON (délimité par une nouvelle ligne), CSV, Avro, Parquet ou Orc.
    • Sous la section Transfer Options - All Formats (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.
    • Si vous avez choisi CSV ou JSON comme format de données, dans la section Transfer Options - JSON, CSV (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.
    • Si vous avez choisi CSV comme format de données, dans la section Transfer Options — CSV (Options de transfert - CSV) :

      • Sous 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.
    • (Facultatif) Développez la section Advanced (Avancé), puis configurez les notificationsd'exécution pour votre transfert.

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

CLI

Saisissez la commande bq mk, puis spécifiez l'indicateur de création de transfert --transfer_config.

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

Où :

  • project_id : facultatif. L'ID de votre projet Google Cloud. Si vous ne fournissez pas de --project_id afin de spécifier un projet particulier, le projet par défaut est utilisé.
  • data_source : obligatoire. La source de données : amazon_s3.
  • display_name : obligatoire. Le nom d'affichage pour 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 : obligatoire. L'ensemble de données cible de la configuration de transfert.
  • parameters : obligatoire. Les paramètres de la configuration de transfert créée, au format JSON. Exemple : --params='{"param":"param_value"}'. Voici les paramètres d'un transfert Amazon S3 :

    • destination_table_name_template : obligatoire. Le nom de votre table de destination.
    • data_path : obligatoire. L'URI Amazon S3, au format suivant :

      s3://mybucket/myfolder/...

      Les URI sont eux aussi compatibles avec les paramètres.

    • access_key_id : obligatoire. Votre ID de clé d'accès.

    • secret_access_key : obligatoire. Votre clé d'accès secrète.

    • file_format : facultatif. Indique le type de fichiers que vous souhaitez transférer : CSV, JSON, AVRO, PARQUET ou ORC. La valeur par défaut est CSV.

    • max_bad_records : facultatif. Le nombre d'enregistrements incorrects autorisés. La valeur par défaut est 0.

    • ignore_unknown_values : facultatif, ignoré si file_format n'est pas JSON ou CSV. Indique si vous souhaitez ignorer les valeurs inconnues dans vos données.

    • field_delimiter : facultatif, s'applique uniquement lorsque le format de fichier file_format est CSV. Le caractère de séparation des champs. La valeur par défaut est une virgule.

    • skip_leading_rows : facultatif, s'applique uniquement si le format de fichier file_format est 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, s'applique uniquement lorsque le format de fichier file_format est CSV. Indique si les sauts de ligne doivent être autorisés dans les champs entre guillemets.

    • allow_jagged_rows : facultatif, s'applique uniquement lorsque le format de fichier file_format est CSV. Indique s'il faut accepter les lignes pour lesquelles il manque des colonnes facultatives finales. Les valeurs absentes seront remplacées par des valeurs "NULL".

Par exemple, la commande suivante crée un transfert Amazon S3 nommé My Transfer, utilisant la valeur s3://mybucket/myfile/*.csv pour data_path_template, l'ensemble de données cible mydataset et le format de fichier file_format 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":"s3://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=amazon_s3

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.

Interroger les données

Lorsque les données sont transférées vers BigQuery, elles sont écrites dans des tables partitionnées avec date d'ingestion. Pour plus d'informations, consultez la page Présentation des tables partitionnées.

Si vous interrogez directement les tables au lieu d'utiliser les vues générées automatiquement, vous devez utiliser la pseudo-colonne _PARTITIONTIME dans votre requête. Pour en savoir plus, consultez la page Interroger des tables partitionnées.

Impact de la correspondance des préfixes ou des caractères génériques

L'API Amazon S3 accepte la correspondance des préfixes, mais pas celle des caractères génériques. Tous les fichiers Amazon S3 correspondant à un préfixe donné seront transférés vers Google Cloud. Toutefois, seuls ceux qui correspondent à l'URI Amazon S3 spécifié dans la configuration du transfert seront effectivement chargés dans BigQuery. Cela peut entraîner un surcoût de sortie Amazon S3 pour tous les fichiers qui sont transférés, mais non chargés dans BigQuery.

À titre d'exemple, considérons le chemin de données suivant :

s3://bucket/folder/*/subfolder/*.csv

ainsi que les fichiers suivants dans l'emplacement source :

s3://bucket/folder/any/subfolder/file1.csv
s3://bucket/folder/file2.csv

Cette combinaison aura pour résultat de transférer vers Google Cloud tous les fichiers Amazon S3 comportant le préfixe s3://bucket/folder/. Dans cet exemple, file1.csv et file2.csv seront tous les deux transférés.

Cependant, seuls les fichiers correspondant à s3://bucket/folder/*/subfolder/*.csv seront effectivement chargés dans BigQuery. Ainsi, dans cet exemple, seul file1.csv sera chargé dans BigQuery.

Dépannage

La section suivante décrit les erreurs courantes et présente les solutions recommandées.

Erreurs Amazon S3 PERMISSION_DENIED

Erreur Action recommandée
L'ID de clé d'accès AWS que vous avez fourni n'existe pas dans nos enregistrements. Vérifiez que la clé d'accès existe et que son ID est correct.
La signature de requête que nous avons calculée ne correspond pas à la signature que vous avez fournie. Vérifiez votre clé et votre méthode de signature. Vérifiez que la configuration de transfert contient la clé d'accès secrète correspondante.
Échec de l'obtention de l'emplacement du compartiment S3 source. Détails supplémentaires : Accès refusé

Échec de l'obtention de l'emplacement du compartiment S3 source. Détails supplémentaires : erreur HTTP/1.1 403 Interdit :

Message d'erreur S3 : Accès refusé
Vérifiez que l'utilisateur IAM AWS est autorisé à effectuer les opérations suivantes :
  • Afficher le bucket Amazon S3
  • Obtenir l'emplacement du bucket
  • Lire les objets du bucket
Le serveur ne parvient pas à initialiser l'importation de l'objet. InvalidObjectState : L'opération n'est pas valide pour la classe de stockage de l'objet

Échec de l'obtention de l'emplacement du compartiment S3 source. Détails supplémentaires : tout accès à cet objet a été désactivé.
Restaurez tous les objets archivés dans Amazon Glacier. Les objets Amazon S3 archivés dans Amazon Glacier ne seront pas accessibles tant qu'ils n'auront pas été restaurés.
Tout accès à cet objet a été désactivé. Vérifiez que l'URI Amazon S3 est correct dans la configuration de transfert.

Erreurs relatives aux limites de transfert Amazon S3

Erreur Action recommandée
Le nombre de fichiers à transférer dépasse la limite de 10 000. Déterminez s'il est possible de réduire le nombre de caractères génériques dans l'URI Amazon S3 à un seul. Si c'est le cas, réessayez avec une nouvelle configuration de transfert, ce qui aura pour effet d'augmenter le nombre maximal de fichiers par transfert.

Déterminez si la configuration de transfert peut être répartie sur plusieurs configurations de transfert, chacune gérant une partie des données sources.
La taille des fichiers à transférer dépasse la limite de 16 492 674 416 640 octets. Déterminez si la configuration de transfert peut être répartie sur plusieurs configurations de transfert, chacune gérant une partie des données source.

Problèmes d'ordre général

Erreur Action recommandée
Les fichiers sont bien transférés depuis Amazon S3, mais pas chargés dans BigQuery. Les journaux de transfert peuvent ressembler à ceci :

Moving data from Amazon S3 to Google Cloud complete: Moved <NNN> object(s).
No new files found matching <Amazon S3 URI>. (Transfert des données depuis Amazon S3 vers Google Cloud terminé : <NNN> objet(s) déplacés. Aucun nouveau fichier trouvé correspondant à <URI Amazon S3>).
Vérifiez que l'URI Amazon S3 est correct dans la configuration de transfert.
Si la configuration de transfert doit charger tous les fichiers ayant un préfixe commun, vérifiez que l'URI Amazon S3 se termine bien par un caractère générique.Par exemple, pour charger tous les fichiers situés dans s3://my-bucket/my-folder/ , l'URI Amazon S3 figurant dans la configuration de transfert doit être s3://my-bucket/my-folder/* plutôt que seulement s3://my-bucket/my-folder/.
Autres problèmes Consultez la section Dépannage des configurations de transfert.

Étapes suivantes