記録セッションからAPIクライアントを導出する
ブラウザを駆動するのは最初の訪問には適したツールですが、100回目には適していません。このスキルは、サイトを使用している間に一度だけネットワークトラフィックを記録し、そのキャプチャしたリクエストを、サイト内部APIと直接通信するスタンドアロンクライアント（スクリプト、CLI、ライブラリ）に変換します。
記録だけですべての情報が含まれています。agent-browserはデフォルトでテキストレスポンスボディ（JSON/HTML/JS）をHARに埋め込むため、ブラウザを閉じた後でもエンドポイントの形状をオフラインで調査できます。
ワークフロー
1. 記録 HARキャプチャを開始し、クライアントに必要なフローを実行する
2. 特定 ノイズの中から実際のAPIエンドポイントを見つける
3. 抽出 リクエスト形状、レスポンススキーマ、認証情報を抽出する
4. 生成 フローごとに関数を持つクライアントを記述する
5. 検証 完了宣言前にすべてのエンドポイントを実際に呼び出す
1. 記録
agent-browser network har start # デフォルトでテキストレスポンスボディを埋め込む
# ... サイトを操作する: 検索、詳細ページを開く、ページネーションなど ...
agent-browser network har stop /tmp/site.har
- クライアントがサポートするすべてのフローを実行し、それぞれを異なる入力（2つの検索語、2つの詳細ページ）で少なくとも2回実行します。記録されたURLを差分比較することで、どの部分がパラメータかを特定できます。
- サイトにログインが必要な場合は、HARを開始する前にログインして、認証情報が不要に記録されないようにします。セッションクッキーはステップ3で別途エクスポートします。
--content allはバイナリボディも埋め込みます（base64）。--content noneは埋め込みを無効にします。ボディあたりの上限は2MBです。
セッションが開いている間は、agent-browser network requests および network request <id> でも同じデータを対話的に取得できます。ただし、ブラウザのナビゲーションやクローズ後も保持されるのはHARのみであるため、複数ページにまたがる操作にはHARを使用することを推奨します。
2. エンドポイントの特定
jq を使用してHARをクエリします:
# すべてのJSON API呼び出し: メソッド、URL、ステータス
jq -r '.log.entries[]
| select(.response.content.mimeType | test("json"))
| "\(.request.method) \(.response.status) \(.request.url)"' /tmp/site.har
アナリティクスやインフラストラクチャのノイズは無視します: テレメトリアップポイント（/collect、/track、/beacon、/log）、サードパーティドメイン（google-analytics、segment、sentry、datadog、intercom、hotjar）、静的アセット。実際のAPIは通常、ファーストパーティ、JSON、そして実行したアクションと相関しています。
3. 形状と認証情報の抽出
# 1つのエンドポイントの詳細: リクエストヘッダー、POSTボディ、レスポンスボディ
jq '.log.entries[] | select(.request.url | test("api/search"))
| {request: {method: .request.method, headers: .request.headers,
postData: .request.postData.text},
response: .response.content.text}' /tmp/site.har
- レスポンススキーマ:
.response.content.textを読む — これが実際のペイロードであり、型を導出するために使用します。 - 認証: エンドポイント間でリクエストヘッダーを比較します。
authorization、cookie、x-csrf-token、x-api-key、およびサイト固有のx-*ヘッダーを探します。重要なものだけを再生 — ステップ5で省略してテストします。 - クッキー:
agent-browser cookies get --json > cookies.jsonでライブセッションをエクスポートし、クライアントが実行時に読み込めるようにします。生成されたソースにクッキー値をハードコードしないでください。
4. クライアントの生成
- 記録されたフローごとに1つの関数（
search(query)、getItem(id)）を、観測されたレスポンスボディから型付けして作成します。 - 認証情報（クッキー、ベアラートークン）はファイルまたは環境変数から読み込み、期限切れ時にユーザーにブラウザログインの再実行を促す明確なエラーメッセージを表示します。
- APIが実際に必要とするヘッダーを再現します — 一部のサイトでは
user-agent、referer、x-requested-withが一致しないと403になります。 - 記録されたクエリ文字列に現れたページネーション、ソート、フィルタパラメータは関数のオプションとして保持します。
5. 検証
生成されたすべての関数を実際のAPIに対して呼び出し、レスポンスの形状を記録と比較します。一般的な障害:
| 症状 | 原因 | 修正 |
|---|---|---|
| 401/403 | 期限切れまたは欠落したセッション | agent-browserで再ログインし、クッキーを再エクスポート |
| 403/419（書き込み時） | CSRFトークンがセッションごとまたはフォームごとに異なる | まずトークンエンドポイントを取得するか、そのフローはブラウザ駆動のままにする |
| 動作してから壊れる | 署名付き/有効期限付きのリクエストパラメータ | そのステップはブラウザにフォールバックし、残りは導出する |
| HARと異なる形状 | A/Bテストや地域依存のレスポンス | 再記録し、結合をオプションフィールドとして扱う |
注意点
- 内部APIはバージョン管理されておらず、予告なく変更されることがあります。クライアントを再導出できるようにHARを保持してください。
- サイトの利用規約とレート制限を尊重し、バルクフェッチには遅延を追加してください。
- HARファイルにはライブセッションの認証情報（クッキー、トークン、POSTボディ）が含まれています。機密情報として扱い、バージョン管理から除外し、使用後は削除してください。