パラメータ化

パラメータについて

ジョブ実行をカスタマイズするには、ジョブ実行、タスク実行またはジョブ実行の動作を変更するパラメータを渡します。

ワークフローの3つの異なるレベル(ジョブ・レベル、タスク・レベルおよびジョブ実行レベル)でパラメータを指定できます。競合の場合、パラメータは次のように優先されます: 「ジョブ実行」→「タスク」→「ジョブ」。

ジョブ実行レベル・パラメータ:ジョブ実行ペイロードで指定されたジョブ実行レベル・パラメータは、ジョブ構成で定義されたタスク・レベル・パラメータよりも優先されます。これは、ジョブ実行中に指定されたパラメータによって、タスク固有のデフォルトが上書きされることを意味します。
タスク・レベル・パラメータ:特定のタスクのジョブ実行パラメータが指定されていない場合、タスクはジョブ構成のタスク・レベルで定義されたパラメータを使用します。同じ名前のジョブ・レベル・パラメータは、その特定のタスクのタスク・レベル・パラメータを上書きします。そのため、タスク固有のパラメータが必要な場合は、ジョブ・パラメータとは異なる名前を付ける必要があります。
ジョブ・レベル・パラメータ:タスク・レベル・パラメータもランタイム・パラメータも指定されていない場合は、ジョブ・レベルで設定されたデフォルト値が適用されます。ジョブ・レベルのパラメータはデフォルトとみなされ、これ以上特定のパラメータを使用できない場合に使用できます。

ノート:

ジョブ・パラメータはタスク・コンテキストでは不変です。これは、解決された値がJobParamRuntimeValueAのパラメータJobParamAを持つジョブが存在する場合、TaskAの実行でJobParamAの値を変更できないことを意味します。JobParamAの値は、すべてのタスクおよびジョブ実行全体に対してJobParamRuntimeValueAのままです。その結果、タスク間で情報を共有する場合は、中間ストレージまたは出力パラメータを使用して、それを実現できます。

タスク名、タスク値キー、またはジョブパラメータ名に特殊文字(!@$%など)が含まれている場合は、それらの識別子をバックティック(`)で囲む必要があります。識別子をバックティックで囲まずに使用できるのは、英数字とアンダースコアのみです。

たとえば:

{
  "VariableWithSpecialChars": "{{job.parameters.`param$@`}}"
}

システム・パラメータはテンプレート化されたパラメータで、その値はワークフロー実行および後続のタスク実行の一部としてシステムによって提供されます。これらのテンプレート・パラメータには、デフォルト値またはそれ以外の値を指定する必要はありません。AIデータ・プラットフォーム・ワークベンチには、ワークフローでサポートされている有効なテンプレート・パラメータ/動的値参照の固定リストがあります。システム・パラメータは、2つの中カッコで囲んで入力します。たとえば、{{job.id}}です。

表12-1サポートされているシステム・パラメータ

パラメータ	説明
お問い合わせ	ハブに割り当てられた一意の識別子。
お問い合わせ	ハブの領域
{{workspace.id}}	ワークスペースに割り当てられた一意な識別子
お問い合わせ	ワークスペースのURL
{{job.id}}	ジョブに割り当てられた一意な識別子
{{job.name}}	ジョブ実行時のジョブの名前
お問い合わせ	ジョブ実行に割り当てられた一意の識別子
{{job.repair_count}}	現在のジョブ実行での修復試行回数
{{job.start_time.[引数]}}	ジョブ実行が開始した時間に基づく値(UTCタイムゾーン)。戻り値は引数オプションに基づきます。日付と時刻の値については、「オプション」を参照してください。
{{ジョブ.パラメータ.[名前]}}	キー[name]を持つジョブ・レベル・パラメータの値
お問い合わせ	ジョブ実行のトリガー・タイプ。指定可能な値は、「手動」および「スケジュール済」です。
ご予約はこちら	このジョブにファイル到着トリガーが構成されている場合、記憶域の場所の値
{{job.trigger.time.[argument]}}	ジョブ実行がトリガーされた時間(UTCタイムゾーン)に基づく値で、cronスケジュールを持つジョブの最も近い分に切り捨てられます。戻り値は引数オプションに基づきます。日付と時刻の値については、「オプション」を参照してください。
{{タスク.名前}}	現在のタスクの名前です
{{タスク.実行_id}}	現在のタスク実行の一意の識別子
お問い合わせ	現在のタスクが実行された回数(再試行および修復を含む)
お問い合わせ	現在のノートブック・タスクのノートブック・パス
{{tasks.[task_name].run_id}}	[task_name]のタスク実行に割り当てられた一意の識別子
{{タスク.[タスク名].result_state}}	タスク[task_name]の結果の状態。使用可能な値は、success、failed、excluded、canceled、skipped、timed out、upstream_canceledおよびupstream_failedです。
{{tasks.[タスク名].error_code}}	タスクの実行中にエラーが発生した場合のタスク[task_name]のエラー・コード。可能な値の例として、RunExecutionError、ResourceNotFoundおよびUnauthorizedErrorがあります。成功したタスクの場合、これは空の文字列に評価されます。
{{タスク.[タスク名].execution_count}}	タスク[task_name]が実行された回数(再試行および修復を含む)
お問い合わせフォーム	ノートブック・タスク[task_name]のノートブックへのパス
{{tasks.[task_name].values.[value_name]}}	タスク[task_name]によって設定されたキー[value_name]を持つタスク値

表12-2日時のオプション

引数	説明
iso_weekday	タイム・スタンプの曜日を表す1から7までの数字を返します
is_weekday	タイムスタンプが平日の場合は`true`を返します
iso_date	日付をISO書式で返します
iso_datetime	ISO形式の日時を返します
年度	タイムスタンプの年の部分を戻します
月	タイムスタンプの月の部分を戻します
日	タイムスタンプの日部分を戻します
時間	タイムスタンプの時間部分を戻します
分	タイムスタンプの分の部分を戻します
秒	タイムスタンプの2番目の部分を返します
タイムスタンプ	ミリ秒単位のスタンプを返します。

タスクとノートブック間でパラメータを渡す

タスクからノートブックにパラメータを渡すことができ、その逆も可能です。これにより、動的なワークフロー動作が可能になり、ノートブックは実行時の値に基づいて処理を調整できます。

oidlUtils.parametersパッケージは、これらのパラメータ操作を処理するために必要な機能を提供します。oidlUtilsパッケージは、AI Data Platform Workbenchのユーティリティ・ライブラリで、パラメータ管理、タスク値の受渡し、その他のワークフロー操作などのタスクを簡略化します。ワークフロー・ステージ間でパラメータを取得および設定するために、ノートブックおよびタスクで一般的に使用されます。

タスク・キー値は文字列またはJSONです。たとえば、文字列をタスク・キー値として使用する場合、パラメータ・コールは次のようになります。

oidlUtils.parameters.setTaskValue(key="payload", value="abc", "defaultValue")

JSONをタスク・キー値として使用するには、パラメータ・コールは次のようになります。

oidlUtils.parameters.setTaskValue(key="payload", value=json.dumps(payload), "defaultValue")

ワークフローの例: パラメータを渡す

このシナリオでは、ワークフローに2つのノートブックがあります。ノートブック1は、タスクからパラメータを受信して処理し、次のタスクでノートブック2に渡される出力パラメータを設定します。

ノートブック1: パラメータの取得および設定

# Get parameter if already set in the task
param_key = "param1"
param_value = oidlUtils.parameters.getParameter(param_key, "defaultValue")
print(param_value)
print("Param {} value is {}".format(param_key, param_value))

 
# Set parameter value in the task
output_parameter_key = "output_parameter"
output_param_value = oidlUtils.parameters.getParameter(output_parameter_key, "defaultValue2")
print("Param {} value is {}".format(output_parameter_key, output_param_value))
oidlUtils.parameters.setTaskValue(output_parameter_key, "1234")

最初のノートブックでは、タスクから渡されたパラメータ(param1)が取得され、次のタスクで使用される新しいパラメータ(output_param_2)が設定されます。

ノートブック2: 出力パラメータの読取り

output_param_2= "output_parameter"
param_value = oidlUtils.parameters.getTaskValue("GetSetParameter", output_param_2, "defaultValue")
print("Param {} value is {}".format(output_param_2, param_value))

2番目のノートブックは、ワークフロー・タスクを介してノートブック1からoutput_param_2を受信し、処理します。

タスク1: ノートブック1
- 最初のタスクでは、ジョブまたはタスク自体からノートブック1にパラメータを渡すことができます。
- ノートブック1では、パラメータを入力パラメータparam1として処理し、新しい出力パラメータ(output_param_2など)を設定します。
タスク2: ノートブック2
- 2番目のタスクでは、ノートブック2は、ワークフローで設定された最初のタスク"GetSetParameter"の名前を渡して、前述のようにノートブック・コードで直接参照することで、タスク1から出力パラメータを受け取ります。
- output_param_2の値はノートブック2に渡され、今後の処理に使用できます。

このアプローチにより、タスクとノートブック間で動的に値を渡しやすくなり、ワークフローの柔軟性と適応性が向上します。