この記事で分かること

外部APIを使う公開ツールの運営者へ。保存結果の再利用に加えて、新しい取得を上限内に保つ方法を、このサイトの実装と小さなデモから整理します。

  • HTTP要求・新規取得・同時取得を分ける考え方。
  • 失敗した取得も、通信前に予算へ計上する理由。
  • 短時間と日次の上限を、永続状態で確かめる方法。

保存結果だけでは防げない連続利用

Ciscoの一次確認ツールへ保存結果の再利用を加えた後、別のOS条件を何度も送られる場合も考慮しました。同じ条件なら保存結果を返せても、未取得の条件が増えれば外部APIの照会と処理負荷が増えます。

IPごとの制限だけでは、接続元が複数ある要求を全体として抑えられません。一方、共有回線のIPを使う正常な利用者まで止まる場合もあります。このサイトでは、HTTP要求、IPごとの新規取得、全体の取得予算を別々に持つ構成にしました。

対象上限保存先
当サイトへのHTTP要求IPごと60回 / 15分、全体600回 / 15分プロセスのメモリー
新しい条件の取得IPごと5回 / 15分プロセスのメモリー
外部API照会の試行全体20回 / 15分、100回 / 24時間非公開の永続ファイル
同時取得異なる条件は2件まで。同条件は1取得を共有プロセスのメモリー

この取得予算は、1回のOS条件の照会処理を1試行として数えます。OAuthの認証と結果のページ取得で発生する複数のHTTP通信は、その試行に含まれます。Cisco側の通信回数制限へ合わせるときは、1試行で発生する通信数と先方の上限も確認します。

数値はこの個人サイトで採用した値です。正常な利用量、外部サービスの制約、共有回線の利用状況に合わせて調整する対象で、すべての公開APIへ同じ値を使うものではありません。

外部通信の前に、取得予算を予約する

取得が成功した後にだけ回数を増やすと、認証失敗や通信失敗を繰り返す要求が上限を消費しません。失敗にも接続や処理が発生するため、このサイトでは接続する前に予算を予約して保存します。

  1. 入力の書式とHTTP要求の上限を確認する。
  2. 期限内の同条件の保存結果があれば返す。
  3. 同条件の取得が進行中なら、その結果を共有する。
  4. 新規取得の上限と同時処理数を確認する。
  5. 全体の取得予算を予約し、永続化できてから通信する。
  6. 結果を検証し、完全な結果だけを保存する。
reservation = budget_reserve(state_dir, now)
if not reservation["allowed"]:
    return "blocked_before_connection"
# ここに進む前に、試行は状態ファイルへ記録されている
# 以降の通信が失敗しても、この試行は数える

予算の保存に失敗した場合は、取得へ進まない扱いです。「上限ファイルが読めないから回数を0にする」と、故障時に制御が外れます。保存状態の破損と上限到達は、利用者への案内も運用側の確認も分けます。

短時間の集中と、1日の総量を別々に見る

15分の上限は短時間の集中、24時間の上限は一日の総量を抑えます。このサイトの全体予算は、試行の時刻を保存し、直近15分と直近24時間に残る件数を数えます。日付が変わった瞬間に予算をすべて戻す処理ではありません。

上限に達したときは、必要な枠が空くまでの時間を計算します。短時間枠が空いても日次枠が満杯なら、日次枠が空くまで新規取得はできません。上限到達を返すHTTP 429と待ち時間の案内は、429 Too Many Requestsの説明 ↗も参照できます。

この制限でも、期限内の保存結果には外部取得の予算を使いません。正常な利用者が同じ条件を確認する際は、保存結果を返せます。ただしHTTP自体の上限は別に適用されます。

成功・失敗・上限到達を手元で試す

Python 3.12系の標準ライブラリだけを使うオフライン例です。cache_demo.pyを新しい作業フォルダに保存し、保存先を専用フォルダへ指定します。

python cache_demo.py --mode budget --state-dir demo-budget --reset

説明用の上限は15分2回、24時間3回です。固定時計を進める例なので、15分や24時間を実際に待つ必要はありません。本番の20回・100回とは別の数値です。

イベントallowedattempts / outcome
successful requesttrue1 / upstream_succeeded
connection failuretrue2 / upstream_failed_but_charged
short window exhaustedfalse2 / blocked_before_connection
short window reopenedtrue3 / upstream_succeeded
daily limit exhaustedfalse3 / blocked_before_connection

二つ目の失敗も回数2へ増え、三つ目は通信前に止まります。短時間の枠が空くと3回目を予約できますが、その次は日次上限で止まります。budget.jsonには成功した結果ではなく、予約した試行時刻が入ります。

--mode combinedは保存結果と取得予算の二つの独立したデモを続けて表示します。本番のように一つのAPI処理へ統合したクライアントではありません。繰り返すときは新しい状態フォルダか--resetを使い、固定時計が保存済みの時刻より前へ戻らないようにします。

再起動と、複数プロセスへの備え

プロセス内のカウンターは起動し直すと失われます。このサイトでは全体の取得予算をDockerの非公開volumeへ置き、再起動後も読み込みます。実ASA照会を1回行い、再起動後と公開画面での保存結果の確認後にも、取得予算が1回のままであることを確認しました。

同じファイルを複数プロセスが同時に更新すると、予約が重なって失われることがあります。本番は一つのアプリプロセスがvolumeを所有する構成です。配布用のPython例にはロックがありますが、複数サーバーや分散した取得予算への対応例ではありません。

接続元IPを使うときも、任意の転送ヘッダーを信用しないようにします。このサイトでは、設定した単一のプロキシから届く正しい形式のIPだけを採用しています。ブラウザーにAPIのClient Secretを渡さないことは、利用回数の制御と合わせて必要です。

失敗時の確認と、抑えられる範囲

正常な利用でも上限へ達するなら、実際の取得件数、保存結果のヒット、同時要求、共有回線の利用を分けて確認します。取得を減らす目的で、古い保存結果を無期限に返すようには変更しません。状態が読めない場合は保存先・権限・JSON・サーバー時刻を確認します。

回数制限は外部APIとアプリ処理を保護する一つの手段です。回線を埋める規模の攻撃を、このカウンターだけで防ぐことはできません。また全体予算が悪用で消費されると、新規取得は正常な利用者にも制限されます。実際の利用を見て、プロキシ側の制御や利用者の確認が必要か判断します。

2026年10月4日に、本番の単一writer・再起動後の取得予算維持と、配布用の予算デモを確認しました。保存の仕様はPython 3.12のosモジュール ↗、HTTPの案内はHTTP 429の説明 ↗を参照しています。