webRequest

Fügen Sie Ereignislistener für die verschiedenen Phasen der Erstellung einer HTTP-Anfrage hinzu, einschließlich Websocket-Anfragen auf ws:// und wss://. 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:

Allerdings werden nicht alle dieser Ereignisse von einer Erweiterung beobachtet. Beispielsweise 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 nicht von einer Erweiterung beobachtet werden kann, zum Beispiel wenn es zu einer data:-URL umleitet.

onErrorOccurred kann jederzeit während der Anfrage ausgelöst werden. Beachten Sie außerdem, dass die Reihenfolge der Ereignisse manchmal davon abweichen kann. Beispielsweise wird in Firefox bei einem HSTS-Upgrade das onBeforeRedirect-Ereignis sofort nach onBeforeRequest ausgelöst. onErrorOccurred wird auch ausgelöst, wenn Firefox-Tracking-Schutz 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 für bestimmte Arten von Ressourcen benachrichtigt werden
ein optionales extraInfoSpec-Objekt. Mit diesem können Sie zusätzliche spezifische Anweisungen für das Ereignis übergeben.

Der Listener-Funktion wird ein details-Objekt übergeben, das Informationen über die Anfrage enthält. Dazu gehört eine Anfragen-ID, die es einem Add-on ermöglicht, Ereignisse, die mit einer einzelnen Anfrage verbunden sind, zu korrelieren. Sie ist innerhalb einer Browsersitzung und im Kontext des Add-ons eindeutig. Sie bleibt während einer Anfrage gleich, sogar bei Umleitungen und Authentifizierungsaustauschen.

Um die webRequest-API für einen bestimmten Host zu nutzen, muss eine Erweiterung die "webRequest" API-Berechtigung und die Host-Berechtigung für diesen Host haben. Um das Feature "blocking" zu verwenden, muss die Erweiterung außerdem 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, muss eine Erweiterung beide Host-Berechtigungen besitzen, wenn sie die Bildanfrage abfangen will.

Anfragen ändern

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

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

Um dies zu tun, müssen Sie eine Option mit dem Wert "blocking" im extraInfoSpec-Argument an das addListener()-Ereignis übergeben. Dies macht den Listener synchron.

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

Anfragen beim Browser-Start

Wenn ein Listener mit der Option "blocking" registriert und während des Erweiterungsstarts registriert wird, wird die Erweiterung frühzeitig gestartet, wenn eine Anfrage beim Browser-Start gestellt wird, die mit dem Listener übereinstimmt. Dies ermöglicht der Erweiterung, die Anfrage beim Browser-Start zu beobachten. Wenn Sie diese Schritte nicht unternehmen, können beim Start erstellte Anfragen übersehen werden.

Spekulative Anfragen

Der Browser kann spekulative Verbindungen herstellen, bei denen angenommen wird, dass eine Anfrage an eine URI bald erfolgen könnte. Dieser Verbindungstyp bietet keine gültigen Tab-Informationen, sodass Anfragedetails wie tabId, frameId, parentFrameId usw. ungenau sind. Diese Verbindungen haben einen webRequest.ResourceType von speculative.

Zugreifen auf Sicherheitsinformationen

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()-Ereignis übergeben.

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

Antworten modifizieren

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 modifizieren, während sie vom Browser empfangen werden.

Um dies zu tun, 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 Ereignislistenern 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 zur Anwendung auf webRequest-Ereignisse beschreibt.
webRequest.ResourceType: Repräsentiert eine bestimmte Art von Ressource, die in einer Web-Anfrage abgerufen wird.
webRequest.SecurityInfo: Ein Objekt, das die Sicherheitseigenschaften einer bestimmten Web-Anfrage 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 an Aufrufen, die handlerBehaviorChanged() in einem Zeitraum von 10 Minuten ausführen kann.

Methoden

webRequest.handlerBehaviorChanged(): Diese Methode kann verwendet werden, um sicherzustellen, dass Ereignislistener korrekt angewendet werden, wenn Seiten im In-Memory-Cache des Browsers liegen.
webRequest.filterResponseData(): Gibt ein webRequest.StreamFilter-Objekt für eine bestimmte 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 gestellt werden soll und bevor Header verfügbar sind. Dies ist ein guter Ort, um 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 Ort, um zuzuhören, wenn Sie HTTP-Anfragen-Header ändern möchten.
webRequest.onSendHeaders: Wird ausgelöst, kurz bevor Header gesendet werden. Wenn Ihr Add-on oder ein anderes Add-on Header in onBeforeSendHeaders geändert hat, sehen Sie hier die geänderte Version.
webRequest.onHeadersReceived: Wird ausgelöst, wenn die HTTP-Antwortheader, die mit einer Anfrage verbunden sind, empfangen wurden. Sie können dieses Ereignis verwenden, um HTTP-Antwortheader zu ändern.
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. Bei 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, stattzufinden.
webRequest.onCompleted: Wird ausgelöst, wenn eine Anfrage abgeschlossen ist.
webRequest.onErrorOccurred: Wird ausgelöst, wenn ein Fehler auftritt.

Browser-Kompatibilität

Zusätzliche Anmerkungen zu Chrome-Inkompatibilitäten.

Beispielerweiterungen

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