ジョブ、cron、および配信不能キュー

ジョブは、関数に対する 1 つのバックグラウンド呼び出しです。 service_role キーを使用してサーバーからそれをキューに入れます。

import { createClient } from '@aurabase/aurabase-js'

const admin = createClient(process.env.AURA_URL!, process.env.AURA_SERVICE_ROLE_KEY!)

const { data: job, error } = await admin.functions.enqueueJob('send-report', {
  payload: { month: '2026-10' },
  delaySecs: 60,   // 最初の試行の前に 60 秒待ってください
  maxAttempts: 3,  // デフォルト
})

getJob(id) または listJobs({ status, limit }) を使用してジョブを読み取ります (limit は 1 ～ 500、デフォルトは 50)。ジョブには status、 attempts、 max_attempts、 error があり、日付は scheduled_at、 started_at、 completed_atです。

ジョブは他のリクエストと同様に関数を呼び出しますが、次の 3 つの違いに対処する必要があります。

Deno.serve(async (req) => {
  const jobId = new URL(req.url).pathname.split('/').pop()
  const { month } = await req.json()
  // …jobId を冪等キーとして使用して、レポートを作成して送信します。
  return new Response('ok')
})

実際の呼び出しは {"method":"JOB","path":"/jobs/d443d541-…","role":null,"userId":null,"body":"{\"items\":[\"a\",\"b\"],\"order\":42}"}として記録されました。

ジョブはユーザーなしで実行されます。 x-aura-user-idに依存しないでください。作品がユーザーに属している場合は、ペイロードにユーザーの ID を入れます。

pending ──claimed──▶ running ──▶ completed
   ▲                    │
   └── after 5 s ◀── failed (attempts left)
                        └──▶ dead (no attempts left)

• ジョブは少なくとも 1 回実行されます。実行中にワーカーが停止すると 2 回実行される可能性があるため、関数を冪等にします。
• 失敗した試行は、maxAttempts に達するまで、5 秒の固定遅延の後、再試行されます。ジョブは deadになります。遅延とデフォルトの試行回数はサービス設定 (JOB_RETRY_DELAY_SECS、 JOB_MAX_RETRIES) です。
• リース (デフォルトでは 450 秒) 後も running のままのジョブは、サービスによって再利用されます。
• 完了したジョブはデフォルトで 14 日間保存されます。

同じ実際の実行で、存在しない関数のジョブは次のシーケンスを経ました。試行 1 は Fonction 'ghost' introuvableで 3 秒で失敗し、試行 2 は約 9 秒で失敗し、ジョブは dead になり、 attempts は max_attemptsと同等になりました。

死んだジョブはキュー内に残り、一覧表示して再試行できます。これらのルートにはまだ SDK メソッドがありません。service_role キーを持つ HTTP を使用してください。

# 死んだジョブをリストする
curl "$AURA_URL/v1/functions/jobs/dlq" -H "apikey: $AURA_SERVICE_ROLE_KEY"

# 1 つのジョブを再試行する
curl -X POST "$AURA_URL/v1/functions/jobs/$JOB_ID/retry" -H "apikey: $AURA_SERVICE_ROLE_KEY"

# 死んだジョブをすべて再試行します (最大 1000)
curl -X POST "$AURA_URL/v1/functions/jobs/dlq/requeue" -H "apikey: $AURA_SERVICE_ROLE_KEY"
# → {"データ":{"リクエストされた":1},"メタ":null}

再試行すると、ジョブは試行カウンタをリセットせずに pending に戻されるため、あと 1 回だけ試行され、再度失敗した場合は dead に戻ります。再試行する前に、原因を修正してください (欠落している関数をデプロイするなど)。

cron エントリは関数自体を呼び出しません。関数が起動されるたびに、ジョブがキューに入れられます。

await admin.functions.createCronJob('nightly-cleanup', '0 3 * * *', 'cleanup', {
  payload: { dryRun: false },
})

const { data: crons } = await admin.functions.listCronJobs()
await admin.functions.deleteCronJob('nightly-cleanup') // IDではなく名前で

• スケジュールには、5 フィールド (min hour day month weekday) または 6 フィールド (sec min hour day month weekday) があります。 5 フィールドのスケジュールは 0 秒前に取得されます。 */1 * * * * は 0 */1 * * * *として保存されます。
• @daily などのエイリアスは、予期される形式を示す 400 で拒否されます。
• 時間は UTC です。
• last_run および next_run は、最初の起動までは null です。実際の実行では、15:40 に作成されたスケジュールは 15:41:00 に起動され、next_run 15:42:00 と表示されました。
• エントリの作成時にペイロードは凍結されます。
• 不明な名前を削除すると、 404が返されます。 cron エントリを削除すると、cron エントリの起動も停止します。
• SDK には getCronJob または updateCronJobがありません。エントリを削除して、再度作成してください。

純粋なデータベース作業の場合、Postgres pg_cron 拡張機能は関数への往復を回避します。Cron ページを参照してください。