Skip to content

非公式本サイトは非公式の日本語ドキュメントであり、Cloudflare 公式サイトではありません。最新情報はdevelopers.cloudflare.comをご確認ください。

Scheduled ハンドラー

最終更新 Markdown で表示Agent セットアップ

背景

Worker が Cron Trigger で呼び出されると、scheduled() ハンドラーがその呼び出しを処理します。


構文

export default {
	async scheduled(controller, env, ctx) {
		await doSomeTaskOnASchedule();
	},
};
interface Env {}
export default {
	async scheduled(
		controller: ScheduledController,
		env: Env,
		ctx: ExecutionContext,
	) {
		await doSomeTaskOnASchedule();
	},
};
from workers import WorkerEntrypoint

class Default(WorkerEntrypoint):
    async def scheduled(self, controller, env, ctx):
        # controller.cron contains the cron pattern that triggered this event
        # controller.scheduledTime contains the scheduled time in ms since epoch
        print(f"Cron triggered: {controller.cron}")

プロパティ

  • controller.cron string
    • ScheduledEvent を開始した Cron Trigger の値です。
  • controller.type string
    • コントローラーの種類です。常に "scheduled" を返します。
  • controller.scheduledTime number
    • ScheduledEvent の実行予定時刻です。1970 年 1 月 1 日 UTC からのミリ秒です。new Date(controller.scheduledTime) でパースできます。
  • env object
    • ES modules 形式で Worker に関連付けられたバインディングを含むオブジェクトです。KV 名前空間や Durable Objects などです。
  • ctx object
    • ES modules 形式で Worker に関連付けられたコンテキストを含むオブジェクトです。現在、このオブジェクトには waitUntil 関数だけが含まれます。

複数の Cron Trigger を扱う

1 つの Worker に複数の Cron Trigger を設定すると、各トリガーは同じ scheduled() ハンドラーを呼び出します。controller.cron でどのスケジュールが発火したかを見分け、それぞれ別の処理を実行します。

{
	"triggers": {
		"crons": ["*/5 * * * *", "0 0 * * *"],
	},
}
[triggers]
crons = [ "*/5 * * * *", "0 0 * * *" ]
export default {
	async scheduled(controller, env, ctx) {
		switch (controller.cron) {
			case "*/5 * * * *":
				await fetch("https://example.com/api/sync");
				break;
			case "0 0 * * *":
				await env.MY_KV.put("last-cleanup", new Date().toISOString());
				break;
		}
	},
};
export default {
	async scheduled(
		controller: ScheduledController,
		env: Env,
		ctx: ExecutionContext,
	) {
		switch (controller.cron) {
			case "*/5 * * * *":
				await fetch("https://example.com/api/sync");
				break;
			case "0 0 * * *":
				await env.MY_KV.put("last-cleanup", new Date().toISOString());
				break;
		}
	},
} satisfies ExportedHandler<Env>;
from workers import WorkerEntrypoint, fetch
from datetime import datetime, timezone

class Default(WorkerEntrypoint):
    async def scheduled(self, controller, env, ctx):
        if controller.cron == "*/5 * * * *":
            await fetch("https://example.com/api/sync")
        elif controller.cron == "0 0 * * *":
            await env.MY_KV.put("last-cleanup", datetime.now(timezone.utc).isoformat())

controller.cron の値は、設定に書いた Cron 式の文字列そのものです。空白を含め、1 文字単位で一致している必要があります。

メソッド

Workers スクリプトが Cron Trigger で呼び出されると、Workers ランタイムは ScheduledEvent を開始し、Workers モジュールクラスの scheduled 関数が処理します。ctx 引数は関数の実行コンテキストを表し、この先の動作を制御する次のメソッドを持ちます。

  • ctx.waitUntil(promise) : void - このメソッドで、呼び出しが完了する前に決着すべき非同期タスク(ログ、サードパーティサービスへの分析送信、ストリーミング、キャッシュなど)を登録します。最初に失敗した ctx.waitUntil が観測され、Cron Trigger の Past Events テーブルにステータスとして記録されます。それ以外は成功として報告されます。

役に立ちましたか?