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 GoogleSQL-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

Warnung: Wenn die Spanner-Zieldatenbank nicht leer ist, werden vorhandene Daten möglicherweise durch neue überschrieben.

Vorlagenparameter

Erforderliche Parameter

• instanceId: Die Instanz-ID der Spanner-Datenbank.
• databaseId: Die Datenbank-ID der Spanner-Datenbank.
• importManifest: Der Pfad in Cloud Storage, der beim Importieren von Manifestdateien verwendet werden soll. Beispiel: gs://your-bucket/your-folder/your-manifest.json.

Optionale Parameter

• spannerHost: Der Cloud Spanner-Endpunkt, der in der Vorlage aufgerufen werden soll. Wird nur zum Testen verwendet. Beispiel: https://batch-spanner.googleapis.com. Die Standardeinstellung ist https://batch-spanner.googleapis.com.
• columnDelimiter: Das Spaltentrennzeichen, das in der Quelldatei verwendet wird. Der Standardwert ist ,. Beispiel: ,
• fieldQualifier: Das Zeichen, das jeden Wert in der Quelldatei, die das Spaltentrennzeichen enthält, umgeben muss. Der Standardwert ist ein doppeltes Anführungszeichen.
• 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 (https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html) an.
• timestampFormat: Das zum Parsen der Zeitstempelspalten verwendete Format. Ist der Zeitstempel eine lange Ganzzahl, wird er als UNIX-Epoche geparst. Andernfalls wird er als String mit dem Format 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) 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: Die ID des Google Cloud-Projekts, das die Spanner-Datenbank enthält. Wenn nicht festgelegt, wird die Projekt-ID des Google Cloud-Standardprojekts verwendet.
• spannerPriority: Die Anfragepriorität für Spanner-Aufrufe. Mögliche Werte sind HIGH, MEDIUM und LOW. Der Standardwert ist MEDIUM.
• handleNewLine: Wenn true, können die Eingabedaten Zeilenumbruchzeichen enthalten. Andernfalls führen Zeilenumbruchzeichen zu einem Fehler. Der Standardwert ist false. Die Aktivierung der Neuzeilenbehandlung kann die Leistung beeinträchtigen.
• invalidOutputPath: Der Cloud Storage-Pfad, der beim Schreiben von Zeilen verwendet werden soll, die nicht importiert werden können. Beispiel: gs://your-bucket/your-path. Die Standardeinstellung ist leer.

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

1. Rufen Sie die Dataflow-Seite Job aus Vorlage erstellen auf.
Zur Seite "Job aus Vorlage erstellen“
2. Geben Sie im Feld Jobname einen eindeutigen Jobnamen ein.
3. 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.

4. Wählen Sie im Drop-down-Menü Dataflow-Vorlage die Option the Text Files on Cloud Storage to Cloud Spanner templateaus.
5. Geben Sie Ihre Parameterwerte in die Parameterfelder ein.
6. Klicken Sie auf Job ausführen.

gcloud

Hinweis: Um classic-Vorlagen mit dem Google Cloud CLI auszuführen, benötigen Sie das Google Cloud CLI in der Version 138.0.0 oder höher.

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

Ersetzen Sie dabei Folgendes:

• 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"
   }
}

Ersetzen Sie dabei Folgendes:

• 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

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