◉GEMINI LABEN
●CLI 0.71 — Gemini CLI v0.71.0 のプレビュー版が公開されました。安定版は v0.70.0 のままです●TOOL RETR — Tool retrieval(Preview)で、道具の定義を必要なときだけモデルに読ませられるようになりました●2.5 ROUTE — 12/1 から gemini-2.5-pro は 3.8 Flash へ、2.5-flash は 3.5 Flash-Lite へ自動で回り、料金も移行先になります(残り9日)●OAUTH — 保存済みの MCP の OAuth トークンが、URL を差し替えた先にも確認なしで送られる、という報告が出ています●PICK — Gemini 4 のどのモデルを日常に使うかは、推論・長文・価格の3つで比べると迷いにくくなります●AG NEON — Antigravity の App v2.34.0 で、Gemini API キーからも Gemini 4 Neon を選べるようになりました●CLI 0.71 — Gemini CLI v0.71.0 のプレビュー版が公開されました。安定版は v0.70.0 のままです●TOOL RETR — Tool retrieval(Preview)で、道具の定義を必要なときだけモデルに読ませられるようになりました●2.5 ROUTE — 12/1 から gemini-2.5-pro は 3.8 Flash へ、2.5-flash は 3.5 Flash-Lite へ自動で回り、料金も移行先になります(残り9日)●OAUTH — 保存済みの MCP の OAuth トークンが、URL を差し替えた先にも確認なしで送られる、という報告が出ています●PICK — Gemini 4 のどのモデルを日常に使うかは、推論・長文・価格の3つで比べると迷いにくくなります●AG NEON — Antigravity の App v2.34.0 で、Gemini API キーからも Gemini 4 Neon を選べるようになりました
記事一覧/高度な活用
⬡ 高度な活用/2026-06-27上級

Gemini の完了イベントは二度届きます — Webhook と照合ポーラーを「実質1回」にする冪等な受け口

Gemini の長時間オペレーションを Webhook で受けつつ照合ポーラーで二重化すると、同じ完了イベントが二度届き、公開や課金が二度走ります。冪等キーの取り方と claim→実行→確定の三相で「実質1回」にする受け口を実装します。

gemini121webhook3idempotencybatch-api3production105

✦ プレミアム記事

長時間オペレーションをポーリングから Webhook へ移し、さらに取りこぼし対策として照合ポーラーを足した直後に、別の不具合が顔を出します。同じバッチの完了が二度処理され、生成済みの記事が二度公開されたり、完了通知が二通飛んだりするのです。

これは照合を足したことの副作用ではなく、二重路を持った時点で構造的に避けられない現象です。Webhooks に移してもデプロイの瞬間にイベントは落ちる、という照合の話が「欠落を拾い直す」側だとすれば、本記事は「拾い直した結果、同じものを二度掴んでしまう」側の手当てです。受け口を冪等にして、何度届いても副作用は一度だけ、という状態を作ります。

なぜ二度処理が起きるのか — 二重路は「事故」ではなく前提

Gemini の Webhook 配信は at-least-once です。受信側が 2xx を返す前にコネクションが切れれば、Google 側は配信成功を確認できず、同じイベントを再送します。受信は成功していたのに 2xx の返却だけ失敗した、というケースでも再送は起きます。つまり Webhook 単体でも、同じ完了が二度届く前提で組む必要があります。

そこへ照合ポーラーが加わると、重複の経路はさらに増えます。

重複が生まれる経路何が起きているか
Webhook の再送2xx 返却前に切断 → Google が同一イベントを再配信
Webhook と照合ポーラーの衝突Webhook 受信処理中に、低頻度ポーラーが同じ完了を独立に検知
デプロイ中の二度受け旧インスタンスが処理開始 → 切替で応答できず → 新インスタンスへ再送
手動リトライ運用者がポーラーを手で再実行し、確定前の完了を再投入

ここで大事なのは、これらを「異常系」として individually 潰そうとしないことです。どの経路も塞ぎきれません。代わりに、受け口を「何回呼ばれても結果が変わらない」形にしておけば、経路の数を気にせず済みます。冪等性とは、入口の数を減らす努力ではなく、出口を一本にする設計です。

全体像 — 受け口を「判定」と「副作用」に割る

二度処理を防ぐ鍵は、完了イベントを受け取ってから副作用(公開・課金・通知)を起こすまでの間に、一つの関門を置くことです。関門の役割は「この完了は、まだ誰も副作用を起こしていないか」を原子的に判定することです。

設計を三相に分けます。

  1. 正規化 — 届いたイベントから安定した冪等キーを取り出す
  2. クレーム(claim) — 「自分がこの完了を処理する」と先に主張し、競合を弾く
  3. 確定(commit) — 副作用を起こし切ってから、処理済みを記録する

Webhook レシーバーも照合ポーラーも、最後はこの同じ受け口を呼ぶだけにします。入口は複数でも、副作用を起こす関数は一つです。

✦

ここまでお読みいただきありがとうございます。

この記事の続きを読む

この先には、実装コードやベンチマーク結果など、実務でお役に立てる内容をご用意しています。このサイトは広告を掲載しておらず、サーバーや開発にかかる費用はメンバーの皆様のご支援で成り立っています。もしお役に立てていましたら、ご支援いただけますと大変ありがたいです。

この記事で得られること
✦Webhook と照合ポーラーの二重路で完了処理が二度走り、公開や通知が重複していた人が、実質1回に収める設計を手に入れられる
✦operation name から冪等キーを正規化し、SQLite の UNIQUE 制約で競合を弾く claim→実行→確定の三相を、動くコードで導入できる
✦副作用が途中で落ちたときの再試行と、クレームの有効期限の決め方まで含めて、無人パイプラインを安心して回せるようになる
Stripe による安全な決済 · いつでもキャンセル可能
✦

この記事を購入する

この先の内容をすべてお読みいただけます。一度のご購入で、いつでも何度でもアクセスできます。このサイトは広告を掲載しておらず、皆さまのご支援がサーバー費用などの運営を支えています。

または
メンバーシップなら全記事が読み放題 →
シェア

お読みいただきありがとうございます

Gemini Lab は広告なしで運営しており、サーバー費用などの運営コストはメンバーシップのご支援で賄っています。実装コード・ベンチマーク・本番設計パターンなど、実務でお役立ていただける記事を毎日更新しています。もし読んでよかったと感じていただけましたら、ぜひご覧ください。

  • ✦コピー&ペーストで使える実装コード付き
  • ✦毎日新しい上級ガイドを追加
  • ✦¥580/月 または ¥1,480 の永久アクセス
メンバーシップを見る →

関連記事

⬡ 高度な活用2026-04-27
Gemini Computer Use の自己修復アーキテクチャ — 失敗するブラウザ自動化を本番で安定稼働させる設計パターン
Gemini Computer Use のブラウザ自動化を本番で運用すると、要素消失・モーダル割り込み・ネットワーク遅延で頻繁に失敗します。失敗を「自己修復」させる回復戦略を、検出・分類・リトライ・人間介入のレイヤーに分けて、Pythonの動くコードで設計します。
⬡ 高度な活用2026-04-25
Gemini API で『自己批判するエージェント』を実装する — Reflection × Critic × Refiner で本番品質を継続的に上げる実装
Gemini 3 Pro と 3.5 Flash-Lite を組み合わせて自己批判するエージェントを構築する設計と本番運用ノウハウ。Reflection / Critic-Refiner パターンの実装、コスト上限、過剰修正の防ぎ方まで踏み込んで解説します。
⬡ 高度な活用2026-04-24
Gemini API のシャドウトラフィックで新モデル移行を安全に進める — 出力差分を本番で測る実装パターン
Gemini のモデル移行を「デプロイしてみないと分からない」から卒業するためのシャドウトラフィック設計。本番入力をコピーして新モデルに流し、出力差分を定量評価してから段階的にカットオーバーする実装パターンを、Python と Cloud Tasks のコード付きで解説します。