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:
- Prüfen, ob Sie die erforderlichen Berechtigungen haben
- Aktivieren Sie die BigQuery Migration API.
- Erfassen Sie die Quelldateien mit den SQL-Skripts und Abfragen, die übersetzt werden sollen.
- 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:
Rufen Sie in der Google Cloud Console die Seite BigQuery Migration API auf.
Klicken Sie auf Aktivieren.
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 Befehlgcloud auth print-access-token
oder den OAuth 2.0 Playground (verwenden Sie den Bereichhttps://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/"
}
},
}
}
}
}
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 Formatliteral
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 istsql/
.TOKEN
: das Token zur Authentifizierung. Verwenden Sie zum Generieren eines Tokens den Befehlgcloud auth print-access-token
oder den OAuth 2.0 Playground (verwenden Sie den Bereichhttps://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",
}
}
}
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 Befehlgcloud auth print-access-token
oder den OAuth 2.0 Playground (verwenden Sie den Bereichhttps://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.