Traduire des requêtes SQL avec l'API Translation

Ce document explique comment utiliser l'API Translation dans BigQuery pour traduire des scripts écrits dans d'autres dialectes SQL en requêtes GoogleSQL. L'API Translation peut simplifier le processus de migration des charges de travail vers BigQuery.

Avant de commencer

Avant d'envoyer une tâche de traduction, procédez comme suit :

  1. Assurez-vous de disposer des autorisations requises.
  2. Activez l'API BigQuery Migration.
  3. Collectez les fichiers sources contenant les scripts et les requêtes SQL à traduire.
  4. Importez les fichiers source dans Cloud Storage.

Autorisations requises

Pour obtenir les autorisations nécessaires pour créer des jobs de traduction à l'aide de l'API Translation, demandez à votre administrateur de vous accorder le rôle éditeur MigrationWorkflow (roles/bigquerymigration.editor) sur la ressource parent. Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient les autorisations requises pour créer des jobs de traduction à l'aide de l'API Translation. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Vous devez disposer des autorisations suivantes pour créer des jobs de traduction à l'aide de l'API Translation :

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

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Activer l'API BigQuery Migration

Si votre projet Google Cloud CLI a été créé avant le 15 février 2022, activez l'API BigQuery Migration comme suit :

  1. Dans la console Google Cloud, accédez à la page API BigQuery Migration.

    Accéder à l'API BigQuery Migration

  2. Cliquez sur Activer.

Importer des fichiers d'entrée dans Cloud Storage

Si vous souhaitez utiliser la console Google Cloud ou l'API BigQuery Migration pour effectuer une tâche de traduction, vous devez importer les fichiers sources contenant les requêtes et les scripts à traduire dans Cloud Storage. Vous pouvez également importer des fichiers de métadonnées ou des fichiers YAML de configuration dans le même bucket Cloud Storage contenant les fichiers sources. Pour en savoir plus sur la création de buckets et l'importation de fichiers dans Cloud Storage, consultez les pages Créer des buckets et Importer des objets à partir d'un système de fichiers.

Types de tâches compatibles

L'API Translation peut traduire les dialectes SQL suivants en langage GoogleSQL :

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

Emplacements

L'API Translation est disponible dans les emplacements de traitement suivants :

Description de la région Nom de la région Détail
Asie-Pacifique
Tokyo asia-northeast1
Mumbai asia-south1
Singapour asia-southeast1
Sydney australia-southeast1
Europe
UE (multirégional) eu
Varsovie europe-central2
Finlande europe-north1 Icône Feuille Faibles émissions de CO2
Madrid europe-southwest1 Icône Feuille Faibles émissions de CO2
Belgique europe-west1 Icône Feuille Faibles émissions de CO2
Londres europe-west2 icône feuille Faibles émissions de CO2
Francfort europe-west3 icône feuille Faibles émissions de CO2
Pays-Bas europe-west4 Icône Feuille Faibles émissions de CO2
Zurich europe-west6 Icône Feuille Faibles émissions de CO2
Paris europe-west9 Icône Feuille Faibles émissions de CO2
Turin europe-west12
Amériques
Québec northamerica-northeast1 Icône Feuille Faibles émissions de CO2
São Paulo southamerica-east1 Icône Feuille Faibles émissions de CO2
États-Unis (multirégional) us
Iowa us-central1 Icône Feuille Faibles émissions de CO2
Caroline du Sud us-east1
Virginie du Nord us-east4
Columbus, Ohio us-east5
Dallas us-south1 Icône Feuille Faibles émissions de CO2
Oregon us-west1 Icône Feuille Faibles émissions de CO2
Los Angeles us-west2
Salt Lake City us-west3

Envoyer une tâche de traduction

Pour envoyer une tâche de traduction à l'aide de l'API Translation, utilisez la méthode projects.locations.workflows.create et fournissez une instance de la ressource MigrationWorkflow avec un type de tâche compatible.

Une fois le job envoyé, vous pouvez envoyer une requête pour obtenir les résultats.

Créer une traduction par lot

La commande curl suivante crée un job de traduction par lot où les fichiers d'entrée et de sortie sont stockés dans Cloud Storage. Le champ source_target_mapping contient une liste qui mappe les entrées literal source avec un chemin d'accès relatif facultatif pour la sortie cible.

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

Remplacez les éléments suivants :

  • TYPE : type de tâche de la traduction, qui détermine les dialectes source et cible.
  • TARGET_BASE : URI de base pour toutes les sorties de traduction.
  • BASE : URI de base pour tous les fichiers lus en tant que sources pour la traduction.

  • TARGET_TYPES (facultatif): types de sortie générés. Si aucune valeur n'est spécifiée, du code SQL est généré.

    • sql (par défaut): fichiers de requêtes SQL traduits.
    • suggestion: suggestions générées par IA.

    La sortie est stockée dans un sous-dossier du répertoire de sortie. Le sous-dossier est nommé en fonction de la valeur de TARGET_TYPES.

  • TOKEN : jeton d'authentification. Pour générer un jeton, utilisez la commande gcloud auth print-access-token ou OAuth 2.0 Playground (utilisez le champ d'application https://www.googleapis.com/auth/cloud-platform).

  • PROJECT_ID : projet pour le traitement de la traduction.

  • LOCATION : emplacement dans lequel le job est traité.

La commande précédente renvoie une réponse incluant un ID de workflow écrit au format projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID.

Exemple de traduction par lot

Pour traduire les scripts SQL Teradata du répertoire Cloud Storage gs://my_data_bucket/teradata/input/ et stocker les résultats dans le répertoire Cloud Storage gs://my_data_bucket/teradata/output/, vous pouvez utiliser la requête suivante :

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

Cet appel renvoie un message contenant l'ID de workflow créé dans le champ "name" :

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

Pour obtenir l'état mis à jour du workflow, exécutez une requête GET. La tâche envoie des sorties vers Cloud Storage au fur et à mesure de son exécution. La tâche state passe à COMPLETED une fois que tous les target_types demandés sont générés. Si la tâche aboutit, vous trouverez la requête SQL traduite dans gs://my_data_bucket/teradata/output.

Exemple de traduction par lot avec suggestions d'IA

L'exemple suivant traduit les scripts SQL Teradata situés dans le répertoire Cloud Storage gs://my_data_bucket/teradata/input/ et stocke les résultats dans le répertoire Cloud Storage gs://my_data_bucket/teradata/output/ avec une suggestion d'IA supplémentaire:

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

Une fois la tâche exécutée, les suggestions d'IA se trouvent dans le répertoire Cloud Storage gs://my_data_bucket/teradata/output/suggestion.

Créer un job de traduction interactive avec des entrées et des sorties de littéraux de chaîne

La commande curl suivante crée un job de traduction avec des littéraux de chaîne comme entrées et sorties. Le champ source_target_mapping contient une liste qui mappe les répertoires sources sur un chemin d'accès relatif facultatif pour la sortie cible.

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

Remplacez les éléments suivants :

  • TYPE : type de tâche de la traduction, qui détermine les dialectes source et cible.
  • PATH : identifiant de l'entrée littérale, semblable à un nom de fichier ou un chemin d'accès.
  • STRING : chaîne de données d'entrée littérale (par exemple, SQL) à traduire.
  • TARGETS : cibles attendues que l'utilisateur souhaite renvoyer directement dans la réponse au format literal. Celles-ci doivent être au format d'URI cible (par exemple, GENERATED_DIR + target_spec.relative_path + source_spec.literal.relative_path). Tout élément qui ne figure pas dans cette liste ne sera pas renvoyé dans la réponse. Le répertoire généré, GENERATED_DIR, pour les traductions SQL générales est sql/.
  • TOKEN : jeton d'authentification. Pour générer un jeton, utilisez la commande gcloud auth print-access-token ou OAuth 2.0 Playground (utilisez le champ d'application https://www.googleapis.com/auth/cloud-platform).
  • PROJECT_ID : projet pour le traitement de la traduction.
  • LOCATION : emplacement dans lequel le job est traité.

La commande précédente renvoie une réponse incluant un ID de workflow écrit au format projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID.

Une fois le job terminé, vous pouvez afficher les résultats en interrogeant le job et en examinant le champ translation_literals intégré dans la réponse une fois le workflow terminé.

Exemple de traduction interactive

Pour traduire la chaîne SQL Hive select 1 de manière interactive, vous pouvez utiliser la requête suivante :

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

Vous pouvez utiliser n'importe quel relative_path pour votre littéral, mais le littéral traduit n'apparaîtra dans les résultats que si vous incluez sql/$relative_path dans target_return_literals. Vous pouvez également inclure plusieurs littéraux dans une seule requête. Dans ce cas, chacun de leurs chemins relatifs doit être inclus dans target_return_literals.

Cet appel renvoie un message contenant l'ID de workflow créé dans le champ "name" :

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

Pour obtenir l'état mis à jour du workflow, exécutez une requête GET. Le job est terminé lorsque "state" est remplacé par COMPLETED. Si la tâche aboutit, le code SQL traduit s'affiche dans le message de réponse :

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

Explorer le résultat de la traduction

Après avoir exécuté la tâche de traduction, récupérez les résultats en spécifiant l'ID du workflow de traduction à l'aide de la commande suivante :

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

Remplacez les éléments suivants :

  • TOKEN : jeton d'authentification. Pour générer un jeton, utilisez la commande gcloud auth print-access-token ou OAuth 2.0 Playground (utilisez le champ d'application https://www.googleapis.com/auth/cloud-platform).
  • PROJECT_ID : projet pour le traitement de la traduction.
  • LOCATION : emplacement dans lequel le job est traité.
  • WORKFLOW_ID : ID généré lors de la création d'un workflow de traduction.

La réponse contient l'état de votre workflow de migration et tous les fichiers terminés dans target_return_literals.

La réponse contient l'état de votre workflow de migration et tous les fichiers terminés dans target_return_literals. Vous pouvez interroger ce point de terminaison pour vérifier l'état de votre workflow.