ConvertBox Logo
ConvertBox

cron式の読み方と書き方:5つのフィールド、実例、落とし穴

cron式は分、時、日、月、曜日の五つのフィールドからなり、各フィールドは許可する値の集合を表します。現在時刻がすべてのフィールドに一致するとジョブが実行されますが、日と曜日の二つのフィールドには重要な例外があります。

ConvertBox公開

左から順に並ぶ五つのフィールド

従来のcron式は、スペースで区切った五つのフィールドでできています。cronは1分ごとに起動し、現在の分、時、日、月が、それぞれのフィールドが表す集合に含まれていればジョブを実行します。式は間隔を測るタイマーではなく、時計に対するフィルターです。以下で取り上げる意外な挙動の多くは、この違いで説明できます。

フィールド指定できる値例
分0-5930は30分に実行
時0-230は午前0時、13は午後1時
日1-3115は15日
月1-12またはJAN-DEC7またはJUL
曜日0-6またはSUN-SAT0が日曜日。多くの実装は7も日曜日として受け付ける

四つの特殊文字:* , - /

各フィールドには、一つの数値か、四つの演算子で作った集合を書きます。0-30/10や1,15,20-25のように組み合わせることもできます。

文字意味分フィールドでの例実行される分
*すべての値*0、1、2 … 59
,リスト5,355分と35分
-両端を含む範囲10-1310、11、12、13
/範囲を一定の刻みで進む*/150、15、30、45
-と/範囲の中で刻みを指定0-30/100、10、20、30

フィールドごとに読む実例

式は分から曜日の順に読みます。最初にやりがちな間違いは、分のフィールドを*のままにすることです。* 9 * * *は、09:00から09:59まで毎分、合計60回実行されます。

  • 0 9 * * 1-5:月曜日から金曜日の09:00。
  • */15 9-17 * * 1-5:平日の9時台から17時台まで15分ごと。時の範囲は終わりの値を含むので、最後の実行は17:00ではなく17:45です。
  • 0 */6 * * *:毎日00:00、06:00、12:00、18:00。
  • 5,35 * * * *:毎時5分と35分の、1時間に2回。
  • 30 2 1 * *:毎月1日の02:30。
  • 0 22 * * 0:毎週日曜日の22:00。
  • 0 0 1 1 *:年に1回、1月1日の午前0時。

*/7と31日が期待どおりに動かない理由

刻みの指定は、経過時間でN単位ごとという意味ではありません。フィールドの範囲の最小値から順に値を選び、フィールドが一巡すると最初から選び直します。分フィールドの*/7は0、7、14と続いて56まで一致し、その後0に戻るため、毎時ちょうどの手前に4分の間隔ができます。時フィールドの*/5は0、5、10、15、20に一致するので、日付をまたぐ間隔は4時間です。日フィールドの*/2は奇数日に一致するため、31日に実行された翌日の1日にも実行されます。分なら5、10、15、20、30、時なら2、3、4、6、8、12のように、範囲を割り切る刻みだけが均等な間隔になります。

存在しない日付は、単に一致しないだけです。0 0 31 * *は31日のある七つの月にだけ実行され、残りの五つの月は何の通知もなく飛ばされます。30日は2月を飛ばし、29日はうるう年の2月にしか実行されません。標準のcronには月末を表す記号がありません。よく使われる回避策は、28-31日にジョブを設定し、コマンドの中で翌日が1日かどうかを確かめてから本来の処理を行う方法です。

日と曜日はORで結合される

すべてのフィールドが一致して初めて実行されるという原則には、例外が一つあります。日フィールドと曜日フィールドの両方が制限されているとき、つまりどちらも*でないとき、従来のcronはどちらか一方が一致すればジョブを実行します。0 0 13 * 5は13日の金曜日ではありません。毎月13日に実行され、毎週金曜日にも実行されます。同様に、0 9 1-7 * 1は第1月曜日を意味せず、毎月1日から7日までの毎日と、毎週月曜日に実行されます。

二つのフィールドのどちらかが*であれば、もう一方だけがスケジュールを制限します。多くの人が期待する動作はこちらです。両方の条件を満たす日だけに実行したい場合は、一方を式で制限し、もう一方をコマンドで判定します。0 9 1-7 * *で設定し、今日が月曜日でなければスクリプトを終了させる、という形です。拡張構文を持つスケジューラーはこれを直接書けます。Quartzでは、曜日フィールドのMON#1がその月の第1月曜日を表します。

タイムゾーンと夏時間

式にタイムゾーンは含まれず、実行するシステムがそれを決めます。従来のLinuxのcrontabはサーバーのローカル時刻を使います。GitHub Actionsのスケジュールは常にUTCです。KubernetesのCronJobは、spec.timeZoneを指定しないかぎりクラスターのコントローラーのタイムゾーンに従います。UTCのシステムで日本時間の09:00に実行するには、9時間を引いて0 0 * * *と書く必要があります。日本には夏時間がないため、この差は一年を通じて変わりません。

夏時間を実施しているタイムゾーンでは、危険がさらに二つあります。春に時計を進める日には1時間が存在しないため、その中に設定したジョブはその日に実行されないことがあります。秋に戻す日には1時間が2回あるため、その中のジョブは2回実行されることがあります。スケジューラーがこれらをどう扱うかは実装によって異なります。UTCでスケジュールを組むか、ローカル時刻で切り替えが起きる時間帯を避ければ、どちらの問題も避けられます。

従来のcron、Quartz、プラットフォームごとの方言

cronの構文は一つの標準ではなく、いくつもの変種の集まりです。5フィールドの式はQuartzでは無効であり、Quartzの式はcrontabでは無効です。別の場所からスケジュールをコピーする前に、そのプラットフォームがどの方言を使うかを確認してください。

当サイトのcronヘルパーは標準の5フィールドを解析します。式をページの言語の文章に直し、それとは別に、次の5回の実行時刻をブラウザーのタイムゾーンで表示します。文章と日時の両方が意図と一致すれば、そのタイムゾーンで動く5フィールドのスケジューラー向けの式として正しいと言えます。L、W、#、?などの拡張は表にあるプラットフォームの機能なので、それぞれのドキュメントを参照してください。正規表現を使えば、文字列がスペース区切りの五つのフィールドであることは確認でき、入力の検証に役立ち、正規表現テスターで手軽に試せます。ただし、ジョブがいつ実行されるかは分かりません。

方言フィールド数知っておくべき違い
Unixのcrontab5サーバーのローカル時刻。多くの実装が@dailyや@hourlyなどの省略記法を受け付ける
Quartz6または7秒が先頭、年は末尾で省略可。二つの日付フィールドの一方に?が必須。L、W、#を追加
Spring @Scheduled6秒が先頭、年のフィールドはない
AWS EventBridge6分が先頭、年が末尾、秒はない。二つの日付フィールドの一方に?が必須
GitHub Actions5常にUTC。最短の間隔は5分。負荷が高いと実行が遅れることがある
Kubernetes CronJob5spec.timeZoneを指定しないかぎりコントローラーのタイムゾーン

このガイドで扱ったツール

関連ガイド

ガイド一覧