從工作存取參數值

存取參數值來自你的任務程式碼，包括 Azure Databricks 筆記本、Python 腳本和 SQL 檔案。

參數包括使用者定義參數、上游工作輸出的值，以及作業所產生的元數據值。 請參閱參數化作業。

雖然詳細數據會因 工作類型而有所不同，但有四種常見方法可用來從原始碼參考參數值：

• Databricks 公用程式小工具
• SQL 具名參數語法
• 動態值參考
• 程式代碼自變數

在這些情況下，你都會參考參數的鍵來取得它的值。 鍵有時被稱為參數名稱。

若想了解如何在使用SQL任務與For each任務的元資料驅動工作中應用這些技術，請參見使用控制表驅動工作For each。

請在筆記本程式碼中使用dbutils

在工作中執行的筆記本程序代碼可以使用 dbutils 鏈接庫存取參數的值。 以下範例展示了如何在 Python 中使用 dbutils 來取得傳遞到筆記本任務中的 year_param 任務參數的值。

from pyspark.sql.functions import year

# Retrieve the job-level parameter
year_value = dbutils.widgets.get("year_param")

# Use the value to filter bookings by check-in year
display(spark.read.table("samples.wanderbricks.bookings").filter(year("check_in") == year_value))

參數依名稱存取。 如果工作參數與任務參數共用鍵，則工作參數優先。 請參閱工作參數下推。

上述程式代碼會在獨立筆記本中執行，而不是當做作業的一部分執行時產生錯誤，因為參數不會傳送到獨立筆記本中。 您可以使用下列程式代碼來設定 year_param 參數的預設值：

from pyspark.sql.functions import year

# Set a default for when the notebook runs outside a job
dbutils.widgets.text("year_param", "2025", "Year Parameter")

# Retrieve the parameter, falling back to the default if it isn't set
year_value = dbutils.widgets.get("year_param")

display(spark.read.table("samples.wanderbricks.bookings").filter(year("check_in") == year_value))

雖然這有助於在工作外測試，但同時也能掩蓋錯誤設定的任務或工作參數。

在 SQL 中使用命名參數

當你在筆記本或管線任務中執行 SQL 時，可以使用 命名的參數 語法來取得任務參數。 例如，若要取得名為 year_param 的任務參數，你可以在查詢中使用 :year_param 來取得其值：

SELECT year(check_in) AS year_of_stay, count(*) AS bookings, round(avg(total_amount), 2) AS avg_amount
FROM samples.wanderbricks.bookings
WHERE year(check_in) = :year_param
GROUP BY year(check_in)

以程式碼作為參數存取

對於某些工作類型參數，會以自變數的形式傳遞至程序代碼。 下列任務類型具有傳遞給它們的參數：

• Python script
• Python Wheel
• JAR
• Spark Submit

詳情請見本頁後面的 「依任務類型的詳情」。

針對 dbt 工作，參數會藉由呼叫工作中的 dbt 命令來傳遞。

設定工作時使用動態值參考

當你在 Azure Databricks UI 中設定任務時，請使用動態值參考語法來取得工作參數或其他動態值。 要取得工作參數，請使用語法： {{job.parameters.<name>}}。 例如，在設定 Python wheel 任務時，你可以設定參數的 Key 和 Value 輸入，來參考名為 year_param 的工作參數，例如 year / Year_{{job.parameters.year_param}}。 除了在組態中提供參數的存取，動態值也可讓您存取作業或工作的其他資料，例如 {{job.id}}。 您可以按下 {} 工作組態以取得可能的動態值清單，並將其插入您的設定中。

依工作類型的詳細數據

您使用的其中哪一種方法取決於工作類型。