動的値参照とは

[アーティクル]
10/14/2024

動的値参照では、ジョブとタスクを構成するときに使用できる変数のコレクションが記述されます。動的値参照を使用して、タスクの条件付きステートメントを構成したり、パラメーターまたは引数として情報を渡したりします。

動的値参照には、次のような情報が含まれます。

ジョブ名、タスク名、トリガーの種類など、ジョブに対して構成された値。
ジョブ ID、実行 ID、ジョブの実行開始時刻など、ジョブに関する生成されたメタデータ。
ジョブの修復試行回数またはタスクが実行された再試行回数に関する情報。
指定したタスクの結果の状態。
ジョブパラメーター、タスクパラメーターを使用して構成された値、またはタスク値を使用して設定された値。

動的値参照を使用する

ジョブまたはタスクを構成するときは、動的値参照を使用します。ノートブック、クエリ、JAR などのタスクを使用して構成されたアセットから動的値参照を直接参照することはできません。動的値参照は、タスクにコンテキストを渡すパラメーターまたはフィールドを使用して定義する必要があります。

動的値参照では、二重中かっこ ({{ }}) が使用されます。ジョブまたはタスクを実行すると、動的値参照が文字列リテラルに置き換えられます。たとえば、次のキーと値のペアをタスクパラメーターとして構成するとします。

{"job_run_id": "job_{{job.run_id}}"}

実行 ID が 550315892394120 の場合、job_run_id の値は job_550315892394120 と評価されます。

Note

二重中かっこの間にある内容は式として評価されません。二重中かっこ内の演算または関数は実行できません。

ユーザー指定の値識別子は、英数字とアンダースコア文字をサポートします。識別子をバックティック (` `) で囲んで特殊文字を含むキーをエスケープします。

存在しない動的参照値や中かっこの欠落など、構文エラーはメッセージなしに無視され、リテラル文字列として扱われます。既知の名前空間 ({{job.notebook_url}} など) に属する無効な参照を指定すると、エラーメッセージが表示されます。

ジョブ UI で動的値参照を使用する

動的値参照を受け入れるフィールドには、使用可能な動的値参照を挿入するためのショートカットがあります。 { } をクリックすると、このリストが表示されます。これを指定したフィールドに挿入します。

Note

UI では、タスク値を参照するためのキーは自動補完されません。

動的値参照を受け入れる多くのフィールドでは、正しく使用するために追加の書式設定が必要です。「タスクパラメーターを構成する」を参照してください。

ジョブ JSON で動的値参照を使用する

{{ }} 構文を使用して、Databricks CLI と REST API で使用されるジョブ JSON 定義で動的な値を使用します。

ジョブパラメーターとタスクパラメーターの構文は異なり、タスクパラメーターの構文はタスクの種類によって異なります。

次の例は、動的値参照を使用してジョブパラメーターを構成するための部分的な JSON 構文を示しています。

{
  "parameters": [
    {
      "name": "my_job_id",
      "default": "{{job.id}}"
    },
    {
      "name": "run_date",
      "default": "{{job.start_time.iso_date}}"
    }
  ]
}

次の例は、動的値参照を使用してノートブックタスクパラメーターを構成するための部分的な JSON 構文を示しています。

{
  "notebook_task": {
    "base_parameters": {
      "workspace_id": "workspace_{{workspace.id}}",
      "file_arrival_location": "{{job.trigger.file_arrival.location}}"
    }
  }
}

ジョブ実行のパラメーターを確認する

タスクが完了すると、実行の詳細ページの [パラメーター] で、解決されたパラメーター値を確認できます。「ジョブ実行の詳細を表示する」を参照してください。

サポートされる値参照

次の動的値参照がサポートされています。

リファレンス	説明
`{{job.id}}`	ジョブに割り当てられた一意識別子。
`{{job.name}}`	ジョブ実行時のジョブの名前。
`{{job.run_id}}`	ジョブ実行に割り当てられた一意識別子。
`{{job.repair_count}}`	現在のジョブ実行の修復試行回数。
`{{job.start_time.<argument>}}`	ジョブ実行が開始された時刻 (UTC タイムゾーン) に基づく値。戻り値は、`argument` オプションに基づきます。「日付と時刻の値のオプション」を参照してください。
`{{job.parameters.<name>}}`	キー `<name>` を持つジョブレベルパラメーターの値。
`{{job.trigger.type}}`	ジョブ実行のトリガーの種類。使用できる値は、`periodic`、`one_time`、`run_job_task`、`file_arrival`、`continuous`、`table` です。
`{{job.trigger.file_arrival.location}}`	このジョブに対してファイル到着トリガーが構成されている場合、ストレージの場所の値。
`{{job.trigger.time.<argument>}}`	ジョブ実行がトリガーされた時刻 (UTC タイムゾーン) に基づく値。cron スケジュールを持つジョブの場合は最も近い分に切り捨てられます。戻り値は、`argument` オプションに基づきます。「日付と時刻の値のオプション」を参照してください。
`{{task.name}}`	現在のタスクの名前。
`{{task.run_id}}`	現在のタスク実行の一意識別子。
`{{task.execution_count}}`	現在のタスクが実行された回数 (再試行と修復を含む)。
`{{task.notebook_path}}`	現在のノートブックタスクのノートブックパス。
`{{tasks.<task_name>.run_id}}`	`<task_name>` のタスク実行に割り当てられた一意識別子。
`{{tasks.<task_name>.result_state}}`	タスク `<task_name>` の結果の状態。可能な値は、`success`、`failed`、`excluded`、`canceled`、`evicted`、`timedout`、`upstream_canceled`、`upstream_evicted`、`upstream_failed` です。
`{{tasks.<task_name>.error_code}}`	タスクの実行中にエラーが発生した場合の、タスク `<task_name>` のエラーコード。使用できる値の例は、`RunExecutionError`、`ResourceNotFound`、`UnauthorizedError` です。タスクが正常に終了した場合、これは空の文字列に評価されます。
`{{tasks.<task_name>.execution_count}}`	タスク `<task_name>` が実行された回数 (再試行と修復を含む)。
`{{tasks.<task_name>.notebook_path}}`	ノートブックタスク`<task_name>` のノートブックへのパス。
`{{tasks.<task_name>.values.<value_name>}}`	タスク `<task_name>` によって設定されたキー `<value_name>` を持つタスク値。
`{{workspace.id}}`	ワークスペースに割り当てられた一意識別子。
`{{workspace.url}}`	ワークスペースの URL。

これらの参照は、どのタスクでも設定できます。「タスクパラメーターを構成する」を参照してください。

"タスク値" を持つジョブ内のタスク間でパラメーターを渡すこともできます。「タスク値を使用してタスク間で情報を渡す」を参照してください。

データと時刻の値のオプション

時間ベースのパラメーター変数からの戻り値を指定するには、次の引数を使用します。戻り値はすべて、UTC タイムゾーンのタイムスタンプに基づきます。

引数	説明
`iso_weekday`	タイムスタンの曜日を表す 1 から 7 までの数字を返します。
`is_weekday`	タイムスタンプが平日の場合、`true` を返します。
`iso_date`	ISO 形式の日付を返します。
`iso_datetime`	ISO 形式の日付と時刻を返します。
`year`	タイムスタンプの年の部分を返します。
`month`	タイムスタンプの月の部分を返します。
`day`	タイムスタンプの日の部分を返します。
`hour`	タイムスタンプの時の部分を返します。
`minute`	タイムスタンプの分の部分を返します。
`second`	タイムスタンプの秒の部分を返します。
`timestamp_ms`	タイムスタンプをミリ秒で返します。

非推奨の動的値参照

次の動的値参照は非推奨です。推奨される置換参照は、各変数の説明に含まれています。

変数	説明
`{{job_id}}`	ジョブに割り当てられた一意識別子。代わりに `job.id` を使用してください
`{{run_id}}`	タスク実行に割り当てられた一意識別子。代わりに `task.run_id` を使用してください
`{{start_date}}`	タスクの実行が開始された日付。形式は、UTC タイムゾーンの yyyy-MM-dd です。代わりに `job.start_time.<argument>` を使用してください
`{{start_time}}`	クラスターが作成され、準備ができた後の実行の開始のタイムスタンプ。形式は、`System.currentTimeMillis()` によって返される、UTC タイムゾーンの UNIX エポックからのミリ秒です。代わりに `job.start_time.<format>` を使用してください
`{{task_retry_count}}`	最初の試行が失敗した場合にタスクの実行を試行した再試行の回数。値は最初の試行では 0 で、再試行ごとに増加します。代わりに `task.execution_count` を使用してください
`{{parent_run_id}}`	複数のタスクを持つジョブの実行に割り当てられた一意の識別子。代わりに `job.run_id` を使用してください
`{{task_key}}`	複数のタスクを持つジョブの一部であるタスクに割り当てられた一意の名前。代わりに `task.name` を使用してください

次の方法で共有