Modèle Texte Cloud Storage vers Spanner

Le modèle Texte Cloud Storage vers Spanner est un pipeline par lots qui lit les fichiers texte CSV dans Cloud Storage et les importe dans une base de données Spanner.

Conditions requises pour ce pipeline

  • La base de données et la table Spanner cibles doivent exister.
  • Vous devez disposer d'autorisations en lecture pour le bucket Cloud Storage et d'autorisations en écriture pour la base de données Spanner cible.
  • Le chemin d'accès Cloud Storage en entrée contenant les fichiers CSV doit exister.
  • Vous devez créer un fichier manifeste d'importation contenant une description JSON des fichiers CSV, puis le stocker dans Cloud Storage.
  • Si la base de données Spanner cible possède déjà un schéma, toutes les colonnes spécifiées dans le fichier manifeste doivent disposer des mêmes types de données que les colonnes correspondantes dans le schéma de la base de données cible.
  • Le fichier manifeste, encodé au format ASCII ou UTF-8, doit respecter le format suivant :

  • Les fichiers texte à importer doivent être au format CSV, avec un encodage ASCII ou UTF-8. Nous vous déconseillons d'utiliser l'indicateur d'ordre des octets (BOM) dans les fichiers encodés au format UTF-8.
  • Les données doivent correspondre à l'un des types suivants :

    GoogleSQL

        BOOL
        INT64
        FLOAT64
        NUMERIC
        STRING
        DATE
        TIMESTAMP
        BYTES
        JSON

    PostgreSQL

        boolean
        bigint
        double precision
        numeric
        character varying, text
        date
        timestamp with time zone
        bytea

Paramètres de modèle

Paramètres obligatoires

  • instanceId : ID d'instance de la base de données Spanner
  • databaseId : ID de base de données de la base de données Spanner
  • importManifest : chemin d'accès dans Cloud Storage à utiliser lors de l'importation de fichiers manifestes. (par exemple, gs://your-bucket/your-folder/your-manifest.json).

Paramètres facultatifs

  • spannerHost : Point de terminaison Cloud Spanner à appeler dans le modèle. Utilisé uniquement pour les tests. (Exemple : https://batch-spanner.googleapis.com). La valeur par défaut est https://batch-spanner.googleapis.com.
  • columnDelimiter : séparateur de colonne utilisé par le fichier source. La valeur par défaut est "," (par exemple, ,).
  • fieldQualifier : caractère devant entourer toutes les valeurs du fichier source contenant le columnDelimiter. La valeur par défaut est ".
  • trailingDelimiter : indique si les lignes des fichiers sources comportent des séparateurs finaux (c'est-à-dire si le caractère columnDelimiter apparaît à la fin de chaque ligne, après la dernière valeur de colonne). La valeur par défaut est true.
  • escape : caractère d'échappement utilisé par le fichier source. Par défaut, ce paramètre n'est pas défini et le modèle n'utilise pas de caractère d'échappement.
  • nullString : chaîne représentant une valeur NULL. Par défaut, ce paramètre n'est pas défini et le modèle n'utilise pas de chaîne NULL.
  • dateFormat : format utilisé pour l'analyse des colonnes de date. Par défaut, le pipeline tente d'analyser les colonnes de date au format yyyy-M-d[' 00:00:00'] (par exemple, 2019-01-31 ou 2019-1-1 00:00:00). Si votre format de date est différent, spécifiez-le à l'aide de java.time.format.DateTimeFormatter (https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html).
  • timestampFormat : format utilisé pour l'analyse des colonnes d'horodatage. Si l'horodatage est un entier long, il est analysé selon l'epoch Unix. Dans le cas contraire, il est analysé comme chaîne à l'aide de java.time.format.DateTimeFormatter.ISO_INSTANT (https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html#ISO_INSTANT). Dans les autres cas, spécifiez votre propre chaîne de modèle (par exemple, MMM dd yyyy HH:mm:ss.SSSVV pour les horodatages au format "Jan 21 1998 01:02:03.456+08:00").
  • spannerProjectId : ID du projet Google Cloud qui contient la base de données Spanner. Si ce champ n'est pas défini, l'ID de projet du projet Google Cloud par défaut est utilisé.
  • spannerPriority : priorité des requêtes pour les appels Spanner. Les valeurs possibles sont HIGH, MEDIUM et LOW. La valeur par défaut est MEDIUM.
  • handleNewLine : Si la valeur est true, les données d'entrée peuvent contenir des caractères de retour à la ligne. Autrement, les caractères de retour à la ligne génèrent une erreur. La valeur par défaut est false. L'activation du traitement des retours à la ligne peut réduire les performances.
  • invalidOutputPath : chemin d'accès Cloud Storage à utiliser lors de l'écriture de lignes qui ne peuvent pas être importées. (par exemple, gs://votre-bucket/votre-chemin-d'accès). La valeur par défaut est vide.

Si vous devez utiliser des formats de date ou d'horodatage personnalisés, assurez-vous qu'ils constituent des modèles java.time.format.DateTimeFormatter valides. Le tableau suivant présente des exemples supplémentaires de formats personnalisés pour les colonnes de date et d'horodatage :

Type Valeur d'entrée Format Remarque
DATE 2011-3-31 Par défaut, le modèle peut analyser ce format. Vous n'avez pas besoin de spécifier le paramètre dateFormat.
DATE 2011-3-31 00:00:00 Par défaut, le modèle peut analyser ce format. Vous n'avez pas besoin de spécifier le format. Si vous le souhaitez, vous pouvez utiliser le format yyyy-M-d' 00:00:00'.
DATE 01 Apr, 18 dd MMM, yy
DATE Wednesday, April 3, 2019 AD EEEE, LLLL d, yyyy G
TIMESTAMP 2019-01-02T11:22:33Z
2019-01-02T11:22:33.123Z
2019-01-02T11:22:33.12356789Z
Le format par défaut ISO_INSTANT permet d'analyser ce type d'horodatage. Vous n'avez pas besoin de spécifier le paramètre timestampFormat.
TIMESTAMP 1568402363 Par défaut, le modèle peut analyser ce type d'horodatage et le traiter selon l'epoch Unix.
TIMESTAMP Tue, 3 Jun 2008 11:05:30 GMT EEE, d MMM yyyy HH:mm:ss VV
TIMESTAMP 2018/12/31 110530.123PST yyyy/MM/dd HHmmss.SSSz
TIMESTAMP 2019-01-02T11:22:33Z ou 2019-01-02T11:22:33.123Z yyyy-MM-dd'T'HH:mm:ss[.SSS]VV Si la colonne d'entrée est un mélange entre 2019-01-02T11:22:33Z et 2019-01-02T11:22:33.123Z, le format par défaut peut analyser ce type d'horodatage. Vous n'avez pas besoin de spécifier votre propre format. Vous pouvez exploiter le format yyyy-MM-dd'T'HH:mm:ss[.SSS]VV dans ces deux cas. Vous ne pouvez pas utiliser le format yyyy-MM-dd'T'HH:mm:ss[.SSS]'Z', car le suffixe "Z" doit être analysé en tant qu'ID de fuseau horaire, et non en tant que littéral de caractères. En interne, la colonne d'horodatage est convertie en élément java.time.Instant. Par conséquent, elle doit être spécifiée au format UTC ou associée à des informations de fuseau horaire. Il est impossible d'analyser le format date/heure local, tel que 2019-01-02 11:22:33, en tant qu'élément java.time.Instant valide.

Exécuter le modèle

Console

  1. Accédez à la page Dataflow Créer un job à partir d'un modèle.
  2. Accéder à la page Créer un job à partir d'un modèle
  3. Dans le champ Nom du job, saisissez un nom de job unique.
  4. Facultatif : pour Point de terminaison régional, sélectionnez une valeur dans le menu déroulant. La région par défaut est us-central1.

    Pour obtenir la liste des régions dans lesquelles vous pouvez exécuter un job Dataflow, consultez la page Emplacements Dataflow.

  5. Dans le menu déroulant Modèle Dataflow, sélectionnez the Text Files on Cloud Storage to Cloud Spanner template.
  6. Dans les champs fournis, saisissez vos valeurs de paramètres.
  7. Cliquez sur Run Job (Exécuter la tâche).

gcloud

Dans le shell ou le terminal, exécutez le modèle :

gcloud dataflow jobs run JOB_NAME \
    --gcs-location gs://dataflow-templates-REGION_NAME/VERSION/GCS_Text_to_Cloud_Spanner \
    --region REGION_NAME \
    --parameters \
instanceId=INSTANCE_ID,\
databaseId=DATABASE_ID,\
importManifest=GCS_PATH_TO_IMPORT_MANIFEST

Remplacez les éléments suivants :

  • JOB_NAME : nom de job unique de votre choix
  • VERSION : version du modèle que vous souhaitez utiliser

    Vous pouvez utiliser les valeurs suivantes :

  • REGION_NAME : région dans laquelle vous souhaitez déployer votre job Dataflow, par exemple us-central1
  • INSTANCE_ID : ID de votre instance Spanner
  • DATABASE_ID : ID de votre base de données Spanner
  • GCS_PATH_TO_IMPORT_MANIFEST : chemin d'accès Cloud Storage au fichier manifeste d'importation

API

Pour exécuter le modèle à l'aide de l'API REST, envoyez une requête HTTP POST. Pour en savoir plus sur l'API, ses autorisations et leurs champs d'application, consultez la section projects.templates.launch.

POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/templates:launch?gcsPath=gs://dataflow-templates-LOCATION/VERSION/GCS_Text_to_Cloud_Spanner
{
   "jobName": "JOB_NAME",
   "parameters": {
       "instanceId": "INSTANCE_ID",
       "databaseId": "DATABASE_ID",
       "importManifest": "GCS_PATH_TO_IMPORT_MANIFEST"
   },
   "environment": {
       "machineType": "n1-standard-2"
   }
}

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet Google Cloud dans lequel vous souhaitez exécuter le job Dataflow
  • JOB_NAME : nom de job unique de votre choix
  • VERSION : version du modèle que vous souhaitez utiliser

    Vous pouvez utiliser les valeurs suivantes :

  • LOCATION : région dans laquelle vous souhaitez déployer votre job Dataflow, par exemple us-central1
  • INSTANCE_ID : ID de votre instance Spanner
  • DATABASE_ID : ID de votre base de données Spanner
  • GCS_PATH_TO_IMPORT_MANIFEST : chemin d'accès Cloud Storage au fichier manifeste d'importation

Étapes suivantes