キューでバックグラウンド処理する
キュー は、コンシューマーが受け取るまでメッセージを保持し、バッチ単位で渡します。コンシューマーは、バックグラウンドランナーで動く関数ランタイムか、自分で用意した HTTPS エンドポイントのどちらかです。処理したい速さより早く仕事が届くとき、数秒待ってもよいとき、失敗したら再試行したいときにキューを使います。
キューはライブサイトを変えません。メッセージの送信、処理、削除が影響するのはキューだけです。
以降、distribution は acme-marketing(d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38)、キューを処理する関数ランタイムは 01JBQZ8XKT4A9WN2CDEFGH5RM7 とします。
1. コンシューマーを書く
コンシューマーは /_jobs/queue/{name} への POST を受け取ります。本文にはバッチのメッセージが古い順に入っています。
{
"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 と一緒にもう一度試すメッセージを返します。挙げなかったメッセージは受け取り済みになります。
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. キューを作る
acme-marketing に orders というキューを作って。関数 01JBQZ8XKT4A9WN2CDEFGH5RM7 で処理して、
1 バッチ 25 件、5 回失敗したらあきらめる設定で。edge queues create acme-marketing --name orders --function 01JBQZ8XKT4A9WN2CDEFGH5RM7 \
--batch-size 25 --max-attempts 5curl -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 を実行します。
{
"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. メッセージを送る
acme-marketing の orders キューに {"order": 42} を送って。冪等キーは order-42 で。edge queues send que_01M4XB7Q2W8E5R3T6Y9U1I4O0P --body '{"order": 42}' --key order-42
# 1 行に 1 つの {"body": …} でまとめて送る:
edge queues send que_01M4XB7Q2W8E5R3T6Y9U1I4O0P --file orders.jsonlcurl -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 を実行します。
{
"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 には各バッチの実行が並びます。
acme-marketing の orders キューの状況は?edge queues stats que_01M4XB7Q2W8E5R3T6Y9U1I4O0P
edge queues runs que_01M4XB7Q2W8E5R3T6Y9U1I4O0P --status failedcurl -s https://api.edge.deca-dev.com/v1/queues/que_01M4XB7Q2W8E5R3T6Y9U1I4O0P/stats \
-H "Authorization: Bearer $EDGE_TOKEN"エージェントは edge_queue_stats と edge_queue_runs を実行します。
{
"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 の後ろにある関数は、自分でキューに送ってすぐに訪問者へ応答できます。時間のかかる部分はあとでコンシューマーが行います。まず関数がキューに送れるようにします。
関数 01JBQZ8XKT4A9WN2CDEFGH5RM7 が acme-marketing の orders キューに送れるようにして。edge queues update que_01M4XB7Q2W8E5R3T6Y9U1I4O0P --senders 01JBQZ8XKT4A9WN2CDEFGH5RM7curl -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 を実行します。そのうえで関数の中で次のようにします。
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 のメッセージとして残ります。失敗したキューメッセージに対処する を参照してください。