APIキーの確認を自動化するなら、「生きている／死んでいる」の2択だけでは足りません。認証は通っても使いたいモデルの権限がなかったり、利用上限へ達していたりするためです。キーの状態と、実行したい処理が可能かどうかを分けて記録します。
キーを一覧へ並べて試す仕組みは、秘密情報の複製や余計なリクエストを増やしがちです。管理表には秘密の値を入れず、承認された保管先を識別する名前を載せます。
管理表は秘密情報を含めずに作る
以下は架空の管理例です。実際のキーや接続結果ではありません。
| 管理名 | 用途 | 保管先の識別名 | 管理担当 | 最終確認 | 結果 |
|---|---|---|---|---|---|
| summary-dev | 開発用要約 | 開発環境の設定名 | 開発担当 | 未実施 | 未確認 |
| classify-prod | 本番の分類 | 本番の設定名 | 運用担当 | 未実施 | 未確認 |
これにプロバイダー、対象プロジェクト、使用する機能、許可するモデル、次の確認予定、無効化時の連絡先を加えます。秘密の値を持たない管理名なら、障害の相談や引き継ぎにも使えます。保管先へアクセスできる人の範囲は、表の閲覧者とは別に管理します。
確認結果を状態へ振り分ける
OpenAIのエラー資料では、429にも利用頻度、クレジット、組織やプロジェクトの利用上限など複数の原因があります。429を受けて、すぐにキーを無効と判定しないようにします。
| 状態 | 根拠として残すもの | 次の作業 |
|---|---|---|
| 未確認 | まだ通信していない | 担当者と確認条件を決める |
| 認証要確認 | 認証エラーのコード | 設定先と利用主体を確認する |
| 権限・モデル要確認 | 対象機能とエラーコード | 利用可能なモデルや権限を見る |
| 上限・課金要確認 | 上限に関するエラーコード | 利用状況と設定を確認する |
| 一時的な失敗 | 過負荷や一時的な制限 | 待機条件を確認する |
| 指定処理を確認済み | 対象機能、日時、成功の記録 | 必要な頻度で見直す |
最後の状態も、すべての機能が永久に使えるという意味ではありません。「いつ、何を確かめたか」を限定して記録します。
定期確認は既存の処理結果から始める
毎日すべてのキーで生成要求を送る前に、通常の業務処理が残す成功・失敗の記録を使えるか検討します。既に正常に動いた処理があるなら、確認専用の通信を重ねる必要がない場合もあります。
別途の疎通確認が必要な場合は、対象機能、確認頻度、最大試行数、利用額、失敗時の通知先を先に決めます。機密情報を含まない最小の入力を使い、確認要求にも料金や使用量が生じる前提で管理します。異なるサービスの認証方式やエラーを同じ関数で雑に判定しないことも大切です。
確認結果を記録する形式は、次のように作れます。
{
"setting_id": "summary-dev",
"checked_at": null,
"operation": "text-summary",
"model": null,
"result": "not_checked",
"http_status": null,
"error_code": null,
"next_action": "確認条件を担当者と決める"
}
ログと通知にキーを出さない
Authorizationヘッダー、設定値の一覧、要求全体は、診断ログへそのまま保存しません。記録するのは管理名、日時、対象処理、HTTPコード、秘密情報を除いた原因区分です。エラーメッセージにも入力内容が含まれ得るため、通知へ転記する範囲を決めます。
キーの変更後は管理名と保管先の対応を見直し、古い値を使う処理が残っていないかを確認します。自動確認が失敗しただけで、別のキーへ無制限に切り替える運用にはしません。権限や課金の問題が隠れるためです。
確認画面の考え方はGemini APIキー確認ツールの解説、GASでの設定の持ち方はGAS入門も参考になります。
