Cron Triggers

解決する課題

「毎時ログを集計したい」「毎晩キャッシュをクリアしたい」といった定期処理のために、常時稼働のサーバーやOSレベルのcronデーモンを維持するのは負担です。Cron Triggersは、この定期実行の仕組みをWorkers上でサーバーレスに提供します。

• 定期バッチのためだけにサーバーを立てっぱなしにしたくない
• 外部のHTTPエンドポイントを定期的に叩いて起こす運用（外形監視頼みの疑似cron）から脱したい
• 複数の時間帯・頻度で処理を分けたいが、管理する仕組みは1つにまとめたい
• デプロイパイプラインの一部として、スケジュール定義もコードと一緒にバージョン管理したい

主要概念と用語

• Cron Trigger: Workerに紐づけるスケジュール定義。標準的なcron式（分・時・日・月・曜日）で指定する
• scheduledハンドラー: Worker側で定期実行イベントを受け取るエントリーポイント。HTTPリクエストを受けるfetchハンドラーとは別に定義する
• ScheduledController: ハンドラーに渡されるイベント情報。実行がどのcron式によってトリガーされたか、予定時刻などを含む
• 複数Cron Triggers: 1つのWorkerに複数のcron式を割り当てられ、controller.cronの値で処理を分岐できる
• 手動テスト（Trigger Events）: ダッシュボードやAPIから、スケジュールを待たずにscheduledイベントを即時発火して動作確認できる機能

仕様・制限・クォータ

• スケジュールは標準的なcron構文（5フィールド）で記述する。秒単位の指定はできない
• 1つのWorkerに設定できるCron Triggersの数には上限があるが、通常のバッチ運用では十分な数が用意されている
• 実行時刻はUTC基準で評価される。ローカルタイム換算はコード側または式の指定で行う必要がある
• scheduledハンドラーの実行時間にも、通常のWorkers同様にCPU時間の上限が適用される
• 定期実行はat-least-onceに近い運用を前提とし、まれな遅延・スキップに備えて冪等な設計が推奨される
• Cron Triggerからの実行は外部からのHTTPリクエストではないため、fetchハンドラー向けのルーティングやアクセス制御とは独立して動作する

内部の仕組み

Cloudflareのスケジューラが、Workerに設定されたcron式を評価し、該当時刻になるとエッジ側でscheduledイベントを生成してWorkerのscheduledハンドラーを呼び出します。HTTPリクエストのfetchハンドラーとは呼び出し経路が異なり、外部からの直接アクセスによってscheduled処理が誤って起動することはありません。

• 同一Workerに複数のcron式がある場合、それぞれの式に合致した時刻で個別にイベントが発生する
• ハンドラーはevent.cron（式の文字列）やevent.scheduledTimeを参照し、どのスケジュールに対応する処理かを分岐できる
• 実行結果（成功/失敗）は他のWorkers実行と同様にログ・メトリクスとして記録される
• 内部では他のバインディング（KV、D1、R2、Queuesなど）を通常のWorkerコードと同じ作法で呼び出せる

設計パターン / ベストプラクティス

• 処理は冪等に書く。稀な重複実行やリトライが起きても副作用が二重に積み上がらないようにする
• 長時間かかる処理は、Cron Trigger自体で全部終わらせようとせず、Queuesなどへメッセージを渡して非同期に処理を分割する
• 複数スケジュールを1つのWorkerにまとめる場合は、event.cronの値で処理を明確に分岐し、意図しない処理の混線を避ける
• 実行時刻はUTC基準であることを前提に、日本時間などローカル基準のスケジュールが必要な場合は式の側で時差を考慮する
• 失敗時に気づけるよう、外部通知やログ集約と組み合わせておく

運用・監視

• 実行履歴やエラーはWorkersのログ・可観測性機能で確認できる
• 手動テスト機能で、本番のスケジュールに影響を与えずに処理内容を検証できる
• 失敗が続く場合は、下流で呼び出しているサービス（D1、外部APIなど)の制限やエラー応答を合わせて確認する
• cron式の変更はデプロイの一部として管理し、意図しないスケジュール変更が紛れ込まないようレビューする

コスト

Cron Triggerの起動自体に追加の固定費はかからず、起動されたscheduledハンドラーの実行は通常のWorkersのリクエスト数・実行時間の課金体系に含まれます。定期実行の頻度を上げるほどWorkersの実行回数が増える点は考慮しておく必要があります。

セキュリティ

• scheduledハンドラーは外部からのHTTPリクエストで直接起動されないため、fetchハンドラー向けの認証・認可の抜け穴にはならない
• 定期処理内で外部APIや他サービスの認証情報を使う場合は、環境変数やSecretsの仕組みを使い、コードに直書きしない
• 定期実行の対象リソース（削除・更新系の処理など）に対しては、誤動作時の影響範囲を最小化する設計（対象の絞り込み、ドライラン等）を検討する

関連サービス・比較

ハンズオン / CLI例

wranglerでプロジェクトの設定ファイルにCron Triggerを追加し、scheduledハンドラーの動作をローカルで確認する一連の流れです。

# wrangler.tomlにcron式を追加する例（設定ファイルを直接編集）
# [triggers]
# crons = ["0 0 * * *", "0 */6 * * *"]

# ローカル開発サーバーを起動
wrangler dev

# 別ターミナルから、ローカルのscheduledイベントを手動で発火してテスト
curl "http://localhost:8787/__scheduled?cron=0+0+*+*+*"

# 設定済みのCron Triggerを本番に反映してデプロイ
wrangler deploy

# デプロイ済みWorkerに設定されているCron Triggerを確認
wrangler triggers list