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

使用 Translation API 翻譯 SQL 查詢

本文檔介紹如何使用 BigQuery 中的翻譯 API 將用其他 SQL 方言編寫的腳本翻譯成 GoogleSQL 查詢。翻譯 API 可簡化將工作負載遷移至 BigQuery 的程序。

如要查看這項 SQL 翻譯工具支援的 SQL 方言清單，以及支援的處理位置清單，請參閱「支援的 SQL 方言」和「位置」。

事前準備

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

啟用翻譯

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

所需權限

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

查看及監控遷移工作： MigrationWorkflow 檢視者 (roles/bigquerymigration.viewer)
提交遷移工作： MigrationWorkflow 編輯者 (roles/bigquerymigration.editor)
存取輸入和檔案的 Cloud Storage 值區：儲存空間物件管理員 (roles/storage.objectAdmin) - 來源和目標 Cloud Storage 值區。

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

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

所需權限

若要使用互動式翻譯器、翻譯 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

如果您想使用 Google Cloud 控制台或 BigQuery 遷移 API 來執行翻譯作業，則必須將包含要翻譯的查詢和腳本的來源檔案上傳到雲端儲存。您也可以將任何元資料檔案或設定 YAML 檔案上傳到包含來源檔案的同一個 Cloud Storage bucket 中。如要進一步瞭解如何建立值區，以及將檔案上傳至 Cloud Storage，請參閱「建立值區」和「從檔案系統上傳物件」。

使用輔助 UDF 處理不支援的 SQL 函式

將 SQL 從來源方言轉譯為 BigQuery 時，部分函式可能沒有直接對應的函式。為解決這個問題，BigQuery 遷移服務 (和更廣泛的 BigQuery 社群) 提供輔助使用者定義函式 (UDF)，可複製這些不支援的來源方言函式行為。

這些 UDF 通常位於 bqutil 公開資料集中，因此翻譯後的查詢一開始可以採用 bqutil.<dataset>.<function>() 格式參照這些 UDF。例如：bqutil.fn.cw_count()。

正式環境的重要注意事項

雖然 bqutil 可讓您輕鬆存取這些輔助 UDF，進行初步翻譯和測試，但基於下列原因，不建議直接依賴 bqutil 處理實際工作負載：

版本管控：bqutil 專案會代管這些 UDF 的最新版本，因此定義可能會隨時間變更。如果 UDF 的邏輯更新，直接依賴 bqutil 可能會導致生產查詢發生非預期行為或重大變更。
依附元件隔離：將 UDF 部署至自己的專案，可避免外部變更影響正式環境。
自訂：您可能需要修改或最佳化這些 UDF，進一步滿足特定商業邏輯或效能需求。只有在這些資源位於您的專案中時，才能執行這項操作。
安全性和治理：貴機構的安全政策可能會限制直接存取公開資料集 (例如 bqutil)，以處理正式環境資料。將 UDF 複製到受控環境，符合這類政策規定。

將輔助 UDF 部署至專案

如要穩定可靠地用於正式環境，請將這些輔助 UDF 部署到自己的專案和資料集。這樣一來，您就能完全掌控這些模型的版本、自訂項目和存取權。如需部署這些 UDF 的詳細操作說明，請參閱 GitHub 上的 UDF 部署指南。本指南提供必要的指令碼和步驟，可將 UDF 複製到您的環境。

提交翻譯工作

若要使用翻譯 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\"
              }
            },
            \"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

更改下列內容：

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: 處理作業的 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",
       }
    }
  }
}

任務成功運行後，AI 建議可以在 gs://my_data_bucket/teradata/output/suggestion 雲端儲存目錄中找到。

建立一個互動式翻譯任務，輸入和輸出均為字串字面量。

下列 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：常值項目的 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。

工作完成後，您可以查詢工作，並在工作流程完成後檢查回應中的 translation_literals 內嵌欄位，即可查看結果。

互動式翻譯範例

如要以互動方式翻譯 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"
}

如要取得工作流程的最新狀態，請執行 GET 查詢。當 "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，以擷取結果：

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。

回應中包含您的遷移工作流程的狀態，以及 target_return_literals 中任何已完成的檔案。

回應會包含遷移工作流程的狀態，以及 target_return_literals 中所有已完成的檔案。您可以輪詢此端點以檢查工作流程狀態。