webRequest

Fügen Sie Ereignislistener für die verschiedenen Phasen einer HTTP-Anfrage hinzu, die auch Websocket-Anfragen auf ws:// und wss:// umfassen. Der Ereignislistener erhält detaillierte Informationen über die Anfrage und kann die Anfrage ändern oder abbrechen.

Jedes Ereignis wird in einer bestimmten Phase der Anfrage ausgelöst. Die Reihenfolge der Ereignisse ist wie folgt:

Die Reihenfolge der Anfragen ist onBeforeRequest, onBeforeSendHeader, onSendHeaders, onHeadersReceived, onResponseStarted und onCompleted. Das onHeadersReceived kann ein onBeforeRedirect und ein onAuthRequired verursachen. Ereignisse, die von onHeadersReceived verursacht werden, beginnen am Anfang mit onBeforeRequest. Ereignisse, die von onAuthRequired verursacht werden, beginnen bei onBeforeSendHeader.

Jedoch werden möglicherweise nicht alle dieser Ereignisse von einer Erweiterung beobachtet. Zum Beispiel, onBeforeRedirect könnte nicht von onBeforeRequest gefolgt werden, wenn das Umleitungsziel nicht mit den Ereignis- filter.urls übereinstimmt. Dies kann daran liegen, dass die URLs im Filter eng definiert sind oder das Umleitungsziel von einer Erweiterung nicht beobachtet werden kann, wie zum Beispiel, wenn es zu einer data: URL umleitet.

onErrorOccurred kann jederzeit während der Anfrage ausgelöst werden. Beachten Sie außerdem, dass sich die Reihenfolge der Ereignisse manchmal von dieser unterscheiden kann. Zum Beispiel wird in Firefox bei einem HSTS-Upgrade das onBeforeRedirect Ereignis sofort nach onBeforeRequest ausgelöst. onErrorOccurred wird auch ausgelöst, wenn Firefox Tracking Protection eine Anfrage blockiert.

Alle Ereignisse – außer onErrorOccurred – können drei Argumente an addListener() übergeben:

  • den Listener selbst
  • ein filter Objekt, damit Sie nur über Anfragen zu bestimmten URLs oder bestimmten Ressourcentypen benachrichtigt werden
  • ein optionales extraInfoSpec Objekt. Sie können dieses verwenden, um zusätzliche spezifische Anweisungen für das Ereignis zu übergeben.

Die Listener-Funktion erhält ein details Objekt, das Informationen über die Anfrage enthält. Dazu gehört eine Anfrage-ID, die bereitgestellt wird, um einer Erweiterung die Korrelation von Ereignissen zu einer einzelnen Anfrage zu ermöglichen. Sie ist innerhalb einer Browsersitzung und im Kontext der Erweiterung eindeutig. Sie bleibt während einer Anfrage gleich, auch über Umleitungen und Authentifizierungsaustausche hinweg.

Um die webRequest API für einen bestimmten Host zu verwenden, muss eine Erweiterung die "webRequest" API-Berechtigung und die Host-Berechtigung für diesen Host haben. Um die "blocking"-Funktion zu verwenden, muss die Erweiterung auch die "webRequestBlocking" API-Berechtigung haben.

Um Ressourcen abzufangen, die von einer Seite geladen werden (wie Bilder, Skripte oder Stylesheets), muss die Erweiterung sowohl die Host-Berechtigung für die Ressource als auch für die Hauptseite, die die Ressource anfordert, haben. Zum Beispiel, wenn eine Seite unter https://developer.mozilla.org ein Bild von https://mdn.mozillademos.org lädt, dann muss eine Erweiterung beide Host-Berechtigungen besitzen, um die Bildanforderung abzufangen.

Anfragen ändern

Bei einigen dieser Ereignisse können Sie die Anfrage ändern. Insbesondere können Sie:

Um dies zu tun, müssen Sie eine Option mit dem Wert "blocking" im extraInfoSpec Argument an das addListener() des Ereignisses übergeben. Dadurch wird der Listener synchron.

Im Listener können Sie dann ein BlockingResponse Objekt zurückgeben, das die Änderung angibt, die Sie vornehmen müssen: zum Beispiel den modifizierten Anforderungs-Header, den Sie senden möchten.

Anfragen beim Browserstart

Wenn ein Listener mit der Option "blocking" registriert wird und während des Starts der Erweiterung registriert wird, startet die Erweiterung frühzeitig, wenn eine Anfrage während des Browserstarts gemacht wird, die mit dem Listener übereinstimmt. Dies ermöglicht der Erweiterung, die Anfrage beim Start des Browsers zu beobachten. Wenn Sie diese Schritte nicht unternehmen, könnten Anfragen, die beim Start ausgeführt werden, übersehen werden.

Spekulative Anfragen

Der Browser kann spekulative Verbindungen herstellen, bei denen er feststellt, dass eine Anfrage zu einer URI bald erfolgen könnte. Diese Art von Verbindung liefert keine gültigen Tab-Informationen, sodass Anfragedetails wie tabId, frameId, parentFrameId, usw. ungenau sind. Diese Verbindungen haben einen webRequest.ResourceType von speculative.

Sicherheitsinformationen abrufen

Im onHeadersReceived Listener können Sie auf die TLS Eigenschaften einer Anfrage zugreifen, indem Sie getSecurityInfo() aufrufen. Dazu müssen Sie auch "blocking" im extraInfoSpec Argument an das addListener() des Ereignisses übergeben.

Sie können Details des TLS-Handshakes lesen, diese jedoch nicht ändern oder die Vertrauensentscheidungen des Browsers außer Kraft setzen.

Antworten ändern

Um die HTTP-Antwortkörper für eine Anfrage zu ändern, rufen Sie webRequest.filterResponseData auf und übergeben Sie die ID der Anfrage. Dies gibt ein webRequest.StreamFilter Objekt zurück, das Sie verwenden können, um die Daten zu untersuchen und zu ändern, während sie vom Browser empfangen werden.

Dazu müssen Sie die "webRequestBlocking" API-Berechtigung sowie die "webRequest" API-Berechtigung und die Host-Berechtigung für den betreffenden Host haben.

Typen

webRequest.BlockingResponse

Ein Objekt dieses Typs wird von Event-Listenern zurückgegeben, die "blocking" in ihrem extraInfoSpec Argument gesetzt haben. Durch das Setzen bestimmter Eigenschaften in BlockingResponse kann der Listener Netzwerk-Anfragen ändern.

webRequest.CertificateInfo

Ein Objekt, das ein einzelnes X.509-Zertifikat beschreibt.

webRequest.HttpHeaders

Ein Array von HTTP-Headern. Jeder Header wird als Objekt mit zwei Eigenschaften dargestellt: name und entweder value oder binaryValue.

webRequest.RequestFilter

Ein Objekt, das Filter beschreibt, die auf webRequest Ereignisse angewendet werden können.

webRequest.ResourceType

Repräsentiert eine bestimmte Art von Ressource, die in einer Webanfrage abgerufen wird.

webRequest.SecurityInfo

Ein Objekt, das die Sicherheitseigenschaften einer bestimmten Webanfrage beschreibt.

webRequest.StreamFilter

Ein Objekt, das verwendet werden kann, um HTTP-Antworten zu überwachen und zu ändern, während sie empfangen werden.

webRequest.UploadData

Enthält Daten, die in einer URL-Anfrage hochgeladen wurden.

Eigenschaften

webRequest.MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES

Die maximale Anzahl von Malen, die handlerBehaviorChanged() in einem Zeitraum von 10 Minuten aufgerufen werden kann.

Methoden

webRequest.handlerBehaviorChanged()

Diese Methode kann verwendet werden, um sicherzustellen, dass Ereignislistener korrekt angewendet werden, wenn Seiten im Arbeitsspeicher-Cache des Browsers sind.

webRequest.filterResponseData()

Gibt ein webRequest.StreamFilter Objekt für eine gegebene Anfrage zurück.

webRequest.getSecurityInfo()

Ruft detaillierte Informationen über die TLS-Verbindung ab, die mit einer bestimmten Anfrage verbunden ist.

Ereignisse

webRequest.onBeforeRequest

Wird ausgelöst, wenn eine Anfrage gleich gemacht werden soll und bevor Header verfügbar sind. Dies ist ein guter Ort, um zu lauschen, wenn Sie die Anfrage abbrechen oder umleiten möchten.

webRequest.onBeforeSendHeaders

Wird ausgelöst, bevor HTTP-Daten gesendet werden, aber nachdem HTTP-Header verfügbar sind. Dies ist ein guter Ort, um zu lauschen, wenn Sie HTTP-Anfrage-Header ändern möchten.

webRequest.onSendHeaders

Wird unmittelbar vor dem Senden von Headern ausgelöst. Wenn Ihr Add-On oder ein anderes Add-On Header in onBeforeSendHeaders geändert hat, sehen Sie hier die modifizierte Version.

webRequest.onHeadersReceived

Wird ausgelöst, wenn die HTTP-Antwort-Header einer Anfrage empfangen wurden. Sie können dieses Ereignis verwenden, um HTTP-Antwort-Header zu ändern.

webRequest.onAuthRequired

Wird ausgelöst, wenn der Server den Client auffordert, Authentifizierungsanmeldedaten bereitzustellen. Der Listener kann nichts tun, die Anfrage abbrechen oder Authentifizierungsanmeldedaten bereitstellen.

webRequest.onResponseStarted

Wird ausgelöst, wenn das erste Byte des Antwortkörpers empfangen wird. Für HTTP-Anfragen bedeutet dies, dass die Statuszeile und die Antwort-Header verfügbar sind.

webRequest.onBeforeRedirect

Wird ausgelöst, wenn eine serverinitiierte Umleitung bevorsteht.

webRequest.onCompleted

Wird ausgelöst, wenn eine Anfrage abgeschlossen ist.

webRequest.onErrorOccurred

Wird ausgelöst, wenn ein Fehler auftritt.

Browser-Kompatibilität

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.

Beispielerweiterungen

Hinweis: Diese API basiert auf der chrome.webRequest API von Chromium. Diese Dokumentation ist von web_request.json im Chromium-Code abgeleitet.