Netzwerkanfragen in Manifest V3 ändern
Manifest V3 ändert, wie Erweiterungen mit Änderungen von Netzwerkanfragen umgehen. Anstatt Netzwerkanfragen abzufangen und zur Laufzeit mit chrome.webRequest zu ändern, gibt deine Erweiterung Regeln an, die Aktionen beschreiben, die ausgeführt werden sollen, wenn eine bestimmte Gruppe von Bedingungen erfüllt ist. Dazu verwenden Sie 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 Anwendungsfälle neu schreiben. In diesem Abschnitt werden Sie durch diesen Prozess geführt.
In Manifest V2 kann das Blockieren von Webanfragen sowohl die Leistung von Erweiterungen als auch die Leistung der Seiten, mit denen sie verwendet werden, erheblich beeinträchtigen. Der webRequest-Namespace unterstützt neun potenziell blockierende Ereignisse, von denen jedes eine unbegrenzte Anzahl von Event-Handlern erfordert. Außerdem wird jede Webseite möglicherweise durch mehrere Erweiterungen blockiert und die dafür erforderlichen Berechtigungen sind eingeschränkt. Mit Manifest V3 wird dieses Problem verhindert, indem Callbacks durch deklarative Regeln ersetzt werden.
Dies ist der zweite von drei Abschnitten, in denen Änderungen beschrieben werden, die für Code erforderlich sind, der nicht Teil des Extension Service Workers ist. Darin wird beschrieben, wie blockierende Webanfragen, die von Manifest V2 verwendet werden, in deklarative Netzanfragen umgewandelt werden, die von Manifest V3 verwendet werden. In den anderen beiden Abschnitten geht es um das Aktualisieren des Codes, der für die Migration zu Manifest V3 erforderlich ist, und um die Verbesserung der Sicherheit.
Berechtigungen aktualisieren
Nehmen Sie die folgenden Änderungen im Feld "permissions" in manifest.json vor.
- Entfernen Sie die Berechtigung
"webRequest", wenn Sie keine Netzwerkanfragen mehr berücksichtigen müssen. - Übereinstimmungsmuster von
"permissions"nach"host_permissions"verschieben
Je nach Anwendungsfall müssen Sie weitere Berechtigungen hinzufügen. Diese Berechtigungen werden im jeweiligen Anwendungsfall beschrieben.
Deklarative Regeln für Netzanfragen erstellen
Zum Erstellen deklarativer Netzanfrageregeln muss ein "declarative_net_request"-Objekt zu manifest.json hinzugefügt werden. Der Block "declarative_net_request" enthält ein Array mit "rule_resource"-Objekten, die auf eine Regeldatei verweisen. Die Regeldatei enthält ein Array mit Objekten, die eine Aktion und die Bedingungen angeben, unter denen diese Aktionen ausgelöst werden.
Gängige Anwendungsfälle
In den folgenden Abschnitten werden häufige Anwendungsfälle für deklarative Nettoanfragen beschrieben. Die folgende Anleitung bietet nur einen kurzen Überblick. Weitere Informationen zu diesen Informationen finden Sie in der API-Referenz unter chrome.declarativeNetRequest.
Einzelne URL blockieren
Ein häufiger Anwendungsfall in Manifest V2 war, Webanfragen mithilfe des Ereignisses onBeforeRequest im Hintergrundskript zu blockieren.
chrome.webRequest.onBeforeRequest.addListener((e) => {
return { cancel: true };
}, { urls: ["https://www.example.com/*"] }, ["blocking"]);
Erstelle für Manifest V3 eine neue declarativeNetRequest-Regel mit dem Aktionstyp "block". Beachten Sie das Objekt "condition" in der Beispielregel. Seine "urlFilter" ersetzt die Option urls, die an den webRequest-Listener übergeben wurde. Ein "resourceTypes"-Array gibt die Kategorie der zu blockierenden Ressourcen an. In diesem Beispiel wird nur die HTML-Hauptseite blockiert. Sie können aber beispielsweise nur Schriftarten blockieren.
[
{
"id" : 1,
"priority": 1,
"action" : { "type" : "block" },
"condition" : {
"urlFilter" : "||example.com",
"resourceTypes" : ["main_frame"]
}
}
]
Damit das funktioniert, müssen Sie die Berechtigungen der Erweiterung aktualisieren. Ersetzen Sie in der manifest.json die Berechtigung "webRequestBlocking" durch die Berechtigung "declarativeNetRequest". Die URL wird aus dem Feld "permissions" entfernt, weil zum Blockieren von Inhalten keine Hostberechtigungen erforderlich sind. Wie oben dargestellt, gibt die Regeldatei den oder die Hosts an, für die eine deklarative Netzwerkanfrage gilt.
Wenn Sie dies ausprobieren möchten, ist der folgende Code in unserem Beispiel-Repository verfügbar.
"permissions": [
"webRequestBlocking",
"https://*.example.com/*"
]
"permissions": [
"declarativeNetRequest",
]
Mehrere URLs weiterleiten
Ein weiterer häufiger Anwendungsfall in Manifest V2 war die Verwendung des BeforeRequest-Ereignisses zum Weiterleiten 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 an den webRequest-Listener übergebene Option url. Das "action"-Objekt der Regeldatei enthält in diesem Beispiel ein "redirect"-Feld mit der URL, die zurückgegeben werden soll, anstatt zu filtern.
[
{
"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"]
}
}
In diesem Fall müssen auch die Berechtigungen der Erweiterung geändert werden. 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 eine Weiterleitung neben der Hostberechtigung auch die Berechtigung "declarativeNetRequestWithHostAccess" erforderlich ist.
Wenn Sie dies ausprobieren möchten, ist der folgende Code in unserem Beispiel-Repository verfügbar.
"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 und ein bestimmter Header entfernt werden.
chrome.webRequest.onBeforeSendHeaders.addListener(
function(details) {
removeHeader(details.requestHeaders, 'cookie');
return {requestHeaders: details.requestHeaders};
},
// filters
{urls: ['https://*/*', 'http://*/*']},
// extraInfoSpec
['blocking', 'requestHeaders', 'extraHeaders']);
Dies geschieht auch mit Manifest V3 mit einer Regel in einer Regeldatei. Diesmal ist der Aktionstyp "modifyHeaders". Die Datei enthält ein Array mit "requestHeaders"-Objekten, in denen angegeben wird, welche Header geändert werden sollen. Das "condition"-Objekt enthält nur ein "resourceTypes"-Array. Es werden dieselben Werte wie in den vorherigen Beispielen unterstützt.
Wenn Sie dies ausprobieren möchten, ist der folgende Code in unserem Beispiel-Repository verfügbar.
[
{
"id": 1,
"priority": 1,
"action": {
"type": "modifyHeaders",
"requestHeaders": [
{ "header": "cookie", "operation": "remove" }
]
},
"condition": {
"urlFilter": "|*?no-cookies=1",
"resourceTypes": ["main_frame"]
}
}
]
In diesem Fall müssen auch die Berechtigungen der Erweiterung geändert werden. Ersetzen Sie wie zuvor die Berechtigung "webRequestBlocking" durch die Berechtigung "declarativeNetRequest".
"permissions": [
"webRequest",
"webRequestBlocking",
"https://*/*",
"http://*/*"
],
"permissions": [
"declarativeNetRequest",
],
"host_permissions": [
""
]