スケジューリングパラメーターは、DataWorks における動的なタスクおよび構成管理のためのコアメカニズムです。これにより、コード内で変数プレースホルダーを使用し、スケジューリング中に動的な値を挿入できます。これにより、定期タスクでハードコーディングされた日付を維持するという課題が解決され、ワークスペース、ワークフロー、ノードコンテキスト、ノードローカルの 4 階層のパラメーター階層を使用して構成がコードから分離されます。この分離により、さまざまな環境におけるタスクの柔軟性、再利用性、適応性が大幅に向上します。
本記事では、スケジューリングパラメーターの割り当てソースと式構文に焦点を当てています。本記事を読む前に、「スケジューリングパラメーターの構成と使用」で説明されている基本的な構成方法をよく理解しておいてください。
スケジューリングパラメーターのソース
ノード上でローカルに定義されたパラメーターを使用するだけでなく、コンテキスト、ワークフロー、およびワークスペースのパラメーターも使用できます。これらのソースを、範囲が狭いものから広いものの順に以下に示します。
-
ノードローカル定義 (現在のノード)
[スケジューリング構成] セクションの [スケジューリングパラメーター] エリアで定義されたパラメーターは、現在のノードにのみ適用されます。以下で詳述するように、豊富なパラメーター式をサポートしています。
-
コンテキストパラメーター (ノード間での受け渡し)
コンテキストパラメーターを使用して、上流ノードからの出力値を受け取ります。これにより、値が渡されるだけでなく、ノード間に依存関係が確立されます。このメソッドは、パラメーターの値が上流タスクの結果によって動的に決定される必要がある場合に使用します。パラメーター割り当てエリアの
アイコンをクリックすると、コンテキストパラメーターをすばやく追加できます。詳細については、「ノードコンテキストパラメーターの構成と使用」をご参照ください。 -
ワークフローパラメーター (ワークフロー内での共有)
ワークフローレベルで定義されたパラメーターは、そのワークフロー内のすべてのノードで使用できます。これらは、
${workflow.パラメーター名}のフォーマットを使用して直接参照できます。本記事で説明するパラメーター式のルールは、ワークフローパラメーターにも適用されます。 -
ワークスペースパラメーター (ワークスペース内での共有)
ワークスペースパラメーターは、ワークスペースレベルで定義されたグローバルパラメーターであり、そのワークスペース内のすべてのノードで使用できます。最も一般的な使用方法は、開発環境と本番環境の間で構成を区別することです。たとえば、開発環境では
db_nameという名前のパラメーターを値db_devで定義し、本番環境ではdb_prodで定義できます。スケジューリングパラメーターの値を設定する際に、[ワークスペースパラメーター] を直接選択できます。詳細については、「ワークスペースパラメーターの使用」をご参照ください。
パラメーター式
スケジューリングパラメーターは、パラメーター名とパラメーター値を指定することで割り当てロジックを定義します。パラメーター値は、時間パラメーター、組み込みシステムパラメーター、定数など、複数の形式をサポートしています。パラメーターが定義された後、${parameter name} 形式を使用してコード内で参照できます。
-
カスタム時間パラメーター：
${...}や$[...]などがあり、2 つの時間参照 (ビジネス日付とスケジュール時刻) に基づいて値を変換できます。詳細については、「時間パラメーター」をご参照ください。 -
組み込みシステムパラメーター：$bizdate、$bizmonth、$jobid などがあり、ビジネス日付、ビジネス月、ワークフロー ID などを取得するために使用できます。これらは時間関連の値に限定されません。詳細については、「組み込みスケジューリングパラメーター」をご参照ください。
-
定数：'
123'、'abc'など。
これらのうち、時間パラメーターはスケジューリングパラメーターの主要なユースケースです。タスク実行時にさまざまな時間文字列を動的に置き換えるために使用されます。
時間パラメーター
基本概念：時間参照
DataWorks のすべての動的な時間パラメーターは、以下の 2 つのコアな時間参照に基づいています。
|
概念 |
定義 |
パラメーター値 |
カスタムフォーマット |
時間精度 |
|
ビジネス日付 |
通常、タスクのスケジュールされた実行日の前日を指します。T+1 バッチコンピューティングのシナリオでは、ビジネスデータが生成された日付を表します。たとえば、今日タスクを実行して前日の収益を計算する場合、トランザクションが発生した日付である前日がビジネス日付となります。 |
|
|
年、月、日 |
|
スケジュール時刻 |
ノードの スケジューリング設定 セクションで cron 式 を介して構成された時刻を指します。タスクのランタイムでは、タスクインスタンスが実行されるようにスケジュールされている日に置き換えられます。秒単位で正確であり、実際の実行時間とは独立しています。 この時間はタスクの期待される実行時間を表し、実際の開始時刻と完全に一致しない場合があります。実際の開始時刻は複数の要因に影響されます。 |
|
|
年、月、日、時、分、秒 |
概要：
-
ビジネス日付 ≈ 昨日 (データの日付) =
$bizdate=${yyyymmdd} -
スケジュール時刻 ≈ 今日 (タスクが実行される時間) =
$cyctime=$[yyyymmddhh24miss]
典型的な T+1 タスクは次のように動作します：今日 (スケジュール時刻) の早朝にタスクがトリガーされ、昨日 (ビジネス日付) のデータを処理します。
基本時間パラメーターのデフォルトの戻り値が要件を満たさない場合は、${...} と $[...] を使用してカスタム時間パラメーターを定義できます。カスタム時間パラメーターは、2 つの基本時間参照を変換することによって導出されます。以下のメソッドがサポートされています：
カスタム式を使用してスケジューリングパラメーターに値を割り当てる際は、{...} と [...] の 2 つの括弧の形式を区別するようにしてください。この 2 つの形式は異なる基本時間参照を使用し、全く異なる値を返します。これらを混同すると、本番データの誤りを引き起こす可能性があります。
カスタム時間パラメーター
DataWorks は、${...} と $[...] を使用して、それぞれビジネス日付とスケジュール時刻を取得することをサポートしています。以下の変換タイプにより、ビジネス要件に合わせて時間値を柔軟に変更できます。以下の例では、スケジュール時刻が 02:30:45、ビジネス日付が 20251031 の日次スケジュールを想定しています。基本時間参照は次のとおりです：
-
ビジネス日付：${yyyymmdd}、例：20251031。
-
スケジュール時刻：$[yyyymmddhh24miss]、例：20251101023045。
重要スケジュール時刻は、タスクインスタンスが生成される際に固定される、あらかじめ設定されたスケジューリング時間です。リソース制約や上流ノードの状態によりタスクインスタンスが遅延した場合でも、スケジュール時刻はインスタンスの実際の実行時間とともに変更されません。
${...} と $[...] の主な違い
まず、この 2 つの主な違いを理解してください。${...} と $[...] は、時間参照と計算能力において根本的に異なります。この 2 つの形式を混同すると、データエラーを引き起こす可能性があります。
|
ディメンション |
|
|
|
時間参照 |
ビジネス日付 (T-1) |
スケジュール時刻 (T) |
|
時間精度 |
日 (年、月、日) |
秒 (年、月、日、時、分、秒) |
|
オフセット計算能力 |
年、月、週、日のオフセット計算をサポートします。 |
日、時、分のオフセット計算をサポートします。 |
|
主な制限事項 |
時、分、秒などのより小さな時間単位のフォーマットやオフセット計算はサポートしていません。 |
|
|
デフォルトの同等表現 |
|
|
時間フォーマット
波括弧 ${...} または角括弧 $[...] を、yyyy、yy、mm、dd とカスタムの組み合わせで使用して、ビジネス日付の前後の特定の日数、月数、年数の日付を取得する時間パラメーターを生成します。
|
コード |
説明 |
|
|
||
|
割り当て |
結果 |
割り当て |
結果 |
||
|
|
4桁の年 |
|
|
|
|
|
|
2桁の月 |
|
|
|
|
|
|
2桁の日 |
|
|
|
|
|
|
24時間形式の時 |
サポートされていません (日次精度) |
- |
|
|
|
|
12時間形式の時 |
- |
|
|
|
|
|
分 |
- |
|
|
|
|
|
2番目 |
- |
|
|
|
|
|
年と月 |
|
|
|
|
|
|
アンダースコアをデリミタとしてフォーマット |
|
|
|
|
|
|
ハイフンをデリミタとしてフォーマット |
|
|
|
|
|
|
ハイフンでフォーマットされ、時、分、秒を含む |
サポートされていません (日次精度) |
- |
サポートされているメソッドについては、「文字列連結：メソッド 2」をご参照ください。 |
|
オフセット計算
オフセット計算は動的パラメーターの中核です。ビジネス日付またはスケジュール時刻に値を追加または減算して、基本時間の N 年、月、日、時、分前後の日付と時刻を取得できます (時と分はスケジュール時刻でのみサポートされます)。${...} と $[...] は、基本時間参照の精度が異なるため、サポートする範囲が異なります。
-
${...}オフセット計算-
コア機能：年、月、週、日の整数オフセットをサポートします。
重要時または分のオフセット計算はサポートしていません。${yyyy-mm-dd-1/24} のような式はサポートされていません。
-
構文：
${<time format><±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関数を使用してください。 -
構文：
$[<time format><±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)]
翌月を取得：$[add_months(yyyy_mm,1)]N 週間前/後
週
$[yyyymmdd±7*N]前週を取得：
$[yyyymmdd±7*1]N 日前/後
日
$[yyyymmdd±N]昨日を取得：
$[yyyymmdd-1]N 時間前/後
時
この時間データは、以下のメソッドを使用して取得できます：
-
$[hh24miss±N/24],$[hh24±N/24] -
$[custom time format±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] -
$[custom time format±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 |
サポートされていません |
|