使用转换 API 来转换 SQL 查询

本文档介绍了如何使用 BigQuery 中的转换 API 将用其他 SQL 方言编写的脚本转换为 GoogleSQL 查询。 Translation API 可以简化将工作负载迁移到 BigQuery 的过程。

准备工作

在提交转换作业之前，请完成以下步骤：

确保您拥有所需的所有权限。
启用 BigQuery Migration API。
收集包含待转换的 SQL 脚本和查询的源文件。
将源文件上传到 Cloud Storage。

所需权限

如需获得使用转换 API 创建转换作业所需的权限，请让您的管理员为您授予 parent 资源的 MigrationWorkflow Editor (roles/bigquerymigration.editor) IAM 角色。如需详细了解如何授予角色，请参阅管理访问权限。

此预定义角色可提供使用转换 API 创建转换作业所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

使用转换 API 创建转换作业需要以下权限：

bigquerymigration.workflows.create
bigquerymigration.workflows.get

您也可以使用自定义角色或其他预定义角色来获取这些权限。

启用 BigQuery Migration API

如果您的 Google Cloud CLI 项目是在 2022 年 2 月 15 日之前创建的，请按如下方式启用 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，请参阅创建存储桶，以及从文件系统上传对象。

支持的任务类型

转换 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`
	华沙	`europe-central2`
	芬兰	`europe-north1`	二氧化碳排放量低
	马德里	`europe-southwest1`	二氧化碳排放量低
	比利时	`europe-west1`	二氧化碳排放量低
	伦敦	`europe-west2`	二氧化碳排放量低
	法兰克福	`europe-west3`	二氧化碳排放量低
	荷兰	`europe-west4`	二氧化碳排放量低
	苏黎世	`europe-west6`	二氧化碳排放量低
	巴黎	`europe-west9`	二氧化碳排放量低
	都灵	`europe-west12`
美洲
	圣保罗	`southamerica-east1`	二氧化碳排放量低
	美国多区域	`us`
	爱荷华	`us-central1`	二氧化碳排放量低
	南卡罗来纳	`us-east1`
	北弗吉尼亚	`us-east4`
	俄亥俄州，哥伦布	`us-east5`
	达拉斯	`us-south1`	二氧化碳排放量低
	俄勒冈	`us-west1`	二氧化碳排放量低
	洛杉矶	`us-west2`
	盐湖城	`us-west3`

提交转换作业

如需使用转换 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 Playground（使用范围 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 Playground（使用范围 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 Playground（使用范围 https://www.googleapis.com/auth/cloud-platform）。
PROJECT_ID：处理转换的项目。
LOCATION：处理作业的位置。
WORKFLOW_ID：创建转换工作流时生成的 ID。