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 :

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

Configurer 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 la console Google Cloud.

    Accéder à la page "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) :

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

      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.

      • 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 de WRITE_TRUNCATE, consultez la section Ingestion de données pour les transferts Amazon S3. Pour en savoir plus sur le champ writeDisposition, consultez la section JobConfigurationLoad.

        Détails de la source S3

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

      Options de transfert – Tous les format

    • 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

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

  5. 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 ou ORC. La valeur par défaut est CSV.

    • 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 est WRITE_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 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, 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. 

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 amazon s3 transfer config.
public class CreateAmazonS3Transfer {

  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";
    // Amazon S3 Bucket Uri with read role permission
    String sourceUri = "s3://your-bucket-name/*";
    String awsAccessKeyId = "MY_AWS_ACCESS_KEY_ID";
    String awsSecretAccessId = "AWS_SECRET_ACCESS_ID";
    String sourceFormat = "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", Value.newBuilder().setStringValue(sourceUri).build());
    params.put("access_key_id", Value.newBuilder().setStringValue(awsAccessKeyId).build());
    params.put("secret_access_key", Value.newBuilder().setStringValue(awsSecretAccessId).build());
    params.put("source_format", Value.newBuilder().setStringValue(sourceFormat).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 Aws S3 Config Name")
            .setDataSourceId("amazon_s3")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .setSchedule("every 24 hours")
            .build();
    createAmazonS3Transfer(projectId, transferConfig);
  }

  public static void createAmazonS3Transfer(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("Amazon s3 transfer created successfully :" + config.getName());
    } catch (ApiException ex) {
      System.out.print("Amazon s3 transfer was not created." + ex.toString());
    }
  }
}

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