この記事で分かること
外部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へ同じ値を使うものではありません。
外部通信の前に、取得予算を予約する
取得が成功した後にだけ回数を増やすと、認証失敗や通信失敗を繰り返す要求が上限を消費しません。失敗にも接続や処理が発生するため、このサイトでは接続する前に予算を予約して保存します。
- 入力の書式とHTTP要求の上限を確認する。
- 期限内の同条件の保存結果があれば返す。
- 同条件の取得が進行中なら、その結果を共有する。
- 新規取得の上限と同時処理数を確認する。
- 全体の取得予算を予約し、永続化できてから通信する。
- 結果を検証し、完全な結果だけを保存する。
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回とは別の数値です。
| イベント | allowed | attempts / outcome |
|---|---|---|
| successful request | true | 1 / upstream_succeeded |
| connection failure | true | 2 / upstream_failed_but_charged |
| short window exhausted | false | 2 / blocked_before_connection |
| short window reopened | true | 3 / upstream_succeeded |
| daily limit exhausted | false | 3 / 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の説明 ↗を参照しています。