Ajout d'écouteurs d'événements pour les différentes étapes d'une requête HTTP. L'écouteur de l'événement reçoit des informations détaillées sur la demande et peut modifier ou annuler la demande.

Chaque événement est déclenché à un stade particulier de la demande. La séquence typique des événements est la suivante :

onErrorOccurred peut être tiré à tout moment pendant la requête. Notez également que parfois la séquence des événements peut différer de ceci : par exemple, dans Firefox, lors d'une mise à niveau HSTS, l'événement onBeforeRedirect sera déclenché immédiatement après onBeforeRequest.

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.

Pour utiliser l'API webRequest pour un hôte donné, une extension doit avoir la permission API  "webRequest" et la permission hôte pour cet hôte. Pour utiliser la fonction "blocking", l'extension doit également avoir la permission API "webRequestBlocking".

Pour intercepter des ressources chargées par une page (comme des images, des scripts ou des feuilles de style), l'extension doit avoir la permission de l'hôte pour la ressource ainsi que pour la page principale demandant la ressource. Par exemple, si une page à  "https://developer.mozilla.org" charge une image à partir de "https://mdn.mozillademos.org", alors une extension doit avoir les deux permissions d'hôte si elle doit intercepter la demande d'image.

Modifier une requête

Sur certains de ces événements, vous pouvez modifier la demande. Plus précisément, vous pouvez  :

Pour ce faire, vous devez transmettre une option avec la valeur "blocking" dans l'argument extraInfoSpec à la fonction addListener() de l'événement. Cela rend l'auditeur synchrone. Dans l'écouteur, vous pouvez alors renvoyer un objet BlockingResponse, qui indique la modification à apporter : par exemple, l'en-tête de requête modifié que vous souhaitez envoyer.

Accéder aux informations de sécurité

Dans l'écouteur onHeadersReceived vous pouvez accéder aux propriétés TLS d'une requête en appelant getSecurityInfo(). Pour ce faire, vous devez également transmettre le "blockage" dans l'argument extraInfoSpec à la fonction addListener() de l'évènement.

Vous pouvez lire les détails de la prise de contact TLS, mais vous ne pouvez pas les modifier ou remplacer les décisions de confiance du navigateur.

Modifier les réponses

Pour modifier les corps de réponse HTTP pour une requête, appelez webRequest.filterResponseData, en lui transmettant l'ID de la requête. Cela renvoie un objet webRequest.StreamFilter que vous pouvez utiliser pour examiner et modifier les données reçues par le navigateur.

Pour ce faire, vous devez disposer de la permission de l'API "webRequestBlocking" ainsi que la permission de l'API "webRequest" et la permission de l'hôte pour l'hôte concerné.

Types

webRequest.BlockingResponse

Un objet de ce type est renvoyé par les auditeurs d'événements qui ont défini le "blockage" dans leur argument extraInfoSpec. En définissant des propriétés particulières dans BlockingResponse, the listener can modify network requests.

webRequest.CertificateInfo
Un objet décrivant un seul certificat X.509.
webRequest.HttpHeaders
Un tableau d'en-têtes HTTP. Chaque en-tête est représenté comme un objet avec deux propriétés : name et valeur ou binaryValue.
webRequest.RequestFilter
Un objet décrivant les filtres à appliquer aux événements webRequest.
webRequest.ResourceType
Représente un type particulier de ressources récupérées dans une requête Web.
webRequest.SecurityInfo
Un objet décrivant les propriétés de sécurité d'une requête Web particulière.
webRequest.StreamFilter
Un objet qui peut être utilisé pour surveiller et modifier les réponses HTTP pendant leur réception.
webRequest.UploadData
Contient des données téléchargées dans une requête 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 écouteurs d'événements sont appliqués correctement lorsque les pages se trouvent dans le cache en mémoire du navigateur.
webRequest.filterResponseData()
Retourne un objet webRequest.StreamFilter pour une requête donnée.
webRequest.getSecurityInfo()
Obtient des informations détaillées sur la connexion TLS associée à une requête donnée.

Evénements

webRequest.onBeforeRequest
Lancé lorsqu'une demande est sur le point d'être faite, et avant que les en-têtes ne soient disponibles. C'est un bon endroit pour écouter si vous voulez annuler ou rediriger la demande.
webRequest.onBeforeSendHeaders
Câblé avant d'envoyer des données HTTP, mais après que les en-têtes HTTP soient disponibles. C'est un bon endroit pour écouter si vous voulez modifier les en-têtes de requête HTTP.
webRequest.onSendHeaders
Lancé juste avant l'envoi des en-têtes. Si votre add-on ou d'autres en-têtes modifiés dans onBeforeSendHeaders, vous verrez la version modifiée ici.
webRequest.onHeadersReceived
Lancé lorsque les en-têtes de réponse HTTP associés à une requête ont été reçus. Vous pouvez utiliser cet événement pour modifier les en-têtes de réponse HTTP.
webRequest.onAuthRequired
Déclenché lorsque le serveur demande au client de fournir des informations d'authentification. L'auditeur ne peut rien faire, annuler la demande ou fournir des informations d'authentification.
webRequest.onResponseStarted
Lancé lorsque le premier octet du corps de réponse est reçu. Pour les requêtes HTTP, cela signifie que la ligne d'état et les en-têtes de réponse sont disponibles.
webRequest.onBeforeRedirect
Déclenché lorsqu'une redirection initiée par le serveur est sur le point de se produirer.
webRequest.onCompleted
C'est déclenché lorsqu'une demande est complétée.
webRequest.onErrorOccurred
Déclenché lorsqu'une erreur se produit.

Compatibilité du navigateur

Update compatibility data on GitHub
OrdinateurMobile
ChromeEdgeFirefoxOperaFirefox pour Android
BlockingResponseChrome Support complet OuiEdge Support complet 14Firefox Support complet 45Opera Support complet OuiFirefox Android Support complet 48
CertificateInfoChrome Aucun support NonEdge Aucun support NonFirefox Support complet 62Opera Aucun support NonFirefox Android Support complet 62
HttpHeadersChrome Support complet OuiEdge Support complet 14Firefox Support complet 45Opera Support complet OuiFirefox Android Support complet 48
MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTESChrome Support complet OuiEdge Support complet 14Firefox Support complet 45Opera Support complet OuiFirefox Android Support complet 48
RequestFilterChrome Support complet OuiEdge Support complet 14Firefox Support complet 45Opera Support complet OuiFirefox Android Support complet 48
ResourceTypeChrome Support complet 44Edge Aucun support NonFirefox Support complet 45Opera Support complet 31Firefox Android Support complet 48
SecurityInfoChrome Aucun support NonEdge Aucun support NonFirefox Support complet 62Opera Aucun support NonFirefox Android Support complet 62
StreamFilterChrome Aucun support NonEdge Aucun support NonFirefox Support complet 57Opera Aucun support NonFirefox Android Support complet 57
UploadDataChrome Support complet OuiEdge Support complet 14Firefox Support complet 45Opera Support complet OuiFirefox Android Support complet 48
filterResponseDataChrome Aucun support NonEdge Aucun support NonFirefox Support complet 57Opera Aucun support NonFirefox Android Support complet 57
getSecurityInfoChrome Aucun support NonEdge Aucun support NonFirefox Support complet 62Opera Aucun support NonFirefox Android Support complet 62
handlerBehaviorChangedChrome Support complet OuiEdge Support complet 14Firefox Support complet 45Opera Support complet OuiFirefox Android Support complet 48
onAuthRequiredChrome Support complet OuiEdge Support complet 14Firefox Support complet 54
Notes
Support complet 54
Notes
Notes To handle a request asynchronously, return a Promise from the listener.
Opera Support complet OuiFirefox Android Support complet 54
Notes
Support complet 54
Notes
Notes To handle a request asynchronously, return a Promise from the listener.
onBeforeRedirectChrome Support complet OuiEdge Support complet 14Firefox Support complet 46Opera Support complet OuiFirefox Android Support complet 48
onBeforeRequestChrome Support complet Oui
Notes
Support complet Oui
Notes
Notes Asynchronous event listeners are not supported.
Edge Support complet 14
Notes
Support complet 14
Notes
Notes Asynchronous event listeners are not supported.
Firefox Support complet 46
Notes
Support complet 46
Notes
Notes Asynchronous event listeners are supported from version 52.
Opera Support complet Oui
Notes
Support complet Oui
Notes
Notes Asynchronous event listeners are not supported.
Firefox Android Support complet 48
Notes
Support complet 48
Notes
Notes Asynchronous event listeners are supported from version 52.
onBeforeSendHeadersChrome Support complet Oui
Notes
Support complet Oui
Notes
Notes Asynchronous event listeners are not supported.
Edge Support complet 14
Notes
Support complet 14
Notes
Notes Asynchronous event listeners are not supported.
Firefox Support complet 45
Notes
Support complet 45
Notes
Notes Asynchronous event listeners are supported from version 52.
Opera Support complet Oui
Notes
Support complet Oui
Notes
Notes Asynchronous event listeners are not supported.
Firefox Android Support complet 48
Notes
Support complet 48
Notes
Notes Asynchronous event listeners are supported from version 52.
onCompletedChrome Support complet OuiEdge Support complet 14Firefox Support complet 45Opera Support complet OuiFirefox Android Support complet 48
onErrorOccurredChrome Support complet OuiEdge Support complet 14Firefox Support complet 45Opera Support complet OuiFirefox Android Support complet 48
onHeadersReceivedChrome Support complet Oui
Notes
Support complet Oui
Notes
Notes Asynchronous event listeners are not supported.
Edge Support complet 14
Notes
Support complet 14
Notes
Notes Asynchronous event listeners are not supported.
Firefox Support complet 45
Notes
Support complet 45
Notes
Notes Modification of the 'Content-Type' header is supported from version 51.
Notes Asynchronous event listeners are supported from version 52.
Opera Support complet Oui
Notes
Support complet Oui
Notes
Notes Asynchronous event listeners are not supported.
Firefox Android Support complet 48
Notes
Support complet 48
Notes
Notes Modification of the 'Content-Type' header is supported from version 51.
Notes Asynchronous event listeners are supported from version 52.
onResponseStartedChrome Support complet OuiEdge Support complet 14Firefox Support complet 45Opera Support complet OuiFirefox Android Support complet 48
onSendHeadersChrome Support complet OuiEdge Support complet 14Firefox Support complet 45Opera Support complet OuiFirefox Android Support complet 48

Légende

Support complet  
Support complet
Aucun support  
Aucun support
Voir les notes d'implémentation.
Voir les notes d'implémentation.

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.
  • In Firefox, starting from Firefox 52, some of the browser.webRequest.* APIs allow returning Promises that resolves webRequest.BlockingResponse asynchronously. In Chrome, only webRequest.onAuthRequired supports asynchronous webRequest.BlockingResponse via supplying 'asyncBlocking'.

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,