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.

Intercepter les demandes d'extension

A partir de Firefox 56, les extensions peuvent intercepter les requêtes effectuées sur leurs propres pages groupées. Pour ce faire, passé  browser.extension.getURL("*") dans l'argument RequestFilter :

function logURL(requestDetails) {
  console.log("Loading: " + requestDetails.url);
}

browser.webRequest.onBeforeRequest.addListener(
  logURL,
  {urls: [browser.extension.getURL("*")]}
);

browser.browserAction.onClicked.addListener(() => {
  fetch(browser.extension.getURL("my-page.html"));
});

Il y a des réserves :

  • Vous pouvez seulement intercepter que des requêtes sur vos propres pages, et non sur d'autres URL moz-extension:// . Passer "moz-extension://*/*" ne marchera pas.
  • La demande ne déclenchera que des événements  onBeforeRequest, onCompleted, et onErrorOccurred .
  • La demande ne sera pas interceptée si le changement de la page provient d'un appel d'API WebExtension. Par exemple,  si vous appelez  browser.tabs.create({url: browser.extension.getURL("my-page.html")}), la demande ne sera pas interceptée.

Types

webRequest.ResourceType
Représente un type particulier de ressource extraite dans une requête web.
webRequest.RequestFilter
Un objet décrivant des filtres à appliquer aux événements webRequest.
webRequest.HttpHeaders
Un tableau d'en-tetes HTTP. Chaque en-tête est représenté comme un objet avec deux propriétés : nom et valeur ou binaryValue.
webRequest.BlockingResponse

Un objet de ce type est renvoyé par des auditeurs d'événements qui ont défini "blocage" dans leur argument extraInfoSpec . En définissant des propriétés particulières dans BlockingResponse, l'auditeur peut modifier  les requêtes réseaux.

webRequest.UploadData
Contient des données téléchargées dans une demande d'URL.

Propriétés

webRequest.MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES
Le nombre de fois que handlerBehaviorChanged() peut être appelé dans une période de 10 minutes.

Fonctions

webRequest.handlerBehaviorChanged()
Cette fonction peut être utilisée pour s'assurer que les auditeurs d'événements sont appliqués correctement lorsque les pages se trouvent dans le cache en mémoire du navigateur..

Evénements

webRequest.onAuthRequired
défini lorsque le serveur demande au client de fournir des informations d'identification d'authentification. L'auditeur ne peut rien faire, annule la demande ou fournit des informations d'authentification.
webRequest.onBeforeRedirect
Fired when a server-initiated redirect is about to occur.
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.onCompleted
Fired when a request is completed.
webRequest.onErrorOccurred
Fired when an error occurs.
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.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.onSendHeaders
Fired just before sending headers. If your extension or some other extension modified headers in onBeforeSendHeaders, you'll see the modified version here.

Compatibilité du navigateur

ChromeEdgeFirefoxFirefox for AndroidOpera
BlockingResponse Oui Oui4548 Oui
HttpHeaders Oui Oui4548 Oui
MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES Oui Oui4548 Oui
RequestFilter Oui Oui4548 Oui
ResourceType44 Non454831
StreamFilter Non Non5757 Non
UploadData Oui Oui4548 Oui
filterResponseData Non Non5757 Non
handlerBehaviorChanged Oui Oui4548 Oui
onAuthRequired Oui Oui54 *54 * Oui
onBeforeRedirect Oui Oui4648 Oui
onBeforeRequest Oui * Oui *46 *48 * Oui *
onBeforeSendHeaders Oui * Oui *45 *48 * Oui *
onCompleted Oui Oui4548 Oui
onErrorOccurred Oui Oui4548 Oui
onHeadersReceived Oui * Oui *45 *48 * Oui *
onResponseStarted Oui Oui4548 Oui
onSendHeaders Oui Oui4548 Oui

Example extensions

Remerciements :

Cette API est basée sur l'API Chromium chrome.webRequest. Cette documentation est dérivée de web_request.json dans le code Chromium.

Les données de compatibilité relatives à Microsoft Edge sont fournies par Microsoft Corporation et incluses ici sous la licence Creative Commons Attribution 3.0 pour les États-Unis.

Étiquettes et contributeurs liés au document

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