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 :

  Format et exemple de fichier manifeste

  Le format du fichier manifeste correspond au type de message suivant, affiché ici au format de tampon de protocole :

  message ImportManifest {
    // The per-table import manifest.
    message TableManifest {
      // Required. The name of the destination table.
      string table_name = 1;
      // Required. The CSV files to import. This value can be either a filepath or a glob pattern.
      repeated string file_patterns = 2;
      // The schema for a table column.
      message Column {
        // Required for each Column that you specify. The name of the column in the
        // destination table.
        string column_name = 1;
        // Required for each Column that you specify. The type of the column.
        string type_name = 2;
      }
      // Optional. The schema for the table columns.
      repeated Column columns = 3;
    }
    // Required. The TableManifest of the tables to be imported.
    repeated TableManifest tables = 1;
  
    enum ProtoDialect {
      GOOGLE_STANDARD_SQL = 0;
      POSTGRESQL = 1;
    }
    // Optional. The dialect of the receiving database. Defaults to GOOGLE_STANDARD_SQL.
    ProtoDialect dialect = 2;
  }

  L'exemple suivant illustre un fichier manifeste pour l'importation de tables nommées Albums et Singers dans une base de données Google SQL. La table Albums utilise le schéma de la colonne que la tâche extrait de la base de données, et la table Singers utilise le schéma spécifié par le fichier manifeste :

  {
    "tables": [
      {
        "table_name": "Albums",
        "file_patterns": [
          "gs://bucket1/Albums_1.csv",
          "gs://bucket1/Albums_2.csv"
        ]
      },
      {
        "table_name": "Singers",
        "file_patterns": [
          "gs://bucket1/Singers*.csv"
        ],
        "columns": [
          {"column_name": "SingerId", "type_name": "INT64"},
          {"column_name": "FirstName", "type_name": "STRING"},
          {"column_name": "LastName", "type_name": "STRING"}
        ]
      }
    ]
  }

• 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

Remarque : Si vous ne spécifiez pas les noms des colonnes ni les types de données de la table cible dans le fichier manifeste d'importation, les colonnes des fichiers CSV doivent être dans le même ordre que les colonnes situées dans la base de données cible. Pour afficher l'ordre des colonnes dans votre table, exécutez la requête suivante :

SELECT * FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_NAME =
      TABLE_NAME ORDER BY ORDINAL_POSITION

Avertissement : Si la base de données Spanner cible n'est pas vide, de nouvelles données peuvent remplacer des données préexistantes.

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.
Accéder à la page Créer un job à partir d'un modèle
2. Dans le champ Nom du job, saisissez un nom de job unique.
3. 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.

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

gcloud

Remarque : Pour utiliser Google Cloud CLI afin d'exécuter les modèles classic, vous devez avoir Google Cloud CLI version 138.0.0 ou ultérieure.

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 :

  • latest pour utiliser la dernière version du modèle, disponible dans le dossier parent non daté du bucket gs://dataflow-templates-REGION_NAME/latest/
  • Le nom de la version, par exemple 2023-09-12-00_RC00, pour utiliser une version spécifique du modèle, qui est imbriqué dans le dossier parent daté respectif dans le bucket : gs://dataflow-templates-REGION_NAME/
  Attention : La dernière version des modèles peut être mise à jour avec des modifications destructives. Vos environnements de production devraient utiliser des modèles conservés dans le dernier dossier parent daté afin d'empêcher que ces modifications n'affectent vos workflows.
• 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 :

  • latest pour utiliser la dernière version du modèle, disponible dans le dossier parent non daté du bucket gs://dataflow-templates-REGION_NAME/latest/
  • Le nom de la version, par exemple 2023-09-12-00_RC00, pour utiliser une version spécifique du modèle, qui est imbriqué dans le dossier parent daté respectif dans le bucket : gs://dataflow-templates-REGION_NAME/
  Attention : La dernière version des modèles peut être mise à jour avec des modifications destructives. Vos environnements de production devraient utiliser des modèles conservés dans le dernier dossier parent daté afin d'empêcher que ces modifications n'affectent vos workflows.
• 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

Code source du modèle

Java

Le code source de ce modèle se trouve dans le dépôt GoogleCloudPlatform/DataflowTemplates sur GitHub.

Étapes suivantes

• Apprenez-en plus sur les modèles Dataflow.
• Consultez la liste des modèles fournis par Google.