SQL-Abfragen mit der Translation API übersetzen

In diesem Dokument wird beschrieben, wie Sie mit der Translation API in BigQuery Skripts, die in anderen SQL-Dialekten geschrieben sind, in GoogleSQL-Abfragen übersetzen. Die Translation API kann die Migration von Arbeitslasten zu BigQuery vereinfachen.

Hinweise

Führen Sie die folgenden Schritte aus, bevor Sie einen Übersetzungsjob senden:

1. Prüfen, ob Sie die erforderlichen Berechtigungen haben
2. Aktivieren Sie die BigQuery Migration API.
3. Erfassen Sie die Quelldateien mit den SQL-Skripts und Abfragen, die übersetzt werden sollen.
4. Quelldateien in Cloud Storage hochladen

Erforderliche Berechtigungen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle MigrationWorkflow-Bearbeiter (roles/bigquerymigration.editor) für die Ressource parent zu gewähren, um die Berechtigungen zu erhalten, die Sie zum Erstellen von Übersetzungsjobs mit der konsolidierten Übersetzungs-API benötigen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierte Rolle enthält die Berechtigungen, die zum Erstellen von Übersetzungsjobs mithilfe der konsolidierten Übersetzungs-API erforderlich sind. Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um Übersetzungsjobs mit der konsolidierten Übersetzungs-API zu erstellen:

• bigquerymigration.workflows.create
• bigquerymigration.workflows.get

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

BigQuery Migration API aktivieren

Wenn Ihr Google Cloud-Befehlszeilenprojekt vor dem 15. Februar 2022 erstellt wurde, aktivieren Sie die BigQuery Migration API so:

1. Rufen Sie in der Google Cloud Console die Seite BigQuery Migration API auf.

   Zu „BigQuery Migration API“

2. Klicken Sie auf Aktivieren.

Hinweis: Bei Projekten, die nach dem 15. Februar 2022 erstellt wurden, ist diese API automatisch aktiviert.

Eingabedateien nach Cloud Storage hochladen

Wenn Sie die Cloud Console oder die BigQuery Migration API verwenden möchten, um einen Übersetzungsjob auszuführen, müssen Sie die Quelldateien mit den Abfragen und Skripts hochladen, die in Cloud Storage übersetzt werden sollen. Sie können auch beliebige Metadatendateien oder YAML-Konfigurationsdateien in denselben Cloud Storage-Bucket hochladen, der die Quelldateien enthält. Weitere Informationen zum Erstellen von Buckets und zum Hochladen von Dateien in Cloud Storage erhalten Sie unter Buckets erstellen und Objekte aus einem Dateisystem hochladen.

Unterstützte Aufgabentypen

Die Translation API kann die folgenden SQL-Dialekte in GoogleSQL übersetzen:

• Amazon Redshift SQL - Redshift2BigQuery_Translation
• Apache HiveQL und Beeline-Befehlszeile - HiveQL2BigQuery_Translation
• Apache Spark SQL - SparkSQL2BigQuery_Translation
• Azure Synapse T-SQL - AzureSynapse2BigQuery_Translation
• Greenplum SQL - Greenplum2BigQuery_Translation
• IBM Db2 SQL - Db22BigQuery_Translation
• IBM Netezza SQL und NZPLSQL - Netezza2BigQuery_Translation
• MySQL SQL - MySQL2BigQuery_Translation
• Oracle SQL, PL/SQL, Exadata - Oracle2BigQuery_Translation
• PostgreSQL SQL - Postgresql2BigQuery_Translation
• Presto oder Trino SQL – Presto2BigQuery_Translation
• Snowflake SQL - Snowflake2BigQuery_Translation
• SQLite - SQLite2BigQuery_Translation
• SQL Server T-SQL - SQLServer2BigQuery_Translation
• Teradata und Teradata Vantage - Teradata2BigQuery_Translation
• Vertica SQL - Vertica2BigQuery_Translation

Standorte

Die Translation API ist an den folgenden Verarbeitungsstandorten verfügbar:

	Beschreibung der Region	Name der Region	Details
Asiatisch-pazifischer Raum
	Tokio	asia-northeast1
	Mumbai	asia-south1
	Singapur	asia-southeast1
	Sydney	australia-southeast1
Europa
	EU (mehrere Regionen)	eu
	Warschau	europe-central2
	Finnland	europe-north1	Niedriger CO2-Wert
	Madrid	europe-southwest1	Niedriger CO2-Wert
	Belgien	europe-west1	Niedriger CO2-Wert
	London	europe-west2	Niedriger CO2-Wert
	Frankfurt	europe-west3	Niedriger CO2-Wert
	Niederlande	europe-west4	Niedriger CO2-Wert
	Zürich	europe-west6	Niedriger CO2-Wert
	Paris	europe-west9	Niedriger CO2-Wert
	Turin	europe-west12
Amerika
	São Paulo	southamerica-east1	Niedriger CO2-Wert
	USA (mehrere Regionen)	us
	Iowa	us-central1	Niedriger CO2-Wert
	South Carolina	us-east1
	Northern Virginia	us-east4
	Columbus, Ohio	us-east5
	Dallas	us-south1	Niedriger CO2-Wert
	Oregon	us-west1	Niedriger CO2-Wert
	Los Angeles	us-west2
	Salt Lake City	us-west3

Übersetzungsjob senden

Verwenden Sie zum Senden eines Übersetzungsjobs mit der Translation API die Methode projects.locations.workflows.create und geben Sie eine Instanz der Ressource MigrationWorkflow mit einer unterstützten Aufgabentyp.

Sobald der Job gesendet wurde, können Sie eine Abfrage stellen, um Ergebnisse zu erhalten.

Batchübersetzung erstellen

Mit dem folgenden curl-Befehl wird ein Batchübersetzungsjob erstellt, in dem die Ein- und Ausgabedateien in Cloud Storage gespeichert werden. Das Feld source_target_mapping enthält eine Liste, die die literal-Quelleinträge einem optionalen relativen Pfad für die Zielausgabe zuordnet.

curl -d "{
  \"tasks\": {
      string: {
        \"type\": \"TYPE\",
        \"translation_details\": {
            \"target_base_uri\": \"TARGET_BASE\",
            \"source_target_mapping\": {
              \"source_spec\": {
                  \"base_uri\": \"BASE\"
              }
            },
        }
      }
  }
  }" \
  -H "Content-Type:application/json" \
  -H "Authorization: Bearer TOKEN" -X POST https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows

Ersetzen Sie Folgendes:

• TYPE: Der Aufgabentyp der Übersetzung, der den Quell- und Zieldialekt bestimmt.
• TARGET_BASE: Der Basis-URI für alle Übersetzungsausgaben.
• BASE ist der Basis-URI für alle Dateien, die als Quellen für die Übersetzung gelesen werden.
• TOKEN: das Token zur Authentifizierung. Verwenden Sie zum Generieren eines Tokens den Befehl gcloud auth print-access-token oder den OAuth 2.0 Playground (verwenden Sie den Bereich https://www.googleapis.com/auth/cloud-platform).
• PROJECT_ID: das Projekt, in dem die Übersetzung verarbeitet werden soll.
• LOCATION: der Standort, an dem der Job verarbeitet wird.

Der vorherige Befehl gibt eine Antwort zurück, die eine Workflow-ID im Format projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID enthält.

Beispiel für eine Batchübersetzung

Wenn Sie die Teradata-SQL-Scripts im Cloud Storage-Verzeichnis gs://my_data_bucket/teradata/input/ übersetzen und die Ergebnisse im Cloud Storage-Verzeichnis gs://my_data_bucket/teradata/output/ speichern möchten, können Sie die folgende Abfrage verwenden:

{
  "tasks": {
     "task_name": {
       "type": "Teradata2BigQuery_Translation",
       "translation_details": {
         "target_base_uri": "gs://my_data_bucket/teradata/output/",
           "source_target_mapping": {
             "source_spec": {
               "base_uri": "gs://my_data_bucket/teradata/input/"
             }
          },
       }
    }
  }
}

Hinweis: Der String "task_name" in diesem Beispiel ist eine Kennung für die Übersetzungsaufgabe und kann auf einen beliebigen Wert festgelegt werden.

Dieser Aufruf gibt eine Nachricht mit der erstellten Workflow-ID im Feld "name" zurück:

{
  "name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
  "tasks": {
    "task_name": { /*...*/ }
  },
  "state": "RUNNING"
}

Wenn Sie den aktualisierten Status des Workflows abrufen möchten, führen Sie eine GET-Abfrage aus. Der Job ist abgeschlossen, wenn "state" in COMPLETED wechselt. Wenn die Aufgabe erfolgreich abgeschlossen wurde, finden Sie die übersetzte SQL-Anweisung unter gs://my_data_bucket/teradata/output.

Interaktiven Übersetzungsjob mit Stringliteraleingaben und -ausgaben erstellen

Mit dem folgenden curl-Befehl wird ein Übersetzungsjob mit Ein- und Ausgaben von Stringliteralen erstellt. Das Feld source_target_mapping enthält eine Liste, die die Quellverzeichnisse einem optionalen relativen Pfad für die Zielausgabe zuordnet.

curl -d "{
  \"tasks\": {
      string: {
        \"type\": \"TYPE\",
        \"translation_details\": {
        \"source_target_mapping\": {
            \"source_spec\": {
              \"literal\": {
              \"relative_path\": \"PATH\",
              \"literal_string\": \"STRING\"
              }
            }
        },
        \"target_return_literals\": \"TARGETS\",
        }
      }
  }
  }" \
  -H "Content-Type:application/json" \
  -H "Authorization: Bearer TOKEN" -X POST https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows

Ersetzen Sie Folgendes:

• TYPE: Der Aufgabentyp der Übersetzung, der den Quell- und Zieldialekt bestimmt.
• PATH: die Kennung des Literaleintrags, ähnlich einem Dateinamen oder Pfad.
• STRING: String der Literaleingabedaten (z. B. SQL), die übersetzt werden sollen.
• TARGETS: die erwarteten Ziele, die der Nutzer direkt in der Antwort im Format literal zurückgeben möchte. Diese sollten im Ziel-URI-Format vorliegen (z. B. GENERATED_DIR + target_spec.relative_path + source_spec.literal.relative_path). Alles, was nicht in dieser Liste enthalten ist, wird in der Antwort nicht zurückgegeben. Das generierte Verzeichnis GENERATED_DIR für allgemeine SQL-Übersetzungen ist sql/.
• TOKEN: das Token zur Authentifizierung. Verwenden Sie zum Generieren eines Tokens den Befehl gcloud auth print-access-token oder den OAuth 2.0 Playground (verwenden Sie den Bereich https://www.googleapis.com/auth/cloud-platform).
• PROJECT_ID: das Projekt, in dem die Übersetzung verarbeitet werden soll.
• LOCATION: der Standort, an dem der Job verarbeitet wird.

Der vorherige Befehl gibt eine Antwort zurück, die eine Workflow-ID im Format projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID enthält.

Wenn der Job abgeschlossen ist, können Sie die Ergebnisse abrufen, indem Sie den Job abfragen und das Inline-Feld translation_literals in der Antwort prüfen, nachdem der Workflow abgeschlossen ist.

Beispiel für eine interaktive Übersetzung

Um den Hive-SQL-String select 1 interaktiv zu übersetzen, können Sie die folgende Abfrage verwenden:

"tasks": {
  string: {
    "type": "HiveQL2BigQuery_Translation",
    "translation_details": {
      "source_target_mapping": {
        "source_spec": {
          "literal": {
            "relative_path": "input_file",
            "literal_string": "select 1"
          }
        }
      },
      "target_return_literals": "sql/input_file",
    }
  }
}

Hinweis: Der String "task_name" in diesem Beispiel ist eine Kennung für die Übersetzungsaufgabe und kann auf einen beliebigen Wert festgelegt werden.

Sie können für das Literal ein beliebiges relative_path verwenden. Das übersetzte Literal wird jedoch nur in den Ergebnissen angezeigt, wenn Sie sql/$relative_path in target_return_literals einschließen. Sie können auch mehrere Literale in einer einzigen Abfrage angeben. In diesem Fall müssen alle relativen Pfade in target_return_literals enthalten sein.

Dieser Aufruf gibt eine Nachricht mit der erstellten Workflow-ID im Feld "name" zurück:

{
  "name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
  "tasks": {
    "task_name": { /*...*/ }
  },
  "state": "RUNNING"
}

Wenn Sie den aktualisierten Status des Workflows abrufen möchten, führen Sie eine GET-Abfrage aus. Der Job ist abgeschlossen, wenn "state" in COMPLETED wechselt. Wenn die Aufgabe erfolgreich war, finden Sie die übersetzte SQL-Anweisung in der Antwortnachricht:

{
  "name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
  "tasks": {
    "string": {
      "id": "0fedba98-7654-3210-1234-56789abcdef",
      "type": "HiveQL2BigQuery_Translation",
      /* ... */
      "taskResult": {
        "translationTaskResult": {
          "translatedLiterals": [
            {
              "relativePath": "sql/input_file",
              "literalString": "-- Translation time: 2023-10-05T21:50:49.885839Z\n-- Translation job ID: projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00\n-- Source: input_file\n-- Translated from: Hive\n-- Translated to: BigQuery\n\nSELECT\n    1\n;\n"
            }
          ],
          "reportLogMessages": [
            ...
          ]
        }
      },
      /* ... */
    }
  },
  "state": "COMPLETED",
  "createTime": "2023-10-05T21:50:49.543221Z",
  "lastUpdateTime": "2023-10-05T21:50:50.462758Z"
}

Übersetzungsausgabe ansehen

Rufen Sie nach dem Ausführen des Übersetzungsjobs die Ergebnisse ab. Geben Sie dazu die Workflow-ID des Übersetzungsjobs mit dem folgenden Befehl an:

curl \
-H "Content-Type:application/json" \
-H "Authorization:Bearer TOKEN" -X GET https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

Ersetzen Sie Folgendes:

• TOKEN: das Token zur Authentifizierung. Verwenden Sie zum Generieren eines Tokens den Befehl gcloud auth print-access-token oder den OAuth 2.0 Playground (verwenden Sie den Bereich https://www.googleapis.com/auth/cloud-platform).
• PROJECT_ID: das Projekt, in dem die Übersetzung verarbeitet werden soll.
• LOCATION: der Standort, an dem der Job verarbeitet wird.
• WORKFLOW_ID: die ID, die beim Erstellen eines Übersetzungsworkflows generiert wird.

Die Antwort enthält den Status des Migrationsworkflows und alle abgeschlossenen Dateien in target_return_literals.

Die Antwort enthält den Status des Migrationsworkflows und alle abgeschlossenen Dateien in target_return_literals. Sie können diesen Endpunkt abfragen, um den Status Ihres Workflows zu prüfen.