Cette traduction est incomplète. Aidez à traduire cet article depuis l'anglais.

Ajoute des receveurs d'évènements dédiés aux différentes étapes d'une requête HTTP en cours. Le receveur d'évènement reçoit les informations précises de la requête, peut la modifier ou l'annuler.

Vue d'ensemble

Chaque évènement est émis à une étape particulière de la requête. Les évènements sont émis dans l'ordre suivant:

(onErrorOccurred peut être émis à n'importe quel moment de la requête.)

Tous les évènements (excepté onErrorOccurred) peuvent prendre trois arguments pour addListener():

  • Le receveur d'évènements lui-même
  • un filter objet, afin de n'être notifié que pour les requêtes effectués par des URLs particulières ou pour un type particulier de ressources.
  • un  extraInfoSpec objet optionnel. Vous pouvez utiliser celui-ci pour passer des instructions spécifiques à l'évènement supplémentaires.

Une fonction d'écoute reçoit un objet details qui contient des informations à propos de la requête. Il inclut un ID de requête, fourni afin de permettre à une extension de relier des évènements associés à une même requête. Il est unique à chaque session de navigation et à l'extension. Il reste le même tout au long d'une requête, même durant les redirections et les échanges d'authentifications.

L'API webRequest ne donne pas accès aux informations de sécurités sensibles, comme les update checks and OCSP checks.

Permissions

Pour utiliser l'API webRequest d'un hote spécifique, vous devez avoir l'autorisation webRequest.  Vous devez également avoir les permissions d'hôte pour les deux, celui qui initialise la requête et la cible de cette requete. par exemple, si "foo.com" charge une ressource depuis "bar.com", vous devez avoir les permissions pour chacun de ces deux hôtes. Remarquez que ceci est plus restrictif que Chrome, qui ne nécéssite que les permissions d'hôte pour la cible de la requête.

Pour utiliser la fonctionnalité de bloquage vous devez également avoir la permission API "webRequestBlocking".

Modifier une requête

à l'écoute de certains de ces évènements, vous pouvez modifier une requête. Généralement vous pouvez:

Pour effectuer ceci, vous devez passer une option avec la valeur "blocking" dans l'argument extraInfoSpec au gestionnaire d'évènement (via addListener()). Ceci rend synchrone le gestionnaire d'évènements. Dans le gestionnaire d'évènement, vous pouvez ensuite renvoyer un objet BlockingResponse, qui indiquera la modification que vous devez faire: par exemple, l'en-tête de requête modifié que vous voulez envoyer.

Depuis Firefox 52, au lieu de renvoyer BlockingResponse, le gestionnaire d'évènement peut renvoyer une Promise qui sera résolue avec une BlockingResponse. Ceci permet au gestionnaire d'évènement de s'occuper des requêtes de manière asynchrone.

Types

webRequest.ResourceType
Represents a particular kind of resource fetched in a web request.
webRequest.RequestFilter
An object describing filters to apply to webRequest events.
webRequest.HttpHeaders
An array of HTTP headers. Each header is represented as an object with two properties: name and either value or binaryValue.
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.UploadData
Contains data uploaded in a URL request.

Properties

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

Functions

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.

Events

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 extension or some other extension 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.

Browser compatibility

ChromeEdgeFirefoxFirefox for AndroidOpera
BlockingResponse (Oui) (Oui)4548 (Oui)
HttpHeaders (Oui) (Oui)4548 (Oui)
MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES (Oui) Non4548 (Oui)
RequestFilter (Oui) (Oui)45 *48 * (Oui)
ResourceType44 * Non45 *48 *31 *
UploadData (Oui) (Oui)4548 (Oui)
handlerBehaviorChanged (Oui) (Oui)4548 (Oui)
onAuthRequired (Oui) (Oui)54 *54 * (Oui)
onBeforeRedirect (Oui) * (Oui) *46 *48 (Oui) *
onBeforeRequest (Oui) * (Oui) *46 *48 * (Oui) *
onBeforeSendHeaders (Oui) * (Oui) *45 *48 * (Oui) *
onCompleted (Oui) * (Oui)45 *48 (Oui) *
onErrorOccurred (Oui) * (Oui) *45 *48 (Oui) *
onHeadersReceived (Oui) * (Oui) *45 *48 * (Oui) *
onResponseStarted (Oui) * (Oui) *45 *48 (Oui) *
onSendHeaders (Oui) * (Oui) *45 *48 (Oui) *

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.

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : Ostefanini
 Dernière mise à jour par : Ostefanini,