Vorlage „Cloud Storage Avro für Spanner-Datenvalidierung“

Die Vorlage „Cloud Storage Avro-Dateien für die Spanner-Datenvalidierung“ ist eine Batchpipeline, die Daten aus Cloud Storage und Spanner liest und vergleicht, um die Korrektheit der Migration zu prüfen.

Pipelineanforderungen

  • Das Cloud Storage-Verzeichnis für Avro-Dateien muss vor der Pipelineausführung vorhanden sein. Generieren Sie diese Avro-Dateien, indem Sie die Pipeline SourceDB zu Cloud Spanner mit dem Parameter gcsOutputDirectory ausführen.
  • Das BigQuery-Ziel-Dataset für Validierungsergebnisse muss vor der Pipelineausführung vorhanden sein.
  • Die Spanner-Tabellen müssen vor der Pipelineausführung vorhanden sein.
  • Die Spanner-Tabellen müssen ein kompatibles Schema haben (entweder direkt oder über Schemazuordnung).
  • Wenn Sie eine Migration validieren möchten, die von der SourceDB-zu-Cloud Spanner-Pipeline durchgeführt wurde, müssen Sie für alle freigegebenen Konfigurationen (z. B. sessionFilePath, schemaOverridesFilePath und transformationJarPath) identische Werte übergeben.

Vorlagenparameter

Erforderliche Parameter

  • gcsInputDirectory: Dieses Verzeichnis wird verwendet, um die AVRO-Dateien der aus der Quelle gelesenen Datensätze zu lesen. Beispiel: gs://your-bucket/your-path.
  • projectId: Dies ist der Name des Cloud Spanner-Projekts.
  • instanceId: Die Cloud Spanner-Zielinstanz.
  • databaseId: Die Cloud Spanner-Zieldatenbank.
  • bigQueryDataset: Die BigQuery-Dataset-ID, unter der die Validierungsergebnisse gespeichert werden. Beispiel: validation_report_dataset.

Optionale Parameter

  • spannerHost: Der Cloud Spanner-Endpunkt, der in der Vorlage aufgerufen werden soll. Beispiel: https://batch-spanner.googleapis.com. Die Standardeinstellung ist https://batch-spanner.googleapis.com.
  • spannerPriority: Die Anfragepriorität für Cloud Spanner-Aufrufe. Der Wert muss einer der folgenden sein: [HIGH,MEDIUM,LOW]. Der Standardwert ist HIGH.
  • sessionFilePath: Pfad der Sitzungsdatei in Cloud Storage, die Zuordnungsinformationen aus dem Spanner Migration Tool enthält. Die Standardeinstellung ist leer.
  • schemaOverridesFilePath: Eine Datei, in der die Überschreibungen für Tabellen- und Spaltennamen von der Quelle zu Spanner angegeben sind. Die Standardeinstellung ist leer.
  • tableOverrides: Dies sind die Tabellennamenüberschreibungen von der Quelle zu Spanner. Sie werden im folgenden Format geschrieben: [{SourceTableName1, SpannerTableName1}, {SourceTableName2, SpannerTableName2}]. In diesem Beispiel wird die Tabelle „Singers“ der Tabelle „Vocalists“ und die Tabelle „Albums“ der Tabelle „Records“ zugeordnet. Beispiel: [{Singers, Vocalists}, {Albums, Records}]. Die Standardeinstellung ist leer.
  • columnOverrides: Dies sind die Überschreibungen der Spaltennamen von der Quelle zu Cloud Spanner. Sie werden im folgenden Format geschrieben: [{SourceTableName1.SourceColumnName1, SourceTableName1.SpannerColumnName1}, {SourceTableName2.SourceColumnName1, SourceTableName2.SpannerColumnName1}]. Beachten Sie, dass der SourceTableName sowohl im Quell- als auch im Spanner-Paar gleich bleiben sollte. Verwenden Sie „tableOverrides“, um Tabellennamen zu überschreiben. Im Beispiel wird „SingerName“ zu „TalentName“ und „AlbumName“ zu „RecordName“ in der Tabelle „Singers“ bzw. „Albums“ zugeordnet. Beispiel: [{Singers.SingerName, Singers.TalentName}, {Albums.AlbumName, Albums.RecordName}]. Die Standardeinstellung ist leer.
  • runId: Eine eindeutige Kennung für den Validierungslauf. Wenn nicht angegeben, wird der Dataflow-Jobname verwendet. Beispiel: run_20230101_120000.
  • transformationJarPath: Speicherort der benutzerdefinierten JAR-Datei in Cloud Storage, die die benutzerdefinierte Transformationslogik für die Verarbeitung von Einträgen enthält. Die Standardeinstellung ist leer.
  • transformationClassName: Vollständig qualifizierter Klassenname mit der benutzerdefinierten Transformationslogik. Es ist ein Pflichtfeld, wenn transformationJarPath angegeben ist. Die Standardeinstellung ist leer.
  • transformationCustomParameters: String mit allen benutzerdefinierten Parametern, die an die benutzerdefinierte Transformationsklasse übergeben werden sollen. Die Standardeinstellung ist leer.
  • tables: Eine durch Kommas getrennte Liste von Quelltabellen, die in den Validierungslauf einbezogen werden sollen. Die Standardeinstellung ist leer.
  • tableConfigurationFilePath: Ein GCS-Dateipfad, der eine JSON-Liste der zu validierenden Quelltabellen enthält. Dabei muss es sich um eine JSON-Datei mit der Struktur {"tableNames": ["table1", "table2"]} handeln. Optional legt optionalConfigurations.<sourceTable>.spannerQuery die Spanner-Abfrage fest, die zum Lesen dieser Tabelle verwendet wird, z.B. um sie auf die ausgewählte shardIds zu beschränken. Verwenden Sie für eine reine Spanner-Tabelle den Spanner-Namen als Schlüssel. Die Abfrageregeln finden Sie im Abschnitt „Validating a subset of shards“ (Teilmenge von Shards validieren) der README.md-Datei des Moduls. Die Standardeinstellung ist leer.
  • shardIds: Eine durch Kommas getrennte Liste logischer Shard-IDs (die IDs, die von der Vorlage „sourcedb-to-spanner“ verwendet werden und als Verzeichnis <table>/<shardId>/ in der Avro-Ausgabe angezeigt werden). Wenn festgelegt, werden nur diese Shards validiert. Tabellen mit einer Sitzungsdatei ShardIdColumn werden nach dieser Spalte gefiltert. Jede andere Tabelle im Bereich muss eine spannerQuery in tableConfigurationFilePath haben, sonst schlägt der Job fehl. Beispiel: shard_001,shard_007. Die Standardeinstellung ist leer.

Führen Sie die Vorlage aus.

Console

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

  5. Wählen Sie im Drop-down-Menü Dataflow-Vorlage die Vorlage Cloud Storage Avro files to Spanner Data Validation aus.
  6. Geben Sie Ihre Parameterwerte in die Parameterfelder ein.
  7. Klicken Sie auf Job ausführen.

gcloud-CLI

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

gcloud dataflow flex-template run JOB_NAME \
    --template-file-gcs-location=gs://dataflow-templates/VERSION/flex/Avro_to_Spanner_Data_Validator \
    --region=REGION_NAME \
    --parameters \
       gcsInputDirectory=PATH_TO_AVRO_FILES,\
       projectId=PROJECT_ID,\
       instanceId=INSTANCE_ID,\
       databaseId=DATABASE_ID,\
       bigQueryDataset=BIGQUERY_DATASET

Ersetzen Sie 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 aktuellen Version der Vorlage, die im nicht datierten übergeordneten Ordner im Bucket verfügbar ist: gs://dataflow-templates/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: die Region, in der Sie Ihren Dataflow-Job bereitstellen möchten, z. B. us-central1
  • PATH_TO_AVRO_FILES: Der Cloud Storage-Pfad zu den Avro-Dateien.
  • PROJECT_ID: die Spanner-Projekt-ID.
  • INSTANCE_ID: die ID der Cloud Spanner-Zielinstanz.
  • DATABASE_ID: die ID der Spanner-Zieldatenbank.
  • BIGQUERY_DATASET: die BigQuery-Dataset-ID für die Validierungsergebnisse.

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/flexTemplates:launch
{
   "launchParameter": {
     "jobName": "JOB_NAME",
     "parameters": {
       "gcsInputDirectory": "PATH_TO_AVRO_FILES",
       "projectId": "PROJECT_ID",
       "instanceId": "INSTANCE_ID",
       "databaseId": "DATABASE_ID",
       "bigQueryDataset": "BIGQUERY_DATASET"
     },
     "containerSpecGcsPath": "gs://dataflow-templates/VERSION/flex/Avro_to_Spanner_Data_Validator"
  }
}

Ersetzen Sie Folgendes:

  • PROJECT_ID: Die Google Cloud Projekt-ID, in der 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 aktuellen Version der Vorlage, die im nicht datierten übergeordneten Ordner im Bucket verfügbar ist: gs://dataflow-templates/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/.
  • LOCATION: die Region, in der Sie Ihren Dataflow-Job bereitstellen möchten, z. B. us-central1
  • PATH_TO_AVRO_FILES: Der Cloud Storage-Pfad zu den Avro-Dateien.
  • PROJECT_ID: die Spanner-Projekt-ID.
  • INSTANCE_ID: die ID der Cloud Spanner-Zielinstanz.
  • DATABASE_ID: die ID der Spanner-Zieldatenbank.
  • BIGQUERY_DATASET: die BigQuery-Dataset-ID für die Validierungsergebnisse.