Netzwerkanfragen in Manifest V3 ändern
Mit Manifest V3 ändert sich die Art und Weise, wie Erweiterungen die Änderung von Netzwerkanfragen verarbeiten. Anstatt Netzwerkanfragen abzufangen 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 Net-Anfragen 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. - Verschieben Sie Übereinstimmungsmuster von
"permissions"nach"host_permissions".
Je nach Anwendungsfall müssen Sie weitere Berechtigungen hinzufügen. Diese Berechtigungen werden mit dem Anwendungsfall beschrieben, den sie unterstützen.
Regeln für deklarative Netzwerkanfragen 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 "declarative_net_request"-Block 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 den 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 wurde 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 das ausprobieren möchten, finden Sie den Code unten in unserem Samples-Repository.
"permissions": [
"webRequestBlocking",
"https://*.example.com/*"
]
"permissions": [
"declarativeNetRequest",
]
Mehrere URLs weiterleiten
Ein weiterer häufiger Anwendungsfall in Manifest V2 war die Verwendung des Ereignisses BeforeRequest, um Webanfragen weiterzuleiten.
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 webRequest-Listener übergeben wird. Beachten Sie, dass das "action"-Objekt der Regeldatei in diesem Beispiel ein "redirect"-Feld mit der zurückzugebenden URL enthält, anstatt der zu filternden URL.
[
{
"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 die Webanfrage-Header vor dem Senden abgefangen und ein bestimmter entfernt werden, um Cookies zu blockieren.
chrome.webRequest.onBeforeSendHeaders.addListener(
function(details) {
removeHeader(details.requestHeaders, 'cookie');
return {requestHeaders: details.requestHeaders};
},
// filters
{urls: ['https://*/*', 'http://*/*']},
// extraInfoSpec
['blocking', 'requestHeaders', 'extraHeaders']);
In Manifest V3 wird dies auch mit einer Regel in einer Regeldatei durchgeführt. Diesmal ist der Aktionstyp "modifyHeaders". Die Datei enthält ein Array von "requestHeaders"-Objekten, in denen die zu ändernden Header und die Art der Änderung angegeben sind. 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"]
}
}
]
In diesem 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": [
""
]