自訂 BigQuery DataFrames 的 Python 函式

自訂 BigQuery DataFrames 的 Python 函式，即可將程式碼轉換為可擴充的 BigQuery 構件，例如 user-defined function (UDF) 或遠端函式。您可以部署這些自訂函式，運用開放原始碼程式庫，並執行標準 SQL API 無法執行的作業。

必要的角色

如要取得完成本文件所述工作所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

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

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

User-defined function (UDF)

您可以使用 UDF (預先發布版)，將自訂 Python 函式轉換為 Python UDF。如需使用範例，請參閱「建立永久 Python UDF」。

在 BigQuery DataFrames 中建立 UDF 時，系統會在指定資料集中，建立 BigQuery 常式做為 Python UDF。如需支援參數的完整組合，請參閱 bigframes.pandas.udf。

需求條件

如要使用 BigQuery DataFrames UDF，請在專案中啟用 BigQuery API。如果您在專案中提供 bigquery_connection 參數，也必須啟用 BigQuery Connection API。

清除所用資源

除了直接在 Google Cloud 控制台或使用其他工具清理雲端構件外，您也可以使用bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id)指令，清理以明確名稱引數建立的 BigQuery DataFrames UDF。

限制

  • UDF 中的程式碼必須是獨立的，也就是說，不得包含任何對函式主體外部定義的匯入或變數的參照。
  • UDF 中的程式碼必須與 Python 3.11 相容，因為程式碼是在雲端的 Python 3.11 環境中執行。
  • 在函式程式碼中進行微幅變更 (例如重新命名變數或插入新行) 後，重新執行 UDF 定義程式碼會導致 UDF 重新建立，即使這些變更對函式的行為沒有影響。
  • 具備 BigQuery 常式讀取權限的使用者可以查看使用者程式碼，因此請務必謹慎加入機密內容。
  • 在 BigQuery 位置，一項專案一次最多可有 1,000 個 Cloud Run 函式。

BigQuery DataFrames UDF 會部署使用者定義的 BigQuery Python 函式，並適用相關限制。

遠端函式

BigQuery DataFrames 可讓您將自訂純量函式轉換為 BigQuery 遠端函式。如需使用範例，請參閱「建立遠端函式」。如需完整的支援參數清單，請參閱「remote_function」。

在 BigQuery DataFrames 建立遠端函式時，系統會建立下列項目：

  • Cloud Run 函式。

  • BigQuery 連線。

    根據預設，系統會使用名為 bigframes-default-connection 的連線。您也可以視需要使用預先設定的 BigQuery 連線，這樣就不必建立連線。預設連線的服務帳戶會獲得 Cloud Run 角色 (roles/run.invoker)。

  • BigQuery 遠端函式，使用透過 BigQuery 連線建立的 Cloud Run 函式。

需求條件

如要使用 BigQuery DataFrames 遠端函式，您必須啟用下列 API：

使用 BigQuery DataFrames 遠端函式時，如果您使用預設 BigQuery 連線，則需要專案 IAM 管理員角色 (roles/resourcemanager.projectIamAdmin)；如果使用預先設定的連線，則需要瀏覽者角色 (roles/browser)。如要避免這項要求，請將 bigframes.pandas.options.bigquery.skip_bq_connection_check 選項設為 True，這樣系統就會直接使用連線 (預設或預先設定)，不會檢查是否存在或權限。如果您使用預先設定的連線，並略過連線檢查，請確認下列事項：

  • 在正確的位置建立連線。
  • 如果您使用 BigQuery DataFrames 遠端函式，服務帳戶在專案中會具備 Cloud Run 叫用者角色 (roles/run.invoker)。

查看及管理連結

BigQuery 連線會建立在與 BigQuery DataFrames 工作階段相同的位置，並使用您在自訂函式定義中提供的名稱。如要查看及管理連結，請按照下列步驟操作：

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

    前往「BigQuery」

  2. 選取您建立遠端函式的專案。

  3. 點選左側窗格中的 「Explorer」。

    醒目顯示的「Explorer」窗格按鈕。

  4. 在「Explorer」窗格中展開專案，然後按一下「Connections」(連結)。

BigQuery 遠端函式會在您指定的資料集中建立，或在匿名資料集 (一種隱藏資料集) 中建立。如果在建立遠端函式時未設定名稱，BigQuery DataFrames 會套用以 bigframes 前置字元開頭的預設名稱。如要查看及管理在使用者指定資料集中建立的遠端函式，請按照下列步驟操作：

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

    前往「BigQuery」

  2. 選取您建立遠端函式的專案。

  3. 點選左側窗格中的 「Explorer」。

    醒目顯示的「Explorer」窗格按鈕。

  4. 在「Explorer」窗格中展開專案，然後點選「資料集」。

  5. 按一下您建立遠端函式的資料集。

  6. 按一下「日常安排」分頁標籤。

如要查看及管理 Cloud Run 函式，請按照下列步驟操作：

  1. 前往「Cloud Run」頁面。

    前往 Cloud Run。

  2. 選取您建立函式的專案。

  3. 在可用服務清單中，依「函式部署類型」篩選。

  4. 如要找出 BigQuery DataFrames 建立的函式，請尋找前置字串為 bigframes 的函式名稱。

清除所用資源

除了直接在 Google Cloud 控制台或使用其他工具清理雲端構件外，您也可以透過下列方式，清理未明確指定名稱引數而建立的 BigQuery 遠端函式，以及相關聯的 Cloud Run 函式：

  • 如要建立 BigQuery DataFrames 工作階段，請使用 session.close() 指令。
  • 如要使用預設的 BigQuery DataFrames 工作階段，請使用 bigframes.pandas.close_session() 指令。
  • 如要查看與 session_id 的過往工作階段，請使用 bigframes.pandas.clean_up_by_session_id(session_id) 指令。

您也可以使用 bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id) 指令，清除以明確名稱引數建立的 BigQuery 遠端函式，以及相關聯的 Cloud Run 函式。

限制

  • 首次建立遠端函式後，約需 90 秒才能使用。其他套件依附元件可能會增加延遲時間。
  • 如果對函式程式碼進行微幅變更 (例如重新命名變數、插入新行，或在筆記本中插入新儲存格)，然後重新執行遠端函式定義程式碼，可能會導致遠端函式重新建立，即使這些變更不會影響函式行為。
  • 具備 Cloud Run 函式讀取權限的使用者可以查看使用者程式碼，因此請務必謹慎加入機密內容。
  • 在單一區域中，一項專案最多可同時有 1,000 個 Cloud Run 函式。詳情請參閱配額的相關說明。

後續步驟