Cloudflare 24：Queues ― 重い仕事を預けて、すぐ返す

間に「キュー」を置き、仕事を預ける

キュー（待ち行列）は、仕事のメモを貯めておく場所です。このメモをメッセージと呼びます。

使い方は、銀行の窓口の整理券に似ています。窓口（送り手）は、用件を聞いて整理券を渡したら、すぐ次の人に対応できます。奥の係（受け手）が、整理券を順に片づけていきます。

図の中で、送り手の Worker は、メッセージをキューに入れた時点で利用者に「受け付けました」と返します。メールが実際に届くのは数秒後かもしれませんが、利用者はもう次の操作に進めます。

Cloudflare Queues の特徴は、送り手も受け手も Worker で書けることです。サーバーを用意したり、キューのソフトウェアを運用したりする必要はありません。キューは「必ず届ける」ことを保証する仕組みを、Cloudflare の側が持っています。

送り手：send() で1行、預けるだけ

送り手の Worker は、バインディング（23号で見たのと同じ仕組み）でキューを受け取り、send() を呼ぶだけです。

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const user = await registerUser(request, env);

    // メール送信は預けるだけ。ここでは待たない
    await env.JOBS.send({ type: "welcome-mail", to: user.email, userId: user.id });

    return Response.json({ ok: true });
  },
};

send() が待つのは「キューが確かに受け取った」までです。メールの送信そのものは待ちません。だから、応答はすぐ返ります。

メッセージの中身には、JSON にできる値（文字列・数値・オブジェクト・配列など）を入れられます。

預けた後、送り手はそのメッセージにもう関わりません。うまく処理されたか、失敗したかは、受け手とキューの間の話になります。

受け手：まとめて受け取り、まとめて片づける

受け手の Worker には、fetch() の代わりに（または並べて）queue() というハンドラを書きます。Cloudflare は、キューに貯まったメッセージを束（バッチ）にして、この queue() を呼び出します。

なぜ1通ずつではなく束なのでしょうか。1通ごとに Worker を起動するより、何通かをまとめて処理したほうが効率がよいからです。たとえば、ログを100件まとめてデータベースに1回で書き込めば、100回書くよりずっと速く、安くなります。

束の区切り方は、2つの設定で決まります。

「件数がいっぱいになる」か「時間が来る」かの、早いほうで束が送られます。メッセージが少ない時間帯でも、待たされすぎることはありません。

受け手は、束の中のメッセージを1件ずつ処理し、うまくいったものに ack()（受け取り済み）を付けます。ack されたメッセージは、キューから消えます。

失敗したら、キューに戻ってやり直す

受け手が仕事に失敗することはよくあります。メール配信サービスが一時的に落ちている、外部 API が混んでいて断られた、などです。

キューの大事な仕事は、こうした一時的な失敗で仕事を失わないことです。受け手がメッセージの処理に失敗すると、そのメッセージはキューに戻され、後でもう一度届けられます。

戻し方は2通りあります。

retry({ delaySeconds: 60 }) のように、次に届けるまでの待ち時間を指定できます。相手が混んでいるときにすぐ再挑戦しても、また断られるだけです。少し間を空けたほうが、成功しやすくなります。

再挑戦の回数には上限があり、max_retries で決めます。既定では数回です。上限を超えても失敗したメッセージがどうなるかは、次のページで見ます。

何度やってもダメなら、DLQ に隔離する

何度再挑戦しても失敗するメッセージがあります。メールアドレスの形式が壊れている、参照している利用者がもう削除されている、受け手のコードにバグがある、などです。これらは、何回やり直しても成功しません。

こうしたメッセージを置いておく場所が、デッドレターキュー（DLQ）です。max_retries を使い切ったメッセージは、設定しておいた DLQ に移されます。

DLQ が無いと、回数を使い切ったメッセージはそのまま消えます。何が失敗したのか、あとから調べる手がかりが残りません。

DLQ も、ふつうのキューと同じものです。だから、DLQ にも受け手を付けられます。

キューを作るときは、DLQ もいっしょに作る習慣にしておきましょう。

受け手が止まっても、受け付けは止まらない

ここまで見てきたことを、少し引いて眺めてみます。キューのいちばんの価値は、送り手と受け手を切り離すことです。

図では、受け手の Worker が止まっています。外のメール配信サービスが落ちたのかもしれませんし、受け手のコードに不具合があってデプロイし直している最中かもしれません。それでも、送り手は何も困りません。メッセージはキューに貯まっていき、利用者には「受け付けました」と返し続けます。受け手が直れば、貯まった分から順に処理されます。

この切り離しは、アクセスの急な増加にも効きます。

ただし、キューの保持期間には限りがあります。何日も止めたままにすると、古いメッセージから消えていきます（料金と制限のページ）。

導入：キューを作り、両側に書く

Queues を使い始める手順は、次のとおりです。

設定は、たとえば次のようになります。送り手と受け手が同じ Worker なら、1つのファイルに両方を書きます。

{
  "queues": {
    "producers": [{ "binding": "JOBS", "queue": "emails" }],
    "consumers": [{ "queue": "emails", "dead_letter_queue": "emails-dlq" }]
  }
}

binding に書いた名前（ここでは JOBS）が、送り手のコードの env.JOBS になります。

Queues は、以前は有料プラン専用でしたが、2026年2月から Workers の無料プランでも使えるようになりました。まず無料で試せます。

Worker の外から取りに行く「HTTP の受け手（pull consumer）」も作れます。Cloudflare の外のサーバーでメッセージを処理したいときに使います。

使い方：queue() で束を受け取り、ack する

受け手のコードは、次のようになります。

type Job = { type: "welcome-mail"; to: string; userId: string };

export default {
  async queue(batch: MessageBatch<Job>, env: Env): Promise<void> {
    for (const msg of batch.messages) {
      try {
        await sendMail(msg.body, env);
        msg.ack(); // 済み。キューから消える
      } catch (err) {
        console.error("送信に失敗", msg.id, err);
        msg.retry({ delaySeconds: 60 }); // 1分後にもう一度
      }
    }
  },
};

ポイントは、1件ずつ ack か retry かを決めることです。

束ごと戻すと、成功していたメッセージまでもう一度処理されます。メールなら二重送信です。1件ずつ決める書き方にしておくと、こうした巻き添えが起きません。

msg.id はメッセージごとの ID、msg.attempts は何回目の挑戦かです。ログに出しておくと、失敗を調べるときに役立ちます。

設定：束の大きさ・再挑戦・DLQ

受け手の設定（consumers）で、キューのふるまいを調整できます。

"consumers": [{
  "queue": "emails",
  "max_batch_size": 10,        // 1束の最大件数
  "max_batch_timeout": 5,      // 束がそろうまで待つ最大の秒数
  "max_retries": 3,            // 再挑戦の回数
  "dead_letter_queue": "emails-dlq",
  "max_concurrency": 5         // 同時に動く受け手の数の上限
}]

どれも既定値があるので、書かなくても動きます。ただし DLQ は既定では無いので、必ず自分で指定してください。

外のサービスに「1秒に何回まで」という上限がある場合は、max_concurrency と max_batch_size を小さめにして、受け手の速さを抑えます。

料金と制限：操作の回数で数える

Queues の料金は、キューに対する操作の回数で数えます。操作とは「書く・読む・消す」のことで、メッセージ 64KB ごとに1回と数えます。

ふつうの小さなメッセージ1通は、「送り手が書く・受け手が読む・ack で消す」で、およそ3回の操作になります。再挑戦すると、そのたびに「読む」が1回増えます。

1通のメッセージの大きさにも上限があります。画像や大きな JSON をそのまま入れず、中身は R2（22号）に置いて、メッセージにはそのキーだけを入れます。1日に1万回というと、およそ3,000通強です。試作には十分ですが、本番ではすぐに届く量なので、有料プランを考えましょう。

保持期間を過ぎたメッセージは、処理されないまま消えます。受け手を長く止めておかないようにしてください。

※2026年9月時点の情報です。料金・上限は変わるので、公式の Pricing と Limits のページで確かめてください。

よくある落とし穴

キューを使うと、「ふつうの関数呼び出し」とは違う性質に出会います。

いちばん大事なのは1つめの冪等（べきとう）です。同じメッセージが2回届いたときに、メールが2通届いたり、ポイントが2回付いたりしてはいけません。

よくある対策は、メッセージに一意の IDを入れておき、受け手が処理する前に「この ID はもう処理したか」を D1（23号）や KV（20号）で確かめる方法です。処理が済んだら、その ID を記録します。

他の号とのつながり

Queues は、ほかの機能と機能の間をつなぐベルトコンベアのような役目をします。

特に Workflows（25号）との使い分けは、よく迷うところです。「メールを1通送る」「画像を1枚縮める」のように、1回で終わる仕事をたくさんさばくなら Queues が向いています。「支払いを確かめ、在庫を押さえ、3日後にリマインドを送る」のように、何段にも分かれ、途中で待ったり、前の段の結果を使ったりする仕事なら Workflows が向いています。