Skip to main content

スケジュールを更新する

Forward Schedule を更新します。

POST /api/v1/forward/schedules/{schedule_id} このページは HTTP 更新 API の説明です。会話で名前・実行内容・時間ルールを変更するには、自然言語による Schedule の変更を使用できます。ツールの instruction と trigger_policy サブフィールドのパッチセマンティクスは、この HTTP リクエストボディには含まれません。 merge-patch セマンティクスを使用します。リクエストに含まれるフィールドは更新され、省略されたフィールドは変更されません。

Headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT または SAT>
Content-TypeYesapplication/json
Idempotency-KeyNo安全でないリクエスト向けの任意のべき等キー。

Path parameters

ParameterTypeRequiredDescription
schedule_idstringYesForward Schedule ID。

Body parameters

ParameterTypeRequiredDescription
namestringNo新しい Schedule 名。
descriptionstringNo新しい Schedule の説明。
template_idstringNo新しい Forward Template ID。
initial_eventsarrayNo初期イベントリストを置き換えます。
resourcesarray|nullいいえSchedule 専用ファイル。省略時は保持、null または [] でクリア、配列は全体を置き換えます。最大 100 件。構造はファイルリソースを参照してください。
executionobjectNo実行ポリシーをマージ更新します。
trigger_policyobject|nullNoトリガーポリシーを更新します。null は manual に変更します。
environment_idstringNo新しい実行環境。
sinksarray|nullNo実行結果の配信先。互換性のため配列形式を維持し、現在は最大 1 件を指定できます。
metadataobjectNoメタデータをマージ更新します。null 値はメタデータキーを削除します。

Trigger policy

trigger_policy は型付きオブジェクトです。作成および更新リクエストでは、設定フィールドである type、expression、timezone のみを受け付けます。null を渡すと Schedule は {"type":"manual"} に変更されます。upcoming_runs_at と last_run_at は Forward が算出するレスポンス専用フィールドです。
FieldTypeRequiredDescription
typestringYescron、once、interval、または manual。
expressionstringConditionalトリガー式。cron、once、interval では必須。manual では不要です。
timezonestringConditionalAsia/Shanghai などの IANA タイムゾーン。cron では必須。once では expression にオフセットがない場合のみ必須。interval と manual では任意です。
upcoming_runs_atarrayResponse onlyUTC ISO 8601 形式の今後のトリガー時刻。現在の実装では [] または次回の予定時刻のみを返します。
last_run_atstring|nullResponse only直近のトリガー時刻。
typeRequired inputDescription
crontype, expression, timezone指定した IANA タイムゾーンで 5 フィールドの cron 式に従って繰り返します。
oncetype, expression, optional timezoneISO 8601 時刻に 1 回実行します。式にオフセットがない場合は timezone が必須です。
intervaltype, expressionPT15M などの ISO 8601 期間に従って繰り返します。
manualtype自動的には実行されません。Run Schedule エンドポイントでトリガーします。
typeexpression formatExampleNotes
cron標準の 5 フィールド cron0 9 * * *分単位のカレンダースケジュール。秒および 6 フィールドの cron はサポートされません。
onceISO 8601 絶対時刻2026-06-23T09:00:00 または 2026-06-23T01:00:00Z対象時刻はサーバーの現在時刻より後である必要があります。1 回限りのタスクには 1 分の最小間隔制限はありません。
intervalISO 8601 期間PT15M、PT1H、P1D固定間隔スケジュール。最小間隔は 1 分です。
manual省略または空-スケジュール実行を作成しません。

Execution policy

execution はマージ更新されます。省略されたフィールドは現在の値を保持します。
FieldTypeDefaultDescription
session_modestringnew_sessionnew_session または reuse_session。
max_concurrent_runsinteger1この Schedule の最大同時実行数。
max_attemptsinteger1単一 Run の実際の試行回数上限。許容値は 1 または 2。範囲外の値は拒否されます。
timeout_msinteger3000001 回の試行のタイムアウト。
session_modeDescription
new_sessionトリガーごとに新しい実行 Session を作成します。以前のコンテキストは再利用されません。
reuse_sessionForward がこの Schedule 用に固定された 1 つの実行 Session を管理し、トリガー間で再利用します。呼び出し側が任意の既存 session_id を指定することはできません。
max_attempts=2 は、同一の Schedule Run が最初の実行に失敗した後、サーバーが自動的に最大1回再試行することを意味します。再試行されるかどうかはサーバーが失敗タイプに基づいて判断します。パラメータエラー、権限エラー、同時実行制限、タイムアウト、接続中断などのシナリオでは再試行が保証されません。クライアントは Schedule Run の attempt フィールドで実際の試行回数を確認できます。 更新時に execution を省略、execution=null を渡す、空オブジェクトを渡す、または max_attempts を含まない部分的な execution を渡す場合、現在の max_attempts 値が保持されます。execution.max_attempts=null を明示的に渡すとパラメータ型エラーとして処理され、デフォルト値へのリセットを意味しません。

ファイルリソース

resources は Schedule 専用のファイル設定全体を置き換え、file_id 単位ではマージしません。省略時は現在の値を保持し、null または [] でクリアします。空でない配列の各要素には type: "file" と file_id が必須で、mount_path は任意です。ファイルは事前にアップロード済みで、現在の呼び出し元がアクセスできる必要があります。 例えば、専用ファイルをクリアする場合は次を送信します。
{
  "resources": []
}
resources を変更しても initial_events_version は増加せず、現在の実行も中断しません。後続の実行では選択したファイルの追加・削除・パス変更が適用され、reuse_session でも同期されます。クリアしても Template / Identity Config の継承ファイルは削除されません。詳細はファイルリソースを参照してください。

配信先

sinks は互換性のため配列形式を維持しており、現在は最大 1 件を指定できます。各要素は次の公開形式のいずれかにする必要があります。
{
  "type": "im_channel",
  "channel_id": "channel_xxx",
  "target": {
    "type": "user",
    "external_id": "536769"
  }
}
{
  "type": "im_channel",
  "channel_id": "channel_xxx",
  "target": {
    "type": "group",
    "external_id": "cid_group_123"
  }
}
target にはチャネル固有のユーザーまたはグループの external_id を指定します。thread と topic はサポートしません。 チャネルの IM 会話で /target を送信すると、その会話の target 設定を取得できます。 sinks を省略すると現在の値を保持し、null または [] を渡すと削除し、要素を 1 件渡すと置換します。配信失敗は対応する Run の push_status に記録されます。

Pair モードの配信

まずペアリングを完了し、ペアリングの一覧から状態が active のレコードの id を取得して、sinks の channel_pairing_id に設定します:
{
  "sinks": [
    {
      "type": "im_channel",
      "channel_pairing_id": "pair_019eabc123"
    }
  ]
}
結果は、そのペアリングにバインドされた個人チャットまたはグループチャットに送信されます。Schedule の identity_id と template_id はペアリングと一致する必要があります。ペアリングを解除すると、そのバインディングへの配信は停止します。

Example request

curl -s -X POST 'https://api.qoder.com/api/v1/forward/schedules/sched_019f00112233445566778899aabbccdd' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Weekday tech brief",
  "resources": [
    {
      "type": "file",
      "file_id": "file_weekday_sources",
      "mount_path": "/data/news-sources.csv"
    }
  ],
  "trigger_policy": {
    "type": "cron",
    "expression": "0 9 * * 1-5",
    "timezone": "Asia/Shanghai"
  },
  "execution": {
    "max_attempts": 2
  },
  "sinks": [
    {
      "type": "im_channel",
      "channel_id": "channel_xxx",
      "target": {
        "type": "user",
        "external_id": "536769"
      }
    }
  ]
}'

Example response

HTTP 200 OK
{
  "id": "sched_019f00112233445566778899aabbccdd",
  "source": "api",
  "source_session_id": null,
  "identity_id": "idn_019eabc123",
  "template_id": "tmpl_support",
  "name": "Weekday tech brief",
  "description": "Generate a daily technology news summary",
  "status": "active",
  "resources": [
    {
      "type": "file",
      "file_id": "file_weekday_sources",
      "mount_path": "/data/news-sources.csv"
    }
  ],
  "initial_events_version": 1,
  "initial_events": [
    {
      "type": "user.message",
      "content": "Read /data/news-sources.csv and summarize current technology news in five bullet points."
    }
  ],
  "execution": {
    "session_mode": "new_session",
    "max_concurrent_runs": 1,
    "max_attempts": 2,
    "timeout_ms": 300000
  },
  "trigger_policy": {
    "type": "cron",
    "expression": "0 9 * * 1-5",
    "timezone": "Asia/Shanghai",
    "upcoming_runs_at": [
      "2026-06-23T01:00:00Z"
    ]
  },
  "environment_id": "env_019e64e01a137caf953ac2ac7b42ec5c",
  "sinks": [
    {
      "type": "im_channel",
      "channel_id": "channel_xxx",
      "target": {
        "type": "user",
        "external_id": "536769"
      }
    }
  ],
  "metadata": {},
  "created_at": "2026-06-22T10:00:00Z",
  "updated_at": "2026-06-22T10:30:00Z"
}

Response fields

更新後の Schedule オブジェクトを返します。

Errors

HTTPTypeCode発生条件
400invalid_request_errorinvalid_trigger_policyトリガーポリシーが不正です。
400invalid_request_errortrigger_policy_too_frequent更新後の cron のトリガー粒度または interval の間隔が 1 分未満です。
400invalid_request_errortrigger_policy_time_too_soon更新後の once の対象時刻または指定した stop_at がサーバーの現在時刻以前です。
400invalid_request_errorinvalid_request名前・説明・初期イベント・実行ポリシーが不正、文字列に未対応の制御文字が含まれる、または新しい Template / Environment が存在しない・アクセス不可・利用できない状態です。または、ファイル数が上限を超える、ID / マウントパスが不正、ID / 明示的なパスが重複する、参照ファイルが存在しない・アクセス不可・File ではありません。
400invalid_request_errorinvalid_request_bodyリクエストボディが空、JSON 構文またはフィールドの型が不正、resources の構造またはフィールドの型が不正、要素に未知のフィールド(enabled など)が含まれる、またはトップレベルの files が指定されています。
400invalid_request_errorunsupported_sinks_inputsinks の数・型・フィールドが不正、または固定 Channel が利用不可、もしくは最終的な Identity/Template と一致しません。
404not_found_errorschedule_not_foundSchedule が存在しないか、現在の owner に属していません。
409invalid_request_errorschedule_archivedSchedule はアーカイブ済みです。
401authentication_error-PAT または SAT が無効または期限切れです。
403permission_erroridentity_mismatchIdentity-bound SAT が、バインドされた Identity 以外の Schedule を要求または操作しています。

Notes

  • 正規化後の initial_events の内容が実際に変わった場合のみ、レスポンスの initial_events_version が増加します。省略や同一内容の送信では増加しません。入力バージョンを参照してください。
  • レスポンスの resources は更新後の Schedule 自身のファイル設定のみを file_id 順で含み、クリア後は [] を返します。
  • sinks を省略すると現在の値を保持し、null または [] を渡すと削除します。これにより、null 許容フィールドのシリアライズに対応します。
  • reuse_session は Forward がこの Schedule 用に固定された実行 Session を管理することを意味します。呼び出し側が任意の既存 session_id を指定することはできません。