iii-cron-scheduling

Cron スケジューリング

類似：node-cron、APScheduler、crontab

主な概念

タスクに当てはまる場合は、以下の概念を使用してください。スケジュールされたジョブすべてに、これらすべてが必要なわけではありません。

• Cron 式は7 フィールド形式を使用します：second minute hour day month weekday year
• CronModuleは式を評価し、スケジュールに従ってトリガーを実行します
• ハンドラーは高速に処理できるようにしてください。cron ハンドラーをブロックするのではなく、負荷の高い処理はキューに登録します
• 各 cron トリガーは、1 つの式を 1 つの関数に関連付けます
• スケジュールが重複していても問題ありません。各トリガーは独立して実行されます

アーキテクチャ

CronModule timer tick
  → registerTrigger type:'cron' expression match
    → registerFunction handler
      → (optional) TriggerAction.Enqueue for heavy work

使用する iii プリミティブ

プリミティブ	目的
registerFunction	スケジュールされたジョブのハンドラーを定義します
registerTrigger({ type: 'cron' })	cron 式を関数に関連付けます
config: { expression: '0 0 9 * * * *' }	7 フィールド形式で cron スケジュールを指定します

参照実装

完全に動作する例として、../references/cron-scheduling.jsを参照してください。cron 式に従って繰り返し実行されるスケジュールタスクで、負荷の高い処理を任意でキューに登録できます。

Python版もあります：../references/cron-scheduling.py

Rust版もあります：../references/cron-scheduling.rs

よくあるパターン

このパターンを使用するコードには、関連する場合、一般的に以下が含まれます。

• registerWorker(url, { workerName }) — ワーカーを初期化します
• registerFunction(id, handler) — スケジュールされたハンドラーを定義します
• registerTrigger({ type: 'cron', config: { expression } }) — スケジュールを関連付けます
• trigger({ function_id, payload, action: TriggerAction.Enqueue({ queue }) }) — 負荷の高い処理を委譲します
• const logger = new Logger() — ジョブごとに構造化ログを記録します

このパターンの調整

タスクに当てはまる場合は、以下の調整を行ってください。

• スケジュールに合わせて 7 フィールド形式の式を調整します（例：6 時間ごとの場合は 0 0 */6 * * * *）
• cron ハンドラーは軽量に保ちます。重い処理を実行するのではなく、検証してキューに登録します
• 状態（例：最終実行時刻）が必要なジョブでは、iii-state-managementと組み合わせます
• 複数の cron トリガーから同じキューに登録し、ファンイン処理を行えます

エンジンの設定

CronModule は iii-config.yaml で有効にする必要があります。注釈付きの設定リファレンス全体については、../references/iii-config.yamlを参照してください。

パターンの適用範囲

• 繰り返しスケジュールではなく、単発の非同期処理に関するタスクでは、iii-queue-processingを優先してください。
• トリガーを時刻ではなく状態変化に応じて実行する場合は、iii-state-reactionsを優先してください。
• 主な要件が時間ベースの定期実行である場合は、iii-cron-schedulingを使用してください。

使用する場面

• タスクの主な内容が iii エンジンのiii-cron-schedulingに関するものである場合に、このスキルを使用します。
• リクエストでこのパターンまたは同等の実装が直接求められている場合に、トリガーされます。

適用範囲

• 無関係なタスクに対する汎用的な代替手段として、このスキルを使用しないでください。
• より具体的な iii スキルが適している場合は、このスキルを適用してはいけません。
• このスキルの例を適用する前に、必ず環境と安全性の制約を確認してください。