webRequest

リクエストを修正する

いくつかのイベントでは、リクエストを修正できます。特に、次のことが可能:

• 次の API でリクエストをキャンセル:

  • onBeforeRequest
  • onBeforeSendHeaders
  • onAuthRequired

• 次の API でリクエストをリダイレクト:

  • onBeforeRequest
  • onHeadersReceived

• 次の API でリクエストヘッダーの修正:

  • onBeforeSendHeaders

• 次の API でレスポンスヘッダーの修正:

  • onHeadersReceived

• 次の API で認証資格情報の提供:

  • onAuthRequired

これを行うには、イベント addListener() の extraInfoSpec の引数に"blocking"の値のオプションを渡す必要があります。これによりリスナーが同期します。

このリスナーでは BlockingResponse オブジェクトを返すことがあります。これは行うことが必要な変更を示します。例えば、送信したい修正後のリクエストヘッダーなどです。

ブラウザー起動時のリクエスト

"blocking" オプションを指定してリスナーを登録し、かつその登録が拡張機能の起動中に実行された場合、ブラウザーの起動中にそのリスナーに一致するリクエストが発生すると、拡張機能は早期に起動します。これにより、拡張機能はブラウザーの起動時にそのリクエストを監視することができます。これらの手順を実行しない場合、起動時に発生したリクエストを見逃してしまう可能性があります。

投機的リクエスト

ブラウザーは、URI へのリクエストがまもなく行われる可能性があると判断した場合、投機的接続を確立することがあります。この種の接続では有効なタブ情報が提供されないため、tabId、frameId、parentFrameId などのリクエストの詳細は不正確になります。これらの接続の webRequest.ResourceType は speculative となります。

セキュリティ情報へのアクセス

onHeadersReceived リスナー内では、getSecurityInfo() を呼ぶことで TLS にアクセスできます。これを行うには、イベントの addListener() の extraInfoSpec 引数に"blocking" を渡す必要もあります。

TLS ハンドシェイクについて詳しく読むことができますが、修正したり、ブラウザーのトラストな決定を上書きできません。

レスポンスの修正

webRequest.filterResponseData にリクエスト ID を渡すことで得られる webRequest.StreamFilter を使うと、ブラウザーが受け取った HTTP リクエストのレスポンス本文を検査したり修正したりすることができます。

そのためには、"webRequestBlocking" 権限と "webRequest" API 権限 、さらに修正したい対象のリクエスト URL にあてはまる host 権限を得ている必要があります。

型

webRequest.BlockingResponse

この型のオブジェクトは、イベントリスナーによって extraInfoSpec 引数にて "blocking" をセットして返されます。BlockingResponse プロパティに特定の値をセットすることで、リスナーはネットワークリクエストを変更できます。

webRequest.CertificateInfo

単一の X.509 証明書を記述するオブジェクト。

webRequest.HttpHeaders

HTTP ヘッダーの配列。それぞれのヘッダーは 2 つのプロパティを持つオブジェクトで表現されます: name と、value か binaryValue のいずれか。

webRequest.RequestFilter

webRequest イベントに適用するフィルターを記述するオブジェクト。

webRequest.ResourceType

ウェブリクエスト内で取得されるリソースの特定の種類を表す。

webRequest.SecurityInfo

特定のウェブリクエストのセキュリティプロパティを記述するオブジェクト。

webRequest.StreamFilter

HTTP レスポンスの受信中に、それをモニターしたり修正したりするのに使うオブジェクト。

webRequest.UploadData

URL リクエスト内でアップロードされるデータを含む。

プロパティ

webRequest.MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES

10 分間に handlerBehaviorChanged() を最大限呼べる回数。

メソッド

webRequest.handlerBehaviorChanged()

このメソッドは、ページがブラウザーのインメモリーキャッシュ内にあるときに、イベントリスナーが確実に呼べるように使われます。

webRequest.filterResponseData()

あるリクエストに対する webRequest.StreamFilter オブジェクトを返します。

webRequest.getSecurityInfo()

あるリクエストに対する TLS コネクションの詳細情報を返します。

イベント

webRequest.onBeforeRequest

リクエストがもうすぐなされて、ヘッダーは利用できないときに発生します。リクエストをキャンセルやリダイレクトしたい場合に、ここをリッスンします。

webRequest.onBeforeSendHeaders

HTTP データを送信する前だが、HTTP ヘッダーが利用できるときに発生します。HTTP リクエストとヘッダーを修正したい場合に、ここをリッスンします。

webRequest.onSendHeaders

ヘッダー送信の直前に発生します。あなたや他の人のアドオンが onBeforeSendHeaders でヘッダーを修正した場合、ここでは修正後のバージョンが見えるでしょう。

webRequest.onHeadersReceived

リクエストに関連する HTTP レスポンスヘッダーを受け取ったときに発生します。HTTP レスポンスヘッダーを修正するのにこのイベントを使用できます。

webRequest.onAuthRequired

サーバーがクライアントに認証資格情報を要求するときに発生します。このリスナーは何もしないか、リクエストをキャンセルするか、認証資格情報を供給するかのいずれかです。

webRequest.onResponseStarted

レスポンスボディの最初のバイトを受け取ったときに発生します。HTTP リクエストにとって、これはステータスラインとレスポンスヘッダーが利用可能ということになります。

webRequest.onBeforeRedirect

サーバーが開始するリダイレクトが起きる直前に発生します。

webRequest.onCompleted

リクエストが完了したときに発生します。

webRequest.onErrorOccurred

エラーが起きたときに発生します。

Example extensions

• http-response
• root-cert-stats
• stored-credentials
• user-agent-rewriter

ブラウザーの互換性

Chrome との非互換性に関するメモ.