Skip to main content
Schedules

Schedule データ構造

Forward Schedule API で共有する Schedule と Schedule Run のレスポンス構造。

Schedule オブジェクト

作成、取得、一覧、更新、アーカイブ、一時停止、再開の各 API はこの構造を返します。
フィールド型説明
idstringsched_ で始まる Schedule ID。
sourcestringサーバーが記録する正式な作成方法。現在は api または tool。作成元を参照してください。
source_session_idstring | null作成元の Session。api では null、tool では空でない sess_*。
identity_idstringSchedule を所有する Forward Identity ID。
template_idstring実行に使用する Forward Template ID。
namestringSchedule 名。
descriptionstringSchedule の説明。未設定の場合は空文字列。
statusstringactive または paused。アーカイブ状態は archived_at で表します。
paused_reasonobject | null一時停止の理由。一時停止していない場合は null。
initial_eventsarray各実行に注入される初期イベント。
initial_events_versioninteger1 から始まる読み取り専用の入力内容バージョン。入力バージョンを参照してください。
resourcesarraySchedule 専用のファイル設定。file_id 順で、未設定時は []。構造と適用規則はファイルリソースを参照してください。
executionobject実行ポリシー。実行ポリシーを参照してください。
trigger_policyobjectトリガーポリシー。トリガーポリシーを参照してください。
environment_idstring実行環境 ID。
sinksarray結果の配信先。未設定の場合は []。
metadataobject呼び出し元の業務メタデータ。
archived_atstring | nullRFC 3339 形式のアーカイブ日時。未アーカイブの場合は null。
created_atstringRFC 3339 形式の作成日時。
updated_atstringRFC 3339 形式の最終更新日時。

実行ポリシー

フィールド型説明
session_modestringnew_session または reuse_session。
max_concurrent_runsinteger同一 Schedule の最大同時 Run 数。
max_attemptsinteger単一 Run の最大試行回数。現在は 1 または 2。
timeout_msinteger1 回の試行のタイムアウト（ミリ秒）。

トリガーポリシー

フィールド型説明
typestringcron、once、interval、または manual。
expressionstringトリガー式。manual では空文字列または省略。
timezonestringIANA タイムゾーン。該当しない場合は空文字列または省略。
start_atstring任意の実行期間の開始日時（RFC 3339）。
stop_atstring任意の実行期間の終了日時（RFC 3339）。
upcoming_runs_atarrayUTC ISO 8601 形式の今後のトリガー日時。現在は [] または最大 1 件。
last_run_atstring | null直近のトリガー日時。
sinks の公開形式と制約はスケジュールを作成するを参照してください。

ファイルリソース

Schedule の作成・更新時は、トップレベルの resources 配列でファイルを指定します。形式は Session、Batch のファイルリソースと同じです。まず File をアップロードして file_id を取得し、現在の呼び出し元がその Schedule の Identity の下でアクセスできる Forward File を参照します。 
{
  "resources": [
    {
      "type": "file",
      "file_id": "file_news_sources",
      "mount_path": "/data/news-sources.csv"
    }
  ]
}
フィールド型必須説明
typestringはい現在は file のみをサポートします。
file_idstringはいFiles API が返すファイル ID。不透明な文字列として扱い、固定プレフィックスは必要ありません。空文字列や制御文字は許可されません。
mount_pathstringいいえAgent コンテナー内のファイルパス。明示する場合は正規の絶対パスで、/ や制御文字を含むパスは不可、最大 1024 バイトです。
各要素には上記フィールドのみを指定でき、enabled などの追加フィールドは受け付けません。最大 100 ファイルまで指定できます。同じ配列内で file_id を重複させたり、異なるファイルに同じマウントパスを明示指定したりすることはできません。トップレベルの files パラメーターは受け付けません。 mount_path を省略するか空文字列にすると /data/workspace/<filename> を使用します。同名ファイルには異なるパスを明示してください。同じファイルが Template / Identity Config ですでに設定されている場合、Schedule のパスを省略すると継承パスを使用します。

作成と更新

リクエストの resourcesSchedule の作成Schedule の更新
省略専用ファイルを設定しません。既存の設定を保持します。
null または []専用ファイルを設定しません。専用ファイル設定をすべてクリアします。
空でない配列配列内のファイルを設定します。専用ファイル設定全体を置き換え、要素単位ではマージしません。
完全な Schedule レスポンスは、既存 Schedule の [] を含め、常に resources 配列を返します。これは Schedule 自身の設定のみを表し、Template / Identity Config から継承したファイルは含みません。省略されたマウントパスがここで実行時パスに補完されることもありません。resources の変更では initial_events_version は増加せず、このバージョンは initial_events のみを表します。

継承と適用タイミング

実行時に Schedule ファイルと現在の Template / Identity Config のファイルをマージします。同じ file_id は重複排除されます。Schedule がパスを省略した場合や継承パスと同じパスを明示した場合は再利用できますが、異なるパスを明示すると競合します。異なるファイルが同じパスを使用することはできません。継承設定とのマージ後にしか検出できない競合は、実行時のタスクメッセージ送信前にエラーになります。 new_session と reuse_session の両方でファイル設定をサポートします。各実行試行は Session の作成またはタスク送信前に、その試行の Schedule 専用 resources を選択します。同じ attempt 内の送信再試行・復旧では選択済みの専用ファイル設定を使い、新しい attempt では更新後の設定を選択できます。更新は現在の実行を中断しません。後続の実行では選択された追加・削除・パス変更が適用され、Session の再利用時にも同期されます。Template / Identity Config の継承ファイルはこのスナップショットに含まれず、現在の設定で引き続き更新されます。 Schedule ファイルをクリアしても、継承ファイルの削除や Template / Identity Config の変更は行われません。ファイルをマウントしても内容は initial_events に自動挿入されません。タスクはメッセージでマウントパスを指定してファイルを読み取れます。例：Read /data/news-sources.csv and summarize its contents。

ファイル削除の制限

未アーカイブの Schedule（一時停止中も含む）がファイルを参照している場合、File の削除は HTTP 409 を返します。ファイル設定の更新・クリア、または Schedule のアーカイブにより、その設定参照が解放されます。まだ終端状態に達していない Run が選択したファイルは Run が終了するまで保護されます。他の Template / Identity Config または Session の参照によって、引き続き削除できない場合もあります。

Schedule Run オブジェクト

手動実行、Run の取得、Run の一覧 API はこの構造を返します。
フィールド型説明
idstringsrun_ で始まる Schedule Run ID。
sourcestring親 Schedule の正式な作成方法。現在は api または tool。作成元を参照してください。
source_session_idstring | null親 Schedule の作成元 Session。
schedule_idstring親 Schedule ID。
identity_idstringForward Identity ID。
template_idstringForward Template ID。
session_idstring | null今回の実行で作成または使用された Session。
statusstringpending、running、completed、failed、または skipped。
trigger_contextobject今回の Run のトリガー方法。Trigger Contextを参照してください。
errorobject | null失敗またはスキップ時の構造化エラー。
result_payloadstring | nullメイン実行のテキスト結果。
error_messagestring | null表示用エラーメッセージ。構造化情報は error に保持されます。
push_sinkstring | null今回の IM 配信に使用する Sink タイプ。未設定の場合は null。
push_statusstringIM 配信状態：pending、succeeded、failed、または skipped。
push_finished_atstring | nullIM 配信の終了日時。
attemptinteger現在または最終的な試行回数。1 から開始します。
initial_events_versioninteger（任意）現在の実行試行で選択された入力バージョン。未選択または確認できない場合は省略します。入力バージョンを参照してください。
initial_eventsarray（任意）単一 Run の取得で include_initial_events=true を指定した場合のみ、現在の試行にバインドされた入力を返します。不明な場合は省略します。入力スナップショットの取得を参照してください。
triggered_atstringRFC 3339 形式のトリガー日時。
started_atstring | nullRFC 3339 形式の実行開始日時。
completed_atstring | nullRFC 3339 形式の実行終了日時。
duration_msinteger | null実行時間（ミリ秒）。
created_atstringRFC 3339 形式のレコード作成日時。
メイン実行の status と IM 配信の push_status は独立しています。Schedule に execution.max_attempts=2 が設定されている場合、同一 Run が最終的に attempt=2 を返す可能性があります。

Identity の有効・無効とスケジュール

Identity が無効な間は新しい Schedule 実行を開始せず、未開始の Run は skipped として記録される場合があります。受け付け済みの実行と結果配信はそのまま完了します。再有効化後、定期タスクは今後のトリガー時刻から再開し、逃したトリガーを再実行しません。期限切れの単発トリガーは skipped Run を保持し、通常どおりアーカイブされます。手動で一時停止、アーカイブ、削除した Schedule は復元されません。Identity の有効化を参照してください。

入力バージョン

initial_events_version はサーバーが管理するため、作成・更新リクエストには指定しません。新規 Schedule は 1 から開始し、正規化後の initial_events の内容が実際に変わった場合のみ増加します。同じ内容の送信や、resources、名前、実行ポリシー、トリガーポリシーの変更では増加しません。以前の内容に戻した場合も新しいバージョンになります。既存 Schedule の現在の入力は 1 を基準とし、過去のバージョンは復元しません。 Run の作成時には入力はまだ紐付けられません。各 attempt で初めて入力を送信する前に、実行器が対応する内容とバージョンを Run に紐付けます。同じ attempt 内の送信リトライや復旧では、この紐付けを再利用します。新しい attempt では更新後の入力を選択できます。バージョンは attempt と合わせて解釈してください。フィールドの存在は入力が選択済みであることを示すだけで、ランタイムによる受信や実行の成功を意味しません。 入力未選択の pending、skipped Run、および実行入力を確認できない過去の Run では、このフィールドを省略します。不明なバージョンを 0 として返すことはなく、現在の Schedule のバージョンで補完することもできません。クライアントは追加フィールドを許容し、欠落したバージョンを不明として扱ってください。 Schedule の作成・更新後に schedule_id、initial_events_version、入力内容の対応を保存し、Run または Webhook コールバックのバージョンから実行入力を関連付けられます。現在の Schedule が返すのは最新設定であり、開始済み Run の設定と異なる場合があります。 Schedule Run の取得で include_initial_events=true を指定すると、現在の Schedule 設定に依存せず、その試行で選択された入力を確認できます。

作成元

source と source_session_id は読み取り専用フィールドで、v1/v2 の完全な Schedule および Schedule Run レスポンスに常に含まれます。
sourcesource_session_id意味
apinull公開 Schedule API で作成。
tool空でない sess_*Forward の管理対象ツールで作成。作成ツール呼び出しを開始した対話 Session を示します。
作成元はサーバーが記録します。作成・更新リクエストでは設定できず、作成元によるフィルタリングもサポートしません。metadata.source は変更可能な業務メタデータであり、正式な作成元を表しません。 Schedule Run は親 Schedule の作成元を継承します。今回のトリガーが手動か自動か、sinks が設定されているかには依存しません。過去の Run やアーカイブ済み Schedule の Run にも適用されます。Run の session_id は今回の実行 Session、trigger_context.type は今回のトリガー方法を示します。作成元 Session は reuse_session の実行先の紐付けを表すものではなく、内部的な作成元への結果配信先も公開の作成元としては扱いません。 作成元フィールドは後方互換性のある JSON フィールドの追加です。クライアントは未知のフィールドを許容してください。サービスのデプロイ後は、過去の Schedule と Run の取得レスポンスにも作成元フィールドが含まれ、データのバックフィルは不要です。

Trigger Context

type説明
scheduleSchedule のトリガーポリシーによる自動実行。scheduled_at を含みます。
manualRun Schedule API による手動実行。

Run Error

status=failed または status=skipped の場合に error が返ることがあります。status=completed では null です。
error.type説明
concurrency_limit_reached同一 Schedule の最大同時 Run 数に達しています。今回のトリガーは記録されますが実行されません。
session_creation_failedForward Session の作成または紐付けに失敗。
execution_failedTemplate の実行に失敗。