◉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 を選べるようになりました
記事一覧/API / SDK
◈ API / SDK/2026-06-24上級

Webhooks に移しても、デプロイの瞬間にイベントは落ちる — Gemini 長時間オペレーションを照合で二重化した運用メモ

ポーリングから Webhooks へ移した後でも、デプロイや一時的な 5xx の瞬間にイベントは取りこぼされます。Gemini の長時間オペレーションを操作台帳と低頻度の照合ポーラーで二重化し、終端イベントの欠落を拾い直す設計を実装メモとして残します。

Gemini API255Webhooks長時間オペレーションBatch API5信頼性設計3

✦ プレミアム記事

個人開発で回している夜間バッチが、ある朝だけ結果を書き戻していませんでした。ログを追うと、Batch API のジョブ自体は成功しています。ただ、完了を知らせる Webhook が届いた時刻に、ちょうどサイトの再デプロイが走っていました。受け口の Worker が一瞬だけ入れ替わり、その一発を取りこぼしていたのです。

ポーリングをやめて Webhooks に移したばかりの頃でした。イベント駆動にすればポーリングの無駄打ちが消える、という素直な期待で移行したのですが、その裏返しとして「受け損ねたら誰も気づかない」という新しい弱点を抱えていたわけです。

この記事は、その取りこぼしを二度と起こさないために組んだ、Webhooks と照合ポーラーの二重化の記録です。Gemini の長時間オペレーション(Batch API や時間のかかる生成)を題材にしていますが、設計の骨格は外部のイベント通知を受ける作り全般に流用できます。

取りこぼしは「異常系」ではなく「通常系」だと捉え直す

Webhooks は配送の保証として at-least-once を掲げます。つまり「最低1回は届けようとする」のであって、「必ず1回届く」ではありません。送り手は数回リトライしますが、受け口が落ち続ければリトライ枠を使い切ります。

個人開発の構成では、これが現実によく起きます。私自身の環境では、Cloudflare Workers に1日10回以上デプロイが走ります。そのたびに数百ミリ秒、受け口が不安定になる窓が開きます。コールドスタートや一時的な 5xx も重なります。送り手のリトライが全てこの窓に当たる確率は低いものの、ゼロではありません。1日に数十件のオペレーションを回していれば、月に1〜2件は静かに落ちます。

ここで大事なのは、これを「まれな障害」として例外処理に追いやらないことです。イベント駆動を採るなら、取りこぼしは設計が織り込むべき通常の挙動です。だからこそ、取りこぼしを回避するために、Webhooks を主経路にしつつ、独立した照合の経路で必ず回収する。この二重化を最初から前提に置きます。

全体像 — 高速路と低速路を分ける

設計は3つの部品で構成します。

部品役割起動契機
操作台帳送信した全オペレーションの状態を一元管理する正本ジョブ送信時に登録
Webhook 受け口(高速路)終端イベントを即時に受けて台帳を閉じるGemini からの通知
照合ポーラー(低速路)台帳に残る未完了を走査し、落ちた終端を拾い直す定期 cron

肝は、台帳を「Webhook が来たかどうか」ではなく「オペレーションが終端に達したかどうか」で管理する点です。終端に達したことを確定させる手段が2つある、と考えます。1つは Webhook(速い)、もう1つは照合時の operations.get 相当の問い合わせ(遅いが確実)。どちらが先に確定させても結果は同じになるよう、状態遷移を冪等にします。

✦

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

この記事の続きを読む

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

この記事で得られること
✦操作台帳(KV)と Webhooks 高速路・照合ポーラー低速路を組み合わせ、終端イベントを落とさない二重化の完全なTypeScript実装
✦デプロイ中に届かなかった Webhook を照合で拾い直す具体的な判定ロジックと、副作用を二重発火させない冪等キーの置き方
✦止まったまま戻らないオペレーションの検知しきい値と、照合の頻度・コストをどう決めたかの実測値
Stripe による安全な決済 · いつでもキャンセル可能
✦

この記事を購入する

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

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

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

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

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

関連記事

◈ API / SDK2026-11-14
OpenAI 互換レイヤーで JSON の形が揃わないとき、既存コードを残したまま response_json_schema へ寄せる3段階
OpenAI SDK の送り先だけを Gemini に向けたコードで、構造化出力が効いていないように見えるときの確かめ方と、関数の境界を変えずに Gemini SDK の response_json_schema へ移す手順を Python で整理します。
◈ API / SDK2026-10-30
「API key expired」と出ても、期限切れとは限りません。キーを作り直す前に、実際に送られているキーを確かめる
Gemini API が 400 の API_KEY_INVALID を返しても、応答だけでは期限切れか別の原因かを区別できません。環境変数の優先順位と空白・引用符を手元で確かめる診断スクリプトを、ダミーキーで動かした結果とともに残します。
◈ API / SDK2026-10-30
ADK のエージェントが「API key expired」で一度も動かない。文面ではなく reason を読むと、疑う順番が決まりました
ADK 経由で 400 INVALID_ARGUMENT「API key expired. Please renew the API key.」が毎回返るとき、期限切れと決めつける前に確かめる順番を整理しました。reason の読み方、環境変数と .env の食い違い、鍵の状態を REST で切り分ける短いスクリプト付きです。