Modello di testo Cloud Storage a Spanner

Il modello File di testo di Cloud Storage in Spanner è una pipeline batch che legge i file di testo CSV da Cloud Storage e li importa in un database Spanner.

Requisiti della pipeline

  • Il database e la tabella Spanner di destinazione devono esistere.
  • Devi disporre delle autorizzazioni di lettura per il bucket Cloud Storage e delle autorizzazioni di scrittura per il database Spanner di destinazione.
  • Il percorso Cloud Storage di input contenente i file CSV deve esistere.
  • Devi creare un file manifest di importazione contenente una descrizione JSON dei file CSV e devi archiviarlo in Cloud Storage.
  • Se il database Spanner di destinazione ha già uno schema, tutte le colonne specificate nel file manifest devono avere gli stessi tipi di dati delle colonne corrispondenti nello schema del database di destinazione.
  • Il file manifest, codificato in ASCII o UTF-8, deve corrispondere al seguente formato:

  • I file di testo da importare devono essere in formato CSV, con codifica ASCII o UTF-8. Ti consigliamo di non utilizzare il marker dell'ordine dei byte (BOM) nei file codificati in UTF-8.
  • I dati devono corrispondere a uno dei seguenti tipi:

    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

Parametri del modello

Parametri obbligatori

  • instanceId: l'ID istanza del database Spanner.
  • databaseId: l'ID del database Spanner.
  • importManifest: il percorso in Cloud Storage da utilizzare per l'importazione dei file manifest. Ad esempio, gs://your-bucket/your-folder/your-manifest.json.

Parametri facoltativi

  • spannerHost: l'endpoint Cloud Spanner da chiamare nel modello. Utilizzato solo per i test. Ad esempio, https://batch-spanner.googleapis.com. Valore predefinito: https://batch-spanner.googleapis.com.
  • columnDelimiter: il delimitatore di colonna utilizzato dal file di origine. Il valore predefinito è ,. Ad esempio: ,.
  • fieldQualifier: il carattere che deve racchiudere qualsiasi valore nel file di origine contenente il delimitatore di colonna. Il valore predefinito è le virgolette doppie.
  • trailingDelimiter: specifica se le righe nei file di origine hanno delimitatori finali, ovvero se il carattere columnDelimiter viene visualizzato alla fine di ogni riga, dopo l'ultimo valore di colonna. Il valore predefinito è true.
  • escape: il carattere di escape utilizzato dal file di origine. Per impostazione predefinita, questo parametro non è impostato e il modello non utilizza il carattere di escape.
  • nullString: la stringa che rappresenta un valore NULL. Per impostazione predefinita, questo parametro non è impostato e il modello non utilizza la stringa nulla.
  • dateFormat: il formato utilizzato per analizzare le colonne di date. Per impostazione predefinita, la pipeline tenta di analizzare le colonne di date come yyyy-M-d[' 00:00:00'], ad esempio 2019-01-31 o 2019-1-1 00:00:00. Se il formato della data è diverso, specificalo utilizzando i pattern java.time.format.DateTimeFormatter (https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html).
  • timestampFormat: il formato utilizzato per analizzare le colonne dei timestamp. Se il timestamp è un numero intero lungo, viene analizzato come tempo Unix epoch. In caso contrario, viene analizzato come stringa utilizzando il formato 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). Per altri casi, specifica la tua stringa di pattern, ad esempio utilizzando MMM dd yyyy HH:mm:ss.SSSVV per i timestamp sotto forma di Jan 21 1998 01:02:03.456+08:00.
  • spannerProjectId: l'ID del progetto Google Cloud che contiene il database Spanner. Se non viene impostato, viene utilizzato l'ID progetto del progetto Google Cloud predefinito.
  • spannerPriority: la priorità della richiesta per le chiamate Spanner. I valori possibili sono HIGH, MEDIUM e LOW. Il valore predefinito è MEDIUM.
  • handleNewLine: se true, i dati di input possono contenere caratteri di a capo. In caso contrario, i caratteri di nuova riga causano un errore. Il valore predefinito è false. L'attivazione della gestione del nuovo riga può ridurre le prestazioni.
  • invalidOutputPath: il percorso Cloud Storage da utilizzare per scrivere le righe che non possono essere importate. Ad esempio, gs://your-bucket/your-path. Il valore predefinito è vuoto.

Se devi utilizzare formati di data o timestamp personalizzati, assicurati che siano patternjava.time.format.DateTimeFormatter validi. La seguente tabella mostra altri esempi di formati personalizzati per le colonne di date e timestamp:

Tipo Valore di input Formato Nota
DATE 2011-3-31 Per impostazione predefinita, il modello può analizzare questo formato. Non è necessario specificare il parametro dateFormat.
DATE 2011-03-31 00:00:00 Per impostazione predefinita, il modello può analizzare questo formato. Non è necessario specificare il formato. Se vuoi, puoi utilizzare yyyy-M-d' 00:00:00'.
DATE 18 apr dd MMM, yy
DATE Mercoledì 3 aprile 2019 EEEE, LLLL d, yyyy G
TIMESTAMP 2019-01-02T11:22:33Z
2019-01-02T11:22:33.123Z
2019-01-02T11:22:33.12356789Z
Il formato predefinito ISO_INSTANT può analizzare questo tipo di timestamp. Non è necessario fornire il parametro timestampFormat.
TIMESTAMP 1568402363 Per impostazione predefinita, il modello può analizzare questo tipo di timestamp e trattarlo come tempo epoch Unix.
TIMESTAMP Tue, 3 Jun 2008 11:05:30 GMT EEE, d MMM yyyy HH:mm:ss VV
TIMESTAMP 31/12/2018 110530.123 PST aaaa/MM/gg HHmmss.SSSz
TIMESTAMP 2019-01-02T11:22:33Z o 2019-01-02T11:22:33.123Z yyyy-MM-dd'T'HH:mm:ss[.SSS]VV Se la colonna di input è un mix di 2019-01-02T11:22:33Z e 2019-01-02T11:22:33.123Z, il formato predefinito può analizzare questo tipo di timestamp. Non è necessario fornire un parametro di formato personalizzato. Puoi utilizzare yyyy-MM-dd'T'HH:mm:ss[.SSS]VV per gestire entrambi i casi. Non puoi utilizzare yyyy-MM-dd'T'HH:mm:ss[.SSS]'Z', perché il suffisso "Z" deve essere interpretato come ID fuso orario e non come carattere letterale. Internamente, la colonna del timestamp viene convertita in un java.time.Instant. Pertanto, deve essere specificato in UTC o avere informazioni sul fuso orario associate. La data/ora locale, ad esempio 02-01-2019 11:22:33, non può essere analizzata come java.time.Instant valido.

Esegui il modello

Console

  1. Vai alla pagina Crea job da modello di Dataflow.
  2. Vai a Crea job da modello
  3. Nel campo Nome job, inserisci un nome univoco per il job.
  4. (Facoltativo) Per Endpoint a livello di regione, seleziona un valore dal menu a discesa. La regione predefinita è us-central1.

    Per un elenco delle regioni in cui puoi eseguire un job Dataflow, consulta Località di Dataflow.

  5. Nel menu a discesa Modello di flusso di dati, seleziona the Text Files on Cloud Storage to Cloud Spanner template.
  6. Nei campi dei parametri forniti, inserisci i valori dei parametri.
  7. Fai clic su Esegui job.

gcloud

Nella shell o nel terminale, esegui il modello:

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

Sostituisci quanto segue:

  • JOB_NAME: un nome di job univoco a tua scelta
  • VERSION: la versione del modello che vuoi utilizzare

    Puoi utilizzare i seguenti valori:

  • REGION_NAME: la regione in cui vuoi eseguire il deployment del job Dataflow, ad esempio us-central1
  • INSTANCE_ID: il tuo ID istanza Spanner
  • DATABASE_ID: il tuo ID database Spanner
  • GCS_PATH_TO_IMPORT_MANIFEST: il percorso di Cloud Storage al file manifest di importazione

API

Per eseguire il modello utilizzando l'API REST, invia una richiesta POST HTTP. Per ulteriori informazioni sull'API e sui relativi ambiti di autorizzazione, consulta 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"
   }
}

Sostituisci quanto segue:

  • PROJECT_ID: l'ID del progetto Google Cloud in cui vuoi eseguire il job Dataflow
  • JOB_NAME: un nome di job univoco a tua scelta
  • VERSION: la versione del modello che vuoi utilizzare

    Puoi utilizzare i seguenti valori:

  • LOCATION: la regione in cui vuoi eseguire il deployment del job Dataflow, ad esempio us-central1
  • INSTANCE_ID: il tuo ID istanza Spanner
  • DATABASE_ID: il tuo ID database Spanner
  • GCS_PATH_TO_IMPORT_MANIFEST: il percorso di Cloud Storage al file manifest di importazione

Passaggi successivi