Questa pagina è stata tradotta dall'API Cloud Translation.

Modello di testo Cloud Storage in Spanner

Il modello Da testo a Spanner da Cloud Storage è una pipeline batch che legge il testo CSV da Cloud Storage e li importa in un database Spanner.

Requisiti della pipeline

Devono esistere il database e la tabella Spanner di destinazione.
Devi disporre delle autorizzazioni di lettura per il bucket Cloud Storage e di quelle di scrittura per il database Spanner di destinazione.
Deve esistere il percorso Cloud Storage di input contenente i file CSV.
Devi creare un file manifest di importazione contenente una descrizione JSON del CSV e devi archiviare il file manifest in Cloud Storage.
Se il database Spanner di destinazione ha già uno schema, qualsiasi colonna specificata nel il file manifest deve avere gli stessi tipi di dati delle colonne corrispondenti nella dello schema del database.

Il file manifest, codificato in ASCII o UTF-8, deve avere il seguente formato:

Formato ed esempio del manifest

Il formato del file manifest corrisponde al seguente tipo di messaggio, mostrato qui in formato del buffer di protocollo:

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'esempio seguente mostra un file manifest per l'importazione di tabelle denominato Albums e Singers in un database di dialetti GoogleSQL. La tabella Albums utilizza lo schema delle colonne recuperato dal job dal database e la tabella Singers utilizza lo schema utilizzato dal file manifest specifica:

{
  "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"}
      ]
    }
  ]
}

I file di testo da importare devono essere in formato CSV, con codifica ASCII o UTF-8. I nostri suggerimenti Mancato utilizzo del byte Order Mark (BOM) nei file con codifica 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

Nota: se non specifichi i nomi e i dati delle colonne della tabella di destinazione nel file manifest di importazione, le colonne dei file CSV devono essere nello stesso ordine del file nel database di destinazione. Puoi vedere l'ordine delle colonne nella tabella eseguendo la seguente query:

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

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 durante l'importazione dei file manifest. ad esempio gs://your-bucket/your-folder/your-manifest.json.

Parametri facoltativi

spannerHost : l'endpoint di Cloud Spanner da chiamare nel modello. Utilizzato solo per i test. Esempio: https://batch-spanner.googleapis.com. Il valore predefinito è: https://batch-spanner.googleapis.com.
columnDelimiter : il delimitatore di colonna utilizzato dal file di origine. Il valore predefinito è ",". (ad es. ,).
fieldQualifier : il carattere che deve circondare qualsiasi valore nel file di origine contenente columnDelimiter. Il valore predefinito è ".
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 della 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 null.
dateFormat : il formato utilizzato per analizzare le colonne delle date. Per impostazione predefinita, la pipeline tenta di analizzare le colonne delle date come yyyy-M-d[' 00:00:00'], ad esempio 2019-01-31 o 2019-1-1 00:00:00. Se il formato data è diverso, specifica il formato 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 del timestamp. Se il timestamp è un numero intero lungo, viene analizzato come ora dell'epoca Unix. In caso contrario, viene analizzata 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). In altri casi, specifica una 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 configurato, viene utilizzato l'ID del progetto Google Cloud predefinito.
spannerPriority : la priorità delle richieste 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 nuova riga. In caso contrario, i caratteri di nuova riga causano un errore. Il valore predefinito è false. L'attivazione della gestione delle nuove righe può ridurre le prestazioni.
invalidOutputPath : il percorso di Cloud Storage da utilizzare durante la scrittura di righe che non possono essere importate. ad esempio gs://your-bucket/your-path. Il campo predefinito è vuoto.

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

Tipo	Valore di input	Formato	Osservazione
`DATE`	2011-3-31		Per impostazione predefinita, il modello può analizzare questo formato. Non è necessario specificare il parametro `dateFormat`.
`DATE`	31-3-2011 00:00:00		Per impostazione predefinita, il modello può analizzare questo formato. Non è necessario specificare il formato. Se vuoi, puoi usare `yyyy-M-d' 00:00:00'`.
`DATE`	01 apr 18	gg 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 considerarlo come epoca Unix nel tempo.
`TIMESTAMP`	Tue, 3 giu 2008 11:05:30 GMT	EEE, g MMM aaaa HH:mm:ss VV
`TIMESTAMP`	31/12/2018 110530.123PST	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, la colonna di input predefinito è in grado di analizzare questo tipo di timestamp. Non è necessario fornire un formato personalizzato . Puoi utilizzare `yyyy-MM-dd'T'HH:mm:ss[.SSS]VV` per gestire entrambi d'uso diversi. Non puoi utilizzare `yyyy-MM-dd'T'HH:mm:ss[.SSS]'Z'` perché il postfisso "Z" deve deve essere analizzato come ID fuso orario, non come valore letterale di caratteri. Internamente, la colonna del timestamp è convertito in un `java.time.Instant`. Pertanto, deve essere specificata nel fuso orario UTC o avere informazioni sul fuso orario associate. La data e ora locale, ad esempio 2019-01-02 11:22:33, non può essere analizzata come un valore `java.time.Instant` valido.

Esegui il modello

Console

Vai alla pagina Crea job da modello di Dataflow.

Vai a Crea job da modello

Nel campo Nome job, inserisci un nome univoco per il job.
(Facoltativo) Per Endpoint a livello di regione, seleziona un valore dal menu a discesa. Il valore predefinito è us-central1.
Per un elenco di regioni in cui è possibile eseguire un job Dataflow, consulta Località di Dataflow.
Dal menu a discesa Modello Dataflow, seleziona the Text Files on Cloud Storage to Cloud Spanner template.
Inserisci i valori parametro negli appositi campi.
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 job univoco di tua scelta
VERSION: la versione del modello che vuoi utilizzare
Puoi utilizzare i seguenti valori:
- latest per utilizzare la versione più recente del modello, disponibile in cartella principale non-dated nel bucket: gs://dataflow-templates-REGION_NAME/latest/
- il nome della versione, ad esempio 2023-09-12-00_RC00, per utilizzare una versione specifica , che puoi trovare nidificata nella rispettiva cartella principale con data del bucket: gs://dataflow-templates-REGION_NAME/
Attenzione:la versione più recente dei modelli potrebbe essere aggiornata con interruzioni modifiche. I tuoi ambienti di produzione devono utilizzare i modelli conservati nel più recente dated (datata) per evitare che queste modifiche che provocano errori influiscano su per i flussi di lavoro di produzione.
REGION_NAME: la regione in cui vuoi di eseguire il deployment del job Dataflow, ad esempio us-central1
INSTANCE_ID: l'ID istanza Spanner
DATABASE_ID: l'ID database di Spanner
GCS_PATH_TO_IMPORT_MANIFEST: il percorso Cloud Storage di il file manifest di importazione

API

Per eseguire il modello utilizzando l'API REST, invia una richiesta POST HTTP. Per ulteriori informazioni sul API e i 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 progetto Google Cloud in cui vuoi eseguire il job Dataflow
JOB_NAME: un nome job univoco di tua scelta
VERSION: la versione del modello che vuoi utilizzare
Puoi utilizzare i seguenti valori:
- latest per utilizzare la versione più recente del modello, disponibile in cartella principale non-dated nel bucket: gs://dataflow-templates-REGION_NAME/latest/
- il nome della versione, ad esempio 2023-09-12-00_RC00, per utilizzare una versione specifica , che puoi trovare nidificata nella rispettiva cartella principale con data del bucket: gs://dataflow-templates-REGION_NAME/
Attenzione:la versione più recente dei modelli potrebbe essere aggiornata con interruzioni modifiche. I tuoi ambienti di produzione devono utilizzare i modelli conservati nel più recente dated (datata) per evitare che queste modifiche che provocano errori influiscano su per i flussi di lavoro di produzione.
LOCATION: la regione in cui vuoi di eseguire il deployment del job Dataflow, ad esempio us-central1
INSTANCE_ID: l'ID istanza Spanner
DATABASE_ID: l'ID database di Spanner
GCS_PATH_TO_IMPORT_MANIFEST: il percorso Cloud Storage di il file manifest di importazione

Codice sorgente del modello

Java

Il codice sorgente di questo modello si trova nel repository GoogleCloudPlatform/DataflowTemplates su GitHub.

Passaggi successivi

Scopri di più sui modelli Dataflow.
Consulta l'elenco dei modelli forniti da Google.