webRequest

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.

Attention : Les protocoles non-HTTP(S) ne supportent pas actuellement la fonctionnalité de "blockage", donc la modification de ces requêtes n'est pas disponible pour le moment. Voir le bug Firefox 1475832 pour plus de détails.

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.

Méthodes

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é des navigateurs

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Firefox for Android
Safari on iOS
webRequest
BlockingResponse
BlockingResponse.upgradeToSecure
CertificateInfo
HttpHeaders
MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES
RequestFilter
RequestFilter.tabId
RequestFilter.urls
RequestFilter.view-source
RequestFilter.windowId
ResourceType
ResourceType.beacon
ResourceType.csp_report
ResourceType.font
ResourceType.image
ResourceType.imageset
ResourceType.main_frame
ResourceType.media
ResourceType.object
ResourceType.object_subrequest
ResourceType.other
ResourceType.ping
ResourceType.script
ResourceType.speculative
ResourceType.stylesheet
ResourceType.sub_frame
ResourceType.web_manifest
ResourceType.websocket
ResourceType.xml_dtd
ResourceType.xmlhttprequest
ResourceType.xslt
SecurityInfo
SecurityInfo.certificateTransparencyStatus
SecurityInfo.certificates
SecurityInfo.cipherSuite
SecurityInfo.errorMessage
SecurityInfo.hsts
SecurityInfo.isDomainMismatch
SecurityInfo.isExtendedValidation
SecurityInfo.isNotValidAtThisTime
SecurityInfo.isUntrusted
SecurityInfo.keaGroupName
SecurityInfo.protocolVersion
SecurityInfo.secretKeyLength
SecurityInfo.signatureSchemeName
SecurityInfo.state
SecurityInfo.usedDelegatedCredentials
SecurityInfo.usedEch
SecurityInfo.usedOcsp
SecurityInfo.usedPrivateDns
SecurityInfo.weaknessReasons
StreamFilter
StreamFilter.close
StreamFilter.disconnect
StreamFilter.error
StreamFilter.ondata
StreamFilter.onerror
StreamFilter.onstart
StreamFilter.onstop
StreamFilter.resume
StreamFilter.status
StreamFilter.suspend
StreamFilter.write
UploadData
filterResponseData
getSecurityInfo
getSecurityInfo.options
handlerBehaviorChanged
onAuthRequired
onAuthRequired.asyncBlocking
onAuthRequired.details
details.challenger
details.cookieStoreId
details.documentUrl
details.frameId
details.incognito
details.isProxy
details.method
details.originUrl
details.parentFrameId
details.proxyInfo
details.realm
details.requestId
details.responseHeaders
details.scheme
details.statusCode
details.statusLine
details.tabId
details.thirdParty
details.timeStamp
details.type
details.url
details.urlClassification
onBeforeRedirect
onBeforeRedirect.details
details.cookieStoreId
details.documentUrl
details.frameId
details.fromCache
details.incognito
details.ip
details.method
details.originUrl
details.parentFrameId
details.proxyInfo
details.redirectUrl
details.requestId
details.responseHeaders
details.statusCode
details.statusLine
details.tabId
details.thirdParty
details.timeStamp
details.type
details.url
details.urlClassification
onBeforeRequest
onBeforeRequest.details
details.cookieStoreId
details.documentUrl
details.frameAncestors
details.frameId
details.incognito
details.method
details.originUrl
details.parentFrameId
details.proxyInfo
details.requestBody
details.requestId
details.tabId
details.thirdParty
details.timeStamp
details.type
details.url
details.urlClassification
onBeforeSendHeaders
onBeforeSendHeaders.details
details.cookieStoreId
details.documentUrl
details.frameAncestors
details.frameId
details.incognito
details.method
details.originUrl
details.parentFrameId
details.proxyInfo
details.requestHeaders
details.requestId
details.tabId
details.thirdParty
details.timeStamp
details.type
details.url
details.urlClassification
onCompleted
onCompleted.details
details.cookieStoreId
details.documentUrl
details.frameId
details.fromCache
details.incognito
details.ip
details.method
details.originUrl
details.parentFrameId
details.proxyInfo
details.requestId
details.responseHeaders
details.statusCode
details.statusLine
details.tabId
details.thirdParty
details.timeStamp
details.type
details.url
details.urlClassification
onErrorOccurred
onErrorOccurred.details
details.cookieStoreId
details.documentUrl
details.error
details.frameId
details.fromCache
details.incognito
details.ip
details.method
details.originUrl
details.parentFrameId
details.proxyInfo
details.requestId
details.tabId
details.thirdParty
details.timeStamp
details.type
details.url
details.urlClassification
onHeadersReceived
onHeadersReceived.details
details.cookieStoreId
details.documentUrl
details.frameAncestors
details.frameId
details.fromCache
details.incognito
details.ip
details.method
details.originUrl
details.parentFrameId
details.proxyInfo
details.requestId
details.responseHeaders
details.statusCode
details.statusLine
details.tabId
details.thirdParty
details.timeStamp
details.type
details.url
details.urlClassification
onResponseStarted
onResponseStarted.details
details.cookieStoreId
details.documentUrl
details.frameId
details.fromCache
details.incognito
details.ip
details.method
details.originUrl
details.parentFrameId
details.proxyInfo
details.requestId
details.responseHeaders
details.statusCode
details.statusLine
details.tabId
details.thirdParty
details.timeStamp
details.type
details.url
details.urlClassification
onSendHeaders
onSendHeaders.details
details.cookieStoreId
details.documentUrl
details.frameId
details.incognito
details.method
details.originUrl
details.parentFrameId
details.proxyInfo
details.requestHeaders
details.requestId
details.tabId
details.thirdParty
details.timeStamp
details.type
details.url
details.urlClassification

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
See implementation notes.
Has more compatibility info.

Example extensions

Note :

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.