ビジュアルワークフローにおけるサードパーティAPI向けサーキットブレーカー パターン

サードパーティAPIの障害が一つ以上の機能を壊す理由

単一のサードパーティAPIは日常業務の中心に位置することが多い：決済、住所確認、在庫同期、メッセージ送信、本人確認など。ベンダーに問題が起きると、たいてい一つのボタンだけが壊れるわけではありません。ワークフロー全体が停止し、先に進むための応答を待つ必要が出ます。

だからこそサーキットブレーカーが重要です。これは理論ではなく、統合が不健康なときでも主要な業務を回し続ける実践的な方法です。

遅いことと停止は別のダメージを与えます。

APIが遅いとワークフローは成功しようとし続けますが、各ステップが待たされます。ユーザーはロード中の画面を見て、サポートには「止まっている」というチケットが届き、バックグラウンドジョブが蓄積します。遅延は自分のシステムが壊れているように見せがちです。

APIがダウンするとタイムアウトや明確なエラーが返ります。判りやすい一方で危険なのは、ワークフローが再試行しがちで、多数のリクエストが同時に再試行するとトラフィックの嵐を作り回復を難しくし、自分のシステムまで引きずり下ろす可能性があることです。

一般的な症状はすぐに現れます：タイムアウト、増え続けるキュー、部分的な更新、手動でのクリーンアップの増加。

本当の被害は連鎖反応です。配送レート提供者が遅いと、見積もりがないため注文確定が遅れます。決済が止まると、他は正常でもサポートが返金を出せないことがあります。

障害を無かったことにはできません。目標は、ワークフローに明確なフォールバック経路、一時的なブロックルール、アラートを設計して、統合が復旧する間もビジネスが注文を受け顧客対応を続けられるようにすることです。

サーキットブレーカーを簡単に説明すると

サーキットブレーカーはAPI呼び出しの安全スイッチです。サードパーティサービスが失敗し始めたとき、ブレーカーはワークフローがそれを何度も叩くのを止めます。単一の障害が遅延やタイムアウト、詰まりを招く代わりに、被害範囲を制御します。

サーキットブレーカーの結果は三つに分かれます：

• ベンダーが健全に見えるときは呼び出しを許可する。
• 失敗が多いときは呼び出しをブロックして即座にフォールバックを取る。
• 短い休止後に限定的なテスト呼び出しを試す。

ラベルで言うなら「Closed」「Open」「Half-open」です。名前自体は重要ではなく、予測可能性が大事です。ベンダーが不調なとき、ワークフローは毎回同じ振る舞いをするべきです。

これはエラーを隠すものではありません。失敗は記録し、ユーザーや運用に明確な状態を示し、適切な担当者にアラートを送ります。速やかに失敗を選び、安全な代替にルートするか、短時間の後に再試行する、という選択をしています。

どのAPI呼び出しが業務を止めてはならないかを選ぶ

サーキットブレーカーは選択的に使うと効果的です。全てのベンダー呼び出しが特別な保護を必要とするわけではありません。まずは、ブロックされるとお金や注文、顧客アクセスが止まるようなステップから始めてください。

実践的な方法は一つのユーザーリクエストを端から端まで追うことです。どのタイムアウトがユーザーに操作中断を強いるか、あるいは後でチームが手作業で直さなければならない混乱を生むかを見ます。

典型的に「業務を止めてはいけない」呼び出しは、支払い、配送とフルフィルメント、ログイン/SSO/MFA、OTPや確認メッセージ、承認に結びつくコンプライアンスチェックなどです。

ユーザー向けのステップとバックグラウンドジョブは分けて考えましょう。チェックアウト画面で待っているユーザーには速い判断が必要です：成功、フォールバック、または明確なメッセージで停止。追跡番号の同期のようなバックグラウンド作業は、メインフローをブロックしない限り遅い再試行が許容されます。

範囲の膨張を避けるために小さく始めてください。まず1〜3ワークフローを保護し、信頼が得られたら拡張します。

何が「安全なフォールバック」かを事前に定義してください。良いフォールバックは具体的でテスト可能です：

• 支払い：カートを失わないよう注文を「支払い保留」として保存する。
• 配送：キャッシュされたレート、フラットレートを使うか、注文を確定してラベル購入を遅らせる。
• 本人確認：SSOが落ちているときはパスワードログインを許可する、またはメール確認に切り替える。
• メッセージング：SMSを後で送るようキューに入れ、可能なら代替経路を提供する。

AppMaster の Business Process Editor では、これは通常きれいな分岐になります：コア操作は続行し、ベンダー依存のステップだけが制御された代替を取ります。

状態、閾値、タイマーの説明

サーキットブレーカーは安全スイッチです。普通は呼び出しを通しますが、ベンダーが失敗し始めたらワークフローを無駄な時間やエラーの蓄積から守るために切り替わります。

三つの状態

Closed は通常です。APIを呼び、続行します。

失敗があるラインを越えるとブレーカーは Open になります。しばらくベンダー呼び出しを止め、キャッシュ値やキュー処理、代替フローへ即座にルートします。

クールダウン後にブレーカーは Half-open になります。少数のテスト呼び出しを許可し、成功すれば Closed に戻し、失敗すれば再び Open にします。

測定すべきもの

ベンダーがどう失敗するかに合ったシグナルを使います：

• タイムアウト
• HTTP 5xx エラー
• 上昇するレイテンシ（実用に耐えない遅さ）
• 接続/DNSエラー
• 429 レート制限

ビジュアルワークフローツールでは、これらは通常ステータスコード、経過時間、特定のエラー出力といった単純なチェックにマップされます。

初期閾値と二つの重要なタイマー

説明しやすい数字から始めて、実際のトラフィックでチューニングします。例：

• 30〜60秒の間に5〜10回失敗したらブレーカーを開く。
• またはローリングウィンドウで20%〜40%の失敗率になったら開く。
• レイテンシはプロセスが許容できる時間（多くは2〜5秒）を超えたら失敗と扱う。

それから二つのタイマーを設定します：

• クールダウン時間（Open 状態）: 通常30秒〜5分。
• ハーフオープンのテスト窓: 1〜5回のテスト呼び出し、または10〜30秒の短い時間窓など。

目標は単純です：ベンダーが不健康なときは速く失敗し、回復したら自動的に復帰すること。

ステップバイステップ：ビジュアルワークフローでサーキットブレーカーを作る

最も重要な設計は「今ベンダーを呼ぶべきか？」の判断を一箇所にまとめることです。各ワークフローに散らばせてはいけません。

1) ベンダー呼び出しを再利用可能ブロックの背後に置く

すべてのワークフローがそのベンダーを必要とするときに呼べるサブプロセス（再利用可能なワークフローブロック）を作成します。AppMaster ではこれは Business Process に自然に対応します。幅は狭く保ちます：入力が入り、ベンダーにリクエストを送り、成功/失敗の明確な結果を返すだけにします。

2) カウントだけでなく時間で失敗を追跡する

各結果をタイムスタンプ付きで記録します。最後の成功、最後の失敗、ウィンドウ内の失敗数、現在の状態、クールダウン期限などを保存してください。

これらのフィールドはテーブルに永続化し、ブレーカーが再起動や複数インスタンス間で一貫性を保てるようにします。Data Designer 経由の PostgreSQL がよく合います。

3) 毎回従う状態変化を定義する

ルールは単純に保ちます。例：2分間に5回の失敗があれば Open に切り替える。Open の間はクールダウンが過ぎるまでベンダー呼び出しをスキップする。クールダウン後は Half-open にして一回の管理された試行を許可する。成功すれば Close、失敗すれば再び Open。

4) ワークフローを分岐させる：ベンダーパス vs フォールバックパス

ベンダー呼び出しの前に保存された状態をチェックします：

• Closed: ベンダーを呼び、成功または失敗を更新する。
• Open: 呼び出しをスキップしてフォールバックを実行する。
• Half-open: 制限された試行を許可し、成功/失敗で閉じるか再開するか決める。

例：配送ラベルAPIが落ちている場合、フォールバックは注文を「ラベル保留」ステータスで作成し、チェックアウトや倉庫作業をブロックしないようにして再試行ジョブをキューに入れることができます。

5) ワークフロー間で共有する

複数のワークフローやサーバーがある場合、同じブレーカー状態を読み書きする必要があります。そうでなければ、あるインスタンスは既に停止を決めているのに別のインスタンスがベンダーを叩き続ける可能性があります。

作業を進めるフォールバック

サーキットブレーカーは呼び出しをブロックするだけでは意味がありません。ブロックされたときに何をするか決めておく必要があります。良いフォールバックはユーザーの作業を進め、データを保護し、後での調整を予測可能にします。

フォールバックは作業に合うものを選んでください。配送レート提供者が落ちている場合、正確な価格がなくても注文を受けられることがあります。ビジュアルワークフローでは、失敗したAPIステップを使いやすい結果を生むフォールバック分岐にルートします。

実務でよくあるフォールバック：

• 最後に知られているキャッシュ値を使う（鮮度ウィンドウを明示）
• 安全なデフォルトの見積りを使用し、明確に表示する
• 手動レビューに回す
• 作業を後で再試行するためにキューに入れる（非同期ジョブ）

ユーザー体験はロジックと同じくらい重要です。あいまいなエラーを出さないでください。何が起きたかと次にユーザーができることを伝えます：「現在レートを確認できません。推定配送費で注文するか、レビュー用に保存できます」など。

短期障害と長期障害の両方を計画してください。短期（数分）は「続行してバックグラウンドで再試行」でよいことが多い一方、長期（数時間）は手動レビューや承認の導入が必要になる場合があります。

最後に、すべてのフォールバックを追跡して照合しやすくしてください。最低限、フォールバックの種類、元のリクエスト詳細、ユーザーに返した内容（推定かどうか）、フォローアップ用のステータスを記録します。

一時的なブロックルールと賢い再試行

制御されていない再試行は小さなベンダーの不調を本当の障害に変えます。多くのワークフローが同時に再試行するとスパイク（thundering herd 問題）を生み、ベンダーがさらに遅くなりキューが溜まり、レート制限を消費します。

再試行は予測可能で制限され、ブレーカー状態を尊重すべきです。実用的なポリシー：

• 最大再試行を低く保つ（多くは2〜3回）
• 指数バックオフを使う（例：2s、8s、30s）
• ジッターを加えて同調を避ける
• 総再試行時間に上限を設ける（例：60〜90秒）
• ブレーカーが Open の場合は再試行しないでフォールバックに移る

一時的ブロックは関連するが別物です。レスポンスが「今は動作しない」と明示している場合に適用します。一般的ルール：

• 429 レート制限： Retry-After 指定があればその期間、なければ安全な固定ウィンドウでブロックする
• 401/403 認証失敗： 資格情報が更新されるまでブロックし、更新後に一度テストする
• 継続的な 5xx： 短時間ブロックし、後に小さなテストを許可する

ブロック中に既に進行中の作業をどう扱うかを決めます：キューに入れる、別ルートへ回す、あるいはグレースフルに劣化（例：「SMS送信を遅らせる」）するなど。

何をすべきかが分かるアラート

サーキットブレーカーは人に速やかに伝わり、何をするべきか分かるときにのみ役に立ちます。目的はノイズではなく、挙動が変わったときに一つの明確なメッセージを出すことです：呼び出しがブロックされている、フォールバックが有効になっている、またはブレーカーが予想より長く開いたままになっている、など。

良いデフォルトのトリガー：

• ブレーカーが開いたときに通知する
• 期待以上に長く開いたままなら通知する
• 開く前にエラーが急増したら通知する

アラートは実行可能であること。ベンダーとエンドポイント、現在の状態と変更時刻、ユーザーにどんな影響が出るか、ワークフローが今何をしているか（ブロック、再試行、フォールバック）、そして推奨される次の一手を含めてください。

重大度に応じてアラートのルーティングを変えます。重要でない補助APIはメールで十分でも、支払いやログイン、注文送信はページ（オンコール）に値するかもしれません。AppMaster ではこれを severity フラグに応じてメール、Telegram、SMS に分岐することで実現できます。

回復状況を見られるように小さな指標セットを追跡してください：ベンダーごとのブロックされた呼び出し数やフォールバック利用率があれば十分なことが多いです。

例：注文を止めずにベンダー障害を扱う

よくある障害は、配送レート提供者が顧客がチェックアウトしているときに落ちるケースです。ワークフローが注文作成時にライブレートを必須にしていると、単一障害で注文が止まってしまいます。

通常は注文が作られ、その後ワークフローがライブレートを要求し、選択されたキャリアと価格で注文が保存されます。

ベンダーが失敗し始めると呼び出しはタイムアウトしたり 5xx を返します。閾値（例：2分で5回失敗）に達するとブレーカーは開きます。

Open の間、ワークフローは短いウィンドウ（例：10分）でベンダー呼び出しを止めます。これにより障害のベンダーが全員のチェックアウトを引きずり下ろすのを防ぎます。

チェックアウトをブロックする代わりにフォールバックは次のようにできます：

• フラットレートを適用する（または安全な見積りを使う）
• とにかく注文を作成する
• 注文を「配送レート保留」とマークして後で再計算する
• ベンダーのエラー詳細を保存してフォローアップする

AppMaster ではこれが Business Process Editor の明確な分岐になり、shipping_rate_status や shipping_rate_source のような Data Designer フィールドで裏付けられます。

本番リリース前のクイックチェック

サーキットブレーカーはデモ時と同じようにストレス下でも動くべきです。リリース前に基本を確認してください：

• 閾値とクールダウンが文書化され変更しやすいこと
• Open 状態が即座に呼び出しをブロックすること（ベンダーのタイムアウトを待たない）
• フォールバック挙動が金銭や顧客との約束に対して安全であること
• Half-open のプローブが数回のテスト呼び出しに制限されていること
• ログにタイミングと影響が分かりやすく記録されていること

フォールバックの安全性には特に時間を割いてください。作業を進めるフォールバックが金銭的リスクを生むことがあります。例えば決済プロバイダが落ちているときに「支払い済み」とマークするのは危険です。より安全なのは「支払い保留」として、顧客に明確に伝える方法です。

回復テストは意図的に行ってください。障害を強制し、ブレーカーが開くのを観察し、クールダウンを待って Half-open が少数のプローブだけ送ることを確認します。成功すれば素早く閉じ、失敗すればベンダーを洪水させることなく再び開くべきです。

ログは1分以内に次の質問に答えられるべきです：誰が影響を受けたか、いつ始まったか、どのワークフローステップがブレーカーを引いたか、どのフォールバックが使われたか。

次のステップ：AppMaster でパターンを実装する

日常業務に支障を来す可能性がある統合（支払い、配送ラベル、SMS、CRM同期など）を一つ選んでください。その単一の呼び出しに対してエンドツーエンドでブレーカーを構築します。チームが挙動を信頼できるようになったら、同じテンプレートを別のベンダーにも適用してください。

AppMaster ではブレーカー状態を PostgreSQL に Data Designer でモデル化します。シンプルに保ち、ベンダー（またはエンドポイント）ごとにレコードを置き、state、failure_count、last_failure_at、open_until、短い last_error のようなフィールドを持たせます。

次に Business Process Editor で読みやすい分岐ロジックを実装します。明快さは凝った仕組みより重要です。

実用的な構築順：

1. ブレーカー状態をチェックし、open_until が未来なら呼び出しをブロックする。
2. ベンダーAPIを呼び、成功とエラー両方をキャプチャする。
3. 成功時はカウンターをリセットしてブレーカーを閉じる。
4. 失敗時はカウンターを増やし、閾値に達したらブレーカーを開く。
5. ユーザー向けフローはフォールバックへルートする（作業をキュー化、キャッシュデータを使う、手動処理を許すなど）。

フォールバックの決定はサポートや運用がユーザーに何を見せるか分かるよう平易な言葉で文書化してください。

ブレーカーが開いたら、所有者に AppMaster のメッセージングモジュール（メール、SMS、Telegram）で通知します。重要なのはベンダー、エンドポイント、状態、そして推奨される最初のアクションです。

これらのワークフローを AppMaster で構築するなら、appmaster.io はビジュアルな Business Process がエンドポイント、バックグラウンドジョブ、アラートを共通のブレーカー状態で動かせる実用的な出発点になります。