Traduci query SQL con l'API Translation

Questo documento descrive come utilizzare l'API di traduzione in BigQuery per tradurre gli script scritti in altri dialetti SQL in query GoogleSQL. L'API di traduzione può semplificare la procedura di migrazione dei carichi di lavoro a BigQuery.

Prima di iniziare

Prima di inviare un job di traduzione, completa i seguenti passaggi:

1. Assicurati di disporre di tutte le autorizzazioni richieste.
2. Abilitare l'API BigQuery Migration.
3. Raccogliere i file di origine contenenti gli script e le query SQL da tradurre.
4. Caricare i file di origine in Cloud Storage.

Autorizzazioni obbligatorie

Per ottenere le autorizzazioni necessarie per creare job di traduzione utilizzando l'API di traduzione, chiedi all'amministratore di concederti il ruolo IAM MigrationWorkflow Editor (roles/bigquerymigration.editor) nella risorsa parent. Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene le autorizzazioni necessarie per creare job di traduzione usando l'API di traduzione. Per visualizzare le autorizzazioni esatte richieste, espandi la sezione Autorizzazioni richieste:

Autorizzazioni obbligatorie

Per creare job di traduzione utilizzando l'API di traduzione, sono necessarie le seguenti autorizzazioni:

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

Potresti anche riuscire a ottenere queste autorizzazioni con ruoli personalizzati altri ruoli predefiniti.

Abilita l'API BigQuery Migration

Se il tuo progetto Google Cloud CLI è stato creato prima del 15 febbraio 2022, attiva l'API BigQuery Migration come segue:

1. Nella console Google Cloud, vai alla pagina dell'API BigQuery Migration.

   Vai all'API BigQuery Migration

2. Fai clic su Attiva.

Nota: per i progetti creati dopo il 15 febbraio 2022 questa API è abilitata automaticamente.

Carica i file di input su Cloud Storage

Se vuoi utilizzare la console Google Cloud o l'API BigQuery Migration per eseguire un job di traduzione, devi caricare i file di origine contenenti le query e gli script da tradurre in Cloud Storage. Tu puoi anche caricare qualsiasi file di metadati o file YAML di configurazione nello stesso bucket Cloud Storage contenente i file di origine. Per ulteriori informazioni sulla creazione di bucket e sul caricamento di file su Cloud Storage, consulta Creare bucket e Caricare oggetti da un file system.

Tipi di attività supportati

L'API di traduzione può tradurre i seguenti dialetti SQL in GoogleSQL:

• Amazon Redshift SQL - Redshift2BigQuery_Translation
• Apache HiveQL e interfaccia a riga di comando Beeline - HiveQL2BigQuery_Translation
• Apache Spark SQL - SparkSQL2BigQuery_Translation
• Azure Synapse T-SQL - AzureSynapse2BigQuery_Translation
• SQL Greenplum - Greenplum2BigQuery_Translation
• IBM Db2 SQL - Db22BigQuery_Translation
• IBM Netezza SQL e NZPLSQL - Netezza2BigQuery_Translation
• SQL MySQL - MySQL2BigQuery_Translation
• Oracle SQL, PL/SQL, Exadata - Oracle2BigQuery_Translation
• SQL PostgreSQL - Postgresql2BigQuery_Translation
• Presto o Trino SQL - Presto2BigQuery_Translation
• Snowflake SQL - Snowflake2BigQuery_Translation
• SQLite - SQLite2BigQuery_Translation
• SQL Server T-SQL - SQLServer2BigQuery_Translation
• Teradata e Teradata Vantage - Teradata2BigQuery_Translation
• SQL vertica - Vertica2BigQuery_Translation

Località

L'API di traduzione è disponibile nelle seguenti località di elaborazione:

	Descrizione della regione	Nome della regione	Dettagli
Asia Pacifico
	Tokyo	asia-northeast1
	Mumbai	asia-south1
	Singapore	asia-southeast1
	Sydney	australia-southeast1
Europa
	Multiregionale UE	eu
	Varsavia	europe-central2
	Finlandia	europe-north1	Bassi livelli di CO2
	Madrid	europe-southwest1	A basse emissioni di CO2
	Belgio	europe-west1	A basse emissioni di CO2
	Londra	europe-west2	Bassi livelli di CO2
	Francoforte	europe-west3	A basse emissioni di CO2
	Paesi Bassi	europe-west4	Bassi livelli di CO2
	Zurigo	europe-west6	A basse emissioni di CO2
	Parigi	europe-west9	A basse emissioni di CO2
	Torino	europe-west12
Americhe
	San Paolo	southamerica-east1	A basse emissioni di CO2
	Stati Uniti (più regioni)	us
	Iowa	us-central1	Bassi livelli di CO2
	Carolina del Sud	us-east1
	Virginia del Nord	us-east4
	Columbus, Ohio	us-east5
	Dallas	us-south1	A basse emissioni di CO2
	Oregon	us-west1	A basse emissioni di CO2
	Los Angeles	us-west2
	Salt Lake City	us-west3

Inviare un job di traduzione

Per inviare un job di traduzione utilizzando l'API Translation, utilizza il metodo projects.locations.workflows.create e fornisci un'istanza della risorsa MigrationWorkflow con un tipo di attività supportato.

Una volta inviato il job, puoi inviare una query per ottenere i risultati.

Crea una traduzione batch

Il seguente comando curl crea un job di traduzione batch in cui i file di input e di output vengono archiviati in Cloud Storage. Il campo source_target_mapping contiene un elenco che mappa le voci literal di origine a un relativo facoltativo del percorso dell'output di destinazione.

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

Sostituisci quanto segue:

• TYPE: il tipo di attività della traduzione, che determina il dialetto di origine e di destinazione.
• TARGET_BASE: l'URI di base di tutte le traduzioni come output.
• BASE: l'URI di base per tutti i file letti come origini per la traduzione.
• TOKEN: il token per l'autenticazione. Per generare un token, utilizza il comando gcloud auth print-access-token o OAuth 2.0 Playground (utilizza l'ambito https://www.googleapis.com/auth/cloud-platform).
• PROJECT_ID: il progetto per elaborare la traduzione.
• LOCATION: la posizione in cui viene elaborato il job.

Il comando precedente restituisce una risposta che include un ID flusso di lavoro scritto nel formato projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID.

Esempio di traduzione batch

a tradurre gli script Teradata SQL nella directory Cloud Storage gs://my_data_bucket/teradata/input/ e archivia i risultati nel Directory di Cloud Storage gs://my_data_bucket/teradata/output/, potresti utilizzare la seguente query:

{
  "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/"
             }
          },
       }
    }
  }
}

Nota: la stringa "task_name" in questo esempio è un identificatore per il dell'attività di traduzione e può essere impostato sul valore che preferisci.

Questa chiamata restituirà un messaggio contenente l'ID flusso di lavoro creato nel Campo "name":

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

Per ottenere lo stato aggiornato del flusso di lavoro, esegui una query GET. Il job viene completato quando "state" diventa COMPLETED. Se l'attività è stata completata correttamente, il codice SQL tradotto è disponibile in gs://my_data_bucket/teradata/output.

Crea un job di traduzione interattivo con input e output letterali stringa

Il seguente comando curl crea un job di traduzione con input e output di stringhe litterali. Il campo source_target_mapping contiene un elenco che mappa il a un percorso relativo facoltativo per l'output di destinazione.

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

Sostituisci quanto segue:

• TYPE: il tipo di attività della traduzione, che determina il dialetto di origine e di destinazione.
• PATH: l'identificatore della voce letterale, simile a un nome file o a un percorso.
• STRING: stringa di dati di input letterali (ad esempio SQL) da tradurre.
• TARGETS: i target previsti che l'utente vuole restituire direttamente nella risposta nel formato literal. Devono essere nel formato URI di destinazione (ad esempio, GENERATED_DIR + target_spec.relative_path + source_spec.literal.relative_path). Tutto ciò che non è incluso in questo elenco non viene restituito nella risposta. La directory generata, GENERATED_DIR per le traduzioni SQL generali, è sql/.
• TOKEN: il token per l'autenticazione. Per generare un token, utilizza il comando gcloud auth print-access-token o OAuth 2.0 Playground (utilizza l'ambito https://www.googleapis.com/auth/cloud-platform).
• PROJECT_ID: il progetto per elaborare una traduzione automatica.
• LOCATION: la località in cui si trova il lavoro in fase di elaborazione.

Il comando precedente restituisce una risposta che include un ID flusso di lavoro scritto nel formato projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID.

Una volta completato il job, puoi visualizzare i risultati eseguendo una query sul job. ed esaminando il campo translation_literals in linea nella risposta dopo il viene completato il flusso di lavoro.

Esempio di traduzione interattiva

Per tradurre la stringa SQL Hive select 1 in modo interattivo, puoi utilizzare la seguente query:

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

Nota: la stringa "task_name" in questo esempio è un identificatore per l'attività di traduzione e può essere impostata su qualsiasi valore che preferisci.

Puoi utilizzare qualsiasi relative_path per il tuo valore letterale, ma il valore letterale tradotto verrà visualizzato nei risultati solo se includi sql/$relative_path in target_return_literals. Puoi anche includere più letterali in una singola query, in tal caso ognuno dei relativi percorsi relativi deve essere incluso in target_return_literals.

Questa chiamata restituirà un messaggio contenente l'ID flusso di lavoro creato nel Campo "name":

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

Per ottenere lo stato aggiornato del flusso di lavoro, esegui una query GET. Il job è completato quando "state" diventa COMPLETED. Se l'attività ha esito positivo, troverai il codice SQL tradotto nel messaggio di risposta:

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

Esplorare l'output della traduzione

Dopo aver eseguito il job di traduzione, recupera i risultati specificando l'ID flusso di lavoro del job di traduzione utilizzando il seguente comando:

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

Sostituisci quanto segue:

• TOKEN: il token per l'autenticazione. Per generare un token, utilizza il comando gcloud auth print-access-token o OAuth 2.0 Playground (utilizza l'ambito https://www.googleapis.com/auth/cloud-platform).
• PROJECT_ID: il progetto per elaborare una traduzione automatica.
• LOCATION: la posizione in cui viene elaborato il job.
• WORKFLOW_ID: l'ID generato quando crei un flusso di lavoro di traduzione.

La risposta contiene lo stato del flusso di lavoro di migrazione e tutti i file completati in target_return_literals.

La risposta conterrà lo stato del flusso di lavoro di migrazione e qualsiasi file completati in target_return_literals. Puoi eseguire il polling di questo endpoint per verificare lo stato del flusso di lavoro.