Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

使用 Translation API 翻譯 SQL 查詢

本文說明如何在 BigQuery 中使用 BigQuery Migration API，將以其他 SQL 方言編寫的指令碼翻譯成 GoogleSQL 查詢。

如需這項 SQL 轉譯器支援的 SQL 方言清單，以及支援的處理位置清單，請參閱「支援的 SQL 方言」和「位置」。

事前準備

提交翻譯工作前，請先完成下列步驟。

選擇翻譯模式

BigQuery Migration API 支援兩種翻譯模式。這兩種模式都使用相同的 API 方法，並以非同步工作形式執行。這兩種模式的差異在於提供來源 SQL 的方式，以及接收翻譯後 SQL 的方式：

批次翻譯：API 會從 Cloud Storage 讀取來源檔案，並將翻譯檔案和報告寫入 Cloud Storage。使用批次翻譯功能一次翻譯多個檔案，例如遷移整個程式碼集時。
互動式翻譯：您可以在要求主體中以字串常值形式傳遞 SQL，並從工作流程回應中讀取翻譯後的 SQL。您不需要將 SQL 或翻譯輸出內容儲存在 Cloud Storage。視需要使用互動式翻譯功能翻譯個別查詢，例如翻譯應用程式或開發人員工具中的查詢。

啟用翻譯

啟用必要的 BigQuery Migration API。詳情請參閱「啟用 SQL 翻譯」。

所需權限

如要取得使用互動式翻譯器、Translation API 或批次 SQL 翻譯器建立翻譯工作所需的權限，請要求管理員授予您 parent 資源的下列 IAM 角色：

查看及監控遷移工作： MigrationWorkflow 檢視者 (roles/bigquerymigration.viewer)
提交遷移工作： MigrationWorkflow 編輯者 (roles/bigquerymigration.editor)
存取輸入和檔案的 Cloud Storage bucket：來源和目的地 Cloud Storage bucket 的「Storage Object Admin」(roles/storage.objectAdmin)。

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這些預先定義的角色具備使用互動式翻譯器、Translation API 或批次 SQL 翻譯器建立翻譯工作所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要使用互動式翻譯器、Translation API 或批次 SQL 翻譯器建立翻譯工作，必須具備下列權限：

bigquerymigration.workflows.create
bigquerymigration.workflows.get
bigquerymigration.workflows.list
bigquerymigration.workflows.delete
bigquerymigration.subtasks.get
bigquerymigration.subtasks.list
storage.objects.get
storage.objects.list
storage.objects.create

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

將輸入檔案上傳至 Cloud Storage

如要執行批次翻譯工作，請務必將含有要翻譯查詢和指令碼的來源檔案上傳至 Cloud Storage。您也可以將任何中繼資料檔案或設定 YAML 檔案上傳至包含來源檔案的相同 Cloud Storage bucket。

如要進一步瞭解如何建立 bucket 並將檔案上傳至 Cloud Storage，請參閱「建立 bucket」和「從檔案系統上傳物件」。

不支援的 SQL 函式

如果來源查詢參照的 SQL 函式在 GoogleSQL 中沒有直接對應項目，可以使用輔助使用者定義函式 (UDF)。詳情請參閱「使用輔助 UDF 處理不支援的 SQL 函式」。

提交翻譯工作

如要使用 BigQuery Migration API 提交翻譯工作，請使用 projects.locations.workflows.create 方法，並提供 MigrationWorkflow 資源的例項和支援的工作類型。

提交工作後，您可以輪詢工作狀態。

建立批次翻譯作業

下列 curl 指令會建立批次翻譯工作，輸入和輸出檔案都儲存在 Cloud Storage 中。source_target_mapping 欄位包含清單，可將來源目錄對應至目標輸出的選用相對路徑。

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/v2/projects/PROJECT_ID/locations/LOCATION/workflows

更改下列內容：

TYPE：翻譯的工作類型，決定來源和目標方言。
TARGET_BASE：所有翻譯輸出內容的基礎 URI。
BASE：做為翻譯來源讀取的所有檔案的基本 URI。
TARGET_TYPES (選用)：生成的輸出類型。如未指定，系統會產生 SQL。
- sql (預設)：翻譯後的 SQL 查詢檔案。
- suggestion：AI 生成的建議。
輸出內容會儲存在輸出目錄的子資料夾中。子資料夾的名稱會根據 TARGET_TYPES 中的值而定。
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。

批次翻譯範例

如要翻譯 Cloud Storage 目錄 gs://my_data_bucket/teradata/input/ 中的 Teradata SQL 指令碼，並將結果儲存在 Cloud Storage 目錄 gs://my_data_bucket/teradata/output/ 中，您可以使用下列查詢：

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

這項呼叫會傳回訊息，其中包含 "name" 欄位中建立的工作流程 ID：

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

如要取得工作流程的最新狀態，請執行 GET 查詢。作業會隨著進度將輸出內容傳送至 Cloud Storage。所有要求的 target_types 生成後，工作會變更為 stateCOMPLETED。如果作業成功，您可以在 gs://my_data_bucket/teradata/output 中找到翻譯後的 SQL 查詢。

使用 AI 建議進行批次翻譯的範例

以下範例會翻譯 gs://my_data_bucket/teradata/input/ Cloud Storage 目錄中的 Teradata SQL 指令碼，並將結果儲存在 gs://my_data_bucket/teradata/output/ Cloud Storage 目錄中，同時提供額外的 AI 建議：

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

工作順利執行後，您可以在 gs://my_data_bucket/teradata/output/suggestion Cloud Storage 目錄中找到 AI 建議。

建立互動式翻譯

下列 curl 指令會建立互動式翻譯工作，並使用字串常值做為輸入和輸出。source_target_mapping 欄位包含一份清單，可將來源 literal 項目對應至目標輸出的選用相對路徑。

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/v2/projects/PROJECT_ID/locations/LOCATION/workflows

更改下列內容：

TYPE：翻譯的工作類型，決定來源和目標方言。
PATH：字面值項目的 ID，類似於檔案名稱或路徑。
STRING：要翻譯的字串，可以是輸入資料 (例如 SQL)。
TARGETS：使用者希望以 literal 格式直接在回應中傳回的預期目標。這些應採用目標 URI 格式 (例如 GENERATED_DIR + target_spec.relative_path + source_spec.literal.relative_path)。如果不在這個清單中，就不會傳回回應。產生的目錄 (一般 SQL 翻譯) 為 GENERATED_DIRsql/。
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。

建立工作流程後，請檢查工作狀態，查看結果。

互動式翻譯範例

如要以互動方式翻譯 Apache Hive SQL 字串 select 1，可以使用下列查詢：

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

您可以在字面值中使用任何 relative_path，但只有在 target_return_literals 中加入 sql/$relative_path，翻譯後的字面值才會顯示在結果中。您也可以在單一查詢中加入多個常值，但必須在 target_return_literals 中加入每個常值的相對路徑。

這項呼叫會傳回訊息，其中包含 "name" 欄位中建立的工作流程 ID：

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

如要取得工作流程的最新狀態，請查看工作狀態。當 "state" 變更為 COMPLETED 時，工作即完成。如果工作成功，您會在回應訊息中看到翻譯後的 SQL：

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

檢查工作狀態

翻譯工作會以非同步方式執行。提交工作流程後，請傳送包含工作流程 ID 的 GET 要求，以擷取工作流程狀態：

curl \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer TOKEN" \
  -X GET https://bigquerymigration.googleapis.com/v2/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。

工作流程狀態

回覆包含 state 欄位，指出工作流程的目前狀態：

STATE_UNSPECIFIED：工作流程狀態未指定。
RUNNING：工作流程正在執行中。定期輪詢端點，直到狀態變更為止。
PAUSED：工作流程已暫停。
COMPLETED：工作流程順利完成。您現在可以擷取結果。
FAILED：工作流程發生錯誤。檢查回應中的 taskResult 和 reportLogMessages 欄位，瞭解錯誤詳細資料。

工作流程 state 達到 COMPLETED 或 FAILED 時，您可以停止輪詢。

擷取結果

結果的擷取方式取決於您提交的是批次翻譯或互動式翻譯：

批次翻譯：翻譯檔案、摘要報告和任何 AI 建議都會寫入您在 target_base_uri 中指定的 Cloud Storage 目的地目錄。您可以使用 gcloud CLI 儲存空間指令、Cloud Storage 用戶端程式庫或 REST API，直接從 Cloud Storage 讀取這些檔案：
```
gcloud storage cp --recursive TARGET_URI LOCAL_DIRECTORY
```
更改下列內容：
- TARGET_URI：目標基準 URI，例如 gs://my_data_bucket/teradata/output/。
- LOCAL_DIRECTORY：接收檔案的本機目錄。
如要進一步瞭解目的地值區中產生的檔案，請參閱「探索翻譯輸出內容」。
互動式翻譯：如果工作是使用字串常值輸入內容和 target_return_literals 設定，翻譯後的查詢會直接在工作流程回應的 translatedLiterals 欄位中傳回：
```
"taskResult": {
  "translationTaskResult": {
    "translatedLiterals": [
      {
        "relativePath": "sql/input_file",
        "literalString": "SELECT 1;\n"
      }
    ]
  }
}
```
針對 translatedLiterals 中的每個項目擷取 literalString 欄位，取得翻譯後的查詢。