動的値参照とは

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

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

• ジョブの設定値 (ジョブ名、タスク名、トリガー・タイプなど)。

• ジョブ ID、実行 ID、ジョブ実行開始時刻など、ジョブに関する生成されたメタデータ。

• ジョブが行った修復の試行回数、またはタスクが実行した再試行回数に関する情報。

• 指定したタスクの結果の状態。

• ジョブ・パラメーター、タスク・パラメーターを使用して構成された値、またはタスク値を使用して設定された値。

動的な値参照を使用する

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

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

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

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

注：

二重中括弧の内容は、式として評価されません。 二重中括弧で操作や関数を実行することはできません。

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

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

ジョブ UI での動的値参照の使用

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

注：

UI は、タスク値を参照するためのキーをオートコンプリートしません。

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

ジョブ 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。

これらの参照は、任意のタスクで設定できます。 Configure タスク パラメーターを参照してください。

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

日付と時刻の値のオプション

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

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

非推奨の動的値参照

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

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