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 パーミッションを持たねばなりません。

リクエストを修正する

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

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

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

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

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

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

レスポンスを修正する

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

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

webRequest.BlockingResponse

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

webRequest.CertificateInfo
単一の X.509 証明書を記述するオブジェクト。
webRequest.HttpHeaders
HTTP ヘッダーの配列。それぞれのヘッダーは 2 つのプロパティを持つオブジェクトで表現されます: name と、valuebinaryValue のいずれか。
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
エラーが起きたときに発火します。

ブラウザー実装状況

Update compatibility data on GitHub
デスクトップモバイル
ChromeEdgeFirefoxOperaAndroid 版 Firefox
BlockingResponseChrome 完全対応 ありEdge 完全対応 14Firefox 完全対応 45Opera 完全対応 ありFirefox Android 完全対応 48
CertificateInfoChrome 未対応 なしEdge 未対応 なしFirefox 完全対応 62Opera 未対応 なしFirefox Android 完全対応 62
HttpHeadersChrome 完全対応 ありEdge 完全対応 14Firefox 完全対応 45Opera 完全対応 ありFirefox Android 完全対応 48
MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTESChrome 完全対応 ありEdge 完全対応 14Firefox 完全対応 45Opera 完全対応 ありFirefox Android 完全対応 48
RequestFilterChrome 完全対応 ありEdge 完全対応 14Firefox 完全対応 45Opera 完全対応 ありFirefox Android 完全対応 48
ResourceTypeChrome 完全対応 44Edge 未対応 なしFirefox 完全対応 45Opera 完全対応 31Firefox Android 完全対応 48
SecurityInfoChrome 未対応 なしEdge 未対応 なしFirefox 完全対応 62Opera 未対応 なしFirefox Android 完全対応 62
StreamFilterChrome 未対応 なしEdge 未対応 なしFirefox 完全対応 57Opera 未対応 なしFirefox Android 完全対応 57
UploadDataChrome 完全対応 ありEdge 完全対応 14Firefox 完全対応 45Opera 完全対応 ありFirefox Android 完全対応 48
filterResponseDataChrome 未対応 なしEdge 未対応 なしFirefox 完全対応 57Opera 未対応 なしFirefox Android 完全対応 57
getSecurityInfoChrome 未対応 なしEdge 未対応 なしFirefox 完全対応 62Opera 未対応 なしFirefox Android 完全対応 62
handlerBehaviorChangedChrome 完全対応 ありEdge 完全対応 14Firefox 完全対応 45Opera 完全対応 ありFirefox Android 完全対応 48
onAuthRequiredChrome 完全対応 ありEdge 完全対応 14Firefox 完全対応 54
補足
完全対応 54
補足
補足 To handle a request asynchronously, return a Promise from the listener.
Opera 完全対応 ありFirefox Android 完全対応 54
補足
完全対応 54
補足
補足 To handle a request asynchronously, return a Promise from the listener.
onBeforeRedirectChrome 完全対応 ありEdge 完全対応 14Firefox 完全対応 46Opera 完全対応 ありFirefox Android 完全対応 48
onBeforeRequestChrome 完全対応 あり
補足
完全対応 あり
補足
補足 Asynchronous event listeners are not supported.
Edge 完全対応 14
補足
完全対応 14
補足
補足 Asynchronous event listeners are not supported.
Firefox 完全対応 46
補足
完全対応 46
補足
補足 Asynchronous event listeners are supported from version 52.
Opera 完全対応 あり
補足
完全対応 あり
補足
補足 Asynchronous event listeners are not supported.
Firefox Android 完全対応 48
補足
完全対応 48
補足
補足 Asynchronous event listeners are supported from version 52.
onBeforeSendHeadersChrome 完全対応 あり
補足
完全対応 あり
補足
補足 Asynchronous event listeners are not supported.
Edge 完全対応 14
補足
完全対応 14
補足
補足 Asynchronous event listeners are not supported.
Firefox 完全対応 45
補足
完全対応 45
補足
補足 Asynchronous event listeners are supported from version 52.
Opera 完全対応 あり
補足
完全対応 あり
補足
補足 Asynchronous event listeners are not supported.
Firefox Android 完全対応 48
補足
完全対応 48
補足
補足 Asynchronous event listeners are supported from version 52.
onCompletedChrome 完全対応 ありEdge 完全対応 14Firefox 完全対応 45Opera 完全対応 ありFirefox Android 完全対応 48
onErrorOccurredChrome 完全対応 ありEdge 完全対応 14Firefox 完全対応 45Opera 完全対応 ありFirefox Android 完全対応 48
onHeadersReceivedChrome 完全対応 あり
補足
完全対応 あり
補足
補足 Asynchronous event listeners are not supported.
Edge 完全対応 14
補足
完全対応 14
補足
補足 Asynchronous event listeners are not supported.
Firefox 完全対応 45
補足
完全対応 45
補足
補足 Modification of the 'Content-Type' header is supported from version 51.
補足 Asynchronous event listeners are supported from version 52.
Opera 完全対応 あり
補足
完全対応 あり
補足
補足 Asynchronous event listeners are not supported.
Firefox Android 完全対応 48
補足
完全対応 48
補足
補足 Modification of the 'Content-Type' header is supported from version 51.
補足 Asynchronous event listeners are supported from version 52.
onResponseStartedChrome 完全対応 ありEdge 完全対応 14Firefox 完全対応 45Opera 完全対応 ありFirefox Android 完全対応 48
onSendHeadersChrome 完全対応 ありEdge 完全対応 14Firefox 完全対応 45Opera 完全対応 ありFirefox Android 完全対応 48

凡例

完全対応  
完全対応
未対応  
未対応
実装ノートを参照してください。
実装ノートを参照してください。

Extra notes on Chrome incompatibilities.

Example extensions

Acknowledgements

This API is based on Chromium's chrome.webRequest API. This documentation is derived from web_request.json in the Chromium code.

Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.