Netzwerkanfragen in Manifest V3 ändern
Mit Manifest V3 ändert sich die Art und Weise, wie Erweiterungen die Änderung von Netzwerkanfragen verarbeiten. Anstatt Netzwerkanfragen zu erfassen und sie mit chrome.webRequest zur Laufzeit zu ändern, gibt Ihre Erweiterung Regeln an, die Aktionen beschreiben, die ausgeführt werden sollen, wenn eine bestimmte Gruppe von Bedingungen erfüllt ist. Verwenden Sie dazu die Declarative Net Request API.
Die Web Request API und die Declarative Net Request APIs unterscheiden sich erheblich. Anstatt einen Funktionsaufruf durch einen anderen zu ersetzen, müssen Sie Ihren Code in Bezug auf die Anwendungsfälle umschreiben. In diesem Abschnitt wird dieser Vorgang beschrieben.
In Manifest V2 kann das Blockieren von Webanfragen sowohl die Leistung von Erweiterungen als auch die Leistung der Seiten beeinträchtigen, mit denen sie arbeiten. Der Namespace webRequest unterstützt neun potenziell blockierende Ereignisse, für die jeweils eine unbegrenzte Anzahl von Ereignishandlern verwendet werden kann. Schlimmer noch: Jede Webseite wird möglicherweise von mehreren Erweiterungen blockiert und die dafür erforderlichen Berechtigungen sind invasiv. Manifest V3 schützt vor diesem Problem, indem Callbacks durch deklarative Regeln ersetzt werden.
Dies ist der zweite von drei Abschnitten, in denen Änderungen für Code beschrieben werden, der nicht Teil des Service Workers der Erweiterung ist. Darin wird beschrieben, wie blockierende Webanfragen, die von Manifest V2 verwendet werden, in deklarative Netzwerkanfragen umgewandelt werden, die von Manifest V3 verwendet werden. In den anderen beiden Abschnitten erfahren Sie, wie Sie Ihren Code aktualisieren, um zu Manifest V3 zu migrieren, und wie Sie die Sicherheit verbessern.
Berechtigungen aktualisieren
Nehmen Sie die folgenden Änderungen am Feld "permissions" in Ihrer manifest.json vor.
- Entfernen Sie die Berechtigung
"webRequest", wenn Sie Netzwerkanfragen nicht mehr beobachten müssen. - Übereinstimmungsmuster von
"permissions"nach"host_permissions"verschieben.
Je nach Anwendungsfall müssen Sie weitere Berechtigungen hinzufügen. Diese Berechtigungen werden mit dem Anwendungsfall beschrieben, den sie unterstützen.
Deklarative Nettoanfrageregeln erstellen
Wenn Sie deklarative Regeln für Netzwerkanfragen erstellen möchten, müssen Sie Ihrem manifest.json ein "declarative_net_request"-Objekt hinzufügen. Der Block "declarative_net_request" enthält ein Array von "rule_resource"-Objekten, die auf eine Regeldatei verweisen. Die Regeldatei enthält ein Array von Objekten, die eine Aktion und die Bedingungen angeben, unter denen diese Aktionen aufgerufen werden.
Gängige Anwendungsfälle
In den folgenden Abschnitten werden gängige Anwendungsfälle für deklarative Net-Anfragen beschrieben. Die folgende Anleitung ist nur ein kurzer Überblick. Weitere Informationen zu allen hier aufgeführten Informationen finden Sie in der API-Referenz unter chrome.declarativeNetRequest.
Einzelne URL blockieren
Ein häufiger Anwendungsfall in Manifest V2 war das Blockieren von Webanfragen mit dem Ereignis onBeforeRequest im Hintergrundskript.
chrome.webRequest.onBeforeRequest.addListener((e) => { return { cancel: true }; }, { urls: ["https://www.example.com/*"] }, ["blocking"]);
Erstellen Sie für Manifest V3 eine neue declarativeNetRequest-Regel mit dem Aktionstyp "block". Beachten Sie das Objekt "condition" in der Beispielregel. Die "urlFilter" ersetzt die urls-Option, die an den webRequest-Listener übergeben wird. Mit einem "resourceTypes"-Array wird die Kategorie der zu blockierenden Ressourcen angegeben. In diesem Beispiel wird nur die Haupt-HTML-Seite blockiert. Sie können aber auch nur Schriftarten blockieren.
[ { "id" : 1, "priority": 1, "action" : { "type" : "block" }, "condition" : { "urlFilter" : "||example.com", "resourceTypes" : ["main_frame"] } } ]
Dazu müssen Sie die Berechtigungen der Erweiterung aktualisieren. Ersetzen Sie in manifest.json die Berechtigung "webRequestBlocking" durch die Berechtigung "declarativeNetRequest". Die URL wird aus dem Feld "permissions" entfernt, da zum Blockieren von Inhalten keine Hostberechtigungen erforderlich sind. Wie oben gezeigt, gibt die Regeldatei den oder die Hosts an, auf die eine deklarative Net-Anfrage angewendet wird.
Wenn Sie dies ausprobieren möchten, finden Sie den folgenden Code in unserem Beispiel-Repository.
"permissions": [ "webRequestBlocking", "https://*.example.com/*" ]
"permissions": [ "declarativeNetRequest", ]
Mehrere URLs weiterleiten
Ein weiterer häufiger Anwendungsfall in Manifest V2 war die Verwendung des BeforeRequest-Ereignisses zur Weiterleitung von Webanfragen.
chrome.webRequest.onBeforeRequest.addListener((e) => { console.log(e); return { redirectUrl: "https://developer.chrome.com/docs/extensions/mv3/intro/" }; }, { urls: [ "https://developer.chrome.com/docs/extensions/mv2/" ] }, ["blocking"] );
Verwenden Sie für Manifest V3 den Aktionstyp "redirect". Wie zuvor ersetzt "urlFilter" die Option url, die an den Listener webRequest übergeben wurde. Beachten Sie, dass in diesem Beispiel das "action"-Objekt der Regeldatei ein "redirect"-Feld enthält, das die zurückzugebende URL anstelle der gefilterten URL enthält.
[ { "id" : 1, "priority": 1, "action": { "type": "redirect", "redirect": { "url": "https://developer.chrome.com/docs/extensions/mv3/intro/" } }, "condition": { "urlFilter": "https://developer.chrome.com/docs/extensions/mv2/", "resourceTypes": ["main_frame"] } }
Für dieses Szenario sind auch Änderungen an den Berechtigungen der Erweiterung erforderlich. Ersetzen Sie wie zuvor die Berechtigung "webRequestBlocking" durch die Berechtigung "declarativeNetRequest". Die URLs werden wieder aus der manifest.json in eine Regeldatei verschoben. Beachten Sie, dass für die Weiterleitung neben der Hostberechtigung auch die Berechtigung "declarativeNetRequestWithHostAccess" erforderlich ist.
Wenn Sie das ausprobieren möchten, finden Sie den Code unten in unserem Samples-Repository.
"permissions": [ "webRequestBlocking", "https://developer.chrome.com/docs/extensions/*", "https://developer.chrome.com/docs/extensions/reference" ]
"permissions": [ "declarativeNetRequestWithHostAccess" ], "host_permissions": [ "https://developer.chrome.com/*" ]
Cookies blockieren
In Manifest V2 müssen zum Blockieren von Cookies die Webanfrageheader abgefangen werden, bevor sie gesendet werden, und einen bestimmten Header entfernen.
chrome.webRequest.onBeforeSendHeaders.addListener( function(details) { removeHeader(details.requestHeaders, 'cookie'); return {requestHeaders: details.requestHeaders}; }, // filters {urls: ['https://*/*', 'http://*/*']}, // extraInfoSpec ['blocking', 'requestHeaders', 'extraHeaders']);
Bei Manifest V3 geschieht dies auch mit einer Regel in einer Regeldatei. Diesmal ist der Aktionstyp "modifyHeaders". Die Datei enthält ein Array mit "requestHeaders"-Objekten, in denen die zu ändernden Header angegeben werden und wie sie geändert werden. Das "condition"-Objekt enthält nur ein "resourceTypes"-Array. Es werden dieselben Werte wie in den vorherigen Beispielen unterstützt.
Wenn Sie das ausprobieren möchten, finden Sie den Code unten in unserem Samples-Repository.
[ { "id": 1, "priority": 1, "action": { "type": "modifyHeaders", "requestHeaders": [ { "header": "cookie", "operation": "remove" } ] }, "condition": { "urlFilter": "|*?no-cookies=1", "resourceTypes": ["main_frame"] } } ]
Für dieses Szenario sind auch Änderungen an den Berechtigungen der Erweiterung erforderlich. Ersetzen Sie wie zuvor die Berechtigung "webRequestBlocking" durch die Berechtigung "declarativeNetRequest".
"permissions": [ "webRequest", "webRequestBlocking", "https://*/*", "http://*/*" ],
"permissions": [ "declarativeNetRequest", ], "host_permissions": [ "" ]