タスクからのパラメーター値へのアクセス

この記事では、タスク内のコード (Databricks ノートブック、Python スクリプト、SQL ファイルなど) からパラメーター値にアクセスする方法について説明します。

パラメーターには、ユーザー定義パラメーター、アップストリーム タスクから出力される値、およびジョブによって生成されたメタデータ値が含まれます。 ジョブのパラメータ化を参照してください。

詳細は タスクの種類によって異なりますが、ソース コードからパラメーター値を参照するために使用される一般的な方法は 4 つあります。

• Databricks ユーティリティ ウィジェット
• SQL 名前付きパラメーターの構文
• 動的値の参照
• コード引数

いずれの場合も、パラメーターのキーを参照してその値にアクセスします。 このキーは、パラメーターの名前と呼ばれることもあります。

ノートブックのコードで dbutils を使用する

タスクで実行されているノートブック コードは、 dbutils ライブラリを使用して parameter の値にアクセスできます。 次の例は、Python で dbutils を使用して、ノートブック タスクに渡される year_param タスク パラメーターの値を取得する方法を示しています。

Python

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

# Use the value in your code
display(babynames.filter(babynames.Year == year_value))

パラメーターには名前でアクセスします。タスク・パラメーターとジョブ・パラメーターが同じ名前の場合、ジョブ・パラメーターがフェッチされます。

上記のコードは、パラメーターがスタンドアロン ノートブックに送信されないため、ジョブの一部としてではなく、スタンドアロン ノートブックで実行するとエラーが発生します。次のコードを使用して、 year_param パラメーターのデフォルトを設定できます。

Python

# Set a default (for when not running in a job)
dbutils.widgets.text("year_param", "2012", "Year Parameter")

# Retrieve a job-level parameter (will use default if it doesn't exist)
year_value = dbutils.widgets.get("year_param")

# Use the value in your code
display(babynames.filter(babynames.Year == year_value))

これはジョブの外部でテストする場合に役立ちますが、タスクまたはジョブのパラメーターが正しく設定されていない場合に非表示になるという欠点もあります。

SQL ノートブックで名前付きパラメーターを使用する

ノートブック タスクで SQL を実行している場合は、 名前付きパラメーター 構文を使用してタスク パラメーターにアクセスできます。 たとえば、 year_paramというタスク パラメーターにアクセスするには、クエリで の :year_param を使用してその値を取得できます。

SQL

SELECT *
FROM baby_names_prepared
WHERE Year_Of_Birth = :year_param
GROUP BY First_Name

コード引数としてのアクセス

一部のタスクタイプでは、パラメーターは引数としてコードに渡されます。次のタスクタイプには、引数が渡されます。

• Python script
• Python Wheel
• JAR
• Spark Submit

詳細については、この記事で後述する 「タスクの種類別の詳細」を参照してください。

dbtタスクの場合、パラメーターはタスクで dbt コマンドを呼び出すことによって渡されます。

タスクの設定時に動的な値参照を使用する

Databricks UI でタスクを構成する場合は、 動的値参照 構文を使用して、ジョブ パラメーターまたはその他の動的値にアクセスします。ジョブ・パラメーターにアクセスするには、構文 {{job.parameters.<name>}}を使用します。たとえば、 Python wheel タスクを構成するときに、パラメーターの Key 入力と Value 入力を設定して、 year_paramというジョブ パラメーター ( year / Twitter など) を参照するように設定できます Year_{{job.parameters.year_param}}。 動的値を使用すると、設定内のパラメーターにアクセスできるだけでなく、ジョブやタスクに関する他のデータ ( {{job.id}}など) にもアクセスできます。タスク設定で {} をクリックすると、可能な動的値のリストを取得し、それらを設定に挿入できます。

タスクタイプ別の詳細

これらの方法のどれを使用するかは、タスクのタイプによって異なります。

タスクのタイプ	構成でのアクセス	コードでのアクセス
ノートブック	Databricks UI で動的な値参照を使用して、ノートブックを構成できます (たとえば、タスク パラメーター値でジョブ パラメーターを参照します)。「異なるパラメーターでジョブを実行」オプションを使用してタスクを手動で実行する場合は、パラメーターをオーバーライドまたは追加できます。	ノートブックで SQL の名前付きパラメーターを使用するか、コードで dbutils.widgets 使用できます。
Pythonスクリプト	タスクで定義されたパラメーターは、引数としてスクリプトに渡されます。 「 パラメーター 」テキスト・ボックスでは、動的な値参照を使用できます。	パラメーターは、位置引数として読み取ることも、Pythonの argparse モジュールを使用して解析することもできます。
Python Wheel	タスク定義で定義されたパラメーターは、キーワード引数としてコードに渡されます。 Python wheel ファイルは、キーワード引数を受け入れるように構成する必要があります。パラメーターの値で動的な値参照を使用できます。	スクリプトのキーワード引数としてアクセスします。Python wheelDatabricksファイルにパッケージ化された スクリプトで引数を読み取る例については、 ジョブでの SAP ファイルの使用を参照してくださいPython Python wheel。
SQL	タスク設定では、動的な値参照を使用できます。	名前付きパラメーターを使用して、パラメーター値にアクセスします。
パイプライン	パイプラインでは、タスクへのパラメーターの受け渡しはサポートされていません。	サポートされていません。
dbt	動的値参照を使用して、タスクの設定時にパラメーターを dbt コマンドとして渡すことができます。	dbtコマンドとしてアクセスします。
JAR	動的値参照を使用して、タスクの構成時に パラメーター テキスト ボックスの引数としてパラメーターを渡すことができます。	パラメーターは、メイン クラスの main メソッドの引数としてアクセスされます。
Spark Submit	動的値参照を使用して、タスクの構成時に パラメーター テキスト ボックスの引数としてパラメーターを渡すことができます。	パラメーターは、メインクラスのmainメソッドの引数としてアクセスされます。
ジョブを実行	動的値参照を使用して、タスクの設定時に 一連のジョブ・パラメーター を作成できます。値には、動的な値参照を含めることができます。	該当なし。
if/else条件	動的な値参照は、タスクを構成するとき ( たとえば、条件 ) で使用できます。	該当なし。
For each	タスクの入力を設定するときに、動的な値参照を使用できます。ネストされたタスクは、ネストされたタスクの各反復に対してタスク パラメーターとして 1 つの入力を受け取ります。	ネストされたタスク アクセス パラメーター (タスクの種類に基づく)。
クリーンルームのノートブック	Databricks UI で動的な値参照を使用して、ノートブックを構成できます (たとえば、タスク パラメーター値でジョブ パラメーターを参照します)。	ノートブックで SQL の名前付きパラメーターを使用するか、コードで dbutils.widgets 使用できます。