Vorlage "Cloud Storage Text für Spanner"

Die Vorlage "Cloud Storage Text für Spanner" ist eine Batchpipeline, die CSV-Textdateien aus Cloud Storage liest und in eine Spanner-Datenbank importiert.

Pipelineanforderungen

Die Spanner-Zieldatenbank und -tabelle müssen vorhanden sein.
Sie benötigen Leseberechtigungen für den Cloud Storage-Bucket und Schreibberechtigungen für die Spanner-Zieldatenbank.
Der Cloud Storage-Eingabepfad mit den CSV-Dateien muss vorhanden sein.
Sie müssen eine Importmanifestdatei mit einer JSON-Beschreibung der CSV-Dateien erstellen. Sie müssen diese Manifestdatei in Cloud Storage speichern.
Wenn die Spanner-Zieldatenbank bereits über ein Schema verfügt, müssen alle in der Manifestdatei angegebenen Spalten dieselben Datentypen wie die entsprechenden Spalten im Schema der Zieldatenbank haben.

Die ASCII- oder UTF-8-codierte Manifestdatei muss folgendem Format entsprechen:

Manifestformat und Beispiel

Das Format der Manifestdatei entspricht dem folgenden Nachrichtentyp, der hier im Protokollpufferformat dargestellt wird:

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;
}

Das folgende Beispiel zeigt eine Manifestdatei für den Import von Tabellen mit den Namen Albums und Singers in eine Datenbank im Google SQL-Dialekt. Die Tabelle Albums verwendet das Spaltenschema, das der Job aus der Datenbank abruft. Die Tabelle Singers verwendet das Schema, das in der Manifestdatei angegeben ist:

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

Zu importierende Textdateien müssen im CSV-Format mit ASCII- oder UTF-8-Codierung vorliegen. Wir empfehlen, in UTF-8-codierten Dateien keine Bytereihenfolge-Marke (Byte Order Mark, BOM) zu verwenden.

Die Daten müssen einem der folgenden Typen entsprechen:

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

Hinweis: Wenn Sie die Spaltennamen und Datentypen der Zieltabelle in der Importmanifestdatei nicht angeben, müssen die Spalten in den CSV-Dateien in der gleichen Reihenfolge wie die Spalten in der Zieldatenbank sein. Sie können die Reihenfolge der Spalten in Ihrer Tabelle anzeigen lassen, wenn Sie folgende Abfrage ausführen:

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

Vorlagenparameter

Parameter	Beschreibung
`instanceId`	Die Instanz-ID der Spanner-Datenbank.
`databaseId`	Die Datenbank-ID der Spanner-Datenbank.
`importManifest`	Der Pfad in Cloud Storage zur Importmanifestdatei.
`columnDelimiter`	Das Spaltentrennzeichen, das in der Quelldatei verwendet wird. Der Standardwert ist `,`.
`fieldQualifier`	Das Zeichen, das jeden Wert in der Quelldatei, die das `columnDelimiter` enthält, einschließen muss. Der Standardwert ist `"`.
`trailingDelimiter`	Gibt an, ob die Zeilen in den Quelldateien nachgestellte Trennzeichen haben (ob das Zeichen `columnDelimiter` also am Ende jeder Zeile nach dem letzten Spaltenwert erscheint). Der Standardwert ist `true`.
`escape`	Das von der Quelldatei verwendete Escapezeichen. Dieser Parameter ist standardmäßig nicht gesetzt und die Vorlage verwendet kein Escapezeichen.
`nullString`	Der String, der einen `NULL`-Wert darstellt. Dieser Parameter ist standardmäßig nicht gesetzt und die Vorlage verwendet den Null-String nicht.
`dateFormat`	Das zum Parsen der Datumsspalten verwendete Format. Standardmäßig versucht die Pipeline, die Datumsspalten als `yyyy-M-d[' 00:00:00']` zu parsen, z. B. als 2019-01-31 oder 2019-1-1 00:00:00. Wenn sich Ihr Datumsformat unterscheidet, geben Sie es mit den Mustern `java.time.format.DateTimeFormatter` an.
`timestampFormat`	Das zum Parsen der Zeitstempelspalten verwendete Format. Ist der Zeitstempel eine lange Ganzzahl, wird er als UNIX-Epoche geparst. Ansonsten wird er als String mit dem Format `java.time.format.DateTimeFormatter.ISO_INSTANT` geparst. In anderen Fällen geben Sie Ihren eigenen Musterstring an, z. B. mithilfe von `MMM dd yyyy HH:mm:ss.SSSVV` für Zeitstempel im Format `"Jan 21 1998 01:02:03.456+08:00"`.
`spannerProjectId`	Optional: Die Google Cloud-Projekt-ID der Spanner-Datenbank. Wenn nicht festgelegt, wird das Google Cloud-Standardprojekt verwendet.
`spannerPriority`	(Optional) Die Anfragepriorität für Spanner-Aufrufe. Folgende Werte sind möglich: `HIGH`, `MEDIUM`, `LOW`. Der Standardwert ist `MEDIUM`.
`handleNewLine`	(Optional) Wenn `true`, können die Eingabedaten Zeilenumbruchzeichen enthalten. Andernfalls verursachen Zeilenumbruchzeichen einen Fehler. Der Standardwert ist `false`. Die Aktivierung des Zeilenumbruchs kann die Leistung beeinträchtigen.
`invalidOutputPath`	(Optional) Der Cloud Storage-Pfad zum Schreiben von Zeilen, die nicht importiert werden können.

Wenn Sie benutzerdefinierte Datums- oder Zeitstempelformate verwenden müssen, stellen Sie sicher, dass sie gültige java.time.format.DateTimeFormatter-Muster haben. Die folgende Tabelle zeigt zusätzliche Beispiele für benutzerdefinierte Formate in den Datums- und Zeitstempelspalten:

Typ	Eingabewert	Format	Bemerkung
`DATE`	2011-3-31		Die Vorlage kann dieses Format standardmäßig parsen. Sie müssen den Parameter `dateFormat` nicht angeben.
`DATE`	2011-3-31 00:00:00		Die Vorlage kann dieses Format standardmäßig parsen. Sie müssen das Format nicht angeben. Sie können `yyyy-M-d' 00:00:00'` verwenden.
`DATE`	01. Apr 18	tt. MMM jj
`DATE`	Mittwoch, 3. April 2019	EEEE, d. MMMM jjjj
`TIMESTAMP`	2019-01-02T11:22:33Z 2019-01-02T11:22:33.123Z 2019-01-02T11:22:33.12356789Z		Das Standardformat `ISO_INSTANT` kann diese Art von Zeitstempel parsen. Sie müssen den Parameter `timestampFormat` nicht angeben.
`TIMESTAMP`	1568402363		Standardmäßig kann die Vorlage diese Art von Zeitstempel parsen und sie als Unix-Epochen-Zeit behandeln.
`TIMESTAMP`	Di, 3. Jun 2008 11:05:30 GMT	EEE, d. MMM jjjj HH:mm:ss VV
`TIMESTAMP`	31.12.2018 110530.123PST	tt.MM.jjjj HHmmss.SSSSz
`TIMESTAMP`	2019-01-02T11:22:33Z oder 2019-01-02T11:22:33.123Z	jjjj-MM-tt'T'HH:mm:ss[.SSS]VV	Wenn die Eingabespalte eine Kombination aus 2019-01-02T11:22:33Z und 2019-01-02T11:22:33.123Z ist, kann das Standardformat diese Art von Zeitstempel parsen. Sie müssen keinen eigenen Formatparameter angeben. Sie können jedoch `yyyy-MM-dd'T'HH:mm:ss[.SSS]VV` verwenden, um beide Fälle zu verarbeiten. Beachten Sie, dass Sie `yyyy-MM-dd'T'HH:mm:ss[.SSS]'Z'` nicht verwenden können, da das Postfix "Z" als Zeitzonen-ID und nicht als Zeichenliteral geparst werden muss. Intern wird die Zeitstempelspalte in eine `java.time.Instant` umgewandelt. Daher muss es in UTC angegeben werden oder mit Zeitzoneninformationen verknüpft sein. Lokales Datum, z. B. 2019-01-02 11:22:33, kann nicht als gültige `java.time.Instant` geparst werden.

Führen Sie die Vorlage aus.

Console

Rufen Sie die Dataflow-Seite Job aus Vorlage erstellen auf.

Zur Seite "Job aus Vorlage erstellen“

Geben Sie im Feld Jobname einen eindeutigen Jobnamen ein.
Optional: Wählen Sie für Regionaler Endpunkt einen Wert aus dem Drop-down-Menü aus. Die Standardregion ist us-central1.
Eine Liste der Regionen, in denen Sie einen Dataflow-Job ausführen können, finden Sie unter Dataflow-Standorte.
Wählen Sie im Drop-down-Menü Dataflow-Vorlage die Option the Text Files on Cloud Storage to Cloud Spanner template aus.
Geben Sie Ihre Parameterwerte in die Parameterfelder ein.
Klicken Sie auf Job ausführen.

gcloud

Führen Sie die Vorlage in der Shell oder im Terminal aus:

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

Dabei gilt:

JOB_NAME: ein eindeutiger Jobname Ihrer Wahl
VERSION: die Version der Vorlage, die Sie verwenden möchten
Sie können die folgenden Werte verwenden:
- latest zur Verwendung der neuesten Version der Vorlage, die im nicht datierten übergeordneten Ordner im Bucket verfügbar ist: gs://dataflow-templates-REGION_NAME/latest/
- Den Versionsnamen wie 2023-09-12-00_RC00, um eine bestimmte Version der Vorlage zu verwenden. Diese ist verschachtelt im jeweiligen datierten übergeordneten Ordner im Bucket enthalten: gs://dataflow-templates-REGION_NAME/.
Achtung: Die neueste Version der Vorlagen wird möglicherweise mit funktionsgefährdenden Änderungen aktualisiert. In Ihren Produktionsumgebungen sollten Vorlagen verwendet werden, die sich im aktuellsten datierten übergeordneten Ordner befinden, um zu verhindern, dass diese funktionsgefährdenden Änderungen Ihre Produktionsworkflows beeinträchtigen.
REGION_NAME: die Region, in der Sie Ihren Dataflow-Job bereitstellen möchten, z. B. us-central1
INSTANCE_ID: Ihre Spanner-Instanz-ID
DATABASE_ID: Ihre Spanner-Datenbank-ID
GCS_PATH_TO_IMPORT_MANIFEST: Der Cloud Storage-Pfad zu Ihrer Importmanifestdatei

API

Senden Sie eine HTTP-POST-Anfrage, um die Vorlage mithilfe der REST API auszuführen. Weitere Informationen zur API und ihren Autorisierungsbereichen finden Sie unter 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"
   }
}

Dabei gilt:

PROJECT_ID: die ID des Google Cloud-Projekts, in dem Sie den Dataflow-Job ausführen möchten
JOB_NAME: ein eindeutiger Jobname Ihrer Wahl
VERSION: die Version der Vorlage, die Sie verwenden möchten
Sie können die folgenden Werte verwenden:
- latest zur Verwendung der neuesten Version der Vorlage, die im nicht datierten übergeordneten Ordner im Bucket verfügbar ist: gs://dataflow-templates-REGION_NAME/latest/
- Den Versionsnamen wie 2023-09-12-00_RC00, um eine bestimmte Version der Vorlage zu verwenden. Diese ist verschachtelt im jeweiligen datierten übergeordneten Ordner im Bucket enthalten: gs://dataflow-templates-REGION_NAME/.
Achtung: Die neueste Version der Vorlagen wird möglicherweise mit funktionsgefährdenden Änderungen aktualisiert. In Ihren Produktionsumgebungen sollten Vorlagen verwendet werden, die sich im aktuellsten datierten übergeordneten Ordner befinden, um zu verhindern, dass diese funktionsgefährdenden Änderungen Ihre Produktionsworkflows beeinträchtigen.
LOCATION: die Region, in der Sie Ihren Dataflow-Job bereitstellen möchten, z. B. us-central1
INSTANCE_ID: Ihre Spanner-Instanz-ID
DATABASE_ID: Ihre Spanner-Datenbank-ID
GCS_PATH_TO_IMPORT_MANIFEST: Der Cloud Storage-Pfad zu Ihrer Importmanifestdatei

Quellcode der Vorlage

Java

Der Quellcode dieser Vorlage befindet sich im Repository "GoogleCloudPlatform/DataflowTemplates" auf GitHub.

Nächste Schritte

Informationen zu Dataflow-Vorlagen
Sehen Sie sich die Liste der von Google bereitgestellten Vorlagen an.