Skip to content

キューでバックグラウンド処理する ​

キュー は、コンシューマーが受け取るまでメッセージを保持し、バッチ単位で渡します。コンシューマーは、バックグラウンドランナーで動く関数ランタイムか、自分で用意した HTTPS エンドポイントのどちらかです。処理したい速さより早く仕事が届くとき、数秒待ってもよいとき、失敗したら再試行したいときにキューを使います。

キューはライブサイトを変えません。メッセージの送信、処理、削除が影響するのはキューだけです。

以降、distribution は acme-marketing(d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38)、キューを処理する関数ランタイムは 01JBQZ8XKT4A9WN2CDEFGH5RM7 とします。

1. コンシューマーを書く ​

コンシューマーは /_jobs/queue/{name} への POST を受け取ります。本文にはバッチのメッセージが古い順に入っています。

json
{
  "type": "queue",
  "job_id": "job_01M4X7T2K9Q0V3B8N6C5D1E2F3",
  "attempt": 1,
  "distribution_id": "d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38",
  "queue": { "id": "que_01M4XB7Q2W8E5R3T6Y9U1I4O0P", "name": "orders" },
  "messages": [
    { "id": "msg_01M4XB9D3F6G8H1J4K7L0Z2X5C", "body": { "order": 42 }, "attempt": 1, "created_at": "2026-10-19T03:12:09+00:00" }
  ]
}

2xx を返すとバッチ全体を受け取ったことになり、Edge はそのメッセージを削除します。一部だけ再試行したいときは、2xx と一緒にもう一度試すメッセージを返します。挙げなかったメッセージは受け取り済みになります。

js
function handler(request, env) {
  const { messages } = JSON.parse(request.body);
  const retry = [];
  for (const message of messages) {
    if (!sendInvoice(message.body.order)) retry.push({ id: message.id, delay_seconds: 300 });
  }
  return { statusCode: 200, body: JSON.stringify({ retry }) };
}

それ以外の応答(4xx や 5xx、クラッシュ、タイムアウト)では、バッチのすべてのメッセージが間隔を広げながら再試行されます。配信は少なくとも 1 回なので、同じメッセージが 2 回届くことがあります。処理は message.id をキーにしてください。理由は バックグラウンドジョブ で説明しています。

2. キューを作る ​

text
acme-marketing に orders というキューを作って。関数 01JBQZ8XKT4A9WN2CDEFGH5RM7 で処理して、
1 バッチ 25 件、5 回失敗したらあきらめる設定で。
bash
edge queues create acme-marketing --name orders --function 01JBQZ8XKT4A9WN2CDEFGH5RM7 \
  --batch-size 25 --max-attempts 5
bash
curl -s -X POST https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/queues \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "orders",
        "consumer": {"type": "wasm", "script_id": "01JBQZ8XKT4A9WN2CDEFGH5RM7"},
        "batch_size": 25,
        "max_attempts": 5
      }'

エージェントは edge_queue_create を実行します。

json
{
  "queue_id": "que_01M4XB7Q2W8E5R3T6Y9U1I4O0P",
  "name": "orders",
  "consumer": { "type": "wasm", "script_id": "01JBQZ8XKT4A9WN2CDEFGH5RM7" },
  "batch_size": 25,
  "batch_wait_seconds": 5,
  "concurrency": 2,
  "max_attempts": 5,
  "retention_days": 4,
  "paused": false,
  …
}

バッチは満杯になるとすぐに、そうでなければいちばん古いメッセージが batch_wait_seconds 待ったところで送られます。concurrency は同時に処理できるバッチの数です。

自分のサーバーでキューを処理するには、HTTPS の URL を指定します。--webhook https://crm.example.com/edge-batches、または "consumer": {"type": "webhook", "url": "https://crm.example.com/edge-batches"} です。このとき応答に signing_secret が 1 回だけ含まれます。各バッチは上と同じ本文で届き、Edge の Webhook と同じ方法で署名されます。どの 2xx でもバッチ全体を受け取ったことになります。

3. メッセージを送る ​

text
acme-marketing の orders キューに {"order": 42} を送って。冪等キーは order-42 で。
bash
edge queues send que_01M4XB7Q2W8E5R3T6Y9U1I4O0P --body '{"order": 42}' --key order-42
# 1 行に 1 つの {"body": …} でまとめて送る:
edge queues send que_01M4XB7Q2W8E5R3T6Y9U1I4O0P --file orders.jsonl
bash
curl -s -X POST https://api.edge.deca-dev.com/v1/queues/que_01M4XB7Q2W8E5R3T6Y9U1I4O0P/messages \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"body": {"order": 42}, "idempotency_key": "order-42"}]}'

エージェントは edge_queue_send を実行します。

json
{
  "queue_id": "que_01M4XB7Q2W8E5R3T6Y9U1I4O0P",
  "messages": [{ "message_id": "msg_01M4XB9D3F6G8H1J4K7L0Z2X5C", "duplicate": false }]
}

そのメッセージがまだキューにある間に同じ idempotency_key を送ると、同じ message_id が duplicate: true 付きで返り、何も追加されません。delay_seconds(最大 7 日)を付けるとメッセージを遅らせて届けます。3 日後に送るリマインダーは、"delay_seconds": 259200 を付けたメッセージ 1 件です。

送るだけのサーバーや CI ジョブには、queue.send だけを持つ パーソナルアクセストークン を使います。送信はできますが、メッセージの読み取りや削除はできません。

cron からスケジュールどおりにキューへ送ることもできます。ターゲットを {"type": "enqueue", "queue": "orders"}(CLI では --enqueue orders)にします。関数をスケジュールで実行する を参照してください。

4. 処理の進み具合を見る ​

Web アプリで Distributions を開き、acme-marketing を選びます。Queues には、キューごとのコンシューマー、待っているメッセージ、バッチ処理中のメッセージ、dead のメッセージの数と、いちばん古いメッセージの待ち時間が表示されます。Pause で新しいバッチを止め(処理中のバッチは最後まで進みます)、Resume で再開します。Background jobs には各バッチの実行が並びます。

text
acme-marketing の orders キューの状況は?
bash
edge queues stats que_01M4XB7Q2W8E5R3T6Y9U1I4O0P
edge queues runs que_01M4XB7Q2W8E5R3T6Y9U1I4O0P --status failed
bash
curl -s https://api.edge.deca-dev.com/v1/queues/que_01M4XB7Q2W8E5R3T6Y9U1I4O0P/stats \
  -H "Authorization: Bearer $EDGE_TOKEN"

エージェントは edge_queue_stats と edge_queue_runs を実行します。

json
{
  "depth": { "ready": 140, "delayed": 3, "leased": 25, "dead": 0 },
  "oldest_ready_age_seconds": 12,
  "batches_in_flight": 2,
  "last_hour": { "batches_succeeded": 58, "batches_failed": 1, "batch_failure_rate": 0.0169, "dead_lettered": 0 }
}

キューに 10,000 件を超えるメッセージがたまったとき、またはいちばん古いメッセージが 1 時間以上待っているときに知るには、Webhook を queue.backlog.high に登録します。

エンドポイントから仕事を渡す ​

/_api の後ろにある関数は、自分でキューに送ってすぐに訪問者へ応答できます。時間のかかる部分はあとでコンシューマーが行います。まず関数がキューに送れるようにします。

text
関数 01JBQZ8XKT4A9WN2CDEFGH5RM7 が acme-marketing の orders キューに送れるようにして。
bash
edge queues update que_01M4XB7Q2W8E5R3T6Y9U1I4O0P --senders 01JBQZ8XKT4A9WN2CDEFGH5RM7
bash
curl -s -X PATCH https://api.edge.deca-dev.com/v1/queues/que_01M4XB7Q2W8E5R3T6Y9U1I4O0P \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"senders": ["01JBQZ8XKT4A9WN2CDEFGH5RM7"]}'

エージェントは edge_queue_update を実行します。そのうえで関数の中で次のようにします。

js
function handler(request, env) {
  const order = JSON.parse(request.body);
  const { id } = env.queue.send('orders', order, { idempotencyKey: `order-${order.id}` });
  return { statusCode: 202, body: JSON.stringify({ queued: id }) };
}

関数が送れるのは訪問者のリクエスト 1 回につき 10 件です。senders に入っていない関数には code が denied のエラーが返ります。メソッドの一覧は 関数ランタイム にあります。

次に ​

試行回数を使い切ったメッセージは dead のメッセージとして残ります。失敗したキューメッセージに対処する を参照してください。