遠端函式和 Translation API 教學課程

您可以將 BigQuery 遠端函式與 Cloud Translation API 結合，直接使用 SQL 和 Python 翻譯任何語言的內容。在 BigQuery 中翻譯資料，即可翻譯網站使用者留言，或將多語言支援要求整合為案件工作人員使用的通用語言。

目標

• 將必要角色指派給帳戶。
• 建立 Cloud Run functions 函式。
• 建立 BigQuery 資料集。
• 建立 BigQuery 連線和服務帳戶。
• 將權限授予 BigQuery 服務帳戶。
• 建立 BigQuery 遠端函式。
• 呼叫 BigQuery 遠端函式。

費用

在本文件中，您會使用下列 Google Cloud計費元件：

• BigQuery
• Cloud Run functions
• Cloud Translation

您可以使用 Pricing Calculator，根據預測用量估算費用。

初次使用 Google Cloud 的使用者可能符合免費試用期資格。

事前準備

建議您為本教學課程建立 Google Cloud 專案。此外，請確認您具備完成本教學課程所需的角色。

設定 Google Cloud 專案

如要為本教學課程設定 Google Cloud 專案，請完成下列步驟：

登入 Google Cloud 帳戶。如果您未曾使用過 Google Cloud，歡迎 建立帳戶，親自體驗實際使用我們產品的成效。新客戶還能獲得價值 $300 美元的免費抵免額，用於執行、測試及部署工作負載。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery, BigQuery Connection, Cloud Translation, Cloud Run functions, Cloud Build, Cloud Logging, Cloud Pub/Sub, Artifact Registry, and Cloud Run Admin APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery, BigQuery Connection, Cloud Translation, Cloud Run functions, Cloud Build, Cloud Logging, Cloud Pub/Sub, Artifact Registry, and Cloud Run Admin APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

帳戶必要角色

如要取得執行本教學課程工作所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

• BigQuery 資料擁有者 (roles/bigquery.dataOwner)
• BigQuery 連線管理員 (roles/bigquery.connectionAdmin)
• Cloud Functions 開發人員 (roles/cloudfunctions.developer)

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

這些預先定義的角色具備執行本教學課程中各項工作所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

您必須具備下列權限，才能執行本教學課程中的工作：

• bigquery.datasets.create
• bigquery.connections.create
• bigquery.connections.get
• cloudfunctions.functions.create

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

Compute Engine 預設服務帳戶的必要角色

啟用 Cloud Run functions 的 API 時，系統會建立 Compute Engine 預設服務帳戶。如要完成本教學課程，您必須將 Cloud Translation API 使用者角色授予這個預設服務帳戶。

1. 取得指派給專案的 ID。

2. 複製 Compute Engine 預設服務帳戶。預設服務帳戶應如下所示：

   [e-mail]
   

   將 PROJECT_NUMBER 替換為專案 ID。

3. 前往 Google Cloud 控制台的「IAM」(身分與存取權管理) 頁面。

   前往「IAM」頁面

4. 選取專案。

5. 按一下「 授予存取權」，然後在「新增主體」欄位中，貼上先前複製的 Compute Engine 預設服務帳戶。

6. 在「Assign roles」(指派角色) 清單中，搜尋並選取「Cloud Translation API User」(Cloud Translation API 使用者)。

7. 按一下 [儲存]。

建立 Cloud Run 函式

使用 Cloud Run functions 建立函式，將輸入文字翻譯成西班牙文。

1. 建立 Cloud Run functions 函式，並採用下列規格：

   • 在「Environment」(環境) 中選取「2nd gen」(第 2 代)。
   • 在「Function name」(函式名稱) 中輸入 translation-handler。
   • 在「Region」(區域) 中，選取「us-central1」。

   • 在「Maximum number of instances」(執行個體數量上限) 中輸入 10。

     這項設定位於「Runtime, build, connections and security settings」(執行階段、建構作業、連線和安全性設定) 專區。

     在本教學課程中，我們使用的值低於預設值，以控制傳送至 Translation 的要求比率。

   • 在「執行階段」部分，選取「Python 3.10」。

   • 在「Entry point」(進入點) 中輸入 handle_translation。

2. 在檔案清單中選取 main.py，然後貼上下列程式碼。

   在試用這個範例之前，請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Python 設定操作說明進行操作。詳情請參閱 BigQuery Python API 參考文件。

   如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

   from __future__ import annotations
   
   
   import flask
   import functions_framework
   from google.api_core.retry import Retry
   from google.cloud import translate
   
   # Construct a Translation Client object
   translate_client = translate.TranslationServiceClient()
   
   
   # Register an HTTP function with the Functions Framework
   @functions_framework.http
   def handle_translation(request: flask.Request) -> flask.Response:
       """BigQuery remote function to translate input text.
   
       Args:
           request: HTTP request from BigQuery
           https://cloud.google.com/bigquery/docs/reference/standard-sql/remote-functions#input_format
   
       Returns:
           HTTP response to BigQuery
           https://cloud.google.com/bigquery/docs/reference/standard-sql/remote-functions#output_format
       """
       try:
           # Parse request data as JSON
           request_json = request.get_json()
           # Get the project of the query
           caller = request_json["caller"]
           project = extract_project_from_caller(caller)
           if project is None:
               return flask.make_response(
                   flask.jsonify(
                       {
                           "errorMessage": (
                               'project can\'t be extracted from "caller":' f" {caller}."
                           )
                       }
                   ),
                   400,
               )
           # Get the target language code, default is Spanish ("es")
           context = request_json.get("userDefinedContext", {})
           target = context.get("target_language", "es")
   
           calls = request_json["calls"]
           translated = translate_text([call[0] for call in calls], project, target)
   
           return flask.jsonify({"replies": translated})
       except Exception as err:
           return flask.make_response(
               flask.jsonify({"errorMessage": f"Unexpected error {type(err)}:{err}"}),
               400,
           )
   
   
   def extract_project_from_caller(job: str) -> str:
       """Extract project id from full resource name of a BigQuery job.
   
       Args:
           job: full resource name of a BigQuery job, like
             "//bigquery.googleapi.com/projects/<project>/jobs/<job_id>"
   
       Returns:
           project id which is contained in the full resource name of the job.
       """
       path = job.split("/")
       return path[4] if len(path) > 4 else None
   
   
   def translate_text(
       calls: list[str], project: str, target_language_code: str
   ) -> list[str]:
       """Translates the input text to specified language using Translation API.
   
       Args:
           calls: a list of input text to translate.
           project: the project where the translate service will be used.
           target_language_code: The ISO-639 language code to use for translation
             of the input text. See
             https://cloud.google.com/translate/docs/advanced/discovering-supported-languages-v3#supported-target
               for the supported language list.
   
       Returns:
           a list of translated text.
       """
       location = "<your location>"
       parent = f"projects/{project}/locations/{location}"
       # Call the Translation API, passing a list of values and the target language
       response = translate_client.translate_text(
           request={
               "parent": parent,
               "contents": calls,
               "target_language_code": target_language_code,
               "mime_type": "text/plain",
           },
           retry=Retry(),
       )
       # Convert the translated value to a list and return it
       return [translation.translated_text for translation in response.translations]
   
   

   將 <your location> 更新為 us-central1。

3. 在檔案清單中選取「requirements.txt」requirements.txt，然後貼上下列文字：

   Flask==3.1.3; python_version >= '3.9'
   functions-framework==3.9.2
   google-cloud-translate==3.18.0
   Werkzeug==3.1.9; python_version >= '3.10'
   

4. 按一下「部署」，等待函式部署完成。

5. 按一下「Trigger」(觸發條件) 分頁標籤。

6. 複製「Trigger URL」值並儲存，稍後會用到。建立 BigQuery 遠端函式時，必須使用這個網址。

建立 BigQuery 資料集

建立 BigQuery 資料集，用於存放遠端函式。建立資料集時，請加入下列規格：

• 在「Dataset ID」(資料集 ID) 中輸入 remote_function_test。
• 在「位置類型」部分，選取「多區域」。
• 在「多區域」部分，選取「美國 (多個美國地區)」。

建立 BigQuery 連線和服務帳戶

建立 BigQuery 連線，以便在 Cloud Run functions 和 Cloud Run 中，使用任何支援的語言實作遠端函式。建立連線時，系統會為該連線建立服務帳戶。

1. 建立 Google Cloud 資源連線，規格如下：

   • 在「連線類型」部分，選取「BigLake 與遠端函式 (Cloud 資源)」。
   • 在「Connection ID」部分輸入 remote-function-connection。
   • 在「位置類型」部分，選取「多區域」。
   • 在「多區域」部分，選取「美國 (多個美國地區)」。

2. 開啟「Connections」(連線) 清單 ，然後選取「us.remote-function-connection」。

3. 複製服務帳戶 ID 並儲存，供稍後使用。您必須在下一個步驟中，將權限授予這個 ID。

將權限授予 BigQuery 服務帳戶

您在上一個步驟中建立的服務帳戶需要使用 Cloud Run 的權限，BigQuery 遠端函式才能使用 Cloud Run functions 函式。如要將權限授予服務帳戶，請完成下列步驟：

1. 前往「Cloud Run」頁面。

   前往 Cloud Run。

2. 選取專案。

3. 勾選「translation-handler」旁的核取方塊。

4. 在「Permissions」(權限) 面板中，按一下「Add principal」(新增主體)。

5. 在「新增主體」欄位，輸入先前複製的服務帳戶 ID。

6. 在「Assign roles」(指派角色) 清單中，搜尋並選取「Cloud Run Invoker」。

7. 按一下 [儲存]。

注意： 新權限最多可能需要一分鐘才會生效。

建立 BigQuery 遠端函式

如要透過 BigQuery 遠端函式，使用將文字翻譯成西班牙文的 Cloud Run 函式，請完成下列步驟。

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往「BigQuery」

2. 在查詢編輯器中輸入下列查詢：

   CREATE OR REPLACE FUNCTION `remote_function_test.translate_text`(x STRING)
   RETURNS
   STRING
       REMOTE WITH CONNECTION `us.remote-function-connection`
   OPTIONS (
       endpoint = 'TRIGGER_URL',
       max_batching_rows = 10);
   

   將 TRIGGER_URL 替換成您先前建立 Cloud Run 函式時儲存的觸發條件網址。

3. 按一下「執行」。系統會顯示類似下列內容的訊息：

   This statement created a new function named
   your_project.remote_function_test.translate_text.
   

注意： 為限制 HTTP 要求中包含的資料列數量，max_batching_rows 選項會設為 10。如未指定 max_batching_rows 選項，BigQuery 會決定 HTTP 要求中包含的資料列數量。

呼叫 BigQuery 遠端函式

建立遠端函式後，請測試該函式，確認已連結至 Cloud Run functions 函式，並產生預期的西班牙文結果。

1. 在 BigQuery 查詢編輯器中輸入下列查詢，然後點選「Run」(執行)。

   SELECT
     remote_function_test.translate_text('This new feature is fantastic!')
       AS translated_text;
   

   結果大致如下：

   +-------------------------------------------+
   | translated_text                           |
   +-------------------------------------------+
   | ¡Esta nueva característica es fantástica! |
   +-------------------------------------------+
   

2. 選用：如要在公開資料集測試遠端函式，請輸入下列查詢，然後點選「執行」。如要限制傳回的結果，請使用 LIMIT 子句。

   SELECT
       text,
       remote_function_test.translate_text(text) AS translated_text
   FROM
       (SELECT text FROM `bigquery-public-data.hacker_news.full` LIMIT 3);
   

   結果大致如下：

   +---------------------------------------------------------------------------+
   | text                            | translated_text                         |
   +---------------------------------------------------------------------------+
   | These benchmarks look good.     | Estos puntos de referencia se ven bien. |
   | Who is using Java?              | ¿Quién está usando Java?                |
   | You need more database storage. | Necesitas más almacenamiento.           |
   +---------------------------------------------------------------------------+
   

刪除資源

如果不打算在這項專案中使用這些函式，可以刪除專案，避免產生額外費用。這項操作會永久刪除與專案相關聯的所有資源。

注意：刪除專案會造成以下影響：

• 專案中的所有內容都會遭到刪除。如果使用現有專案來進行本文中的任務，刪除專案將一併移除當中已完成的其他任務'。
• 自訂專案 ID 會消失。當您之前建立這個專案時，可能建立了想要在日後使用的自訂專案 ID。如要保留使用該專案 ID 的網址 (例如 appspot.com 網址)，請刪除在該專案中選取的資源，而不是刪除整個專案。

如果打算探索多種架構、教學課程或快速入門導覽課程，重複使用專案可避免超出專案配額限制。

1. 前往 Google Cloud 控制台的「Manage resources」(管理資源) 頁面。

   前往「Manage resources」(管理資源)

2. 在專案清單中選取要刪除的專案，然後點選「Delete」(刪除)。
3. 在對話方塊中輸入專案 ID，然後按一下 [Shut down] (關閉) 以刪除專案。

後續步驟

• 瞭解如何在 BigQuery 中使用遠端函式。
• 瞭解 Translation。
• 瞭解 Cloud Run functions。
• 瞭解 Cloud Run。