Skip to content

関数をバックグラウンドジョブとして試す ​

関数ランタイムは訪問者のリクエストなしに バックグラウンドジョブ として、5 秒ではなく最長 14 分動かせます。このページでは関数をジョブと同じ形で一度実行し、スケジュールで起動する前に、ジョブイベントを扱えることとデッドライン内に終わることを確かめます。

このページの操作でライブサイトは変わりません。テスト実行は訪問者のリクエストではなく、再試行もされません。

関数ランタイムはエージェント(MCP)でのみ管理します。CLI や HTTP のルートはまだありません。作成されたジョブ実行は Web アプリ、CLI、API のどれでも確認できます。

以降、distribution は acme-marketing(d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38)、関数ランタイムはビルド済みの 01JBQZ8XKT4A9WN2CDEFGH5RM7 とします。まだない場合は エンドポイントを追加する から始めてください。

1. ジョブイベントを扱う ​

ジョブは /_jobs/{kind}/{name} への POST として、JSON 文字列のボディでハンドラに届きます。パスで振り分け、副作用は job_id をキーにしてください。ジョブは複数回実行されることがあります。

js
function handler(request, env) {
  if (request.path.startsWith('/_jobs/')) {
    const job = JSON.parse(request.body);
    // job.type は cron、queue、workflow のいずれか。job.job_id は再試行でも変わりません。
    console.log(`job ${job.job_id} attempt ${job.attempt}`);
    return { statusCode: 200, body: JSON.stringify({ done: true }) };
  }
  return { statusCode: 404, body: 'not found' };
}

処理が終わったら 2xx を返します。5xx は再試行を求め、4xx はジョブが成功しえないので再試行しないことを伝えます。イベントの形は 関数ランタイム にあります。

2. デッドラインを設定する ​

関数が指定しない限り、ジョブには 300 秒が与えられます。1〜840 秒の範囲で変更でき、変更しても関数は再ビルドされません。

text
acme-marketing の関数 01JBQZ8XKT4A9WN2CDEFGH5RM7 のバックグラウンドタイムアウトを
600 秒にして。ソースは変えないで。

エージェントは background_timeout_seconds だけを指定して edge_function_update を実行します。再ビルドしないので応答は "job_id": null で、"background_timeout_seconds": 600 が返ります。

3. cron ジョブとして実行する ​

text
acme-marketing の関数 01JBQZ8XKT4A9WN2CDEFGH5RM7 を cron ジョブとして一度実行して、
ジョブ ID、状態、所要時間、stderr を見せて。

エージェントは trigger: "cron" で edge_function_invoke を実行します。本物の cron が送るイベントに "test": true を加えてバックグラウンドランナーに送り、結果を待ちます。

json
{
  "trigger": "cron",
  "job_id": "job_01M4X7T2K9Q0V3B8N6C5D1E2F3",
  "job_status": "succeeded",
  "deadline_seconds": 600,
  "status_code": 200,
  "body": "{\"done\":true}",
  "stderr": "job job_01M4X7T2K9Q0V3B8N6C5D1E2F3 attempt 1",
  "duration_ms": 1840,
  "fetch_count": 0,
  …
}

キューのコンシューマーを試すときは trigger: "queue" を指定し、ジョブが運ぶメッセージを渡します。たとえば {"messages": [{"id": "msg_1", "body": {"order": 42}}]} です。ワークフローのステップには trigger: "workflow" を使います。

deadline_exceeded で失敗したら、手順 2 でデッドラインを延ばすか、1 回の実行で行う処理を減らしてください。fuel_exhausted は、設定できるどのデッドラインでも 1 回の実行には重すぎることを意味します。

4. ジョブ実行を確認する ​

Web アプリで Distributions を開き、acme-marketing を選びます。パネルの Background jobs に最近の実行が状態と所要時間とともに並びます。テスト実行には Test run と表示されます。

text
acme-marketing で失敗したバックグラウンドジョブの実行を一覧して。
bash
edge jobs ls acme-marketing --status failed
bash
curl -s "https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/jobs?status=failed" \
  -H "Authorization: Bearer $EDGE_TOKEN"

エージェントは edge_job_runs を実行します。各実行には status、error_code、fuel_used、duration_ms、fetch_count があります。実行は 30 日間保持されます。

関数が出力した内容は、そのジョブのランタイムログをエージェントに頼んで確認します。エージェントは job_id を指定して edge_function_logs を実行します。

次に ​

ジョブが 2 回実行されうる理由と、どの失敗が再試行されるかは バックグラウンドジョブ を読んでください。