chrome.declarativeNetRequest

Beschreibung

Mit der chrome.declarativeNetRequest API können Netzwerk-Anfragen durch Angabe deklarativer Regeln blockiert oder geändert werden. So können Erweiterungen Netzwerkanfragen ändern, ohne sie abzufangen und ihren Inhalt anzusehen. Das bietet mehr Datenschutz.

Berechtigungen

declarativeNetRequest
declarativeNetRequestWithHostAccess

Die Berechtigungen „declarativeNetRequest“ und „declarativeNetRequestWithHostAccess“ bieten dieselben Funktionen. Der Unterschied zwischen ihnen besteht darin, wann Berechtigungen angefordert oder gewährt werden.

"declarativeNetRequest"
Löst bei der Installation eine Berechtigungswarnung aus, bietet aber impliziten Zugriff auf allow-, allowAllRequests- und block-Regeln. Verwenden Sie diese Option nach Möglichkeit, um keinen uneingeschränkten Zugriff auf Hosts anfordern zu müssen.
"declarativeNetRequestFeedback"
Aktiviert Debugging-Funktionen für entpackte Erweiterungen, insbesondere getMatchedRules() und onRuleMatchedDebug.
"declarativeNetRequestWithHostAccess"
Bei der Installation wird keine Berechtigungswarnung angezeigt, aber Sie müssen Hostberechtigungen anfordern, bevor Sie Aktionen auf einem Host ausführen können. Das ist sinnvoll, wenn Sie deklarative Netzwerkanforderungsregeln in einer Erweiterung verwenden möchten, die bereits Hostberechtigungen hat, ohne zusätzliche Warnungen zu generieren.

Verfügbarkeit

Chrome 84 und höher

Manifest

Zusätzlich zu den zuvor beschriebenen Berechtigungen muss für bestimmte Arten von Regelsätzen, insbesondere für statische Regelsätze, der Manifestschlüssel "declarative_net_request" deklariert werden. Dabei sollte es sich um ein Dictionary mit einem einzelnen Schlüssel namens "rule_resources" handeln. Dieser Schlüssel ist ein Array mit Wörterbüchern vom Typ Ruleset, wie unten dargestellt. Der Name „Ruleset“ wird nicht im JSON des Manifests angezeigt, da es sich lediglich um ein Array handelt. Statische Regelsätze werden weiter unten in diesem Dokument erläutert.

{   "name": "My extension",   ...    "declarative_net_request" : {     "rule_resources" : [{       "id": "ruleset_1",       "enabled": true,       "path": "rules_1.json"     }, {       "id": "ruleset_2",       "enabled": false,       "path": "rules_2.json"     }]   },   "permissions": [     "declarativeNetRequest",     "declarativeNetRequestFeedback"   ],   "host_permissions": [     "http://www.blogger.com/*",     "http://*.google.com/*"   ],   ... }

Regeln und Regelsätze

Wenn Sie diese API verwenden möchten, müssen Sie mindestens ein Regelset angeben. Ein Regelsatz enthält ein Array von Regeln. Eine einzelne Regel führt einen der folgenden Schritte aus:

  • Blockieren Sie eine Netzwerkanfrage.
  • Aktualisieren Sie das Schema (von „http“ zu „https“).
  • Verhindert, dass eine Anfrage blockiert wird, indem alle übereinstimmenden blockierten Regeln negiert werden.
  • Netzwerkanfrage umleiten
  • Anfrage- oder Antwortheader ändern.

Es gibt drei Arten von Regelsätzen, die auf leicht unterschiedliche Weise verwaltet werden.

Dynamisch
Sie bleiben über Browsersitzungen und Erweiterungs-Upgrades hinweg erhalten und werden mit JavaScript verwaltet, während eine Erweiterung verwendet wird.
Sitzung
Wird gelöscht, wenn der Browser geschlossen wird und wenn eine neue Version der Erweiterung installiert wird. Sitzungsregeln werden mit JavaScript verwaltet, während eine Erweiterung verwendet wird.
Statisch
Wird verpackt, installiert und aktualisiert, wenn eine Erweiterung installiert oder aktualisiert wird. Statische Regeln werden in JSON-formatierten Regeldateien gespeichert und in der Manifestdatei aufgeführt.

Dynamische und sitzungsbezogene Regelsätze

Dynamische und sitzungsbezogene Regelsätze werden mit JavaScript verwaltet, während eine Erweiterung verwendet wird.

  • Dynamische Regeln bleiben über Browsersitzungen und Erweiterungs-Upgrades hinweg bestehen.
  • Sitzungsregeln werden gelöscht, wenn der Browser geschlossen wird und wenn eine neue Version der Erweiterung installiert wird.

Es gibt nur jeweils einen dieser Regelsatztypen. Eine Erweiterung kann Regeln dynamisch hinzufügen oder entfernen, indem sie updateDynamicRules() und updateSessionRules() aufruft, sofern die Regeln nicht überschritten werden. Informationen zu den Beschränkungen für Regeln finden Sie unter Beschränkungen für Regeln. Ein Beispiel dafür finden Sie unter Codebeispiele.

Statische Regelsätze

Im Gegensatz zu dynamischen Regeln und Sitzungsregeln werden statische Regeln verpackt, installiert und aktualisiert, wenn eine Erweiterung installiert oder aktualisiert wird. Sie werden in Regeldateien im JSON-Format gespeichert, die der Erweiterung mit den Schlüsseln "declarative_net_request" und "rule_resources" wie oben beschrieben sowie einem oder mehreren Ruleset-Wörterbüchern angegeben werden. Ein Ruleset-Wörterbuch enthält einen Pfad zur Regeldatei, eine ID für das in der Datei enthaltene Regelset und Informationen dazu, ob das Regelset aktiviert oder deaktiviert ist. Die letzten beiden sind wichtig, wenn Sie ein Regelset programmatisch aktivieren oder deaktivieren.

{   ...   "declarative_net_request" : {     "rule_resources" : [{       "id": "ruleset_1",       "enabled": true,       "path": "rules_1.json"     },     ...     ]   }   ... }

Um Regelsatzdateien zu testen, laden Sie Ihre Erweiterung entpackt. Fehler und Warnungen zu ungültigen statischen Regeln werden nur für entpackte Erweiterungen angezeigt. Ungültige statische Regeln in gepackten Erweiterungen werden ignoriert.

Beschleunigte Überprüfung

Änderungen an statischen Regelsätzen können möglicherweise beschleunigt überprüft werden. Weitere Informationen

Statische Regeln und Regelsätze aktivieren und deaktivieren

Sowohl einzelne statische Regeln als auch vollständige statische Regelsätze können zur Laufzeit aktiviert oder deaktiviert werden.

Die aktivierten statischen Regeln und Regelsätze bleiben über Browsersitzungen hinweg erhalten. Beide werden bei Erweiterungsupdates nicht beibehalten. Das bedeutet, dass nach einem Update nur die Regeln verfügbar sind, die Sie in Ihren Regeldateien belassen haben.

Aus Leistungsgründen gibt es auch Einschränkungen hinsichtlich der Anzahl der Regeln und Regelsätze, die gleichzeitig aktiviert werden können. Rufen Sie getAvailableStaticRuleCount() auf, um die Anzahl der zusätzlichen Regeln zu prüfen, die aktiviert werden können. Informationen zu den Beschränkungen für Regeln finden Sie unter Beschränkungen für Regeln.

Rufen Sie updateStaticRules() auf, um statische Regeln zu aktivieren oder zu deaktivieren. Diese Methode verwendet ein UpdateStaticRulesOptions-Objekt, das Arrays mit IDs von Regeln enthält, die aktiviert oder deaktiviert werden sollen. Die IDs werden mit dem Schlüssel "id" des Ruleset-Dictionarys definiert. Es gilt ein Limit von maximal 5.000 deaktivierten statischen Regeln.

Rufen Sie updateEnabledRulesets() auf, um statische Regelsätze zu aktivieren oder zu deaktivieren. Diese Methode verwendet ein UpdateRulesetOptions-Objekt, das Arrays mit IDs von Regelsätzen enthält, die aktiviert oder deaktiviert werden sollen. Die IDs werden mit dem Schlüssel "id" des Ruleset-Dictionarys definiert.

Build-Regeln

Unabhängig vom Typ beginnt eine Regel mit vier Feldern, wie unten dargestellt. Während für die Tasten "id" und "priority" eine Zahl angegeben werden muss, können für die Tasten "action" und "condition" mehrere Blockierungs- und Weiterleitungsbedingungen angegeben werden. Die folgende Regel blockiert alle Skriptanfragen, die von "foo.com" an eine beliebige URL mit "abc" als Teilstring gesendet werden.

{   "id" : 1,   "priority": 1,   "action" : { "type" : "block" },   "condition" : {     "urlFilter" : "abc",     "initiatorDomains" : ["foo.com"],     "resourceTypes" : ["script"]   } }

URL-Abgleich

Mit Declarative Net Request können URLs entweder mit einer Syntax für den Musterabgleich oder mit regulären Ausdrücken abgeglichen werden.

Syntax für URL-Filter

Mit dem Schlüssel "condition" einer Regel kann ein "urlFilter"-Schlüssel für Aktionen für URLs unter einer bestimmten Domain verwendet werden. Sie erstellen Muster mit Tokens für den Musterabgleich. Hier einige Beispiele:

urlFilter Übereinstimmungen Stimmt nicht überein
"abc" https://abcd.com
https://example.com/abcd		 https://ab.com
"abc*d" https://abcd.com
https://example.com/abcxyzd		 https://abc.com
"||a.example.com" https://a.example.com/
https://b.a.example.com/xyz
https://a.example.company		 https://example.com/
"|https*" https://example.com http://example.com/
http://https.com
"example*^123|" https://example.com/123
http://abc.com/example?123		 https://example.com/1234
https://abc.com/example0123

Reguläre Ausdrücke

In Bedingungen können auch reguläre Ausdrücke verwendet werden. Weitere Informationen finden Sie unter dem Schlüssel "regexFilter". Informationen zu den für diese Bedingungen geltenden Einschränkungen finden Sie unter Regeln mit regulären Ausdrücken.

Gute URL-Bedingungen schreiben

Achten Sie beim Schreiben von Regeln darauf, dass immer eine gesamte Domain abgeglichen wird. Andernfalls wird Ihre Regel möglicherweise in unerwarteten Situationen angewendet. Wenn Sie beispielsweise die Syntax für den Musterabgleich verwenden:

  • google.com wird fälschlicherweise mit https://example.com/?param=google.com abgeglichen
  • ||google.com wird fälschlicherweise mit https://google.company abgeglichen
  • https://www.google.com wird fälschlicherweise mit https://example.com/?param=https://www.google.com abgeglichen

Geeignete Methoden:

  • ||google.com/, das mit allen Pfaden und allen Subdomains übereinstimmt.
  • |https://www.google.com/, das mit allen Pfaden, aber keinen Subdomains übereinstimmt.

Verwenden Sie die Zeichen ^ und /, um einen regulären Ausdruck zu verankern. ^https:\/\/www\.google\.com\/ entspricht beispielsweise jedem Pfad auf https://www.google.com.

Regelauswertung

DNR-Regeln werden vom Browser in verschiedenen Phasen des Lebenszyklus von Netzwerkanfragen angewendet.

Vor der Anfrage

Bevor eine Anfrage gesendet wird, kann eine Erweiterung sie mit einer passenden Regel blockieren oder weiterleiten (einschließlich des Upgrades des Schemas von HTTP auf HTTPS).

Für jede Erweiterung ermittelt der Browser eine Liste mit übereinstimmenden Regeln. Regeln mit der Aktion modifyHeaders sind hier nicht enthalten, da sie später verarbeitet werden. Außerdem werden Regeln mit der Bedingung responseHeaders später berücksichtigt (wenn Antwortheader verfügbar sind) und sind nicht enthalten.

Anschließend wählt Chrome für jede Erweiterung maximal einen Kandidaten pro Anfrage aus. Chrome findet eine passende Regel, indem alle passenden Regeln nach Priorität sortiert werden. Regeln mit derselben Priorität werden nach Aktion sortiert (allow oder allowAllRequests > block > upgradeScheme > redirect).

Wenn es sich bei dem Kandidaten um eine allow- oder allowAllRequests-Regel handelt oder der Frame, in dem die Anfrage gestellt wird, zuvor mit einer allowAllRequests-Regel mit höherer oder gleicher Priorität aus dieser Erweiterung übereinstimmt, wird die Anfrage „zugelassen“ und die Erweiterung hat keine Auswirkungen auf die Anfrage.

Wenn mehr als eine Erweiterung diese Anfrage blockieren oder weiterleiten möchte, wird eine einzelne Aktion ausgewählt. In Chrome werden die Regeln dazu in der Reihenfolge block > redirect oder upgradeScheme > allow oder allowAllRequests sortiert. Wenn zwei Regeln vom selben Typ sind, wählt Chrome die Regel der zuletzt installierten Erweiterung aus.

Bevor Anfrageheader gesendet werden

Bevor Chrome Anfrageheader an den Server sendet, werden die Header anhand übereinstimmender modifyHeaders-Regeln aktualisiert.

In einer einzelnen Erweiterung erstellt Chrome die Liste der auszuführenden Änderungen, indem alle übereinstimmenden modifyHeaders-Regeln gesucht werden. Wie bisher werden nur Regeln mit einer höheren Priorität als übereinstimmende allow- oder allowAllRequests-Regeln berücksichtigt.

Diese Regeln werden von Chrome in einer Reihenfolge angewendet, sodass Regeln einer neueren Erweiterung immer vor Regeln einer älteren Erweiterung ausgewertet werden. Außerdem werden Regeln mit höherer Priorität aus einer Erweiterung immer vor Regeln mit niedrigerer Priorität aus derselben Erweiterung angewendet. Das gilt auch für Erweiterungen:

  • Wenn eine Regel an einen Header angehängt wird, können Regeln mit niedrigerer Priorität nur an diesen Header angehängt werden. Set- und Remove-Vorgänge sind nicht zulässig.
  • Wenn in einer Regel ein Header festgelegt wird, können nur Regeln mit niedrigerer Priorität aus derselben Erweiterung an diesen Header angehängt werden. Andere Änderungen sind nicht zulässig.
  • Wenn durch eine Regel ein Header entfernt wird, kann er durch Regeln mit niedrigerer Priorität nicht weiter geändert werden.

Nach Erhalt einer Antwort

Sobald die Antwortheader empfangen wurden, wertet Chrome Regeln mit der Bedingung responseHeaders aus.

Nachdem diese Regeln nach action und priority sortiert und alle Regeln ausgeschlossen wurden, die durch eine übereinstimmende allow- oder allowAllRequests-Regel überflüssig werden (dies geschieht identisch mit den Schritten unter „Vor der Anfrage“), kann Chrome die Anfrage im Namen einer Erweiterung blockieren oder weiterleiten.

Wenn eine Anfrage diese Phase erreicht hat, wurde sie bereits an den Server gesendet und der Server hat Daten wie den Anfragetext empfangen. Eine Blockierungs- oder Weiterleitungsregel mit einer Bedingung für Antwortheader wird weiterhin ausgeführt, kann die Anfrage aber nicht blockieren oder weiterleiten.

Bei einer Blockierungsregel wird dies dadurch gehandhabt, dass die Seite, von der die Anfrage stammt, eine blockierte Antwort erhält und Chrome die Anfrage frühzeitig beendet. Bei einer Weiterleitungsregel sendet Chrome eine neue Anfrage an die weitergeleitete URL. Prüfen Sie, ob diese Verhaltensweisen den Datenschutzanforderungen für Ihre Erweiterung entsprechen.

Wenn die Anfrage nicht blockiert oder weitergeleitet wird, wendet Chrome alle modifyHeaders-Regeln an. Das Anwenden von Änderungen auf Antwortheader funktioniert auf dieselbe Weise wie im Abschnitt „Bevor Anfrageheader gesendet werden“ beschrieben. Änderungen an Anfrageheadern haben keine Auswirkungen, da die Anfrage bereits gestellt wurde.

Sichere Regeln

Als sichere Regeln gelten Regeln mit der Aktion block, allow, allowAllRequests oder upgradeScheme. Für diese Regeln gilt ein erhöhtes Kontingent für dynamische Regeln.

Limits für Regeln

Das Laden und Auswerten von Regeln im Browser führt zu einem Leistungsmehraufwand. Daher gelten bei der Verwendung der API einige Einschränkungen. Die Grenzwerte hängen vom Typ der verwendeten Regel ab.

Statische Regeln

Statische Regeln sind Regeln, die in Regeldateien angegeben sind, die in der Manifestdatei deklariert werden. Eine Erweiterung kann bis zu 100 statische Regelsätze als Teil des Manifestschlüssels "rule_resources" angeben. Es können jedoch nur 50 dieser Regelsätze gleichzeitig aktiviert werden. Letzteres wird als MAX_NUMBER_OF_ENABLED_STATIC_RULESETS bezeichnet. Zusammen enthalten diese Regelsätze mindestens 30.000 Regeln. Das wird als GUARANTEED_MINIMUM_STATIC_RULES bezeichnet.

Die Anzahl der danach verfügbaren Regeln hängt davon ab, wie viele Regeln durch alle Erweiterungen aktiviert werden, die im Browser eines Nutzers installiert sind. Sie können diese Nummer zur Laufzeit durch Aufrufen von getAvailableStaticRuleCount() ermitteln. Ein Beispiel dafür finden Sie unter Codebeispiele.

Sitzungsregeln

Eine Erweiterung kann bis zu 5.000 Sitzungsregeln haben. Dies wird als MAX_NUMBER_OF_SESSION_RULES bereitgestellt.

Vor Chrome 120 lag das Limit für kombinierte dynamische und Sitzungsregeln bei 5.000.

Dynamische Regeln

Eine Erweiterung kann mindestens 5.000 dynamische Regeln haben. Dies wird als MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES bereitgestellt.

Ab Chrome 121 gilt für sichere dynamische Regeln, die als MAX_NUMBER_OF_DYNAMIC_RULES verfügbar sind, ein höheres Limit von 30.000 Regeln. Alle unsicheren Regeln, die innerhalb des Limits von 5.000 Regeln hinzugefügt werden, werden ebenfalls auf dieses Limit angerechnet.

Vor Chrome 120 gab es ein kombiniertes Limit von 5.000 dynamischen Regeln und Sitzungsregeln.

Regeln mit regulären Ausdrücken

Für alle Arten von Regeln können reguläre Ausdrücke verwendet werden. Die Gesamtzahl der Regeln mit regulären Ausdrücken darf jedoch 1.000 nicht überschreiten. Das wird als MAX_NUMBER_OF_REGEX_RULES bezeichnet.

Außerdem darf jede Regel nach der Kompilierung nicht größer als 2 KB sein. Das hängt in etwa mit der Komplexität der Regel zusammen. Wenn Sie versuchen, eine Regel zu laden, die dieses Limit überschreitet, wird eine Warnung wie die folgende angezeigt und die Regel wird ignoriert.

rules_1.json: Rule with id 1 specified a more complex regex than allowed as part of the "regexFilter" key.

Interaktionen mit Service-Workern

Eine declarativeNetRequest gilt nur für Anfragen, die den Netzwerk-Stack erreichen. Das umfasst Antworten aus dem HTTP-Cache, aber möglicherweise nicht Antworten, die über den onfetch-Handler eines Service Workers laufen. declarativeNetRequest wirkt sich nicht auf Antworten aus, die vom Service Worker generiert oder aus CacheStorage abgerufen werden, aber auf Aufrufe von fetch(), die in einem Service Worker erfolgen.

Webzugängliche Ressourcen

Eine declarativeNetRequest-Regel kann nicht von einer öffentlichen Ressourcenanfrage zu einer Ressource weiterleiten, die nicht über das Web zugänglich ist. Dies führt zu einem Fehler. Dies gilt auch dann, wenn die angegebene webzugängliche Ressource der weiterleitenden Erweiterung gehört. Um Ressourcen für declarativeNetRequest zu deklarieren, verwenden Sie das Array "web_accessible_resources" des Manifests.

Header-Änderung

Der Vorgang „Anhängen“ wird nur für die folgenden Header unterstützt: accept, accept-encoding, accept-language, access-control-request-headers, cache-control, connection, content-language, cookie, forwarded, if-match, if-none-match, keep-alive, range, te, trailer, transfer-encoding, upgrade, user-agent, via, want-digest, x-forwarded-for.

Beispiele

Codebeispiele

Dynamische Regeln aktualisieren

Das folgende Beispiel zeigt, wie updateDynamicRules() aufgerufen wird. Die Vorgehensweise für updateSessionRules() ist dieselbe.

// Get arrays containing new and old rules const newRules = await getNewRules(); const oldRules = await chrome.declarativeNetRequest.getDynamicRules(); const oldRuleIds = oldRules.map(rule => rule.id);  // Use the arrays to update the dynamic rules await chrome.declarativeNetRequest.updateDynamicRules({   removeRuleIds: oldRuleIds,   addRules: newRules });

Statische Regelsätze aktualisieren

Im folgenden Beispiel wird gezeigt, wie Sie Regelsätze aktivieren und deaktivieren können, wobei die Anzahl der verfügbaren und die maximale Anzahl der aktivierten statischen Regelsätze berücksichtigt werden. Das ist der Fall, wenn die Anzahl der benötigten statischen Regeln die zulässige Anzahl überschreitet. Damit das funktioniert, müssen einige Ihrer Regelsätze installiert und einige deaktiviert sein (Einstellung "Enabled" auf false in der Manifestdatei).

async function updateStaticRules(enableRulesetIds, disableCandidateIds) {   // Create the options structure for the call to updateEnabledRulesets()   let options = { enableRulesetIds: enableRulesetIds }   // Get the number of enabled static rules   const enabledStaticCount = await chrome.declarativeNetRequest.getEnabledRulesets();   // Compare rule counts to determine if anything needs to be disabled so that   // new rules can be enabled   const proposedCount = enableRulesetIds.length;   if (enabledStaticCount + proposedCount > chrome.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS) {     options.disableRulesetIds = disableCandidateIds   }   // Update the enabled static rules   await chrome.declarativeNetRequest.updateEnabledRulesets(options); }

Regelbeispiele

Die folgenden Beispiele veranschaulichen, wie Chrome Regeln in einer Erweiterung priorisiert. Wenn Sie sie überprüfen, sollten Sie die Priorisierungsregeln in einem separaten Fenster öffnen.

Der Schlüssel „priority“

Für diese Beispiele ist die Hostberechtigung für *://*.example.com/* erforderlich.

Um die Priorität einer bestimmten URL zu ermitteln, sehen Sie sich den (vom Entwickler definierten) "priority"-Schlüssel, den "action"-Schlüssel und den "urlFilter"-Schlüssel an. Diese Beispiele beziehen sich auf die Beispielregeldatei, die darunter aufgeführt ist.

Navigation zu https://google.com
Für diese URL gelten zwei Regeln: die Regeln mit den IDs 1 und 4. Die Regel mit der ID 1 wird angewendet, da "block"-Aktionen eine höhere Priorität als "redirect"-Aktionen haben. Die verbleibenden Regeln gelten nicht, da sie für längere URLs vorgesehen sind.
Aufruf von https://google.com/1234
Aufgrund der längeren URL stimmt jetzt zusätzlich zu den Regeln mit den IDs 1 und 4 auch die Regel mit der ID 2. Die Regel mit der ID 2 wird angewendet, da "allow" eine höhere Priorität als "block" und "redirect" hat.
Aufruf von https://google.com/12345
Alle vier Regeln stimmen mit dieser URL überein. Die Regel mit der ID 3 wird angewendet, da ihre vom Entwickler definierte Priorität die höchste in der Gruppe ist.
[   {     "id": 1,     "priority": 1,     "action": { "type": "block" },     "condition": {"urlFilter": "||google.com/", "resourceTypes": ["main_frame"] }   },   {     "id": 2,     "priority": 1,     "action": { "type": "allow" },     "condition": { "urlFilter": "||google.com/123", "resourceTypes": ["main_frame"] }   },   {     "id": 3,     "priority": 2,     "action": { "type": "block" },     "condition": { "urlFilter": "||google.com/12345", "resourceTypes": ["main_frame"] }   },   {     "id": 4,     "priority": 1,     "action": { "type": "redirect", "redirect": { "url": "https://example.com" } },     "condition": { "urlFilter": "||google.com/", "resourceTypes": ["main_frame"] }   }, ]

Weiterleitungen

Für das folgende Beispiel ist die Hostberechtigung für *://*.example.com/* erforderlich.

Das folgende Beispiel zeigt, wie eine Anfrage von example.com auf eine Seite innerhalb der Erweiterung umgeleitet wird. Der Erweiterungspfad /a.jpg wird zu chrome-extension://EXTENSION_ID/a.jpg aufgelöst, wobei EXTENSION_ID die ID Ihrer Erweiterung ist. Dazu muss /a.jpg im Manifest als webzugängliche Ressource deklariert werden.

{   "id": 1,   "priority": 1,   "action": { "type": "redirect", "redirect": { "extensionPath": "/a.jpg" } },   "condition": {     "urlFilter": "||https://www.example.com/",     "resourceTypes": ["main_frame"]   } }

Im Folgenden wird der Schlüssel "transform" verwendet, um zu einer Subdomain von example.com weiterzuleiten. Es wird ein Domainnamen-Anker („||“) verwendet, um Anfragen mit einem beliebigen Schema von example.com abzufangen. Der Schlüssel "scheme" in "transform" gibt an, dass bei Weiterleitungen zur Subdomain immer „https“ verwendet wird.

{   "id": 1,   "priority": 1,   "action": {     "type": "redirect",     "redirect": {       "transform": { "scheme": "https", "host": "new.example.com" }     }   },   "condition": {     "urlFilter": "||example.com/",     "resourceTypes": ["main_frame"]   } }

Im folgenden Beispiel werden reguläre Ausdrücke verwendet, um von https://www.abc.xyz.com/path zu https://abc.xyz.com/path weiterzuleiten. Beachten Sie im Schlüssel "regexFilter", wie Punkte maskiert werden und dass die Erfassungsgruppe entweder „abc“ oder „def“ auswählt. Mit dem Schlüssel "regexSubstitution" wird die erste zurückgegebene Übereinstimmung des regulären Ausdrucks mit „\1“ angegeben. In diesem Fall wird „abc“ aus der weitergeleiteten URL erfasst und in die Ersetzung eingefügt.

{   "id": 1,   "priority": 1,   "action": {     "type": "redirect",     "redirect": {       "regexSubstitution": "https://\\1.xyz.com/"     }   },   "condition": {     "regexFilter": "^https://www\\.(abc|def)\\.xyz\\.com/",     "resourceTypes": [       "main_frame"     ]   } }

Header

Im folgenden Beispiel werden alle Cookies sowohl aus einem Hauptframe als auch aus allen untergeordneten Frames entfernt.

{   "id": 1,   "priority": 1,   "action": {     "type": "modifyHeaders",     "requestHeaders": [{ "header": "cookie", "operation": "remove" }]   },   "condition": { "resourceTypes": ["main_frame", "sub_frame"] } }

Typen

DomainType

Hier wird beschrieben, ob die Anfrage vom Erstanbieter oder vom Drittanbieter des Frames stammt, in dem sie gestellt wurde. Eine Anfrage gilt als Erstanbieteranfrage, wenn sie dieselbe Domain (eTLD+1) wie der Frame hat, in dem sie gestellt wurde.

Enum

„firstParty“
Die Netzwerkanfrage stammt von der Quelle des Frames, in dem sie ausgelöst wurde.

„thirdParty“
Die Netzwerkanfrage stammt von einem Drittanbieter im Frame, in dem sie generiert wurde.

ExtensionActionOptions

Chrome 88 und höher

Attribute

  • displayActionCountAsBadgeText

    boolean optional

    Gibt an, ob die Anzahl der Aktionen für eine Seite automatisch als Badge-Text der Erweiterung angezeigt werden soll. Diese Einstellung wird sitzungsübergreifend beibehalten.

  • tabUpdate

    TabActionCountUpdate optional

    Chrome 89 und höher

    Details dazu, wie die Anzahl der Aktionen auf dem Tab angepasst werden soll.

GetDisabledRuleIdsOptions

Chrome 111 und höher

Attribute

  • rulesetId

    String

    Die ID, die einem statischen Ruleset entspricht.

GetRulesFilter

Chrome 111 und höher

Attribute

  • ruleIds

    number[] optional

    Falls angegeben, werden nur Regeln mit übereinstimmenden IDs berücksichtigt.

HeaderInfo

Chrome 128 und höher

Attribute

  • excludedValues

    string[] optional

    Wenn diese Bedingung angegeben ist, wird sie nicht erfüllt, wenn der Header vorhanden ist, sein Wert aber mindestens ein Element in dieser Liste enthält. Dabei wird dieselbe Syntax für das Abgleichsmuster wie für values verwendet.

  • Header

    String

    Der Name des Headers. Diese Bedingung wird nur für den Namen abgeglichen, wenn weder values noch excludedValues angegeben sind.

  • Werte

    string[] optional

    Wenn diese Bedingung angegeben ist, wird sie erfüllt, wenn der Wert des Headers mit mindestens einem Muster in dieser Liste übereinstimmt. Dies unterstützt den Abgleich von Headerwerten ohne Berücksichtigung der Groß- und Kleinschreibung sowie die folgenden Konstrukte:

    „*“ : Entspricht einer beliebigen Anzahl von Zeichen.

    ? : Entspricht null oder einem Zeichen.

    „*“ und „?“ können mit einem Backslash maskiert werden, z. B. „\*“ und „\?“.

HeaderOperation

Chrome 86 und höher

Hier werden die möglichen Vorgänge für eine „modifyHeaders“-Regel beschrieben.

Enum

append
Fügt einen neuen Eintrag für den angegebenen Header hinzu. Dieser Vorgang wird für Anfrageheader nicht unterstützt.

„set“
Legt einen neuen Wert für den angegebenen Header fest und entfernt alle vorhandenen Header mit demselben Namen.

remove
Entfernt alle Einträge für den angegebenen Header.

IsRegexSupportedResult

Chrome 87 und höher

Attribute

  • isSupported

    boolean

  • reason

    UnsupportedRegexReason optional

    Gibt den Grund an, warum der reguläre Ausdruck nicht unterstützt wird. Wird nur angegeben, wenn isSupported „false“ ist.

MatchedRule

Attribute

  • ruleId

    Zahl

    Die ID einer Abgleichsregel.

  • rulesetId

    String

    ID der Ruleset, zu der diese Regel gehört. Bei einer Regel, die aus der Gruppe dynamischer Regeln stammt, entspricht dieser Wert DYNAMIC_RULESET_ID.

MatchedRuleInfo

Attribute

  • Regel

    MatchedRule

  • tabId

    Zahl

    Die „tabId“ des Tabs, von dem die Anfrage stammt, sofern der Tab noch aktiv ist. Sonstiges –1.

  • timeStamp

    Zahl

    Der Zeitpunkt, zu dem die Regel erfüllt wurde. Zeitstempel entsprechen der JavaScript-Konvention für Zeiten, d.h. der Anzahl der Millisekunden seit der Epoche.

MatchedRuleInfoDebug

Attribute

MatchedRulesFilter

Attribute

  • minTimeStamp

    number optional

    Falls angegeben, werden nur Regeln berücksichtigt, die nach dem angegebenen Zeitstempel übereinstimmen.

  • tabId

    number optional

    Wenn angegeben, werden nur Regeln für den angegebenen Tab berücksichtigt. Entspricht Regeln, die keinem aktiven Tab zugeordnet sind, wenn der Wert auf -1 festgelegt ist.

ModifyHeaderInfo

Chrome 86 und höher

Attribute

  • Header

    String

    Der Name des Headers, der geändert werden soll.

  • Vorgang

    HeaderOperation

    Der Vorgang, der für einen Header ausgeführt werden soll.

  • Wert

    String optional

    Der neue Wert für den Header. Muss für append- und set-Vorgänge angegeben werden.

QueryKeyValue

Attribute

  • Schlüssel

    String

  • replaceOnly

    boolean optional

    Chrome 94 und höher

    Wenn „true“, wird der Abfrageschlüssel nur ersetzt, wenn er bereits vorhanden ist. Andernfalls wird der Schlüssel auch hinzugefügt, wenn er fehlt. Die Standardeinstellung ist "false".

  • Wert

    String

QueryTransform

Attribute

  • addOrReplaceParams

    QueryKeyValue[] optional

    Die Liste der Schlüssel/Wert-Paare für die Abfrage, die hinzugefügt oder ersetzt werden sollen.

  • removeParams

    string[] optional

    Die Liste der zu entfernenden Abfrageschlüssel.

Redirect

Attribute

  • extensionPath

    String optional

    Pfad relativ zum Erweiterungsverzeichnis. Muss mit „/“ beginnen.

  • regexSubstitution

    String optional

    Ersetzungsmuster für Regeln, in denen ein regexFilter angegeben ist. Die erste Übereinstimmung von regexFilter in der URL wird durch dieses Muster ersetzt. Innerhalb von regexSubstitution können Escape-Ziffern mit Backslash (\1 bis \9) verwendet werden, um die entsprechenden Erfassungsgruppen einzufügen. \0 bezieht sich auf den gesamten übereinstimmenden Text.

  • Transformation

    URLTransform optional

    URL-Transformationen, die ausgeführt werden sollen.

  • URL

    String optional

    Die Weiterleitungs-URL. Weiterleitungen zu JavaScript-URLs sind nicht zulässig.

RegexOptions

Chrome 87 und höher

Attribute

  • isCaseSensitive

    boolean optional

    Gibt an, ob bei der angegebenen regex zwischen Groß- und Kleinschreibung unterschieden wird. Standardwert ist True.

  • regex

    String

    Der zu prüfende reguläre Ausdruck.

  • requireCapturing

    boolean optional

    Gibt an, ob die angegebene regex erfasst werden muss. Die Erfassung ist nur für Weiterleitungsregeln erforderlich, in denen eine regexSubstition-Aktion angegeben ist. Der Standardwert ist "false".

RequestDetails

Attribute

  • documentId

    String optional

    Chrome 106 und höher

    Die eindeutige Kennung für das Dokument des Frames, wenn sich diese Anfrage auf einen Frame bezieht.

  • documentLifecycle

    DocumentLifecycle optional

    Chrome 106 und höher

    Der Lebenszyklus des Dokuments des Frames, wenn es sich bei dieser Anfrage um einen Frame handelt.

  • frameId

    Zahl

    Der Wert 0 gibt an, dass die Anfrage im Hauptframe erfolgt. Ein positiver Wert gibt die ID eines Unterframes an, in dem die Anfrage erfolgt. Wenn das Dokument eines (Unter-)Frames geladen wird (type ist main_frame oder sub_frame), gibt frameId die ID dieses Frames an, nicht die ID des äußeren Frames. Frame-IDs sind innerhalb eines Tabs eindeutig.

  • frameType

    FrameType optional

    Chrome 106 und höher

    Der Typ des Frames, wenn es sich bei dieser Anfrage um einen Frame handelt.

  • Initiator

    String optional

    Der Ursprung, von dem die Anfrage initiiert wurde. Das ändert sich auch durch Weiterleitungen nicht. Wenn es sich um einen undurchsichtigen Ursprung handelt, wird der String „null“ verwendet.

  • method

    String

    Standard-HTTP-Methode.

  • parentDocumentId

    String optional

    Chrome 106 und höher

    Die eindeutige Kennung für das übergeordnete Dokument des Frames, wenn diese Anfrage für einen Frame gilt und ein übergeordnetes Element vorhanden ist.

  • parentFrameId

    Zahl

    ID des Frames, der den Frame umschließt, der die Anfrage gesendet hat. Wird auf -1 gesetzt, wenn kein übergeordneter Frame vorhanden ist.

  • requestId

    String

    Die ID der Anfrage. Anfrage-IDs sind innerhalb einer Browsersitzung eindeutig.

  • tabId

    Zahl

    Die ID des Tabs, auf dem die Anfrage erfolgt. Auf -1 gesetzt, wenn die Anfrage nicht mit einem Tab zusammenhängt.

  • Der Ressourcentyp der Anfrage.

  • URL

    String

    Die URL der Anfrage.

RequestMethod

Chrome 91 und höher

Dies beschreibt die HTTP-Anfragemethode einer Netzwerkanfrage.

Enum

„connect“

„delete“

"get"

"head"

"options"

"patch"

"post"

"put"

"other"

ResourceType

Hier wird der Ressourcentyp der Netzwerkanfrage beschrieben.

Enum

"main_frame"

"sub_frame"

"stylesheet"

"script"

"image"

"font"

„object“

"xmlhttprequest"

„ping“

"csp_report"

"media"

"websocket"

"webtransport"

"webbundle"

"other"

Rule

Attribute

  • Aktion

    RuleAction

    Die Aktion, die ausgeführt werden soll, wenn diese Regel erfüllt wird.

  • Bedingung

    RuleCondition

    Die Bedingung, unter der diese Regel ausgelöst wird.

  • id

    Zahl

    Eine ID, die eine Regel eindeutig identifiziert. Obligatorisch und sollte >= 1 sein.

  • priorität

    number optional

    Regelpriorität. Der Standardfaktor ist 1. Wenn angegeben, muss der Wert >= 1 sein.

RuleAction

Attribute

  • weiterleiten

    Weiterleitung optional

    Beschreibt, wie die Weiterleitung erfolgen soll. Nur für Weiterleitungsregeln gültig.

  • requestHeaders

    ModifyHeaderInfo[] optional

    Chrome 86 und höher

    Die Anfrage-Header, die für die Anfrage geändert werden sollen. Nur gültig, wenn RuleActionType „modifyHeaders“ ist.

  • responseHeaders

    ModifyHeaderInfo[] optional

    Chrome 86 und höher

    Die Antwortheader, die für die Anfrage geändert werden sollen. Nur gültig, wenn RuleActionType „modifyHeaders“ ist.

  • Der auszuführende Aktionstyp.

RuleActionType

Beschreibt die Art der Aktion, die ausgeführt werden soll, wenn eine bestimmte RuleCondition übereinstimmt.

Enum

block
Netzwerkanfrage blockieren

„redirect“
Die Netzwerkanfrage wird weitergeleitet.

„allow“
Die Netzwerkanfrage wird zugelassen. Die Anfrage wird nicht abgefangen, wenn es eine Zulassungsregel gibt, die mit ihr übereinstimmt.

"upgradeScheme"
Das Schema der URL für Netzwerkanfragen wird auf „https“ aktualisiert, wenn die Anfrage „http“ oder „ftp“ ist.

„modifyHeaders“
Anfrage-/Antwortheader aus der Netzwerkanfrage ändern.

allowAllRequests
Alle Anfragen innerhalb einer Frame-Hierarchie zulassen, einschließlich der Frame-Anfrage selbst.

RuleCondition

Attribute

  • domainType

    DomainType optional

    Gibt an, ob die Netzwerkanfrage von der Domain stammt, von der sie gesendet wurde, oder von einem Drittanbieter. Wird diese Option nicht angegeben, werden alle Anfragen akzeptiert.

  • Domains

    string[] optional

    Seit Chrome 101 eingestellt

    Verwenden Sie stattdessen initiatorDomains.

    Die Regel stimmt nur mit Netzwerkanfragen überein, die aus der Liste der domains stammen.

  • excludedDomains

    string[] optional

    Seit Chrome 101 eingestellt

    Verwenden Sie stattdessen excludedInitiatorDomains.

    Die Regel stimmt nicht mit Netzwerkanfragen überein, die aus der Liste der excludedDomains stammen.

  • excludedInitiatorDomains

    string[] optional

    Chrome 101 und höher

    Die Regel stimmt nicht mit Netzwerkanfragen überein, die aus der Liste der excludedInitiatorDomains stammen. Wenn die Liste leer ist oder weggelassen wird, werden keine Domains ausgeschlossen. Dies hat Vorrang vor initiatorDomains.

    Hinweise:

    • Subdomains wie „a.beispiel.de“ sind ebenfalls zulässig.
    • Die Einträge dürfen nur aus ASCII-Zeichen bestehen.
    • Verwenden Sie die Punycode-Codierung für internationalisierte Domains.
    • Dies entspricht dem Initiator der Anfrage und nicht der Anfrage-URL.
    • Subdomains der aufgeführten Domains sind ebenfalls ausgeschlossen.
  • excludedRequestDomains

    string[] optional

    Chrome 101 und höher

    Die Regel stimmt nicht mit Netzwerkanfragen überein, wenn die Domain mit einer Domain aus der Liste von excludedRequestDomains übereinstimmt. Wenn die Liste leer ist oder weggelassen wird, werden keine Domains ausgeschlossen. Dies hat Vorrang vor requestDomains.

    Hinweise:

    • Subdomains wie „a.beispiel.de“ sind ebenfalls zulässig.
    • Die Einträge dürfen nur aus ASCII-Zeichen bestehen.
    • Verwenden Sie die Punycode-Codierung für internationalisierte Domains.
    • Subdomains der aufgeführten Domains sind ebenfalls ausgeschlossen.
  • excludedRequestMethods

    RequestMethod[] optional

    Chrome 91 und höher

    Liste der Anfragemethoden, die nicht mit der Regel übereinstimmen. Es sollte nur eines von requestMethods und excludedRequestMethods angegeben werden. Wenn keines der beiden angegeben ist, werden alle Anfragemethoden abgeglichen.

  • excludedResourceTypes

    ResourceType[] optional

    Liste der Ressourcentypen, die nicht mit der Regel übereinstimmen. Es sollte nur eines von resourceTypes und excludedResourceTypes angegeben werden. Wenn keiner der beiden angegeben ist, werden alle Ressourcentypen außer „main_frame“ blockiert.

  • excludedResponseHeaders

    HeaderInfo[] optional

    Chrome 128 und höher

    Die Regel stimmt nicht überein, wenn die Anfrage einer Antwortheader-Bedingung in dieser Liste entspricht (falls angegeben). Wenn sowohl excludedResponseHeaders als auch responseHeaders angegeben sind, hat das Attribut excludedResponseHeaders Vorrang.

  • excludedTabIds

    number[] optional

    Chrome 92 und höher

    Liste der tabs.Tab.id, mit denen die Regel nicht übereinstimmen soll. Mit der ID tabs.TAB_ID_NONE werden Anfragen ausgeschlossen, die nicht von einem Tab stammen. Wird nur für regelspezifische Regeln unterstützt.

  • initiatorDomains

    string[] optional

    Chrome 101 und höher

    Die Regel stimmt nur mit Netzwerkanfragen überein, die aus der Liste der initiatorDomains stammen. Wenn die Liste nicht angegeben ist, wird die Regel auf Anfragen von allen Domains angewendet. Eine leere Liste ist nicht zulässig.

    Hinweise:

    • Subdomains wie „a.beispiel.de“ sind ebenfalls zulässig.
    • Die Einträge dürfen nur aus ASCII-Zeichen bestehen.
    • Verwenden Sie die Punycode-Codierung für internationalisierte Domains.
    • Dies entspricht dem Initiator der Anfrage und nicht der Anfrage-URL.
    • Subdomains der aufgeführten Domains werden ebenfalls berücksichtigt.
  • isUrlFilterCaseSensitive

    boolean optional

    Gibt an, ob bei urlFilter oder regexFilter (je nachdem, was angegeben ist) zwischen Groß- und Kleinschreibung unterschieden wird. Der Standardwert ist "false".

  • regexFilter

    String optional

    Regulärer Ausdruck, der mit der URL der Netzwerkanfrage abgeglichen werden soll. Dabei wird die RE2-Syntax verwendet.

    Hinweis: Es kann nur entweder urlFilter oder regexFilter angegeben werden.

    Hinweis: regexFilter darf nur aus ASCII-Zeichen bestehen. Sie wird mit einer URL abgeglichen, bei der der Host (im Fall internationalisierter Domains) im Punycode-Format codiert ist und alle anderen Nicht-ASCII-Zeichen als UTF-8-URL codiert sind.

  • requestDomains

    string[] optional

    Chrome 101 und höher

    Die Regel stimmt nur mit Netzwerkanfragen überein, wenn die Domain mit einer Domain aus der Liste requestDomains übereinstimmt. Wenn die Liste nicht angegeben ist, wird die Regel auf Anfragen von allen Domains angewendet. Eine leere Liste ist nicht zulässig.

    Hinweise:

    • Subdomains wie „a.beispiel.de“ sind ebenfalls zulässig.
    • Die Einträge dürfen nur aus ASCII-Zeichen bestehen.
    • Verwenden Sie die Punycode-Codierung für internationalisierte Domains.
    • Subdomains der aufgeführten Domains werden ebenfalls berücksichtigt.
  • requestMethods

    RequestMethod[] optional

    Chrome 91 und höher

    Liste der HTTP-Anfragemethoden, die mit der Regel übereinstimmen können. Eine leere Liste ist nicht zulässig.

    Hinweis: Wenn Sie eine requestMethods-Regelbedingung angeben, werden auch Nicht-HTTP(s)-Anfragen ausgeschlossen. Wenn Sie excludedRequestMethods angeben, ist das nicht der Fall.

  • resourceTypes

    ResourceType[] optional

    Liste der Ressourcentypen, die mit der Regel übereinstimmen können. Eine leere Liste ist nicht zulässig.

    Hinweis: Dies muss für allowAllRequests-Regeln angegeben werden und darf nur die Ressourcentypen sub_frame und main_frame enthalten.

  • responseHeaders

    HeaderInfo[] optional

    Chrome 128 und höher

    Die Regel stimmt überein, wenn die Anfrage mit einer der Antwortheader-Bedingungen in dieser Liste übereinstimmt (falls angegeben).

  • tabIds

    number[] optional

    Chrome 92 und höher

    Liste der tabs.Tab.id, mit denen die Regel übereinstimmen soll. Eine ID von tabs.TAB_ID_NONE entspricht Anfragen, die nicht von einem Tab stammen. Eine leere Liste ist nicht zulässig. Wird nur für regelspezifische Regeln unterstützt.

  • urlFilter

    String optional

    Das Muster, das mit der URL der Netzwerkanfrage abgeglichen wird. Unterstützte Konstrukte:

    „*“: Platzhalter, der einer beliebigen Anzahl von Zeichen entspricht.

    | : Anker links/rechts: Wenn dieses Zeichen an einem der beiden Enden des Musters verwendet wird, gibt es den Anfang bzw. das Ende der URL an.

    '||' : Anker für Domainname: Wenn am Anfang des Musters verwendet, gibt er den Beginn einer (Unter-)Domain der URL an.

    ^ : Trennzeichen: Entspricht allem außer einem Buchstaben, einer Ziffer oder einem der folgenden Zeichen: _, -, . oder %. Das Muster muss auch mit dem Ende der URL übereinstimmen.

    urlFilter besteht daher aus den folgenden Teilen: (optionaler linker Anker/Domainname) + Muster + (optionaler rechter Anker).

    Wenn das Feld leer ist, werden alle URLs abgeglichen. Ein leerer String ist nicht zulässig.

    Ein Muster, das mit ||* beginnt, ist nicht zulässig. Verwenden Sie stattdessen *.

    Hinweis: Es kann nur entweder urlFilter oder regexFilter angegeben werden.

    Hinweis: urlFilter darf nur aus ASCII-Zeichen bestehen. Sie wird mit einer URL abgeglichen, bei der der Host (im Fall internationalisierter Domains) im Punycode-Format codiert ist und alle anderen Nicht-ASCII-Zeichen als UTF-8-URL codiert sind. Wenn die Anfrage-URL beispielsweise http://abc.рф?q=ф lautet, wird urlFilter mit der URL http://abc.xn--p1ai/?q=%D1%84 abgeglichen.

Ruleset

Attribute

  • aktiviert

    boolean

    Gibt an, ob das Regelset standardmäßig aktiviert ist.

  • id

    String

    Ein nicht leerer String, der das Regelset eindeutig identifiziert. IDs, die mit „_“ beginnen, sind für die interne Verwendung reserviert.

  • Pfad

    String

    Der Pfad des JSON-Regelsatzes relativ zum Erweiterungsverzeichnis.

RulesMatchedDetails

Attribute

  • rulesMatchedInfo

    MatchedRuleInfo[]

    Regeln, die dem angegebenen Filter entsprechen.

TabActionCountUpdate

Chrome 89 und höher

Attribute

  • increment

    Zahl

    Der Betrag, um den die Anzahl der Aktionen des Tabs erhöht werden soll. Bei negativen Werten wird die Anzahl verringert.

  • tabId

    Zahl

    Der Tab, für den die Anzahl der Aktionen aktualisiert werden soll.

TestMatchOutcomeResult

Chrome 103 und höher

Attribute

  • matchedRules

    MatchedRule[]

    Die Regeln (falls vorhanden), die der hypothetischen Anfrage entsprechen.

TestMatchRequestDetails

Chrome 103 und höher

Attribute

  • Initiator

    String optional

    Die Initiator-URL (falls vorhanden) für die hypothetische Anfrage.

  • method

    RequestMethod optional

    Standard-HTTP-Methode der hypothetischen Anfrage. Standardmäßig wird „get“ für HTTP-Anfragen verwendet. Für Nicht-HTTP-Anfragen wird dieser Parameter ignoriert.

  • responseHeaders

    object optional

    Chrome 129 und höher

    Die Header, die in einer hypothetischen Antwort enthalten wären, wenn die Anfrage nicht blockiert oder umgeleitet wird, bevor sie gesendet wird. Wird als Objekt dargestellt, das einen Headernamen einer Liste von Stringwerten zuordnet. Wenn nichts angegeben ist, werden bei der hypothetischen Antwort leere Antwortheader zurückgegeben, die mit Regeln übereinstimmen können, die auf das Nichtvorhandensein von Headern abgestimmt sind. Z. B. {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}

  • tabId

    number optional

    Die ID des Tabs, auf dem die hypothetische Anfrage erfolgt. Muss nicht einer echten Tab-ID entsprechen. Der Standardwert ist -1. Das bedeutet, dass die Anfrage nicht mit einem Tab verknüpft ist.

  • Der Ressourcentyp der hypothetischen Anfrage.

  • URL

    String

    Die URL der hypothetischen Anfrage.

UnsupportedRegexReason

Chrome 87 und höher

Beschreibt den Grund, warum ein bestimmter regulärer Ausdruck nicht unterstützt wird.

Enum

"syntaxError"
Der reguläre Ausdruck ist syntaktisch falsch oder verwendet Funktionen, die in der RE2-Syntax nicht verfügbar sind.

"memoryLimitExceeded"
Der reguläre Ausdruck überschreitet das Speicherlimit.

UpdateRuleOptions

Chrome 87 und höher

Attribute

  • addRules

    Rule[] optional

    Regeln, die hinzugefügt werden sollen.

  • removeRuleIds

    number[] optional

    IDs der zu entfernenden Regeln. Ungültige IDs werden ignoriert.

UpdateRulesetOptions

Chrome 87 und höher

Attribute

  • disableRulesetIds

    string[] optional

    Die Menge der IDs, die einem statischen Ruleset entsprechen und deaktiviert werden sollen.

  • enableRulesetIds

    string[] optional

    Die Menge der IDs, die einem statischen Ruleset entsprechen und aktiviert werden sollen.

UpdateStaticRulesOptions

Chrome 111 und höher

Attribute

  • disableRuleIds

    number[] optional

    Eine Reihe von IDs, die den zu deaktivierenden Regeln in Ruleset entsprechen.

  • enableRuleIds

    number[] optional

    Eine Reihe von IDs, die den Regeln in Ruleset entsprechen, die aktiviert werden sollen.

  • rulesetId

    String

    Die ID, die einem statischen Ruleset entspricht.

URLTransform

Attribute

  • Fragment

    String optional

    Das neue Fragment für die Anfrage. Sollte entweder leer sein, in diesem Fall wird das vorhandene Fragment gelöscht, oder mit „#“ beginnen.

  • Host

    String optional

    Der neue Host für die Anfrage.

  • Passwort

    String optional

    Das neue Passwort für die Anfrage.

  • Pfad

    String optional

    Der neue Pfad für die Anfrage. Wenn das Feld leer ist, wird der vorhandene Pfad gelöscht.

  • Port

    String optional

    Der neue Port für die Anfrage. Wenn das Feld leer ist, wird der vorhandene Port gelöscht.

  • Abfrage

    String optional

    Die neue Abfrage für die Anfrage. Muss entweder leer sein (in diesem Fall wird die vorhandene Abfrage gelöscht) oder mit „?“ beginnen.

  • queryTransform

    QueryTransform optional

    Schlüssel/Wert-Paare für Abfragen hinzufügen, entfernen oder ersetzen

  • Schema

    String optional

    Das neue Schema für die Anfrage. Zulässige Werte sind „http“, „https“, „ftp“ und „chrome-extension“.

  • Nutzername

    String optional

    Der neue Nutzername für die Anfrage.

Attribute

DYNAMIC_RULESET_ID

Die ID des Regelsatzes für die dynamischen Regeln, die von der Erweiterung hinzugefügt werden.

Wert

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

Das Zeitintervall, innerhalb dessen MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules-Aufrufe erfolgen können, angegeben in Minuten. Zusätzliche Aufrufe schlagen sofort fehl und runtime.lastError wird festgelegt. Hinweis: getMatchedRules-Aufrufe, die mit einer Nutzeraktion verknüpft sind, sind vom Kontingent ausgenommen.

Wert

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89 und höher

Die Mindestanzahl statischer Regeln, die einer Erweiterung in allen aktivierten statischen Regelsätzen garantiert werden. Alle Regeln über diesem Limit werden auf das globale Limit für statische Regeln angerechnet.

Wert

30.000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

Die Anzahl der Aufrufe von getMatchedRules innerhalb eines Zeitraums von GETMATCHEDRULES_QUOTA_INTERVAL.

Wert

20

MAX_NUMBER_OF_DYNAMIC_RULES

Die maximale Anzahl dynamischer Regeln, die eine Erweiterung hinzufügen kann.

Wert

30.000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94 und höher

Die maximale Anzahl statischer Rulesets, die eine Erweiterung gleichzeitig aktivieren kann.

Wert

50

MAX_NUMBER_OF_REGEX_RULES

Die maximale Anzahl von Regeln für reguläre Ausdrücke, die eine Erweiterung hinzufügen kann. Dieses Limit wird separat für die Gruppe dynamischer Regeln und die in der Datei mit Regelressourcen angegebenen Regeln ausgewertet.

Wert

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120 und höher

Die maximale Anzahl von regelspezifischen Regeln, die eine Erweiterung hinzufügen kann.

Wert

5.000

MAX_NUMBER_OF_STATIC_RULESETS

Die maximale Anzahl statischer Rulesets, die eine Erweiterung als Teil des Manifestschlüssels "rule_resources" angeben kann.

Wert

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120 und höher

Die maximale Anzahl von „unsicheren“ dynamischen Regeln, die eine Erweiterung hinzufügen kann.

Wert

5.000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120 und höher

Die maximale Anzahl von „unsicheren“ regelspezifischen Regeln, die eine Erweiterung hinzufügen kann.

Wert

5.000

SESSION_RULESET_ID

Chrome 90 und höher

Regelsatz-ID für die sitzungsbezogenen Regeln, die von der Erweiterung hinzugefügt wurden.

Wert

"_session"

Methoden

getAvailableStaticRuleCount()

Chrome 89 und höher 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(): Promise<number>

Gibt die Anzahl der statischen Regeln zurück, die eine Erweiterung aktivieren kann, bevor das globale Limit für statische Regeln erreicht wird.

Ausgabe

  • Promise<number>

    Chrome 91 und höher

getDisabledRuleIds()

Chrome 111 und höher 
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
): Promise<number[]>

Gibt die Liste der statischen Regeln in der angegebenen Ruleset zurück, die derzeit deaktiviert sind.

Parameter

Ausgabe

  • Promise<number[]>

getDynamicRules()

chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
): Promise<Rule[]>

Gibt die aktuelle Gruppe dynamischer Regeln für die Erweiterung zurück. Anrufer können die Liste der abgerufenen Regeln optional filtern, indem sie eine filter angeben.

Parameter

  • filtern

    GetRulesFilter optional

    Chrome 111 und höher

    Ein Objekt zum Filtern der Liste der abgerufenen Regeln.

Ausgabe

  • Promise<Rule[]>

    Chrome 91 und höher

getEnabledRulesets()

chrome.declarativeNetRequest.getEnabledRulesets(): Promise<string[]>

Gibt die IDs für die aktuelle Gruppe aktivierter statischer Regelsätze zurück.

Ausgabe

  • Promise<string[]>

    Chrome 91 und höher

getMatchedRules()

chrome.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
): Promise<RulesMatchedDetails>

Gibt alle Regeln zurück, die für die Erweiterung zutreffen. Anrufer können die Liste der übereinstimmenden Regeln optional filtern, indem sie ein filter angeben. Diese Methode ist nur für Erweiterungen mit der Berechtigung "declarativeNetRequestFeedback" oder der Berechtigung "activeTab" für die in filter angegebene tabId verfügbar. Hinweis: Regeln, die nicht mit einem aktiven Dokument verknüpft sind und vor mehr als fünf Minuten abgeglichen wurden, werden nicht zurückgegeben.

Parameter

  • filtern

    MatchedRulesFilter optional

    Ein Objekt zum Filtern der Liste der übereinstimmenden Regeln.

Ausgabe

getSessionRules()

Chrome 90 und höher 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
): Promise<Rule[]>

Gibt die aktuell festgelegten sitzungsbezogenen Regeln für die Erweiterung zurück. Anrufer können die Liste der abgerufenen Regeln optional filtern, indem sie eine filter angeben.

Parameter

  • filtern

    GetRulesFilter optional

    Chrome 111 und höher

    Ein Objekt zum Filtern der Liste der abgerufenen Regeln.

Ausgabe

  • Promise<Rule[]>

    Chrome 91 und höher

isRegexSupported()

Chrome 87 und höher 
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
): Promise<IsRegexSupportedResult>

Prüft, ob der angegebene reguläre Ausdruck als regexFilter-Regelbedingung unterstützt wird.

Parameter

  • regexOptions

    RegexOptions

    Der reguläre Ausdruck, der geprüft werden soll.

Ausgabe

setExtensionActionOptions()

Chrome 88 und höher 
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
): Promise<void>

Konfiguriert, ob die Anzahl der Aktionen für Tabs als Badge-Text der Erweiterungsaktion angezeigt werden soll, und bietet eine Möglichkeit, diese Anzahl zu erhöhen.

Parameter

Ausgabe

  • Promise<void>

    Chrome 91 und höher

testMatchOutcome()

Chrome 103 und höher 
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
): Promise<TestMatchOutcomeResult>

Prüft, ob eine der declarativeNetRequest-Regeln der Erweiterung mit einer hypothetischen Anfrage übereinstimmen würde. Hinweis: Nur für entpackte Erweiterungen verfügbar, da diese Funktion nur während der Entwicklung von Erweiterungen verwendet werden soll.

Parameter

Ausgabe

updateDynamicRules()

chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
): Promise<void>

Ändert die aktuellen dynamischen Regeln für die Erweiterung. Die Regeln mit den in options.removeRuleIds aufgeführten IDs werden zuerst entfernt und dann die in options.addRules angegebenen Regeln hinzugefügt. Hinweise:

  • Diese Aktualisierung erfolgt als einzelner atomarer Vorgang: Entweder werden alle angegebenen Regeln hinzugefügt und entfernt oder es wird ein Fehler zurückgegeben.
  • Diese Regeln bleiben über Browsersitzungen und Erweiterungsupdates hinweg erhalten.
  • Statische Regeln, die als Teil des Erweiterungspakets angegeben werden, können mit dieser Funktion nicht entfernt werden.
  • MAX_NUMBER_OF_DYNAMIC_RULES ist die maximale Anzahl dynamischer Regeln, die eine Erweiterung hinzufügen kann. Die Anzahl der unsicheren Regeln darf MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES nicht überschreiten.

Parameter

Ausgabe

  • Promise<void>

    Chrome 91 und höher

updateEnabledRulesets()

chrome.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
): Promise<void>

Aktualisiert die Menge der aktivierten statischen Regelsätze für die Erweiterung. Die Regelsätze mit den in options.disableRulesetIds aufgeführten IDs werden zuerst entfernt und dann die in options.enableRulesetIds aufgeführten Regelsätze hinzugefügt. Die aktivierten statischen Regelsätze werden sitzungsübergreifend, aber nicht über Erweiterungsupdates hinweg beibehalten. Das heißt, der Manifestschlüssel rule_resources bestimmt die aktivierten statischen Regelsätze bei jedem Erweiterungsupdate.

Parameter

Ausgabe

  • Promise<void>

    Chrome 91 und höher

updateSessionRules()

Chrome 90 und höher 
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
): Promise<void>

Ändert die aktuellen sitzungsbezogenen Regeln für die Erweiterung. Die Regeln mit den in options.removeRuleIds aufgeführten IDs werden zuerst entfernt und dann die in options.addRules angegebenen Regeln hinzugefügt. Hinweise:

  • Diese Aktualisierung erfolgt als einzelner atomarer Vorgang: Entweder werden alle angegebenen Regeln hinzugefügt und entfernt oder es wird ein Fehler zurückgegeben.
  • Diese Regeln werden nicht sitzungsübergreifend beibehalten und werden im Arbeitsspeicher gesichert.
  • MAX_NUMBER_OF_SESSION_RULES ist die maximale Anzahl von Sitzungsregeln, die eine Erweiterung hinzufügen kann.

Parameter

Ausgabe

  • Promise<void>

    Chrome 91 und höher

updateStaticRules()

Chrome 111 und höher 
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
): Promise<void>

Deaktiviert und aktiviert einzelne statische Regeln in einem Ruleset. Änderungen an Regeln, die zu einer deaktivierten Ruleset gehören, werden erst wirksam, wenn sie wieder aktiviert wird.

Parameter

Ausgabe

  • Promise<void>

Ereignisse

onRuleMatchedDebug

chrome.declarativeNetRequest.onRuleMatchedDebug.addListener(
  callback: function,
)

Wird ausgelöst, wenn eine Regel mit einer Anfrage übereinstimmt. Nur für entpackte Erweiterungen mit der Berechtigung "declarativeNetRequestFeedback" verfügbar, da sie nur für Debugging-Zwecke verwendet werden soll.

Parameter