encore-cron

Encore の Cron ジョブ

手順

Encore.ts の CronJob 宣言は、スケジュールを既存の api(...) エンドポイントに結び付けます。エンドポイントは指定した周期で実行されます。CronJob はパッケージレベルで宣言してください。関数の内部では宣言しないでください。

import { CronJob } from "encore.dev/cron";
import { api } from "encore.dev/api";

// 1. The endpoint to call (typically internal: expose: false)
export const aggregateDailyOrders = api(
  { expose: false },
  async (): Promise<void> => {
    // Aggregation logic
  }
);

// 2. Package-level cron declaration
const _ = new CronJob("aggregate-daily-orders", {
  title: "Aggregate orders for the previous day",
  schedule: "0 2 * * *",  // 02:00 UTC every day
  endpoint: aggregateDailyOrders,
});

スケジュール形式

フィールド	例	説明
every	"1h"、"30m"、"6h"	単純な間隔。24時間を均等に分割できる必要があります — "7h" は無効です。
schedule	"0 9 * * 1"	標準的な cron 式（5フィールド、UTC）。

よく使われる cron 式

Cron	意味
"0 * * * *"	毎時0分
"0 2 * * *"	毎日 02:00 UTC
"0 0 * * 0"	毎週日曜日の午前0時 UTC
"0 4 15 * *"	毎月15日の 04:00 UTC

重要な動作

• encore run でローカル実行している場合、Cron ジョブは実行されません。 cron が発火するのはデプロイされた環境だけです。
• cron エンドポイントは expose: false にすることをお勧めします。外部からトリガーできないようにするためです。呼び出せるのは cron スケジューラーだけであるべきです。
• schedule 内の時刻はすべて UTC です。スケジュールを設計する際はローカル時刻から変換してください。
• エンドポイントはモジュールの読み込み時にすでに存在している必要があります。CronJob より前に宣言してください。

ガイドライン

• 「一定の間隔で実行する」場合は every を使用します（24時間を均等に分割できる必要があります）。
• 特定の時刻や曜日に実行する場合は schedule を使用します。
• エンドポイントのロジックは冪等に保ってください。cron は遅延して発火したり、再デプロイの間にリトライされたりする可能性があります。
• イベントドリブンのバックグラウンド処理（時間ドリブンではないもの）には、代わりに encore-pubsub スキルを使用してください。