スケジューリングパラメーターは、DataWorks の動的なタスク管理と構成管理における中核的な仕組みです。コード内で変数プレースホルダーを使用することで、スケジューリング時に動的な値を注入できます。これにより、定期タスクにおける日付のハードコーディング問題を解決し、ワークスペース、ワークフロー、ノードコンテキスト、ノードローカルという 4 階層のパラメーター構造を通じて、構成をコードから分離します。この分離により、タスクの柔軟性、再利用性、そして異なる環境への適応性が大幅に向上します。
この記事では、スケジューリングパラメーターの割り当てソースと式の構文に焦点を当てています。この記事を読む前に、スケジューリングパラメーターの構成と使用で説明されている基本的な構成方法を必ずご確認ください。
スケジューリングパラメーターのソース
ノード上でローカルに定義されたパラメーターを使用するだけでなく、コンテキスト、ワークフロー、およびワークスペースのパラメーターも使用できます。これらのソースを、スコープが狭いものから広いものの順に以下に示します。
-
ノードローカル定義 (現在のノード)
[スケジューリング構成] セクションの [スケジューリングパラメーター] エリアで定義されたパラメーターは、現在のノードにのみ適用されます。以下で詳述するように、豊富なパラメーター式をサポートしています。
-
コンテキストパラメーター (ノード間での受け渡し)
コンテキストパラメーターを使用して、上流ノードから出力値を受け取ります。これにより、値が渡されるだけでなく、ノード間に依存関係が確立されます。パラメーターの値が上流タスクの結果によって動的に決定される必要がある場合、このメソッドを使用します。パラメーター割り当てエリアの
アイコンをクリックすると、コンテキストパラメーターをすばやく追加できます。詳細については、「ノードコンテキストパラメーターの構成と使用」をご参照ください。
-
ワークフローパラメーター (ワークフロー内で共有)
ワークフローレベルで定義されたパラメーターは、そのワークフロー内のすべてのノードで使用できます。
${workflow.Parameter name}の形式で直接参照できます。この記事で説明されているパラメーター式のルールは、ワークフローパラメーターにも適用されます。
-
ワークスペースパラメーター (ワークスペース内で共有)
ワークスペースパラメーターは、ワークスペースレベルで定義されたグローバルパラメーターであり、そのワークスペース内のすべてのノードで利用できます。最も一般的な使用方法は、開発環境と本番環境の構成を区別することです。たとえば、開発環境では
db_nameという名前のパラメーターを値db_devで定義し、本番環境ではdb_prodで定義できます。スケジューリングパラメーターの値を設定する際、[ワークスペースパラメーター] を直接選択できます。詳細については、「ワークスペースパラメーターの使用」をご参照ください。
パラメーター式
スケジューリングパラメーターは、パラメーター名とパラメーター値を指定することで割り当てロジックを定義します。パラメーター値は、時間パラメーター、組み込みシステムパラメーター、定数など、複数の形式をサポートしています。パラメーターを定義した後、${parameter name} 形式を使用してコード内で参照できます。
-
カスタム時間パラメーター：
${...}や$[...]など。ビジネス日付とスケジュール時刻という 2 つの時間基準に基づいて値を変換できます。詳細については、「時間パラメーター」をご参照ください。 -
組み込みシステムパラメーター：$bizdate、$bizmonth、$jobid など。ビジネス日付、ビジネス月、ワークフロー ID などを取得するために使用できます。時間関連の値に限定されません。詳細については、「組み込みスケジューリングパラメーター」をご参照ください。
-
定数: '
123'、''abc'など。
サポートされる特殊文字：· ～ ! @ # $ % ^ & * ( ) - = _ + およびスペース。パラメーター値にスペースが含まれる場合は、値を一重引用符で囲みます。例：'xxx xxx'。
これらのうち、時間パラメーターは、タスク実行時にさまざまな時間文字列を動的に置き換えるために使用される、スケジューリングパラメーターの主なユースケースです。
時間パラメーター
コアコンセプト：時間基準
DataWorks のすべての動的な時間パラメーターは、以下の 2 つのコアな時間基準に基づいています。
|
概念 |
定義 |
パラメーター値 |
カスタムフォーマット |
時間精度 |
|
ビジネス日付 |
通常、タスクのスケジュール実行日の前日を指します。T+1 バッチコンピューティングのシナリオでは、ビジネスデータが生成された日付を表します。たとえば、今日タスクを実行して前日の収益を計算する場合、トランザクションが発生した前日がビジネス日付になります。 |
|
|
年、月、日 |
|
スケジュール時刻 |
ノードの Scheduling Settings セクションで [cron 式] を使用して設定された時間を指します。タスクのランタイム時に、タスクインスタンスの実行がスケジュールされている日に置き換えられます。秒単位で正確であり、実際の実行時間とは無関係です。 この時間はタスクの期待実行時刻を表し、実際の開始時刻と完全に一致するとは限りません。実際の開始時刻は複数の要因に影響されます。 |
|
|
年、月、日、時、分、秒 |
概要：
-
ビジネス日付 ≈ 昨日 (データの対象日) =
$bizdate=${yyyymmdd} -
スケジュール時刻 ≈ 今日 (タスクの実行日) =
$cyctime=$[yyyymmddhh24miss]
典型的な T+1 タスクは次のように動作します：今日 (スケジュール時刻) の早朝にタスクがトリガーされ、昨日 (ビジネス日付) のデータを処理します。
以下に、ビジネス日付が 2025-10-16 の場合の、$bizdate と ${yyyymmdd}、$cyctime と $[yyyymmddhh24miss] のパラメーター定義とプレビュー結果を示します。
|
|
|
基本時間パラメーターのデフォルトの戻り値が要件を満たさない場合は、${...} と $[...] を使用してカスタム時間パラメーターを定義できます。カスタム時間パラメーターは、2 つの基本時間基準を変換することによって導出されます。以下のメソッドがサポートされています：
カスタム式を使用してスケジューリングパラメーターに値を割り当てる場合は、2 つの括弧形式 {...} と [...] を区別してください。この 2 つの形式は異なる基本時間基準を使用し、まったく異なる値を返します。これらを混同すると、本番データの誤りを引き起こす可能性があります。
カスタム時間パラメーター
DataWorks は ${...} と $[...] を使用して、それぞれビジネス日付とスケジュール時刻を取得することをサポートしています。以下の変換タイプにより、ビジネス要件に合わせて時間値を柔軟に変更できます。以下の例では、スケジュール時刻が 02:30:45、ビジネス日付が 20251031 の日次スケジュールを想定しています。基本時間基準は次のとおりです：
-
ビジネス日付：${yyyymmdd}、例：20251031。
-
スケジュール時刻：$[yyyymmddhh24miss]、例：20251101023045。
重要スケジュール時刻は、タスクインスタンスが生成される際に固定される、事前に設定されたスケジューリング時間です。タスクインスタンスがリソースの制約や上流ノードのステータスのために遅延した場合でも、スケジュール時刻はインスタンスの実際の実行時間とともに変更されません。
${...} と $[...] の主な違い
まず、この 2 つの主な違いを理解してください。${...} と $[...] は、時間基準と計算能力において根本的に異なります。これら 2 つの形式を混同すると、データエラーを引き起こす可能性があります。
|
次元 |
|
|
|
時間基準 |
ビジネス日付 (T-1) |
スケジュール時刻 (T) |
|
時間精度 |
日 (年、月、日) |
秒 (年、月、日、時、分、秒) |
|
オフセット計算機能 |
年、月、週、日のオフセット計算をサポートします。 |
日、時、分のオフセット計算をサポートします。 |
|
主な制限 |
時、分、秒などのより小さな時間単位のフォーマットやオフセット計算はサポートしていません。 |
|
|
デフォルトの同等表現 |
|
|
時間フォーマット
中括弧 ${...} または角括弧 $[...] を、yyyy、yy、mm、dd とカスタムの組み合わせで使用して、ビジネス日付の N 年、N ヶ月、または N 日前後の日付を取得する時間パラメーターを生成します。
|
コード |
説明 |
|
|
||
|
割り当て |
結果 |
割り当て |
結果 |
||
|
|
4桁の年 |
|
|
|
|
|
|
2桁の月 |
|
|
|
|
|
|
2桁の日 |
|
|
|
|
|
|
24時間形式の時 |
サポートされていません (日レベルの精度) |
- |
|
|
|
|
12時間形式の時 |
- |
|
|
|
|
|
分 |
- |
|
|
|
|
|
2番目 |
- |
|
|
|
|
|
年と月 |
|
|
|
|
|
|
ハイフンを区切り文字として使用してフォーマット |
|
|
|
|
|
|
ハイフンでフォーマットされ、時、分、秒を含む |
サポートされていません (日レベルの精度) |
- |
サポートされている方法については、「文字列連結：メソッド 2」をご参照ください。 |
|
オフセット計算
オフセット計算は動的パラメーターの中核です。ビジネス日付またはスケジュール時刻に値を加算または減算して、基本時間の N 年、N ヶ月、N 日、N 時間、または N 分前後の日付と時刻を取得できます (時と分はスケジュール時刻でのみサポートされます)。${...} と $[...] は、基本時間基準の精度が異なるため、サポートする範囲が異なります。
-
${...}のオフセット計算-
コア機能：年、月、週、日の整数オフセットをサポートします。
重要時または分のオフセット計算はサポートされていません。${yyyy-mm-dd-1/24} のような式はサポートされていません。
-
構文：
${<時間フォーマット><±N>}。ここで、N は時間フォーマットの最小単位に対応します。たとえば、フォーマットが yyyymm の場合、N は月単位です。フォーマットが yyyymmdd の場合、N は日単位です。日付オフセット期間
オフセット単位
構文
例
N 年前/後
年
${yyyy±N}または${yy±N}前年を取得：
${yyyy-1}N ヶ月前/後
月
${yyyymm±N}
前月を取得：
${yyyymm-1}N 週間前/後
週
${yyyymmdd±7*N}
前週を取得：
${yyyymmdd-7*1}N 日前/後
日
${yyyymmdd±N}
一昨日を取得：
${yyyymmdd-1}
-
-
$[...]のオフセット計算-
コア機能：日、時、分の小数オフセットをサポートします。
重要$[...]は$[yyyy-N]または$[mm-N]の時間フォーマットを使用して N 年前または N ヶ月前の日付を取得することはできません。年または月のオフセット計算を実行するには、add_months関数を使用してください。 -
構文：
$[<時間フォーマット><±N>]。時オフセットには N/24、分オフセットには N/24/60 を使用します。N はオフセットする時間または分の数です。要件
オフセット単位
構文
例
N 年前/後
年
$[add_months(yyyymmdd,12*N)](N 年後)$[add_months(yyyymmdd,-12*N)](N 年前)前年を取得：
$[add_months(yyyymmdd,-12)]N ヶ月前/後
月
$[add_months(yyyymmdd,N)](N ヶ月後)$[add_months(yyyymmdd,-N)](N ヶ月前)前月を取得：
$[add_months(yyyymmdd,-1)]N 週間前/後
週
$[yyyymmdd±7*N]前週を取得：
$[yyyymmdd±7*1]N 日前/後
日
$[yyyymmdd±N]昨日を取得：
$[yyyymmdd-1]N 時間前/後
時
この時間データは、次のメソッドを使用して取得できます：
-
$[hh24miss±N/24],$[hh24±N/24] -
$[カスタム時間フォーマット±N/24]
異なる時間フォーマットを使用して前の時間を取得：
-
月を取得：
$[mm-1/24]。 -
年を取得：
$[yyyy-1/24]。 -
年と月を取得：
$[yyyymm-1/24]。 -
年、月、日を取得：
$[yyyymmdd-1/24]。 -
前日と前の時間を取得：
$[yyyymmdd-1-1/24]
N 分前/後
分
この時間データは、次のメソッドを使用して取得できます：
-
$[hh24miss±N/24/60] -
$[yyyymmddhh24miss±N/24/60] -
$[mi±N/24/60] -
$[カスタム時間フォーマット±N/24/60]
異なる時間フォーマットを使用して、スケジュール時刻の 15 分前を取得：
-
$[yyyy-15/24/60] -
$[yyyymm-15/24/60] -
$[yyyymmdd-15/24/60] -
$[hh24-15/24/60] -
$[mi-15/24/60]
複雑な組み合わせのオフセット
日 + 時
$[yyyymmdd±N±M/24]。ここで、N は日のオフセット、M は時のオフセットです。例：1 日前と 1 時間前を取得 →
$[yyyymmdd-1-1/24]説明-
時または分のオフセット計算を実行すると、日付境界の交差が発生する可能性があります。パラメーターが日付境界の交差をどのように処理するかについては、「時間パラメーターにおける日付境界の交差の処理」をご参照ください。
-
月末日に月のオフセット計算を実行する場合、対象の月に対応する日がない場合、結果はその月の最終日に自動的に調整されます。たとえば、現在の日付が 2025-03-31 で、1 ヶ月後方へのオフセットが適用された場合、2 月には 31 日がないため、結果は 2025-02-28 になります。
-
-
エンジン関数を使用した二次変換
スケジューリングパラメーターの組み込みフォーマットとオフセットが、目的の値を直接生成できない場合 (たとえば、前月の最終日など)、対象ノードのコンピュートエンジンの組み込み関数を使用するか、代入ノードを使用して、呼び出し時に時間パラメーターに二次変換を実行できます。
詳細については、「エンジン関数を使用した二次変換の実行」をご参照ください。
文字列連結
このメソッドを使用して、組み込み構文がサポートしていないパターンの日付文字列を構築します。スケジューリングパラメーターによって生成された日付部分と、固定の定数文字列を組み合わせます。
例 1：各月の最初の日を動的に取得する。
-
シナリオ：タスクが実行される日に関係なく、
yyyymm01形式で現在の月の最初の日を表す文字列が必要です。 -
実装：
-
年と月を抽出：
${yyyymm}を使用して、現在のビジネス日付の年と月を取得します (たとえば、ビジネス日付が20231027の場合、結果は202310です)。 -
定数を連結：抽出した年と月を文字列
'01'と連結します。 -
パラメーター呼び出し：
first_day_of_month=${yyyymm}01
-
-
結果：タスク実行時、
${first_day_of_month}は20231001に置き換えられます。
例 2：yyyy-mm-dd hh24:mi:ss 形式で時間を取得する。
-
シナリオ：
yyyy-mm-dd hh24:mi:ss形式の時間文字列、たとえば2023-11-01 02:30:45を取得します。 -
実装：
-
2 つのパラメーターを定義：
datetime1とdatetime2を定義し、datetime1=$[yyyy-mm-dd]とdatetime2=$[hh24:mi:ss-1/24/60]として割り当てます。 -
パラメーターを連結：
datetime1とdatetime2をスペースで連結します。 -
パラメーター呼び出し：pt=
${datetime1}${datetime2}。
-
-
結果：タスク実行時、
${datetime1}${datetime2}は2023-11-01 02:30:45に置き換えられます。
組み込みスケジューリングパラメーター
DataWorks は以下の組み込みシステムパラメーターをサポートしており、これらはスケジューリングパラメーター値として使用できます。ただし、時間フォーマットが固定されているため、このアプローチは柔軟性に欠けます。柔軟な変換をサポートするカスタム時間パラメーターを使用することを推奨します。
|
組み込みパラメーター |
定義 |
|
$bizdate |
ビジネス日付、フォーマットは このパラメーターは広く使用されています。日次スケジューリングでは、ビジネス日付はデフォルトでタスクの期待実行日の前日になります。 |
|
$cyctime |
タスクのスケジュール時刻、フォーマットは |
|
$gmtdate |
現在の日付、フォーマットは このパラメーターはデフォルトで現在の日付になります。データをバックフィルする場合、入力日付は |
|
$bizmonth |
ビジネス月、フォーマットは
|
|
$jobid |
タスクが属するワークフローの ID。 |
|
$nodeid |
ノード ID。 |
|
$taskid |
ノードによって生成されたインスタンス ID。 |
付録
データバックフィル時のパラメーター置換
タスクがオペレーションセンターに送信された後、データをバックフィルして、データの修復、バックフィル、または遡及分析のために指定された日付範囲内の過去のタスクインスタンスをバッチ生成および実行できます。
-
ビジネス日付 ($bizdate)：データバックフィル中、選択したビジネス日付は $bizdate の置換結果と一致します。スケジューリングパラメーターが
${...}カスタムフォーマットを使用する場合、基本時間は選択された日付となり、その後、指定された時間式に従って変換されます。 -
スケジュール時刻 ($cyctime)：データバックフィル中、$cyctime の置換結果は
選択したビジネス日付 + 1日です。たとえば、データバックフィルに選択されたビジネス日付が
20250315の場合、データバックフィル中の$cyctimeパラメーターの置換結果は20250316000000です。スケジューリングパラメーターが$[...]フォーマットを使用する場合、基本時間は選択されたビジネス日付 + 1 となり、その後、指定された時間式に従って変換されます。
スケジューリングパラメーター、ビジネス日付、スケジュール時刻、および実際の実行時間の関係
|
関係タイプ |
説明と例 |
|
スケジューリングパラメーターと実際の実行時間の関係 |
スケジューリングパラメーターの置換値は、インスタンスが生成されるときに決定されます。したがって、置換値はインスタンスの実際の実行時間によって変化しません。 |
|
スケジューリングパラメーターとスケジュール時刻の関係 |
スケジューリングパラメーターが 例えば、現在のノードが、スケジュール時刻範囲が
|
|
スケジューリングパラメーター、ビジネス日付、スケジュール時刻の関係 |
|
夏時間に関する注意
DataWorks は、夏時間 (DST) の開始日と終了日にタスクが正しく実行されることを保証します。製品が DST の移行をどのように処理するかについての詳細は、「夏時間」をご参照ください。お住まいの地域で DST が実施されている場合、タスク実行への DST 移行による追加の複雑さを避けるために、このドキュメントを確認することを推奨します。
カスタムパラメーターの値の比較
このセクションでは、ODPS SQL ノードを例として使用します。タスクのスケジュール時刻が 2025年7月20日 10:30:00 であると仮定すると、次の表は ${…} と $[…] パラメーターの時間値構成を示しています。
|
時間値 |
${…} パラメーター |
$[…] パラメーター |
|
年を取得：2025 |
|
|
|
年を取得：25 |
|
|
|
年を取得：2024 |
|
|
|
月を取得：07 |
|
|
|
日を取得：20 |
|
|
|
日付を取得：2025年6月20日 |
重要 このアプローチは各月の日数を考慮する必要があるため、推奨されません。前月の同じ日付を取得するには、 |
|
|
日付を取得：2025年7月19日 |
|
|
|
日付を取得：2024年7月20日 |
重要 このアプローチはうるう年を考慮する必要があるため、推奨されません。前年の同じ日付を取得するには、 |
|
|
時間を取得：10:30:00 |
サポートされていません |
|
|
時間を取得：2025-07-20 10:30:00 |
サポートされていません |
|
|
時間を取得：2025-07-20 10:29:00 |
サポートされていません |
|
|
時間を取得：2025-07-20 09:30:00 |
サポートされていません |
|
|
前日の時間を秒単位で取得し、日付と時間の間にスペースを入れない： 2025071910:30:00 |
サポートされていません |
|
|
前日の時間を秒単位で取得し、日付と時間の間にスペースを入れる： 20250719 10:30:00 |
サポートされていません |
|