使用遠端函式

主控台

1. 前往「BigQuery」頁面

   前往 BigQuery

2. 在「Explorer」窗格中，按一下 add「新增資料」：

   

   「Add data」對話方塊隨即開啟。

3. 在「Filter By」窗格中的「Data Source Type」部分，選取「Business Applications」。

   或者，您也可以在「Search for data sources」欄位中輸入 Vertex AI。

4. 在「精選資料來源」部分，按一下「Vertex AI」。

5. 按一下「Vertex AI 模型：BigQuery 聯盟」解決方案資訊卡。

6. 在「連線類型」清單中，選取「Vertex AI 遠端模型、遠端函式和 BigLake (Cloud 資源)」。

7. 在「連線 ID」欄位中，輸入連線的名稱。

8. 點選「建立連線」。

9. 按一下「前往連線」。

10. 在「連線資訊」窗格中，複製服務帳戶 ID，以便在後續步驟中使用。

bq

1. 在指令列環境中建立連線：

   bq mk --connection --location=REGION --project_id=PROJECT_ID \
       --connection_type=CLOUD_RESOURCE CONNECTION_ID

   --project_id 參數會覆寫預設專案。

   更改下列內容：

   • REGION：您的連線區域
   • PROJECT_ID：您的 Google Cloud 專案 ID
   • CONNECTION_ID：連線 ID

   建立連線資源時，BigQuery 會建立專屬的系統服務帳戶，並將該帳戶與連線建立關聯。

   疑難排解：如果您收到下列連線錯誤，請更新 Google Cloud SDK：

   Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
   

2. 擷取並複製服務帳戶 ID，以便在後續步驟中使用：

   bq show --connection PROJECT_ID.REGION.CONNECTION_ID

   輸出結果會與下列內容相似：

   name                          properties
   1234.REGION.CONNECTION_ID     {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel.iam.gserviceaccount.com"}
   

Terraform

使用 google_bigquery_connection 資源。

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

以下範例會在 US 地區中建立名為 my_cloud_resource_connection 的 Cloud 資源連線：

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

如要在 Google Cloud 專案中套用 Terraform 設定，請完成下列各節中的步驟。

準備 Cloud Shell

1. 啟動 Cloud Shell。

2. 設定要套用 Terraform 設定的預設 Google Cloud 專案。

   您只需為每個專案執行這個指令一次，而且可以在任何目錄中執行。

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   如果您在 Terraform 設定檔中設定明確的值，系統就會覆寫環境變數。

準備目錄

每個 Terraform 設定檔都必須有自己的目錄 (也稱為根模組)。

1. 在 Cloud Shell 中建立目錄，並在該目錄中建立新檔案。檔案名稱必須包含 .tf 副檔名，例如 main.tf。在本教學課程中，檔案稱為 main.tf。

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. 如果您正在參考教學課程，可以複製各個章節或步驟中的程式碼範例。

   將範例程式碼複製到新建立的 main.tf 中。

   您可以視需要從 GitHub 複製程式碼。如果 Terraform 程式碼片段是端對端解決方案的一部分，建議您採用這種做法。

3. 查看並修改要套用至環境的範例參數。
4. 儲存變更。
5. 初始化 Terraform。這項操作只需對每個目錄執行一次。

   terraform init

   如要使用最新版的 Google 供應器，您可以選擇加入 -upgrade 選項：

   terraform init -upgrade

套用變更

1. 檢查設定，確認 Terraform 要建立或更新的資源符合您的預期：

   terraform plan

   視需要修正設定。

2. 執行下列指令，並在提示中輸入 yes，即可套用 Terraform 設定：

   terraform apply

   等待 Terraform 顯示「Apply complete!」(套用完成) 訊息。

3. 開啟 Google Cloud 專案即可查看結果。在 Google Cloud 控制台中，前往 UI 中的資源，確認 Terraform 已建立或更新這些資源。

SQL

在 BigQuery 中執行下列 CREATE FUNCTION 陳述式：

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

   前往 BigQuery

2. 在查詢編輯器中輸入以下陳述式：

   CREATE FUNCTION PROJECT_ID.DATASET_ID.remote_add(x INT64, y INT64) RETURNS INT64
   REMOTE WITH CONNECTION PROJECT_ID.LOCATION.CONNECTION_NAME
   OPTIONS (
     endpoint = 'ENDPOINT_URL'
   )

   請依指示取代下列項目：

   • DATASET_ID：BigQuery 資料集的 ID。
   • ENDPOINT_URL：Cloud Run 函式或 Cloud Run 遠端函式端點的網址。

3. 按一下 play_circle「Run」。

如要進一步瞭解如何執行查詢，請參閱「執行互動式查詢」一文。

BigQuery DataFrames

1. 請啟用必要的 API，並確認您已獲得必要的角色，詳情請參閱「遠端函式」的「必要條件」一節。

2. 使用 remote_function 修飾符：

   import bigframes.pandas as bpd
   
   # Set BigQuery DataFrames options
   bpd.options.bigquery.project = your_gcp_project_id
   bpd.options.bigquery.location = "US"
   
   # BigQuery DataFrames gives you the ability to turn your custom scalar
   # functions into a BigQuery remote function. It requires the GCP project to
   # be set up appropriately and the user having sufficient privileges to use
   # them. One can find more details about the usage and the requirements via
   # `help` command.
   help(bpd.remote_function)
   
   # Read a table and inspect the column of interest.
   df = bpd.read_gbq("bigquery-public-data.ml_datasets.penguins")
   df["body_mass_g"].head(10)
   
   # Define a custom function, and specify the intent to turn it into a remote
   # function. It requires a BigQuery connection. If the connection is not
   # already created, BigQuery DataFrames will attempt to create one assuming
   # the necessary APIs and IAM permissions are setup in the project. In our
   # examples we will be letting the default connection `bigframes-default-connection`
   # be used. We will also set `reuse=False` to make sure we don't
   # step over someone else creating remote function in the same project from
   # the exact same source code at the same time. Let's try a `pandas`-like use
   # case in which we want to apply a user defined scalar function to every
   # value in a `Series`, more specifically bucketize the `body_mass_g` value
   # of the penguins, which is a real number, into a category, which is a
   # string.
   @bpd.remote_function(
       reuse=False,
       cloud_function_service_account="default",
   )
   def get_bucket(num: float) -> str:
       if not num:
           return "NA"
       boundary = 4000
       return "at_or_above_4000" if num >= boundary else "below_4000"
   
   # Then we can apply the remote function on the `Series` of interest via
   # `apply` API and store the result in a new column in the DataFrame.
   df = df.assign(body_mass_bucket=df["body_mass_g"].apply(get_bucket))
   
   # This will add a new column `body_mass_bucket` in the DataFrame. You can
   # preview the original value and the bucketized value side by side.
   df[["body_mass_g", "body_mass_bucket"]].head(10)
   
   # The above operation was possible by doing all the computation on the
   # cloud. For that, there is a google cloud function deployed by serializing
   # the user code, and a BigQuery remote function created to call the cloud
   # function via the latter's http endpoint on the data in the DataFrame.
   
   # The BigQuery remote function created to support the BigQuery DataFrames
   # remote function can be located via a property `bigframes_remote_function`
   # set in the remote function object.
   print(f"Created BQ remote function: {get_bucket.bigframes_remote_function}")
   
   # The cloud function can be located via another property
   # `bigframes_cloud_function` set in the remote function object.
   print(f"Created cloud function: {get_bucket.bigframes_cloud_function}")
   
   # Warning: The deployed cloud function may be visible to other users with
   # sufficient privilege in the project, so the user should be careful about
   # having any sensitive data in the code that will be deployed as a remote
   # function.
   
   # Let's continue trying other potential use cases of remote functions. Let's
   # say we consider the `species`, `island` and `sex` of the penguins
   # sensitive information and want to redact that by replacing with their hash
   # code instead. Let's define another scalar custom function and decorate it
   # as a remote function. The custom function in this example has external
   # package dependency, which can be specified via `packages` parameter.
   @bpd.remote_function(
       reuse=False,
       packages=["cryptography"],
       cloud_function_service_account="default",
   )
   def get_hash(input: str) -> str:
       from cryptography.fernet import Fernet
   
       # handle missing value
       if input is None:
           input = ""
   
       key = Fernet.generate_key()
       f = Fernet(key)
       return f.encrypt(input.encode()).decode()
   
   # We can use this remote function in another `pandas`-like API `map` that
   # can be applied on a DataFrame
   df_redacted = df[["species", "island", "sex"]].map(get_hash)
   df_redacted.head(10)