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 :

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 à la page "BigQuery" de Cloud Console.

    Accéder à BigQuery

  2. Cliquez sur 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 Enregistrer.

bq

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 : valeur obligatoire. La source de données : amazon_s3.
  • display_name : valeur 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 : valeur obligatoire. Il s'agit de l'ensemble de données cible de la configuration de transfert.
  • parameters : valeur 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 : valeur obligatoire. Le nom de votre table de destination.
    • data_path : valeur obligatoire. L'URI Amazon S3, au format suivant :

      s3://mybucket/myfolder/...

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

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

    • secret_access_key : valeur 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. Cette valeur est ignorée si file_format n'est pas défini sur JSON ou CSV. Indique si vous souhaitez ignorer les valeurs inconnues dans vos données.

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

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

Étape suivante