次のような場合に使用: スケジュールに基づいて実行される機能を構築するとき。定期実行ジョブ、繰り返し処理、定期的なデータ確認、cron（定時実行）ジョブ、監視、アラート機能などが対象です。 このドキュメントでは、以下を解説しています： - インターバルハンドラー（一定間隔で処理を実行する機構）の署名 - cron式（日時指定の記法） - UTC タイムゾーン（協定世界時）の制約 - `lastRunAt` パターン（前回実行時刻を記録し、新しいデータを検出する方法）
Use when building a val that runs on a schedule — periodic jobs, recurring tasks, polling, cron jobs, monitoring, alerting. Covers the interval handler signature, cron expressions, the UTC timezone constraint, and the `lastRunAt` pattern for detecting new items since the previous run.
インターバル val（fileType: "interval"）は、cron 式で定義された定期スケジュールに従って実行されます。
外部 API のポーリング、リマインダーの送信、クリーンアップ処理、レポート生成など、
リクエストへの応答ではなくタイマーベースで行うべき処理に使用します。
// 詳細: https://docs.val.town/vals/cron/
export default async function (interval: Interval) {
// interval.lastRunAt: Date | undefined
console.log(interval);
}
ファイルには必ず export が必要です — ハンドラーには export default を使用します。
Cron 式は UTC で実行されます。 人間が読みやすい形式のスケジュール（例：「東部時間の午前9時」）は、 cron 式を書く前に UTC に変換してください。 サマータイム（夏時間）は考慮されないため、年間を通じて許容できる UTC 時刻を選択してください。
lastRunAt パターンinterval.lastRunAt は直前の正常実行時のタイムスタンプです（初回実行時は undefined）。
全件を再スキャンする代わりに、直前の実行以降に作成されたアイテムだけを取得するために活用できます:
export default async function (interval: Interval) {
const since = interval.lastRunAt ?? new Date(Date.now() - 24 * 60 * 60 * 1000);
const newItems = await fetchItemsSince(since);
for (const item of newItems) {
await handle(item);
}
}
このパターンにより、実行が抜けた場合でも冪等性が保たれ、 同じデータの二重処理を防ぐことができます。
read_interval_settings — インターバルファイルの現在の cron 式と有効状態を取得します。write_interval_settings — cron 式の変更、またはインターバルの一時停止・再開を行います。シンプルなスケジュールジョブであれば、interval タイプのファイルを1つ持つ新しい val を
直接作成すれば十分です — テンプレートは不要です。
テンプレートは、ダッシュボード・AI agent・Webhook と UI の組み合わせなど、
より複雑な構成に向いています。
インターバル val を編集した後は、次回のスケジュール実行を待たずに、
run_file を使ってハンドラーを手動で呼び出して動作確認を行いましょう。
Interval vals (fileType: "interval") run on a recurring schedule defined by a cron expression. Use them for polling external APIs, sending reminders, running cleanups, generating reports, or any work that should happen on a clock rather than in response to a request.
// Learn more: https://docs.val.town/vals/cron/
export default async function (interval: Interval) {
// interval.lastRunAt: Date | undefined
console.log(interval);
}
The file must have an export — export default for the handler.
Cron expressions run in UTC. Convert any human-readable schedule (e.g. "9am Eastern") to UTC before writing the cron expression. Daylight savings is not handled — pick a UTC time that's close enough year-round.
lastRunAt patterninterval.lastRunAt is the timestamp of the previous successful run (or undefined on the first run). Use it to fetch only items created since the last run, instead of re-scanning everything:
export default async function (interval: Interval) {
const since = interval.lastRunAt ?? new Date(Date.now() - 24 * 60 * 60 * 1000);
const newItems = await fetchItemsSince(since);
for (const item of newItems) {
await handle(item);
}
}
This makes the val idempotent against missed runs and avoids reprocessing.
read_interval_settings — fetch the current cron expression and active state of an interval file.write_interval_settings — change the cron expression or pause/resume an interval.For simple scheduled jobs, create a new val with a single interval-type file directly — no template needed. Templates are for more complex shapes (dashboards, AI agents, webhook + UI combos).
After editing an interval val, use run_file to invoke the handler manually instead of waiting for the next scheduled run.
原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。