在 UDF 中獲取任務上下文

使用 TaskContext PySpark API 在運行 Batch Unity Catalog Python UDF 或 PySpark UDF 時獲取上下文資訊。

例如，使用者身份和集群標籤等上下文資訊可以驗證使用者的身份以訪問外部服務。

需求

• TaskContext 在 Databricks Runtime 版本 16.3 及更高版本上受支援。

• 以下 UDF 類型支援 TaskContext：

  • Batch Unity Catalog Python UDF
  • 標量 Python UDF

使用TaskContext獲取上下文資訊

選擇一個選項卡可查看 PySpark UDF 或 Batch Unity Catalog Python UDF 的 TaskContext 示例。

PySpark UDF

以下 PySpark UDF 示例列印使用者的上下文：

@udf
def log_context():
  import json
  from pyspark.taskcontext import TaskContext
  tc = TaskContext.get()

  # Returns current user executing the UDF
  session_user = tc.getLocalProperty("user")

  # Returns cluster tags
  tags = dict(item.values() for item in json.loads(tc.getLocalProperty("spark.databricks.clusterUsageTags.clusterAllTags  ") or "[]"))

  # Returns current version details
  current_version = {
    "dbr_version": tc.getLocalProperty("spark.databricks.clusterUsageTags.sparkVersion"),
    "dbsql_version": tc.getLocalProperty("spark.databricks.clusterUsageTags.dbsqlVersion")
  }

  return {
    "user": session_user,
    "job_group_id": job_group_id,
    "tags": tags,
    "current_version": current_version
  }

Batch Unity 目錄 Python UDF

以下 Batch Unity Catalog Python UDF 示例獲取使用者的身份以使用服務憑證調用 AWS Lambda 函數：

%sql
CREATE OR REPLACE FUNCTION main.test.call_lambda_func(data STRING, debug BOOLEAN) RETURNS STRING LANGUAGE PYTHON
PARAMETER STYLE PANDAS
HANDLER 'batchhandler'
CREDENTIALS (
  `batch-udf-service-creds-example-cred` DEFAULT
)
AS $$
import boto3
import json
import pandas as pd
import base64
from pyspark.taskcontext import TaskContext


def batchhandler(it):
  # Automatically picks up DEFAULT credential:
  session = boto3.Session()

  client = session.client("lambda", region_name="us-west-2")

  # Can propagate TaskContext information to lambda context:
  user_ctx = {"custom": {"user": TaskContext.get().getLocalProperty("user")}}

  for vals, is_debug in it:
    payload = json.dumps({"values": vals.to_list(), "is_debug": bool(is_debug[0])})

    res = client.invoke(
      FunctionName="HashValuesFunction",
      InvocationType="RequestResponse",
      ClientContext=base64.b64encode(json.dumps(user_ctx).encode("utf-8")).decode(
        "utf-8"
      ),
      Payload=payload,
    )

    response_payload = json.loads(res["Payload"].read().decode("utf-8"))
    if "errorMessage" in response_payload:
      raise Exception(str(response_payload))

    yield pd.Series(response_payload["values"])
$$;

在註冊後呼叫 UDF。

SELECT main.test.call_lambda_func(data, false)
FROM VALUES
('abc'),
('def')
AS t(data)

TaskContext 屬性

該方法 TaskContext.getLocalProperty() 具有以下屬性鍵：

屬性索引鍵	說明	範例使用方式
user	當前執行UDF的使用者	tc.getLocalProperty("user") ->"alice"
spark.jobGroup.id	與當前 UDF 關聯的 Spark 作業組 ID	tc.getLocalProperty("spark.jobGroup.id") ->"jobGroup-92318"
spark.databricks.clusterUsageTags.clusterAllTags	將元數據標籤集群為鍵值對，格式為 JSON 字典的字串表示形式	tc.getLocalProperty("spark.databricks.clusterUsageTags.clusterAllTags") ->[{"Department": "Finance"}]
spark.databricks.clusterUsageTags.region	工作空間所在的區域	tc.getLocalProperty("spark.databricks.clusterUsageTags.region") ->"us-west-2"
accountId	運行上下文的 Databricks 帳戶 ID	tc.getLocalProperty("accountId") ->"1234567890123456"
orgId	工作區 ID（在 DBSQL 上不可用）	tc.getLocalProperty("orgId") ->"987654321"
spark.databricks.clusterUsageTags.sparkVersion	群集的 Databricks Runtime 版本（在非 DBSQL 環境中）	tc.getLocalProperty("spark.databricks.clusterUsageTags.sparkVersion") ->"16.3"
spark.databricks.clusterUsageTags.dbsqlVersion	DBSQL 版本（在 DBSQL 環境中）	tc.getLocalProperty("spark.databricks.clusterUsageTags.dbsqlVersion") ->"2024.35"