Queues — 非同期メッセージング

Queues のモデル — producer と consumer を分離する

Cloudflare Queues は、Workers に統合されたメッセージキューです。HTTP リクエストを受けた Worker がその場で重い処理（画像変換、外部 API 呼び出し、メール送信など）を実行すると、応答はその分遅くなり、失敗時のリカバリも複雑になります。Queues を使うと「受け付ける側」と「処理する側」を分離できます。登場人物は 4 つです。

最小構成はこれだけです。producer はバインディング経由で送り、consumer は fetch の代わりに（あるいは同じ Worker 内に併設して）queue ハンドラを実装します。

// producer 側 — バインディング経由でメッセージを送る
await env.MY_QUEUE.send({ url: req.url, method: req.method });

// consumer 側 — queue ハンドラでバッチを受け取る
export default {
  async queue(batch, env, ctx): Promise<void> {
    for (const msg of batch.messages) {
      console.log(msg.body);
    }
  },
} satisfies ExportedHandler<Env>;

配送保証は at-least-once（少なくとも 1 回）です。メッセージは必ず 1 回以上配送されますが、まれに 2 回以上届くことがあります。また、発行した順序どおりに consumer へ届くことは保証されません。したがって「同じメッセージを 2 回処理しても壊れない」冪等な設計が基本になります。ドキュメントが推奨するのは、メッセージ書き込み時に一意な ID を生成し、データベースの主キーや外部 API の冪等キーとして使い、重複を受け側で弾く方法です。

接続関係には明確なルールがあります。1 つのキューに書き込む producer Worker の数に制限はありませんが、1 つのキューに接続できる consumer Worker は 1 つだけです。逆に、1 つの consumer Worker を複数のキューに接続することはでき、その場合は batch.queue（バッチの取得元キュー名）で処理を分岐できます。なお HTTP で任意の環境からメッセージを取得する pull 型 consumer もありますが、本章では Workers による push 型に絞ります。

バッチ配送 — サイズとタイムアウトの調整

consumer へのメッセージ配送はバッチ単位です。呼び出し回数を減らしてコストを下げ、外部 API への書き込みをまとめられます。バッチの形は consumer 設定の 2 つの値で決まり、どちらかの条件に先に達した時点で配送されます。

たとえば max_batch_size = 30、max_batch_timeout = 10 なら、30 件溜まった時点か、10 秒経過した時点のどちらか早い方でバッチが届きます。キューが空のときは queue ハンドラ自体が呼ばれないので、無駄な起動は発生しません。調整の軸は「どれだけ待てるか（レイテンシ）」「外部システムへ書き込む単位」「呼び出し回数（コスト）」の 3 つです。

producer 側もまとめ書きできます。sendBatch() は 1 回の呼び出しで最大 100 件（合計 256 KB まで）を書き込みます。また delaySeconds オプションで、メッセージが consumer へ配送可能になるまでの遅延を最大 24 時間まで指定できます。

// 最大 100 件（合計 256 KB まで）をまとめて送る
await env.MY_QUEUE.sendBatch(items.map((item) => ({ body: item })));

// 10 分後から配送されるメッセージ
await env.MY_QUEUE.send(task, { delaySeconds: 600 });

リトライ・ack / retry の個別制御・Dead Letter Queue

既定の挙動はバッチ単位の all-or-nothing です。queue ハンドラが正常に return すれば（返した Promise と waitUntil() に渡した Promise がすべて解決すれば）バッチ全体が確認応答（ack）され、例外を投げればバッチ全体がリトライ対象になります。リトライ回数は consumer 設定の max_retries（既定 3 回）で制御し、上限に達したメッセージはキューから削除されます。

ただし「10 件中 8 件目だけ失敗」のようなケースで全 10 件を再配送されると、処理済みの 7 件が重複実行されます。これを避けるのが個別制御です。

• msg.ack() — そのメッセージを処理済みとして確定する。以降ハンドラが例外を投げても再配送されない
• msg.retry(options?) — そのメッセージだけを次のバッチで再配送させる（negative acknowledgement）
• batch.ackAll() / batch.retryAll(options?) — バッチ全体に対する同等操作

優先順位のルールは「先勝ち・個別優先」です。同じメッセージに対する 2 回目以降の ack() / retry() は無視され、個別に呼んだメッセージにはバッチ全体への ackAll() / retryAll() は適用されません。

retry() には delaySeconds を渡せます。各メッセージには配送試行回数 attempts（1 始まり）が付いているので、組み合わせると指数バックオフを実装できます。上流 API が 429 Too Many Requests を返したときに消費速度を落とす、といった使い方が典型です。

const BASE_DELAY_SECONDS = 30;

export default {
  async queue(batch, env, ctx): Promise<void> {
    for (const msg of batch.messages) {
      // attempts は 1 から始まる配送試行回数
      msg.retry({
        delaySeconds: BASE_DELAY_SECONDS ** msg.attempts,
      });
    }
  },
} satisfies ExportedHandler<Env>;

max_retries を使い切ったメッセージの行き先が Dead Letter Queue（DLQ）です。consumer 設定の dead_letter_queue にキュー名を指定すると、リトライ上限に達したメッセージは削除される代わりにそのキューへ書き込まれます（指定した名前のキューが存在しなければ自動作成されます）。DLQ もただのキューなので、consumer を接続して内容を検査・再処理できます。consumer のない DLQ に入ったメッセージは 4 日で削除される点に注意してください。なお、リトライは 1 回ごとに読み取りオペレーションとして課金対象になります。

プランと制限（2026-08 時点）

Queues は Workers Free / Paid の両プランで利用できます。課金単位は「オペレーション」で、64 KB ごとの書き込み・読み取り・削除がそれぞれ 1 オペレーションです。通常、1 メッセージの配送には書き込み 1 + 読み取り 1 + 削除 1 の計 3 オペレーションかかります。

Free プランでも本章のハンズオンは完走できますが、保持期間 24 時間固定・1 日 10,000 オペレーションという制約があるため、実運用では Workers Paid が前提と考えてください。主な技術的制限は次のとおりです。

• メッセージサイズ: 最大 128 KB（約 100 バイトの内部メタデータ込み）
• スループット: キューあたり 5,000 メッセージ/秒。超過すると send() / sendBatch() が Too Many Requests 例外を投げる
• キュー数: アカウントあたり 10,000。バックログ: キューあたり 25 GB
• consumer の実行時間: 1 呼び出しあたり wall time 15 分。CPU 時間は既定 30 秒（limits.cpu_ms で最大 5 分まで拡張可）
• 同時 consumer 呼び出し: 最大 250。バックログの増加に応じて自動でスケールアウトし、max_concurrency で上限を固定できる

つまずきポイント

理解度チェック

まとめと次章へ

• Queues は producer（send() / sendBatch()）と consumer（queue ハンドラ）を分離する、at-least-once 配送のメッセージキュー。順序は保証されないため冪等設計が前提
• 配送はバッチ単位。max_batch_size（既定 10 件）と max_batch_timeout（既定 5 秒）の早い方で届く
• 失敗時は max_retries（既定 3 回）までバッチ単位で再配送。msg.ack() / msg.retry() で個別制御でき、delaySeconds と attempts でバックオフも組める
• リトライ上限を超えたメッセージは Dead Letter Queue へ退避して調査・再処理する
• 「受け付け即応答 + 裏で処理」は、producer の send() を await してから 202 を返すだけで実現できる

キューは「1 発の非同期処理」に向きますが、複数ステップの処理を途中経過ごと永続化してリトライしたい場合は、次章の Workflows がより適したツールです。キューで作った受付パターンはそのまま Workflows の起動にも応用できます。

• Getting started · Cloudflare Queues docs
• How Queues Works
• Batching, Retries and Delays
• Dead Letter Queues
• JavaScript APIs
• Limits / Pricing