スケジュール実行

Braidrun のスケジューラーは 4 種類のトリガータイプに対応します: CRON（周期式）、INTERVAL（固定間隔）、ONE_TIME（一度きり）、DELAYED_COMPLETION（ワークフローのチェーントリガー）。すべての schedule はプラットフォームのスケジュールサービスによって一元管理され、サービス再起動後もそれぞれのスケジュールに従ってトリガーを継続します。

コンセプト: スケジュールと実行

1 つの schedule は「いつトリガーするか」を記述します。トリガーごとに 1 回の execution が作成されます。Schedule 自体は長期的なオブジェクトであり、execution は一度きりの実行記録です。Schedule は静的な inputs（キーと値のペア）を 1 セット持つことができ、トリガーのたびに execution の入力変数として使われます。

4 種類のスケジュールタイプ

4 種類のタイプは共通のフィールドセットを共有します: enabled（有効かどうか）、maxRuns（最大トリガー回数）、inputs（静的入力変数）。endTime を過ぎた場合、またはトリガー回数が maxRuns に達した場合、schedule は自動的に無効化されますが、削除はされません。

CRON schedule の作成

curl -X POST https://braidrun.com/api/schedules \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "<workflow-id>",
    "name": "Daily 9 AM report",
    "scheduleType": "CRON",
    "cronExpression": "0 9 * * *",
    "timezone": "Asia/Shanghai",
    "inputs": {
      "environment": "production"
    }
  }'

cron 式は 5 セグメント制です: 分 時 日 月 曜日。*、リスト（1,3,5）、区間（1-5）、ステップ（*/6）に対応します。日曜日は 0 または 7 と書けます。トリガー時刻は schedule 自身の timezone に基づいて計算されます。

INTERVAL: 固定間隔

リクエストボディは CRON と同様に POST /api/schedules に送信しますが、フィールドが異なるだけです。

{
  "workflowId": "<workflow-id>",
  "name": "每 5 分钟同步一次",
  "scheduleType": "INTERVAL",
  "interval": 300000,
  "startTime": 1785542400000,
  "endTime": 1788220800000,
  "maxRuns": 500
}

• interval — トリガー間隔、単位はミリ秒。1 秒未満の値は 1 秒に引き上げられます
• startTime / endTime — 任意、epoch ミリ秒のタイムスタンプ。startTime を設定するとその時刻まで待ってから開始し、endTime を過ぎると自動的に無効化されます
• maxRuns — 任意、この回数だけトリガーした後に自動的に無効化されます

ONE_TIME: 一度きり

{
  "workflowId": "<workflow-id>",
  "name": "上线前补跑一次",
  "scheduleType": "ONE_TIME",
  "startTime": 1785546000000
}

startTime は epoch ミリ秒のタイムスタンプです。時刻が来て 1 回トリガーした後、schedule は自動的に無効化されます。マルチインスタンス展開では、一度きりのロックにより 1 回だけトリガーされることが保証されます。

ワークフローのチェーンスケジュール（DELAYED_COMPLETION）

DELAYED_COMPLETION は 2 つのワークフローをチェーンにつなぎます: 上流ワークフロー A が COMPLETED 状態で終了するたびに、delaySeconds 秒待ってから、この schedule にバインドされたワークフロー B を自動的にトリガーします。典型的な使い方: データ取得ワークフローが完了して 10 分後にレポートワークフローを自動的に実行します。

{
  "workflowId": "<workflow-B-id>",
  "name": "A 完成 10 分钟后跑 B",
  "scheduleType": "DELAYED_COMPLETION",
  "triggerWorkflowId": "<workflow-A-id>",
  "delaySeconds": 600,
  "maxRuns": 10
}

• A が手動、Webhook、スケジュール、チェーンのいずれでトリガーされたかにかかわらず、正常に完了しさえすればカウントされます。失敗またはキャンセルされた実行は下流をトリガーしません
• delaySeconds — 必須、0 から 30 日（2592000 秒）。0 は完了後に即座にトリガーすることを意味します
• maxRuns — 入力しない場合は回数無制限です。1 を入力すると 1 回だけ連鎖します。N を入力すると最大 N 回連鎖し、達すると自動的に無効化されます
• triggerWorkflowId — workflowId と等しくすることはできません（自分自身をトリガーすると無限ループになります）。また、作成者は上流ワークフローに対する閲覧権限が必要です
• 待機中の遅延トリガーは永続化して保存され、サービス再起動やローリングリリースでも失われません。時刻が来ると通常どおりトリガーされます

schedule の管理

# 立即执行一次（返回这次 execution）
curl -X POST https://braidrun.com/api/schedules/<schedule-id>/run \
  -H "Authorization: Bearer <token>"

# 停用（enabled=true 则启用；不带参数则在两者间切换）
curl -X POST "https://braidrun.com/api/schedules/<schedule-id>/toggle?enabled=false" \
  -H "Authorization: Bearer <token>"

# 最近 50 条触发历史
curl "https://braidrun.com/api/schedules/<schedule-id>/history?limit=50" \
  -H "Authorization: Bearer <token>"

toggle の enabled は query パラメータまたは JSON body に入れられます。どちらも指定しない場合は、有効化 / 無効化の間で切り替わります。history の各レコードにはステータス、成否、開始 / 終了時刻が含まれ、limit はデフォルト 50、最大 500 です。

共有入力とパラメータプリセット

schedule に直接 inputs を設定するほか、ワークフローに「パラメータプリセット」を作成することもできます。同一の workflow を異なるプリセットで異なる設定で実行できます。

# 创建一个参数预设
curl -X POST https://braidrun.com/api/workflows/<wf>/presets \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "生产环境",
    "description": "生产环境参数",
    "variables": {
      "environment": "production",
      "debug_mode": "false",
      "max_retries": "3"
    }
  }'

# 用预设触发执行
curl -X POST https://braidrun.com/api/workflows/<wf>/presets/<id>/execute \
  -H "Authorization: Bearer <token>"

複数のワークフローバッチの同時実行

ワークフローリストから複数の項目を選択し、「同時実行」をクリックすると、一度にバッチ実行が開始されます。

• 選択した各ワークフローは独自の実行レコードを作成します
• maxConcurrency を超える実行は、最初に PENDING になります。
• 以前に実行中の実行が完了すると、キュー内の次の実行が自動的に RUNNING に変換されます。
• 0 制限がないことを示し、バッチ全体を同時に開始します

サービス再起動後の動作

• トリガーされた実行: 自動継続が有効になっていない限り、デフォルトは INTERRUPTED です (「再起動と自動再開）
• 時刻に達していない CRON / INTERVAL / ONE_TIME: 再起動後も通常どおりトリガーされます
• 待機中の DELAYED_COMPLETION 遅延トリガー: 永続化されており、再起動後も時刻が来るまで待ってトリガーされます
• ダウンタイム中のトリガーポイントの見逃し: メイクアップなし (二重書き込みのリスクを避けるため)

関連ページ

• Webhook トリガー
• サービス再起動後の自動再開