この翻訳は不完全です。英語から この記事を翻訳 してください。

HTTP リクエスト作成のいろいろなステージでイベントリスナーを追加します。イベントリスナーはリクエストの詳細情報を受け取ったり、リクエストを編集、修正したりします。

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

onErrorOccurred can be fired at any time during the request. Also note that sometimes the sequence of events may differ from this: for example, in Firefox, on an HSTS upgrade, the onBeforeRedirect event will be triggered immediately after onBeforeRequest.

All the events, except onErrorOccurred, can take three arguments to addListener():

  • the listener itself
  • a filter object, so you can only be notified for requests made to particular URLs or for particular types of resource
  • an optional extraInfoSpec object. You can use this to pass additional event-specific instructions.

The listener function is passed a details object containing information about the request. This includes a request ID, which is provided to enable an add-on to correlate events associated with a single request. It is unique within a browser session and the add-on's context. It stays the same throughout a request, even across redirections and authentication exchanges.

To use the webRequest API for a given host, an extension must have the "webRequest" API permission and the host permission for that host. To use the "blocking" feature the extension must also have the "webRequestBlocking" API permission.

To intercept resources loaded by a page (such as images, scripts, or stylesheets), the extension must have the host permission for the resource as well as for the main page requesting the resource. For example, if a page at "https://developer.mozilla.org" loads an image from "https://mdn.mozillademos.org", then an extension must have both host permissions if it is to intercept the image request.

Modifying requests

On some of these events, you can modify the request. Specifically, you can:

To do this, you need to pass an option with the value "blocking" in the extraInfoSpec argument to the event's addListener(). This makes the listener synchronous. In the listener, you can then return a BlockingResponse object, which indicates the modification you need to make: for example, the modified request header you want to send.

Modifying responses

To modify the HTTP response bodies for a request, call webRequest.filterResponseData, passing it the ID of the request. This returns a webRequest.StreamFilter object that you can use to examine and modify the data as it is received by the browser.

To do this, you must have the "webRequestBlocking" API permission as well as the "webRequest" API permission and the host permission for the relevant host.

webRequest.BlockingResponse

An object of this type is returned by event listeners that have set "blocking" in their extraInfoSpec argument. By setting particular properties in BlockingResponse, the listener can modify network requests.

webRequest.HttpHeaders
An array of HTTP headers. Each header is represented as an object with two properties: name and either value or binaryValue.
webRequest.RequestFilter
An object describing filters to apply to webRequest events.
webRequest.ResourceType
Represents a particular kind of resource fetched in a web request.
webRequest.StreamFilter
An object that can be used to monitor and modify HTTP responses while they are being received.
webRequest.UploadData
Contains data uploaded in a URL request.

プロパティ

webRequest.MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES
The maximum number of times that handlerBehaviorChanged() can be called in a 10 minute period.

関数

webRequest.handlerBehaviorChanged()
This function can be used to ensure that event listeners are applied correctly when pages are in the browser's in-memory cache.
webRequest.filterResponseData()
Returns a webRequest.StreamFilter object for a given request.

イベント

webRequest.onBeforeRequest
Fired when a request is about to be made, and before headers are available. This is a good place to listen if you want to cancel or redirect the request.
webRequest.onBeforeSendHeaders
Fired before sending any HTTP data, but after HTTP headers are available. This is a good place to listen if you want to modify HTTP request headers.
webRequest.onSendHeaders
Fired just before sending headers. If your add-on or some other add-on modified headers in onBeforeSendHeaders, you'll see the modified version here.
webRequest.onHeadersReceived
Fired when the HTTP response headers associated with a request have been received. You can use this event to modify HTTP response headers.
webRequest.onAuthRequired
Fired when the server asks the client to provide authentication credentials. The listener can do nothing, cancel the request, or supply authentication credentials.
webRequest.onResponseStarted
Fired when the first byte of the response body is received. For HTTP requests, this means that the status line and response headers are available.
webRequest.onBeforeRedirect
Fired when a server-initiated redirect is about to occur.
webRequest.onCompleted
Fired when a request is completed.
webRequest.onErrorOccurred
Fired when an error occurs.

ブラウザ実装状況

ChromeEdgeFirefoxFirefox for AndroidOpera
BlockingResponse 有り 有り4548 有り
HttpHeaders 有り 有り4548 有り
MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES 有り 有り4548 有り
RequestFilter 有り 有り45 *48 * 有り
ResourceType44 * 無し45 *48 *31 *
StreamFilter 無し 無し5757 無し
UploadData 有り 有り4548 有り
filterResponseData 無し 無し5757 無し
handlerBehaviorChanged 有り 有り4548 有り
onAuthRequired 有り 有り54 *54 * 有り
onBeforeRedirect 有り 有り4648 有り
onBeforeRequest 有り * 有り *46 *48 * 有り *
onBeforeSendHeaders 有り * 有り *45 *48 * 有り *
onCompleted 有り 有り4548 有り
onErrorOccurred 有り 有り4548 有り
onHeadersReceived 有り * 有り *45 *48 * 有り *
onResponseStarted 有り 有り4548 有り
onSendHeaders 有り 有り4548 有り

Chrome incompatibilities

webRequest

  • In Firefox requests can be redirected only if their original URL uses the http: or https: scheme.
  • In Firefox, events are not fired for system requests (for example, extension upgrades or searchbar suggestions). From Firefox 57 onwards, Firefox makes an exception for extensions that need to intercept webRequest.onAuthRequired for proxy authorization. See the documentation for webRequest.onAuthRequired.
  • In Firefox, if an extension wants to redirect a public (e.g. HTTPS) URL to an extension page, the extension's manifest.json file must contain a web_accessible_resources key that lists the URL for the extension page. Note that any website may then link or redirect to that url, and extensions should treat any input (POST data, for examples) as if it came from an untrusted source, just as a normal web page should.

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.

ドキュメントのタグと貢献者

 このページの貢献者: Uemmra3
 最終更新者: Uemmra3,