スケジューリングパラメーターは、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 つの形式は異なる基準時間を使用し、まったく異なる値を返すため、混同すると本番データのエラーを引き起こす可能性があります。
カスタム時間パラメーター
DataWorks では、${...} と $[...] を使用して、それぞれ業務日と予定時刻を取得できます。以下の変換タイプを使用すると、ビジネス要件に合わせて時刻値を柔軟に変更できます。以下の例では、予定時刻が 02:30:45、業務日が 20251031 の日次スケジュールを想定しています。基準時刻は次のとおりです。
業務日付： ${yyyymmdd}、例： 20251031。
スケジュール時刻： $[yyyymmddhh24miss]、例： 20251101023045。
重要スケジュール時刻は事前に設定された時刻であり、タスクインスタンスが生成されるときに固定されます。 タスクインスタンスがリソースの制約や上流ノードのステータスにより遅延した場合でも、スケジュール時刻はインスタンスの実際の実行時間とともに変更されることはありません。
${...} と $[...] の主な違い
まず、この 2 つの主な違いを理解してください。${...} と $[...] は、時間参照と計算機能において根本的に異なります。この 2 つの形式を混在させると、データエラーが発生する可能性があります。
ディメンション |
|
|
基準時間 | 業務日付 (T-1) | スケジュール時刻 (T) |
時間精度 | 日 (年、月、日) | 秒 (年、月、日、時、分、秒) |
オフセット計算能力 | 年、月、週、日のオフセット計算をサポートしています。 | 日、時、分のオフセット計算をサポートしています。 |
主な制限 | 時、分、秒などのより小さな時間単位の書式設定やオフセット計算はサポートしていません。 |
|
デフォルトの同等性 |
|
|
時間フォーマット
波括弧 ${...} または 角括弧 $[...] を、yyyy、yy、mm、および dd とカスタムの組み合わせで使用することで、業務日付を基準として特定の年数、月数、または日数だけ前後する日付を取得する時間パラメーターを生成できます。
コード | 説明 |
|
| ||
割り当て | 結果 | 割り当て | 結果 | ||
| 4 桁の年 |
|
|
|
|
| 2 桁の月 |
|
|
|
|
| 2 桁の日 |
|
|
|
|
| 24 時間形式の時 | 非対応 (日単位の精度) | - |
|
|
| 12 時間形式の時 | - |
|
| |
| 分 | - |
|
| |
| 秒 | - |
|
| |
| 年と月 |
|
|
|
|
| ハイフン区切りの書式 |
|
|
|
|
| ハイフン区切りで、時、分、秒を含む書式 | 非対応 (日単位の精度) | - | サポートされている方法については、「文字列連結」の例 2 をご参照ください。 | |
オフセット計算
オフセット計算は動的パラメーターの中核です。 業務日付または定刻に値を加算または減算することで、基準時間の数年、数ヶ月、数日、数時間、数分前後の日付と時刻を取得できます (時間と分は定刻でのみサポートされます)。 ${...} と $[...] は、基準時間参照の精度が異なるため、サポートする範囲が異なります。
${...}オフセットの計算コア機能： 年、月、週、日の整数オフセットをサポートしています。
重要時または分のオフセット計算はサポートしていません。
${yyyy-mm-dd-1/24}のような式は使用できません。構文は
${<time format><±N>}です。N は時間形式の最小単位に対応し、たとえば、形式が yyyymm の場合は月単位、yyyymmdd の場合は日単位となります。日付オフセット期間
オフセット単位
構文
例
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)]N 週間前後
週
$[yyyymmdd±7*N]先週を取得：
$[yyyymmdd±7*1]N 日前後
日
$[yyyymmdd±N]昨日を取得：
$[yyyymmdd-1]N 時間前後
時間
この時刻データは、次の方法で取得できます：
$[hh24miss±N/24]、$[hh24±N/24]$[カスタム時刻フォーマット±N/24]
様々な時刻書式で 1 時間前を取得：
月を取得:
$[mm-1/24]。年の取得:
$[yyyy-1/24]。年と月を取得:
$[yyyymm-1/24].年、月、日を取得：
$[yyyymmdd-1/24]。前日と 1 時間前を取得する:
$[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：各月の最初の日を動的に取得する
シナリオ: タスクが実行される日に関わらず、当月の 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 となり、その後、指定された時間式に従って変換されます。
スケジューリングパラメーター、ビジネス日付、スケジュール時刻、および実際の実行時間の関係
関係のタイプ | 説明と例 |
スケジューリングパラメーターと実際の実行時間の関係。 | スケジューリングパラメーターの置換値は、インスタンスが生成されたときに決定されます。したがって、置換値はインスタンスの実際の実行時間に応じて変更されません。 |
スケジューリングパラメーターとスケジュール時刻の関係。 | スケジューリングパラメーターが たとえば、現在のノードがスケジュール時刻範囲
|
スケジューリングパラメーター、ビジネス日付、およびスケジュール時刻の関係。 |
夏時間 (DST) に関する注意事項
DataWorks は、夏時間 (DST) が開始および終了する日にタスクが正しく実行されることを保証します。製品が DST 移行をどのように処理するかの詳細については、夏時間 (DST) をご参照ください。DST 移行によるタスク実行の追加の複雑さを回避するため、お住まいの地域で DST が実施されている場合は、このドキュメントを確認することを推奨します。
カスタムパラメーターの値の比較
このセクションでは、ODPS SQL ノードを例として使用します。タスクのスケジュール時刻が 2025 年 7 月 20 日 10:30:00 であると仮定した場合、以下の表は ${…} および $[…] パラメーターの時間値設定を示しています。
時間値 | ${…} パラメーター | $[…] パラメーター |
年を取得：2025 |
|
|
年を取得：25 |
|
|
年を取得：2024 |
|
|
月を取得：07 |
|
|
日を取得：20 |
|
|
日付を取得：2025 年 6 月 20 日 |
重要 このアプローチは各月の日数を考慮する必要があるため、推奨しません。前月の同じ日を取得するには、 |
|
日付を取得：2025 年 7 月 20 日 |
|
|
日付を取得：2024 年 7 月 20 日 |
重要 このアプローチはうるう年を考慮する必要があるため、推奨しません。前年の同じ日を取得するには、 |
|
時刻を取得：10:30:00 | サポートされていません。 |
|
時刻を取得：2025-07-20 10:30:00 | サポートされていません。 |
|
時刻を取得：2025-07-20 10:29:00 | サポートされていません。 |
|
時刻を取得：2025-07-20 09:30:00 | サポートされていません。 |
|
前日の時刻を秒単位の精度で取得し、日付と時刻の間にスペースなしで： 20250719103000 | サポートされていません。 |
|
前日の時刻を秒単位の精度で取得し、日付と時刻の間にスペースを入れて： 20250719 10:30:00 | サポートされていません。 |
|