webRequest

Fügen Sie Ereignis-Listener für die verschiedenen Phasen einer HTTP-Anfrage hinzu, einschließlich WebSocket-Anfragen über ws:// und wss://. Der Ereignis-Listener empfängt detaillierte Informationen über die Anfrage und kann die Anfrage modifizieren oder abbrechen.

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

Jedoch könnten nicht alle dieser Ereignisse von einer Erweiterung beobachtet werden. Zum Beispiel könnte onBeforeRedirect nicht von onBeforeRequest gefolgt werden, wenn das Umleitungsziel nicht dem Ereignis filter.urls entspricht. Dies kann der Fall sein, wenn die URLs im Filter eng definiert sind oder das Umleitungsziel von einer Erweiterung nicht beobachtet werden kann, wie wenn es zu einer data:-URL umleitet.

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

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

der Listener selbst
ein filter-Objekt, damit Sie nur für Anfragen zu bestimmten URLs oder für bestimmte Ressourcentypen benachrichtigt werden können
ein optionales extraInfoSpec-Objekt. Damit können Sie zusätzliche ereignisspezifische Anweisungen übergeben.

Der Listener-Funktion wird ein details-Objekt übergeben, 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 einzigartig innerhalb einer Browsersitzung und dem Kontext der Erweiterung. Sie bleibt während einer Anfrage gleich, selbst ü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 besitzen. Um die "blocking"-Funktion zu nutzen, muss die Erweiterung auch die "webRequestBlocking"-API-Berechtigung besitzen.

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

Modifizieren von Anfragen

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

die Anfrage abbrechen in:
die Anfrage umleiten in:
- onBeforeRequest
- onHeadersReceived
Anfragen-Header modifizieren in:
- onBeforeSendHeaders
Antwort-Header modifizieren in:
- onHeadersReceived
Authentifizierungsdaten bereitstellen in:
- onAuthRequired

Dazu müssen Sie im extraInfoSpec-Argument zum addListener() des Ereignisses eine Option mit dem Wert "blocking" übergeben. Dies macht den Listener synchron.

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

Anfragen beim Browserstart

Wenn ein Listener mit der "blocking"-Option registriert wird und während des Starts der Erweiterung registriert wird, startet die Erweiterung frühzeitig, wenn eine Anfrage beim Start des Browsers gestellt wird, die dem Listener entspricht. Dies ermöglicht der Erweiterung, die Anfrage beim Browserstart zu beobachten. Wenn Sie diese Schritte nicht unternehmen, könnten beim Start gestellte Anfragen verpasst werden.

Spekulative Anfragen

Der Browser kann spekulative Verbindungen herstellen, bei denen er feststellt, dass eine Anfrage zu einer URI möglicherweise bald erfolgen wird. Solche Verbindungen liefern keine gültigen Tab-Informationen, daher sind Anfragedetails wie tabId, frameId, parentFrameId usw. ungenau. Diese Verbindungen haben einen webRequest.ResourceType von speculative.

Zugriff auf Sicherheitsinformationen

Im onHeadersReceived-Listener können Sie die TLS-Eigenschaften einer Anfrage über den Aufruf von getSecurityInfo() abrufen. Dazu müssen Sie auch "blocking" im extraInfoSpec-Argument zum addListener() des Ereignisses übergeben.

Sie können Details des TLS-Handshakes lesen, sie aber nicht modifizieren oder die Vertrauensentscheidungen des Browsers überschreiben.

Modifizieren von Antworten

Um die HTTP-Antwortkörper für eine Anfrage zu modifizieren, 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 sowohl die "webRequestBlocking"-API-Berechtigung als auch die "webRequest" API-Berechtigung und die Host-Berechtigung für den entsprechenden Host besitzen.

Typen

webRequest.BlockingResponse: Ein Objekt dieses Typs wird von Ereignis-Listenern zurückgegeben, die "blocking" in ihrem extraInfoSpec-Argument gesetzt haben. Durch das Setzen bestimmter Eigenschaften in BlockingResponse kann der Listener Netzwerk-Anfragen modifizieren.
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.
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 modifizieren, während sie empfangen werden.
webRequest.UploadData: Enthält Daten, die in einer URL-Anfrage hochgeladen werden.

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 Ereignis-Listener korrekt angewendet werden, wenn Seiten im 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 gegebenen Anfrage verbunden ist.

Ereignisse

webRequest.onBeforeRequest: Wird ausgelöst, wenn eine Anfrage im Begriff ist, gemacht zu werden, und bevor Header verfügbar sind. Dies ist ein guter Zeitpunkt, zuzuhören, 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 Zeitpunkt, zuzuhören, wenn Sie HTTP-Anfragen-Header modifizieren möchten.
webRequest.onSendHeaders: Wird unmittelbar vor dem Senden von Headern ausgelöst. Wenn Ihre Erweiterung oder eine andere Erweiterung Header in onBeforeSendHeaders modifiziert hat, sehen Sie hier die modifizierte Version.
webRequest.onHeadersReceived: Wird ausgelöst, wenn die HTTP-Antwort-Header, die mit einer Anfrage verbunden sind, empfangen wurden. Sie können dieses Ereignis nutzen, um HTTP-Antwort-Header zu modifizieren.
webRequest.onAuthRequired: Wird ausgelöst, wenn der Server den Client auffordert, Authentifizierungsdaten bereitzustellen. Der Listener kann nichts tun, die Anfrage abbrechen oder Authentifizierungsdaten 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 Antwort-Header verfügbar sind.
webRequest.onBeforeRedirect: Wird ausgelöst, wenn eine serverinitiierte Umleitung im Begriff ist, zu erfolgen.
webRequest.onCompleted: Wird ausgelöst, wenn eine Anfrage abgeschlossen ist.
webRequest.onErrorOccurred: Wird ausgelöst, wenn ein Fehler auftritt.

Browser-Kompatibilität

BCD tables only load in the browser

Zusätzliche Hinweise zu Chrome-Inkompatibilitäten.

Beispielerweiterungen

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