Translation API を使用して SQL クエリを変換する

このドキュメントでは、BigQuery で Translation API を使用して、他の SQL 言語で作成されたスクリプトを GoogleSQL クエリに変換する方法について説明します。Translation API を使用すると、ワークロードを BigQuery に移行するプロセスを簡素化できます。

始める前に

変換ジョブを送信する前に、次の手順を行います。

必要な権限がすべて付与されていることを確認します。
BigQuery Migration API を有効にします。
変換対象の SQL スクリプトとクエリが含まれるソースファイルを収集します。
ソースファイルを Cloud Storage にアップロードします。

必要な権限

Translation API を使用して変換ジョブを作成するために必要な権限を取得するには、parent リソースに対する MigrationWorkflow 編集者（roles/bigquerymigration.editor）IAM ロールを付与するよう管理者に依頼してください。ロールの付与の詳細については、アクセス権の管理をご覧ください。

この事前定義ロールには、Translation API を使用して変換ジョブを作成するために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

Translation API を使用して変換ジョブを作成するには、次の権限が必要です。

bigquerymigration.workflows.create
bigquerymigration.workflows.get

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

BigQuery Migration API を有効にする

2022 年 2 月 15 日より前に Google Cloud CLI プロジェクトを作成した場合、次のように BigQuery Migration API を有効にします。

Google Cloud コンソールで、[BigQuery Migration API] ページに移動します。

BigQuery Migration API に移動
[有効にする] をクリックします。

入力ファイルを Cloud Storage にアップロードする

Google Cloud コンソールまたは BigQuery Migration API を使用して変換ジョブを実行する場合は、変換するクエリとスクリプトを含むソースファイルを Cloud Storage にアップロードする必要があります。任意のメタデータファイルまたは構成 YAML ファイルを、ソースファイルが含まれている Cloud Storage バケットにアップロードすることもできます。バケットの作成と Cloud Storage へのファイルのアップロードの詳細については、バケットの作成とファイルシステムからオブジェクトのアップロードをご覧ください。

サポートされているタスクの種類

Translation API によって、次の SQL 言語を GoogleSQL に変換できます。

Amazon Redshift SQL - Redshift2BigQuery_Translation
Apache HiveQL と Beeline CLI - 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 と NZPLSQL - Netezza2BigQuery_Translation
MySQL SQL - MySQL2BigQuery_Translation
Oracle SQL、PL/SQL、Exadata - Oracle2BigQuery_Translation
PostgreSQL SQL - Postgresql2BigQuery_Translation
Presto または Trino SQL - Presto2BigQuery_Translation
Snowflake SQL - Snowflake2BigQuery_Translation
SQLite - SQLite2BigQuery_Translation
SQL Server T-SQL - SQLServer2BigQuery_Translation
Teradata と Teradata Vantage - Teradata2BigQuery_Translation
Vertica SQL - Vertica2BigQuery_Translation

ロケーション

Translation API は、次の処理ロケーションで使用できます。

	リージョンの説明	リージョン名	詳細
アジア太平洋
	東京	`asia-northeast1`
	ムンバイ	`asia-south1`
	シンガポール	`asia-southeast1`
	シドニー	`australia-southeast1`
ヨーロッパ
	EU（マルチリージョン）	`eu`
	ワルシャワ	`europe-central2`
	フィンランド	`europe-north1`	低 CO₂
	マドリッド	`europe-southwest1`	低 CO₂
	ベルギー	`europe-west1`	低 CO₂
	ロンドン	`europe-west2`	低 CO₂
	フランクフルト	`europe-west3`	低 CO₂
	オランダ	`europe-west4`	低 CO₂
	チューリッヒ	`europe-west6`	低 CO₂
	パリ	`europe-west9`	低 CO₂
	トリノ	`europe-west12`
南北アメリカ
	サンパウロ	`southamerica-east1`	低 CO₂
	米国（マルチリージョン）	`us`
	アイオワ	`us-central1`	低 CO₂
	サウスカロライナ	`us-east1`
	北バージニア	`us-east4`
	コロンバス（オハイオ州）	`us-east5`
	ダラス	`us-south1`	低 CO₂
	オレゴン	`us-west1`	低 CO₂
	ロサンゼルス	`us-west2`
	ソルトレイクシティ	`us-west3`

変換ジョブを送信する

Translation API を使用して変換ジョブを送信するには、projects.locations.workflows.create メソッドを使用して、サポートされているタスクの種類の MigrationWorkflow リソースのインスタンスを指定します。

例: 一括変換を作成する

次の curl コマンドは、入力ファイルと出力ファイルが Cloud Storage に保存されるバッチ変換ジョブを作成します。source_target_mapping フィールドには、ソースの literal エントリをターゲット出力の任意の相対パスにマッピングするリストが含まれています。

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

次のように置き換えます。

TYPE: 変換のタスクの種類。これにより、ソースとターゲットの言語が決まります。
TARGET_BASE: すべての変換出力のベース URI。
BASE: 変換元として読み取られるすべてのファイルのベース URI。
TOKEN: 認証用のトークン。トークンを生成するには、gcloud auth print-access-token コマンドまたは OAuth 2.0 プレイグラウンド（スコープは https://www.googleapis.com/auth/cloud-platform）を使用します。
PROJECT_ID: 変換を処理するプロジェクト。
LOCATION: ジョブが処理されるロケーション。

前述のコマンドは、projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID 形式で記述されたワークフロー ID を含むレスポンスを返します。

例: 文字列リテラルの入力と出力を使用してインタラクティブな変換ジョブを作成する

次の curl コマンドは、文字列リテラルの入出力を持つ変換ジョブを作成します。source_target_mapping フィールドには、ソースディレクトリをターゲット出力の相対パス（省略可）にマッピングするリストが含まれます。

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

次のように置き換えます。

TYPE: 変換のタスクの種類。これにより、ソースとターゲットの言語が決まります。
PATH: ファイル名またはパスに類似したリテラルエントリの識別子。
STRING: 変換するリテラル入力データの文字列（SQL など）。
TARGETS: ユーザーがレスポンスで直接返すことを期待しているターゲット（literal 形式）。これらはターゲット URI 形式（例: GENERATED_DIR + target_spec.relative_path + source_spec.literal.relative_path）にする必要があります。このリストにないものはレスポンスで返されません。一般的な SQL 変換用に生成されるディレクトリ GENERATED_DIR は sql/ です。
TOKEN: 認証用のトークン。トークンを生成するには、gcloud auth print-access-token コマンドまたは OAuth 2.0 プレイグラウンド（スコープは https://www.googleapis.com/auth/cloud-platform）を使用します。
PROJECT_ID: 変換を処理するプロジェクト。
LOCATION: ジョブが処理されるロケーション。

前述のコマンドは、projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID 形式で記述されたワークフロー ID を含むレスポンスを返します。

変換出力を確認する

変換ジョブの実行後、次のコマンドを使用して変換ジョブワークフロー ID を指定して結果を取得します。

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

次のように置き換えます。

TOKEN: 認証用のトークン。トークンを生成するには、gcloud auth print-access-token コマンドまたは OAuth 2.0 プレイグラウンド（スコープは https://www.googleapis.com/auth/cloud-platform）を使用します。
PROJECT_ID: 変換を処理するプロジェクト。
LOCATION: ジョブが処理されるロケーション。
WORKFLOW_ID: 変換ワークフローの作成時に生成された ID。