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.
- 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 :
- La partie compartiment de l'URI Amazon S3 ne peut pas être paramétrée.
- Les transferts depuis Amazon S3 avec le paramètre Disposition en écriture défini sur
WRITE_TRUNCATE
transfère tous les fichiers correspondants vers Google Cloud à chaque exécution. Cela peut entraîner des coûts de transfert de données sortantes supplémentaires pour Amazon S3. Pour en savoir plus sur les fichiers transférés lors d'une exécution, consultez la section Impact de la correspondance des préfixes ou des caractères génériques. - Les transferts depuis des régions AWS GovCloud (
us-gov
) ne sont pas acceptés. - Les transferts vers des emplacements BigQuery Omni ne sont pas compatibles.
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 :
L'intervalle minimum entre deux transferts récurrents est de 24 heures. L'intervalle par défaut entre transferts récurrents est de 24 heures.
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.get
etbigquery.datasets.update
sur l'ensemble de données cible
Le rôle IAM prédéfini
bigquery.admin
inclut les autorisationsbigquery.transfers.update
,bigquery.datasets.update
etbigquery.datasets.get
. Pour en savoir plus sur les rôles IAM associés au service de transfert de données BigQuery, consultez la page Contrôle des accès.- Autorisations
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.
Configurer un transfert de données Amazon S3
Pour créer un transfert de données Amazon S3 :
Console
Accédez à la page "BigQuery" de la console Google Cloud.
Cliquez sur Transferts.
Cliquez sur Create a Transfer (Créer un transfert).
Sur la page Create Transfer (Créer un transfert) :
Dans le champ Source de la section Source type (Type de source), choisissez Amazon S3.
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.Dans la section Schedule options (Options de programmation) :
Sélectionnez une fréquence de répétition. Si vous sélectionnez Heures, Jours, Semaines ou Mois, vous devez également spécifier une fréquence. Vous pouvez également sélectionner Personnalisé pour créer une fréquence de répétition plus spécifique. Si vous sélectionnez À la demande, ce transfert ne s'exécute que lorsque vous déclenchez manuellement le transfert.
Le cas échéant, sélectionnez Commencer ou Commencer à l'heure définie, puis indiquez une date de début et une heure d'exécution.
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.
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.
Pour Disposition en écriture, sélectionnez :
WRITE_APPEND
pour ajouter de nouvelles données de manière incrémentielle à votre table de destination existante.WRITE_APPEND
est la valeur par défaut pour la préférence d'écriture.WRITE_TRUNCATE
pour écraser les données de la table de destination à chaque exécution de transfert.
Pour en savoir plus sur la manière dont le service de transfert de données BigQuery ingère des données à l'aide de
WRITE_APPEND
ou deWRITE_TRUNCATE
, consultez la section Ingestion de données pour les transferts Amazon S3. Pour en savoir plus sur le champwriteDisposition
, consultez la sectionJobConfigurationLoad
.
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 une valeur entière pour le nombre maximal d'enregistrements incorrects pouvant être ignorés.
- (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é.
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.
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.
Dans le menu Compte de service, sélectionnez un compte de service parmi ceux associés à votre projet Google Cloud. Vous pouvez associer un compte de service à votre transfert au lieu d'utiliser vos identifiants utilisateur. Pour en savoir plus sur l'utilisation des comptes de service avec des transferts de données, consultez la page Utiliser des comptes de service.
- Si vous vous êtes connecté avec une identité fédérée, vous devez disposer d'un compte de service pour créer un transfert. Si vous vous êtes connecté avec un compte Google, un compte de service pour le transfert est facultatif.
- Le compte de service doit disposer des autorisations requises.
(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.
Cliquez sur Save (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 \ --service_account_name=service_account \ --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 à toute valeur permettant d'identifier 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.
- service_account : nom du compte de service utilisé pour authentifier le transfert. Le compte de service doit appartenir au même
project_id
que celui utilisé pour créer le transfert et doit disposer de toutes les autorisations requises. 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
ouORC
. La valeur par défaut estCSV
.write_disposition : facultatif.
WRITE_APPEND
ne va transférer que les fichiers qui ont été modifiés depuis la dernière exécution réussie.WRITE_TRUNCATE
va transférer tous les fichiers correspondants, y compris ceux qui ont déjà été transférés lors d'une exécution précédente. La valeur par défaut estWRITE_APPEND
.max_bad_records : facultatif. Le nombre d'enregistrements incorrects autorisés. La valeur par défaut est
0
.decimal_target_types : facultatif. 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.
ignore_unknown_values : facultatif. Cette valeur est ignorée si file_format n'est pas défini sur
JSON
ouCSV
. 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 surCSV
. 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 est0
.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
, 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":"s3://mybucket/myfile/*.csv",
"destination_table_name_template":"MyTable",
"file_format":"CSV",
"write_disposition":"WRITE_APPEND",
"max_bad_records":"1",
"ignore_unknown_values":"true",
"field_delimiter":"|",
"skip_leading_rows":"1",
"allow_quoted_newlines":"true",
"allow_jagged_rows":"false"}' \
--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
.
Java
Avant d'essayer cet exemple, suivez les instructions de configuration pour Java du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Java.
Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.
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 transfert de données sortantes d'Amazon S3 pour 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.
Résoudre les problèmes liés à la configuration d'un transfert
Si vous rencontrez des problèmes lors de la configuration de votre transfert, consultez la section Problèmes de transfert avec Amazon S3.
Étapes suivantes
- Pour une introduction aux transferts Amazon S3, consultez la page Présentation des transferts Amazon S3.
- Pour une vue d'ensemble du service de transfert de données BigQuery, consultez la page Présentation du service de transfert de données BigQuery.
- Pour plus d'informations sur l'utilisation des transferts, y compris l'obtention d'informations sur une configuration de transfert, la liste des configurations de transfert et l'affichage de l'historique d'exécution d'un transfert, consultez la page Utiliser les transferts.
- Découvrez comment charger des données avec des opérations multicloud.