Cron Triggers

Cron Triggers は、cron 式を scheduled() ハンドラー を使う Worker に対応付け、Worker をスケジュールで実行できるようにします。

Cron Triggers は、メンテナンスや、第三者 API を呼び出して最新データを集めるなど、定期ジョブに向いています。Cron Triggers でスケジュールされた Workers は、稼働に余裕のあるマシンで実行され、Cloudflare の容量を活かし、トラフィックを効率よく振り分けます。

Cron Triggers は UTC で実行されます。

Cron Trigger に応答するには、Worker に "scheduled" ハンドラー を追加します。

export default {
	async scheduled(controller, env, ctx) {
		console.log("cron processed");
	},
};

interface Env {}
export default {
	async scheduled(
		controller: ScheduledController,
		env: Env,
		ctx: ExecutionContext,
	) {
		console.log("cron processed");
	},
};

from workers import WorkerEntrypoint

class Default(WorkerEntrypoint):
    async def scheduled(self, controller, env, ctx):
        # All four parameters (self, controller, env, ctx) are required
        print("cron processed")

コードの書き方は、次の追加例も参照してください。

• Cron Triggers を設定する
• 複数の Cron Triggers

Worker のコードに "scheduled" イベントを追加したら、Worker プロジェクトの設定も更新します。

Worker を Wrangler で管理している場合、Cron Triggers は Wrangler 設定ファイル だけで管理します。

Cron Triggers の設定例は次のとおりです。

{
	"triggers": {
		// Schedule cron triggers:
		// - At every 3rd minute
		// - At 15:00 (UTC) on first day of the month
		// - At 23:59 (UTC) on the last weekday of the month
		"crons": [
			"*/3 * * * *",
			"0 15 1 * *",
			"59 23 LW * *"
		]
	}
}

[triggers]
crons = [ "*/3 * * * *", "0 15 1 * *", "59 23 LW * *" ]

Wrangler 設定ファイル では、環境 ごとに異なる Cron Trigger も設定できます。選んだ環境の下に triggers 配列を置きます。例:

{
	"env": {
		"dev": {
			"triggers": {
				"crons": [
					"0 * * * *"
				]
			}
		}
	}
}

[env.dev.triggers]
crons = [ "0 * * * *" ]

Cloudflare ダッシュボードで Cron Triggers を追加する手順は次のとおりです。

1. Cloudflare ダッシュボードで、Workers & Pages ページを開きます。

   Workers & Pages を開く ↗

2. Overview で Worker を選び、Settings > Triggers > Cron Triggers を開きます。

Cloudflare は 5 フィールドの cron 式と、Quartz scheduler ↗ に近い cron 構文拡張の多くをサポートします。

Cron Trigger の設定に使える、よくある時間間隔です。

• * * * * *

  • 毎分

• */30 * * * *

  • 30 分ごと

• 45 * * * *

  • 毎時 45 分

• 0 17 * * sun または 0 17 * * 1

  • 日曜日の 17:00（UTC）

• 10 7 * * mon-fri または 10 7 * * 2-6

  • 平日の 07:10（UTC）

• 0 15 1 * *

  • 毎月 1 日の 15:00（UTC）

• 0 18 * * 6L または 0 18 * * friL

  • 毎月最終金曜日の 18:00（UTC）

• 59 23 LW * *

  • 毎月最終平日の 23:59（UTC）

Cron Triggers は、Wrangler の wrangler dev、または Cloudflare Vite plugin ↗ でテストできます。/cdn-cgi/local/scheduled ルートが公開され、HTTP リクエストでテストできます。Cloudflare Vite Plugin を使っている場合は、次のコマンドで正しい Vite のポートを使ってください（Vite のデフォルトは 5173 です）。

curl "http://localhost:8787/cdn-cgi/local/scheduled"

デフォルトでは、エンドポイントは scheduled ハンドラーの結果をテキストで返します。構造化された結果を JSON で返すには、?format=json を付けます。

curl "http://localhost:8787/cdn-cgi/local/scheduled?format=json"

{
  "outcome": "ok",
  "noRetry": false
}

noRetry フィールドは、scheduled ハンドラーが controller.noRetry() を呼び出したときに true になります。

異なる cron パターンをシミュレートするには、cron クエリパラメーターを渡せます。

curl "http://localhost:8787/cdn-cgi/local/scheduled?cron=*+*+*+*+*"

任意で time クエリパラメーターを渡し、scheduled イベントリスナーの controller.scheduledTime を上書きすることもできます。

curl "http://localhost:8787/cdn-cgi/local/scheduled?cron=*+*+*+*+*&time=1745856238000"

Cron Triggers の実行履歴を見るには、Cron Events を開きます。

1. Cloudflare ダッシュボードで、Workers & Pages ページを開きます。

   Workers & Pages を開く ↗

2. Overview で Worker を選びます。

3. Settings を選びます。

4. Trigger Events の下で View events を選びます。

Cron Events は、Cron の scheduled イベントの直近 100 件の呼び出しを保存します。Workers Logs にも Cron Trigger の呼び出しログが記録され、保持期間が長く、フィルターとクエリのインターフェイスがあります。Cron Events にアクセスする API が必要な場合は、Cloudflare の GraphQL Analytics API を使います。

詳細は メトリクスと分析 を参照してください。

デプロイ済み Worker の Cron Trigger をダッシュボードから削除する手順は次のとおりです。

1. Cloudflare ダッシュボードで、Workers & Pages ページを開きます。

   Workers & Pages を開く ↗

2. Worker を選びます。

3. Triggers を開き、削除する Cron Trigger の横の三点アイコンを選び、Delete を選びます。

Worker を Wrangler で管理している場合、Cron Triggers は Wrangler 設定ファイル だけで管理します。

Wrangler で Worker をデプロイすると、以前の Cron Triggers は triggers 配列で指定したものに置き換わります。

• crons プロパティが空の配列の場合、すべての Cron Triggers が削除されます。
• triggers または crons プロパティが undefined の場合、現在デプロイされている Cron Triggers はそのまま残ります。

{
	"triggers": {
		// Remove all cron triggers:
		"crons": []
	}
}

[triggers]
crons = [ ]

Worker あたりの Cron Triggers の上限は、制限 を参照してください。

Green Compute を有効にすると、Cron Triggers は再生可能エネルギーのみで稼働するデータセンター内の Cloudflare 拠点でのみ実行されます。組織は、全体のエネルギー使用量に見合う再生可能エネルギーを調達していれば、100% 再生可能エネルギーで稼働していると主張できます。

再生可能エネルギーは、現地発電（風力タービン、太陽光パネル）、電力購入契約（PPA）による再生可能エネルギー事業者からの直接購入、エネルギークレジット市場の再生可能エネルギークレジット（REC、IREC、GoO）など、いくつかの方法で調達できます。

Green Compute はアカウント単位で設定できます。

1. Cloudflare ダッシュボードで、Workers & Pages ページを開きます。

   Workers & Pages を開く ↗

2. Account details セクションで Compute Setting を探します。

3. Change を選びます。

4. Green Compute を選びます。

5. Confirm を選びます。

• Triggers — Cron Triggers の Wrangler 設定ファイル構文を確認します。
• ES モジュール構文 で Cron Triggers にアクセスする方法を確認します。