16-3 時刻が来たら（scheduled handler）

この節を一言で

目覚ましが鳴ったときに開かれるのは、マニュアルの「時刻が来たら」の章です。

図版を準備中マニュアルが開かれ「時刻が来たら」の章に栞がある

scheduled handler はマニュアルの「時刻が来たら」の章です。

第 2 章で、窓口のマニュアル（Worker）には「お客さんが来たら」の章があると書きました。呼び鈴が鳴るとスタッフはその章を開き、用件票を読んで答えを返します。

目覚まし時計で起きたときは事情が違います。開くべきなのは別の章で、読み上げる相手もいません。いま読んでいるこのサイト（Cloudflare Lab）の見回りの手順も、その章に書きます。

ここでは、時刻の章の書き方、入口の違い、手元での試し方、時間の上限の順に見ます。

Learning goals

この節でできるようになること

• 「時刻が来たら」の章の書き方を説明できる
• 鳴った時刻や設定の文字列を受け取れることを言える
• お客さんの入口との違いを説明できる
• 1 回の実行に許される時間を数字で言える

1. 「時刻が来たら」の章

マニュアルに時刻用の章を作り、そこへ「起きたら何をするか」を書きます。

Cloudflare では、この章を scheduled handler と呼びます。公式は、Cron Triggers によって Worker が呼び出されたとき、scheduled() がその呼び出しを受け持つと説明しています。

次のコードは公式の見本で、「起きたら記録を 1 行残す」だけの内容です。読めなくても大丈夫です。

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

受け取る三つのうち、controller には鳴った合図の情報が入ります。公式によれば controller.cron は今回鳴った設定の文字列そのもの、controller.scheduledTime は鳴る予定だった時刻です。env は引き出し（第 2 章の binding）です。

図版を準備中マニュアルに二つの章。入口の章と時刻の章

マニュアルには「お客さんが来たら」と「時刻が来たら」の章があります。

同じマニュアルに二つの章があり、合図によって開かれる章が変わります。

つまり、目覚ましの行き先は scheduled() で、そこに起きた後の手順を書きます。

2. お客さんの入口との違い

二つの章は、呼ぶ相手が違うだけではありません。お客さんの章は用件票を受け取って答えを返しますが、時刻の章には答えを待つ相手がいません。

残るのは、成功したか失敗したかだけです。公式は、ctx.waitUntil に渡した処理のうち最初に失敗したものが Past Events の表に状態として記録され、そうでなければ成功として報告されると説明しています。

複数の時刻を登録していても、開かれる章は同じ一つです。公式は、controller.cron を見てどの設定で鳴ったかを見分け、時刻ごとに違う処理へ分けるやり方を示しています。

図版を準備中上段は客が呼び鈴を押す、下段は時計が鳴る。返す相手が違う

呼ぶのが客か時計かで、答えを返す相手が変わります。

上は呼び鈴、下は目覚ましです。上には答えを渡す相手がいて、下には記録が残ります。

つまり、時刻の章は「返す」ではなく「終わったことを記録に残す」入口です。

3. 手元で試す

本番の時刻を待って確かめるのは大変です。毎日 0 時にしか鳴らない設定なら、1 回試すのに丸 1 日かかります。そこで試運転では、時計を待たずに手で鳴らします。公式は、wrangler dev に --test-scheduled を付けると /__scheduled という確認用の入口が開き、そこへ要求を送るだけで目覚ましが鳴ったことにできると説明しています。

次の 2 つの命令は、試運転を始めて鳴ったことにするものです。読めなくても大丈夫です。

npx wrangler dev --test-scheduled
curl "http://localhost:8787/__scheduled?cron=*+*+*+*+*"

公式には /cdn-cgi/handler/scheduled という同じ働きの入口もあり、?format=json を付けると結果が "outcome": "ok" のような形で返ります。

図版を準備中試運転中の店で、手で時計の針を回して目覚ましを鳴らす

試運転では、手元から合図を送って目覚ましを鳴らせます。

試運転の店で、手で合図を送って目覚ましを鳴らしています。時刻を待つ必要はありません。

つまり、時刻の章は手元から呼び出して試せます。

4. 1 回に使える時間

見回りには時間がかかります。ここには二つの別々の上限があります。

一つは、始まりから終わりまでの経過時間です。公式の上限の表では、Cron Triggers の 1 回の実行は最大 15 分です。もう一つは、そのうち計算に使った時間です。公式は、他所への問い合わせを待っている時間は計算の時間に数えないと説明しています。

1 回の実行時間（Cron Triggers）

最大 15 分

計算に使う時間（Workers Free）

10 ms

計算に使う時間（Workers Paid・1 時間未満の間隔）

30 秒

つまり、待ち時間の多い見回りなら、無料のプランの計算時間にも収まります。

Cloudflare Lab での使われ方

ここで紹介した時刻の章が、いま読んでいる Cloudflare Lab でどう使われるかを見ます。

Cloudflare Lab は Phase 4 で、scheduled() の中に「出典の URL を順に確かめ、結果を残す」手順を書く予定です。実測（1 回にかかった時間と、確かめた URL の本数）は実装後に追記します。

つまずきやすいところ

つまずきポイント

設定の文字列は空白まで一致させます

公式は、controller.cron の値が登録票の設定と 1 文字ずつ、空白も含めて同じでなければならないと説明しています。

つまずきポイント

待ち時間も 15 分に含まれます

上限の 15 分は経過時間なので、他所の返事を待っている間も進みます。宛先が多いなら分けて鳴らします。

この節のまとめ

• 目覚ましで開かれるのは scheduled() の章です。
• 答えを返す相手はおらず、成功か失敗かが記録に残ります。
• 手元では --test-scheduled で鳴らせ、1 回の実行は最大 15 分です。

この節で出てきた言葉を、つながりの順に並べると次のようになります。

flowchart TD
  A["目覚ましが鳴る<br/>Cron Trigger"] --> B["時刻が来たら<br/>scheduled()"]
  B --> C["鳴った合図の情報<br/>controller.cron"]
  C --> D["1 回の上限<br/>15 分"]
  D --> E["終わったら記録<br/>Past Events"]
  B --> F["手元で試す<br/>--test-scheduled"]

図のラベル: 目覚ましが鳴る Cron Trigger / 時刻が来たら scheduled() / 鳴った合図の情報 controller.cron / 1 回の上限 15 分 / 終わったら記録 Past Events / 手元で試す --test-scheduled

次の節では、この章の中身として毎日の出典確認を設計します。

この節のチェック

問 1目覚ましが鳴ったとき、マニュアルのどの入口が開かれますか？

scheduled handlerお客さんの用件を受ける入口棚から取り出す入口帳簿を開く入口

問 2controller.cron には何が入りますか？

今回鳴った時刻の設定の文字列Worker の名前読者のブラウザの種類アカウントの番号

問 3手元の試運転で目覚ましを鳴らしたことにするには、どうしますか？

wrangler dev に --test-scheduled を付け、開いた入口へ要求を送る本番の時刻になるまで待つパソコンの時計を進める登録票を削除する

問 4Cron Triggers による 1 回の実行に許される時間の上限はどれですか？

15 分30 秒10 ミリ秒上限なし

問 5他所への問い合わせを待っている時間は、計算に使った時間に数えられますか？

数えられない数えられる半分だけ数えられるプランによって数え方が変わる

採点する