webRequest

websocket が ws:// and wss:// としてリクエストするものも含めた、HTTP リクエスト作成のいろいろなステージでイベントリスナーを追加します。イベントリスナーはリクエストの詳細情報を受け取ったり、リクエストを編集、修正したりします。

それぞれのイベントはリクエストの特定ステージで発火します。イベントの典型的なシーケンスは次のようなものです:

onErrorOccurred はリクエストの期間中のあらゆる時に発火します。また注意点としてイベントシーケンスがこれと違うこともあります: 例えば、Firefox では、HSTS 更新の時には、onBeforeRequest のすぐ後にonBeforeRedirect イベントが発火します。

onErrorOccurred を除くすべてのイベントはaddListener() への次の 3 つの引数を取ります:

リスナー自身
filter オブジェクト、これを使って特定の URL や特定のリソースタイプにリクエストされた時だけに通知を受けられます。
オプションのextraInfoSpec オブジェクト。これを使ってイベントに固有な追加の命令を渡せます。

リスナー関数はリクエストの情報を含むdetails オブジェクトを渡されます。これにはリクエスト ID が入っていて、その ID でアドオンは単一のリクエストとイベントを関連付けられます。これはブラウザーセッションとアドオンのコンテキストごとにユニークです。リダイレクトと認証交換であっても、リクエストを通じて同じ値を保ちます。

あるホストに webRequest API を使うには、拡張機能は "webRequest"API パーミッションとそのホストのhost パーミッションを持たねばなりません。「ブロッキング」機能を使うためには、拡張機能は "webRequestBlocking" API 権限も必要です。

ページに読み込まれるリソース (例えば画像、スクリプト、スタイルシート) を中断するには、拡張機能はそのメインページと同様にリソースの host パーミッションも持っている必要があります。例えば、"https://developer.mozilla.org" のページが "https://mdn.mozillademos.org" から画像を読み込む場合、画像のリクエストを中断するには拡張機能は両方の host パーミッションを持たねばなりません。

リクエストを修正する

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

次の API でリクエストをキャンセル:
次の API でリクエストをリダイレクト:
- onBeforeRequest
- onHeadersReceived
次の API でリクエストヘッダーの修正:
- onBeforeSendHeaders
次の API でレスポンスヘッダーの修正:
- onHeadersReceived
次の API で認証資格情報の提供:
- onAuthRequired

これを行うには、イベントaddListener() のextraInfoSpec の引数に"blocking"の値のオプションを渡す必要があります。これによりリスナーが同期します。このリスナーではBlockingResponse オブジェクトを返すことができ、このオブジェクトは加えた修正を指し示します: 例えば、送信したい修正後のリクエストヘッダーなど。

警告:Non-HTTP(S) protocols do not currently support"blocking" functionality, so modifying these requests is not available at this time. SeeFirefox バグ 1475832 for more details.

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: エラーが起きたときに発火します。