chrome.declarativeNetRequest

refresh date: 2026-09-25 robots: noindex

Beschreibung

Die chrome.declarativeNetRequest API wird verwendet, um Netzwerkanfragen durch Angabe deklarativer Regeln zu blockieren oder zu ändern. So können Erweiterungen Netzwerkanfragen ändern, ohne sie abzufangen und ihren Inhalt einzusehen. Das sorgt für mehr Datenschutz.

Berechtigungen

declarativeNetRequest
declarativeNetRequestWithHostAccess

declarativeNetRequestFeedback
host_permissions

Verfügbarkeit

Chrome 84 oder höher

Manifest

Zusätzlich zu den oben beschriebenen Berechtigungen muss für bestimmte Arten von Regelsätzen, insbesondere statische Regelsätze, der Manifestschlüssel "declarative_net_request" deklariert werden. Dieser sollte ein Wörterbuch mit einem einzelnen Schlüssel namens "rule_resources" sein. Dieser Schlüssel ist ein Array, das Wörterbücher vom Typ Ruleset enthält, wie unten dargestellt. Der Name „Ruleset“ wird im JSON-Manifest nicht 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/*"
  ],
  ...
}

Konzepte und Verwendung

Geben Sie einen oder mehrere Regelsätze an, um diese API zu verwenden. Ein Regelsatz enthält ein Array von Regeln. Eine einzelne Regel führt eine der folgenden Aktionen aus:

  • Blockieren Sie eine Netzwerkanfrage.
  • Aktualisieren Sie das Schema (HTTP zu HTTPS).
  • Verhindern, dass eine Anfrage blockiert wird, indem alle übereinstimmenden Blockierungsregeln 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 Erweiterungsupgrades hinweg erhalten und werden mit JavaScript verwaltet, während eine Erweiterung verwendet wird.
Sitzung
Wird gelöscht, wenn der Browser geschlossen und 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.

In den nächsten Abschnitten werden die Regelset-Typen im Detail erläutert.

Dynamische und sitzungsbezogene Regelsätze

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

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

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

Statische Regelsätze

Im Gegensatz zu dynamischen und Sitzungsregeln werden statische Regeln beim Installieren oder Aktualisieren einer Erweiterung verpackt, installiert und aktualisiert. 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-Dictionaries mitgeteilt werden. Ein Ruleset-Wörterbuch enthält einen Pfad zur Regeldatei, eine ID für den in der Datei enthaltenen Regelsatz und gibt an, ob der Regelsatz aktiviert oder deaktiviert ist. Die letzten beiden sind wichtig, wenn Sie einen Regelsatz programmatisch aktivieren oder deaktivieren.

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

Wenn Sie Regeldateien testen möchten, 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.

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 Regeln verfügbar sind, die Sie in Ihren Regeldateien belassen haben.

Aus Leistungsgründen ist auch die Anzahl der Regeln und Regelsätze begrenzt, 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 Regellimits finden Sie unter Regellimits.

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 Dictionarys Ruleset definiert.

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

Build-Regeln

Unabhängig vom Typ beginnt eine Regel mit vier Feldern, wie unten dargestellt. Während die Schlüssel "id" und "priority" eine Zahl annehmen, können die Schlüssel "action" und "condition" mehrere Bedingungen für das Blockieren und Weiterleiten enthalten. Mit der folgenden Regel werden alle Skriptanfragen von "foo.com" an alle URLs mit "abc" als Teilstring blockiert.

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

urlFilter-Übereinstimmungszeichen

Der Schlüssel "condition" einer Regel ermöglicht einen Schlüssel "urlFilter", um auf URLs unter einer bestimmten Domain zu reagieren. Sie erstellen Muster mithilfe von 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://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

Regelpriorisierung

Regeln werden durch Anfragen ausgelöst, die von Webseiten gesendet werden. Wenn mehrere Regeln auf eine bestimmte Anfrage zutreffen, müssen die Regeln priorisiert werden. In diesem Abschnitt wird erläutert, wie sie priorisiert werden. Die Priorisierung erfolgt in zwei Phasen.

  1. Die Priorität wird für Regeln innerhalb einer Erweiterung festgelegt.
  2. Wenn mehrere Erweiterungen eine Regel auf eine Anfrage anwenden können, wird die Priorität für alle Erweiterungen bestimmt, die einer bestimmten Anfrage entsprechen.

Die Zuordnung erfolgt so: Die Regel, die von einer bestimmten Erweiterung priorisiert wird, wird dann gegenüber Regeln von anderen Erweiterungen priorisiert.

Regelpriorisierung innerhalb einer Erweiterung

Innerhalb einer einzelnen Erweiterung wird die Priorisierung so ermittelt:

  1. Die Regel mit der höchsten vom Entwickler definierten Priorität (also dem Feld "priority") wird zurückgegeben.

  2. Wenn es mehr als eine Regel mit der höchsten vom Entwickler definierten Priorität gibt, werden die Regeln anhand des Felds "action" in der folgenden Reihenfolge priorisiert:

    1. allow
    2. allowAllRequests
    3. block
    4. upgradeScheme
    5. redirect

  3. Wenn der Aktionstyp nicht block oder redirect ist, werden alle übereinstimmenden modifyHeaders-Regeln ausgewertet. Beachten Sie, dass Regeln mit einer vom Entwickler definierten Priorität, die niedriger als die für allow und allowAllRequests angegebene Priorität ist, ignoriert werden.

  4. Wenn mehrere Regeln denselben Header ändern, wird die Änderung durch das vom Entwickler definierte Feld "priority" und die angegebenen Vorgänge bestimmt.

    • Wenn eine Regel einen Header anhängt, können Regeln mit niedrigerer Priorität nur an diesen Header angehängt werden. Vorgänge zum Festlegen und Entfernen sind nicht zulässig.
    • Wenn eine Regel einen Header festlegt, können Regeln mit niedrigerer Priorität nur an diesen Header angehängt werden. Andere Änderungen sind nicht zulässig.
    • Wenn eine Regel einen Header entfernt, können Regeln mit niedrigerer Priorität den Header nicht weiter ändern.

Regelpriorisierung zwischen Erweiterungen

Wenn nur eine Erweiterung eine Regel hat, die mit einer Anfrage übereinstimmt, wird diese Regel angewendet. Wenn jedoch mehr als eine Erweiterung mit einer Anfrage übereinstimmt, wird der folgende Prozess verwendet:

  1. Regeln werden mithilfe des Felds "action" in der folgenden Reihenfolge priorisiert:

    1. block
    2. redirect oder upgradeScheme
    3. allow oder allowAllRequests

  2. Wenn mehrere Regeln übereinstimmen, hat die zuletzt installierte Erweiterung Priorität.

Limits für Regeln

Das Laden und Auswerten von Regeln im Browser verursacht einen Leistungsaufwand. Daher gelten bei der Verwendung der API einige Einschränkungen. Die Limits hängen vom Typ der verwendeten Regel ab.

Statische Regeln

Statische Regeln sind in Regeldateien angegeben, die in der Manifestdatei deklariert sind. Eine Erweiterung kann im Manifestschlüssel "rule_resources" bis zu 50 statische Regelsätze angeben. Es können jedoch nur 10 dieser Regelsätze gleichzeitig aktiviert sein. Letzteres wird als MAX_NUMBER_OF_ENABLED_STATIC_RULESETS bezeichnet. Insgesamt sind für diese Regelsätze mindestens 30.000 Regeln garantiert. Dieser wird als GUARANTEED_MINIMUM_STATIC_RULES bezeichnet.

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

Dynamische und sitzungsbezogene Regeln

Die für dynamische und Sitzungsregeln geltenden Limits sind einfacher als die für statische Regeln. Die Gesamtzahl beider darf 5.000 nicht überschreiten. Dieser wird als MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES bezeichnet.

Regeln, die Regex verwenden

Für alle Arten von Regeln können reguläre Ausdrücke verwendet werden. Die Gesamtzahl der Regex-Regeln pro Typ darf jedoch 1.000 nicht überschreiten. Dies wird als MAX_NUMBER_OF_REGEX_RULES bezeichnet.

Außerdem muss jede Regel nach der Kompilierung kleiner als 2 KB sein. Dies entspricht in etwa der Komplexität der Regel. 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 Netzwerkstack erreichen. Dazu gehören Antworten aus dem HTTP-Cache, aber möglicherweise keine Antworten, die über den onfetch-Handler eines Service Workers laufen. „declarativeNetRequest“ hat keine Auswirkungen auf Antworten, die vom Service Worker generiert oder aus CacheStorage abgerufen werden, aber auf Aufrufe von fetch() in einem Service Worker.

Über das Web zugängliche Ressourcen

Eine declarativeNetRequest-Regel kann nicht von einer öffentlichen Ressourcenanfrage zu einer Ressource weiterleiten, die nicht über das Web zugänglich ist. Andernfalls wird ein Fehler ausgelöst. Das gilt auch dann, wenn die angegebene über das Web zugängliche Ressource der weiterleitenden Erweiterung gehört. Verwenden Sie das Array "web_accessible_resources" des Manifests, um Ressourcen für declarativeNetRequest zu deklarieren.

Beispiele

Codebeispiele

Dynamische Regeln aktualisieren

Das folgende Beispiel zeigt, wie updateDynamicRules() aufgerufen wird. Das Verfahren für updateSessionRules() ist dasselbe.

// 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, wobei die Anzahl der verfügbaren und die maximale Anzahl der aktivierten statischen Regelsätze berücksichtigt werden. Das ist sinnvoll, wenn die Anzahl der benötigten statischen Regeln die zulässige Anzahl überschreitet. Damit dies funktioniert, müssen einige Ihrer Regelsätze installiert sein, während andere deaktiviert sind. Dazu müssen Sie in der Manifestdatei "Enabled" auf false setzen.

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 zeigen, wie Chrome Regeln in einer Erweiterung priorisiert. Wenn Sie sie prü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) Schlüssel "priority", den Schlüssel "action" und den Schlüssel "urlFilter" an. Diese Beispiele beziehen sich auf die darunter gezeigte Beispielregeldatei.

Navigation zu https://google.com
Zwei Regeln gelten für diese URL: 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 gelten.
Navigation zu https://google.com/1234
Aufgrund der längeren URL stimmt die Regel mit der ID 2 jetzt zusätzlich zu den Regeln mit den IDs 1 und 4 überein. Die Regel mit der ID 2 gilt, weil "allow" eine höhere Priorität als "block" und "redirect" hat.
Navigation zu https://google.com/12345
Alle vier Regeln stimmen mit dieser URL überein. Die Regel mit der ID 3 wird angewendet, weil 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.

Im folgenden Beispiel wird gezeigt, wie eine Anfrage von example.com an eine Seite innerhalb der Erweiterung weitergeleitet wird. Der Erweiterungspfad /a.jpg wird zu chrome-extension://EXTENSION_ID/a.jpg aufgelöst, wobei EXTENSION_ID die ID Ihrer Erweiterung ist. Damit das funktioniert, muss im Manifest /a.jpg als über das Web zugä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 Beispiel wird der Schlüssel "transform" verwendet, um zu einer Subdomain von example.com weiterzuleiten. Es wird ein Domainnamenanker („||“) verwendet, um Anfragen mit einem beliebigen Schema von example.com abzufangen. Der Schlüssel "scheme" in "transform" gibt an, dass Weiterleitungen zur Subdomain immer „https“ verwenden.

{
  "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. Der Schlüssel "regexSubstitution" gibt die erste zurückgegebene Übereinstimmung des regulären Ausdrucks mit „\1“ an. 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 Unterframes 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 Drittanbieter des Frames stammt, in dem sie erstellt wurde. Eine Anfrage gilt als Erstanbieteranfrage, wenn sie dieselbe Domain (eTLD+1) hat wie der Frame, von dem die Anfrage stammt.

Enum

"firstParty"
Die Netzwerkanfrage ist eine eigene Anfrage für den Frame, in dem sie erstellt wurde.

"thirdParty"
Die Netzwerkanfrage stammt von einem Drittanbieter für den Frame, in dem sie erstellt wurde.

ExtensionActionOptions

Chrome 88 oder höher

Attribute

  • displayActionCountAsBadgeText

    Boolesch optional

    Gibt an, ob die Anzahl der Aktionen für eine Seite automatisch als Badge-Text der Erweiterung angezeigt werden soll. Diese Einstellung bleibt über Sitzungen hinweg erhalten.

  • tabUpdate

    TabActionCountUpdate optional

    Chrome 89 oder höher

    Details dazu, wie die Anzahl der Aktionen des Tabs angepasst werden soll.

GetDisabledRuleIdsOptions

Chrome 111+

Attribute

  • rulesetId

    String

    Die ID, die einem statischen Ruleset entspricht.

GetRulesFilter

Chrome 111+

Attribute

  • ruleIds

    number[] optional

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

HeaderInfo

Chrome 128 oder höher

Attribute

  • excludedValues

    string[] optional

    Wenn angegeben, wird diese Bedingung 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 Übereinstimmungsmuster wie für values verwendet.

  • Header

    String

    Der Name des Headers. Diese Bedingung stimmt nur dann mit dem Namen überein, wenn weder values noch excludedValues angegeben ist.

  • Werte

    string[] optional

    Wenn angegeben, ist diese Bedingung 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ß-/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 oder 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. Wenn Sie die Header einer Anfrage ändern, wird dieser Vorgang nur für bestimmte Header 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 oder 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 übereinstimmenden Regel.

  • rulesetId

    String

    ID des Ruleset, zu dem diese Regel gehört. Bei einer Regel, die aus den dynamischen Regeln stammt, entspricht dies DYNAMIC_RULESET_ID.

MatchedRuleInfo

Attribute

  • Regel

    MatchedRule

  • tabId

    Zahl

    Die „tabId“ des Tabs, von dem die Anfrage stammt, wenn der Tab noch aktiv ist. Andernfalls -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

    Wenn angegeben, werden nur Regeln nach dem angegebenen Zeitstempel abgeglichen.

  • tabId

    number optional

    Wenn angegeben, werden nur Regeln für den angegebenen Tab abgeglichen. Wenn der Wert auf „-1“ festgelegt ist, werden Regeln abgeglichen, die keinem aktiven Tab zugeordnet sind.

ModifyHeaderInfo

Chrome 86 oder 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

    Boolesch optional

    Chrome 94 oder 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 Abfrage-Schlüssel/Wert-Paare, 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, die ein regexFilter angeben. Die erste Übereinstimmung von regexFilter in der URL wird durch dieses Muster ersetzt. Innerhalb von regexSubstitution können mit Backslash maskierte Ziffern (\1 bis \9) verwendet werden, um die entsprechenden Erfassungsgruppen einzufügen. \0 bezieht sich auf den gesamten übereinstimmenden Text.

  • Transformation

    URLTransform optional

    Auszuführende URL-Transformationen.

  • URL

    String optional

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

RegexOptions

Chrome 87 oder höher

Attribute

  • isCaseSensitive

    Boolesch optional

    Gibt an, ob bei der angegebenen regex die Groß-/Kleinschreibung beachtet wird. Standardwert ist True.

  • regex

    String

    Der zu prüfende reguläre Ausdruck.

  • requireCapturing

    Boolesch optional

    Gibt an, ob die angegebene regex erfasst werden muss. Das Erfassen ist nur für Weiterleitungsregeln erforderlich, die eine regexSubstition-Aktion angeben. Der Standardwert ist "false".

RequestDetails

Attribute

  • documentId

    String optional

    Chrome 106 oder höher

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

  • documentLifecycle

    DocumentLifecycle optional

    Chrome 106 oder höher

    Der Lebenszyklus des Dokuments des Frames, wenn diese Anfrage für einen Frame gilt.

  • 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 oder höher

    Der Typ des Frames, wenn diese Anfrage für einen Frame gilt.

  • initiator

    String optional

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

  • method

    String

    Standard-HTTP-Methode.

  • parentDocumentId

    String optional

    Chrome 106 oder höher

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

  • parentFrameId

    Zahl

    ID des Frames, der den Frame umschließt, von dem die Anfrage gesendet wurde. 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, in dem die Anfrage erfolgt. Wird 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 oder höher

Dies beschreibt die HTTP-Anfragemethode einer Netzwerkanfrage.

Enum

"connect"

"delete"

"get"

"head"

"options"

"patch"

"post"

"put"

"other"

ResourceType

Dies beschreibt den Ressourcentyp der Netzwerkanfrage.

Enum

"main_frame"

"sub_frame"

"stylesheet"

"script"

"image"

"font"

"object"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"webtransport"

"webbundle"

"other"

Rule

Attribute

  • Aktion

    RuleAction

    Die auszuführende Aktion, wenn diese Regel übereinstimmt.

  • Bedingung

    RuleCondition

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

  • id

    Zahl

    Eine ID, die eine Regel eindeutig identifiziert. Erforderlich und muss >= 1 sein.

  • priority

    number optional

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

RuleAction

Attribute

  • weiterleiten

    Redirect optional

    Beschreibt, wie die Weiterleitung ausgeführt werden soll. Nur für Weiterleitungsregeln gültig.

  • requestHeaders

    ModifyHeaderInfo[] optional

    Chrome 86 oder höher

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

  • responseHeaders

    ModifyHeaderInfo[] optional

    Chrome 86 oder höher

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

  • Die Art der auszuführenden Aktion.

RuleActionType

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

Enum

"block"
Blockiert die Netzwerkanfrage.

"redirect"
Leitet die Netzwerkanfrage weiter.

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

"upgradeScheme"
Das Schema der Netzwerkanfrage-URL 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 ausgeht, oder von einer Drittanbieterdomain. Wenn Sie diesen Parameter weglassen, werden alle Anfragen akzeptiert.

  • Domains

    string[] optional

    Eingestellt seit Chrome 101

    Verwenden Sie stattdessen initiatorDomains.

    Die Regel gilt nur für Netzwerkanfragen, die von der Liste der domains stammen.

  • excludedDomains

    string[] optional

    Eingestellt seit Chrome 101

    Verwenden Sie stattdessen excludedInitiatorDomains.

    Die Regel gilt nicht für Netzwerkanfragen, die von der Liste der excludedDomains stammen.

  • excludedInitiatorDomains

    string[] optional

    Chrome 101 oder höher

    Die Regel gilt nicht für Netzwerkanfragen, die von der Liste der excludedInitiatorDomains stammen. Wenn die Liste leer ist oder weggelassen wird, werden keine Domains ausgeschlossen. Diese Einstellung hat Vorrang vor initiatorDomains.

    Hinweise:

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

    string[] optional

    Chrome 101 oder höher

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

    Hinweise:

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

    RequestMethod[] optional

    Chrome 91 oder höher

    Liste der Anfragemethoden, die nicht mit der Regel übereinstimmen. Es sollte nur entweder requestMethods oder excludedRequestMethods angegeben werden. Wenn keine der beiden angegeben ist, werden alle Anfragemethoden abgeglichen.

  • excludedResourceTypes

    ResourceType[] optional

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

  • excludedResponseHeaders

    HeaderInfo[] optional

    Chrome 128 oder höher

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

  • excludedTabIds

    number[] optional

    Chrome 92 oder höher

    Liste der tabs.Tab.id, die nicht mit der Regel übereinstimmen sollen. Eine ID von tabs.TAB_ID_NONE schließt Anfragen aus, die nicht von einem Tab stammen. Wird nur für Regeln auf Sitzungsebene unterstützt.

  • excludedTopDomains

    string[] optional

    Chrome 145 oder höher

    Die Regel wird nicht auf Netzwerkanfragen angewendet, wenn die Domain des zugehörigen Frames der obersten Ebene mit einer Domain aus der Liste der excludedTopDomains übereinstimmt. Wenn die Liste leer ist oder weggelassen wird, werden keine Domains ausgeschlossen. Diese Einstellung hat Vorrang vor topDomains.

    Hinweise:

    • Subdomains wie „a.beispiel.de“ sind ebenfalls zulässig.
    • Die Einträge dürfen nur ASCII-Zeichen enthalten.
    • Verwenden Sie die Punycode-Codierung für internationale Domains.
    • Subdomains der aufgeführten Domains sind ebenfalls ausgeschlossen.
    • Bei Anfragen ohne zugehörigen Frame auf oberster Ebene (z.B. von ServiceWorkern initiierte Anfragen) wird stattdessen die Domain des Anfrageinitiators berücksichtigt.
  • initiatorDomains

    string[] optional

    Chrome 101 oder höher

    Die Regel gilt nur für Netzwerkanfragen, die von der Liste der initiatorDomains stammen. Wenn die Liste weggelassen wird, 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 ASCII-Zeichen enthalten.
    • Verwenden Sie die Punycode-Codierung für internationale Domains.
    • Dies wird mit dem Initiator der Anfrage und nicht mit der Anfrage-URL abgeglichen.
    • Subdomains der aufgeführten Domains werden ebenfalls abgeglichen.
  • isUrlFilterCaseSensitive

    Boolesch 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 für den Abgleich mit der URL der Netzwerkanfrage. Dabei wird die RE2-Syntax verwendet.

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

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

  • requestDomains

    string[] optional

    Chrome 101 oder höher

    Die Regel stimmt nur dann mit Netzwerkanfragen überein, wenn die Domain mit einer Domain aus der Liste der requestDomains übereinstimmt. Wenn die Liste weggelassen wird, 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 ASCII-Zeichen enthalten.
    • Verwenden Sie die Punycode-Codierung für internationale Domains.
    • Subdomains der aufgeführten Domains werden ebenfalls abgeglichen.
  • requestMethods

    RequestMethod[] optional

    Chrome 91 oder 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 oder höher

    Die Regel gilt, wenn die Anfrage mit einer Antwortheader-Bedingung in dieser Liste übereinstimmt (falls angegeben).

  • tabIds

    number[] optional

    Chrome 92 oder 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 Regeln auf Sitzungsebene unterstützt.

  • topDomains

    string[] optional

    Chrome 145 oder höher

    Die Regel stimmt nur mit Netzwerkanfragen überein, wenn die Domain des zugehörigen Top-Level-Frames mit einer Domain aus der Liste der topDomains übereinstimmt. Wenn die Liste weggelassen wird, wird die Regel auf Anfragen angewendet, die mit allen Frame-Domains der obersten Ebene verknüpft sind. Eine leere Liste ist nicht zulässig.

    Hinweise:

    • Subdomains wie „a.beispiel.de“ sind ebenfalls zulässig.
    • Die Einträge dürfen nur ASCII-Zeichen enthalten.
    • Verwenden Sie die Punycode-Codierung für internationale Domains.
    • Subdomains der aufgeführten Domains werden ebenfalls abgeglichen.
    • Bei Anfragen ohne zugehörigen Frame auf oberster Ebene (z.B. von ServiceWorkern initiierte Anfragen) wird stattdessen die Domain des Anfrageinitiators berücksichtigt.
  • urlFilter

    String optional

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

    '*' : Platzhalter: Entspricht einer beliebigen Anzahl von Zeichen.

    '|' : Linker/rechter Anker: Wenn dieses Zeichen am Anfang oder Ende des Musters verwendet wird, gibt es den Anfang bzw. das Ende der URL an.

    '||' : Domainnamen-Anker: Wenn dieses Zeichen am Anfang des Musters verwendet wird, gibt es den Anfang einer (Sub-)Domain der URL an.

    '^' : Trennzeichen: Entspricht allem außer einem Buchstaben, einer Ziffer oder einem der folgenden Zeichen: _, -, . oder %. Dies entspricht auch dem Ende der URL.

    Daher besteht urlFilter aus den folgenden Teilen: (optionaler linker/Domainnamen-Anker) + Muster + (optionaler rechter Anker).

    Wenn keine Angabe erfolgt, 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: Die urlFilter darf nur aus ASCII-Zeichen bestehen. Dieser wird mit einer URL abgeglichen, bei der der Host im Punycode-Format codiert ist (bei internationalisierten Domains) und alle anderen Nicht-ASCII-Zeichen in UTF-8 URL-codiert sind. Wenn die Anfrage-URL beispielsweise http://abc.рф?q=ф lautet, wird die urlFilter mit der URL http://abc.xn--p1ai/?q=%D1%84 abgeglichen.

RuleConditionKeys

Chrome 145 oder höher

Enum

"urlFilter"

"regexFilter"

"isUrlFilterCaseSensitive"

"initiatorDomains"

"excludedInitiatorDomains"

"requestDomains"

"excludedRequestDomains"

"topDomains"

"excludedTopDomains"

"domains"

"excludedDomains"

"resourceTypes"

"excludedResourceTypes"

"requestMethods"

"excludedRequestMethods"

"domainType"

"tabIds"

"excludedTabIds"

"responseHeaders"

"excludedResponseHeaders"

Ruleset

Attribute

  • aktiviert

    boolean

    Gibt an, ob der Regelsatz standardmäßig aktiviert ist.

  • id

    String

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

  • Pfad

    String

    Der Pfad des JSON-Regelsatzes relativ zum Verzeichnis der Erweiterung.

RulesMatchedDetails

Attribute

  • rulesMatchedInfo

    MatchedRuleInfo[]

    Regeln, die dem angegebenen Filter entsprechen.

TabActionCountUpdate

Chrome 89 oder höher

Attribute

  • increment

    Zahl

    Der Wert, um den die Anzahl der Aktionen des Tabs erhöht werden soll. Negative Werte verringern die Anzahl.

  • tabId

    Zahl

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

TestMatchOutcomeResult

Chrome 103 oder höher

Attribute

  • matchedRules

    MatchedRule[]

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

TestMatchRequestDetails

Chrome 103 oder 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. Die Standardeinstellung ist „get“ für HTTP-Anfragen. Bei Nicht-HTTP-Anfragen wird sie ignoriert.

  • responseHeaders

    Objekt optional

    Chrome 129 oder höher

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

  • tabId

    number optional

    Die ID des Tabs, in dem die hypothetische Anfrage stattfindet. Muss nicht einer echten Tab-ID entsprechen. Der Standardwert ist -1, was bedeutet, dass die Anfrage nicht mit einem Tab zusammenhängt.

  • topUrl

    String optional

    Chrome 145 oder höher

    Die zugehörige URL des Frames auf oberster Ebene (falls vorhanden) für die Anfrage.

  • Der Ressourcentyp der hypothetischen Anfrage.

  • URL

    String

    Die URL der hypothetischen Anfrage.

UnsupportedRegexReason

Chrome 87 oder höher

Beschreibt, 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 oder 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 oder höher

Attribute

  • disableRulesetIds

    string[] optional

    Die Gruppe von IDs, die einer statischen Ruleset entsprechen, die deaktiviert werden soll.

  • enableRulesetIds

    string[] optional

    Die Gruppe von IDs, die einer statischen Ruleset entsprechen, die aktiviert werden soll.

UpdateStaticRulesOptions

Chrome 111+

Attribute

  • disableRuleIds

    number[] optional

    Satz von IDs, die den Regeln in der zu deaktivierenden Ruleset entsprechen.

  • enableRuleIds

    number[] optional

    Satz von IDs, die den Regeln in der 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, wobei das vorhandene Fragment gelöscht wird, 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 leer, 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. Sollte entweder leer sein, wobei die vorhandene Abfrage gelöscht wird, 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

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

Wert

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

Zeitintervall in Minuten, innerhalb dessen MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules-Aufrufe ausgeführt werden können. Zusätzliche Aufrufe schlagen sofort fehl und legen runtime.lastError fest. Hinweis: getMatchedRules-Aufrufe, die mit einer Nutzergeste verknüpft sind, sind von der Kontingentierung ausgenommen.

Wert

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89 oder höher

Die Mindestanzahl statischer Regeln, die einer Erweiterung für ihre aktivierten statischen Regelsätze garantiert werden. Alle Regeln, die dieses Limit überschreiten, werden auf das globale Limit für statische Regeln angerechnet.

Wert

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

Die Häufigkeit, mit der getMatchedRules innerhalb eines Zeitraums von GETMATCHEDRULES_QUOTA_INTERVAL aufgerufen werden kann.

Wert

20

MAX_NUMBER_OF_DYNAMIC_RULES

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

Wert

30000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94 oder 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 dynamischen Regeln und die in der Regelressourcendatei angegebenen Regeln ausgewertet.

Wert

1.000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120 oder höher

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

Wert

5.000

MAX_NUMBER_OF_STATIC_RULESETS

Die maximale Anzahl statischer Rulesets, die eine Erweiterung im Manifestschlüssel "rule_resources" angeben kann.

Wert

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120 oder höher

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

Wert

5.000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120 oder höher

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

Wert

5.000

SESSION_RULESET_ID

Chrome 90 oder höher

Regelsatz-ID für die von der Erweiterung hinzugefügten Regeln auf Sitzungsebene.

Wert

"_session"

Methoden

getAvailableStaticRuleCount()

Promise Chrome 89 oder höher 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
): Promise<number>

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

Parameter

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (count: number) => void

    • Anzahl

      Zahl

Ausgabe

  • Promise<number>

    Chrome 91 oder höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getDisabledRuleIds()

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

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

Parameter

  • Gibt den Regelsatz an, der abgefragt werden soll.

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      number[]

Ausgabe

  • Promise<number[]>

    Promise, das mit einer Liste von IDs aufgelöst wird, die den deaktivierten Regeln in diesem Regelsatz entsprechen.

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getDynamicRules()

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

Gibt die aktuellen dynamischen Regeln für die Erweiterung zurück. Aufrufer können die Liste der abgerufenen Regeln optional filtern, indem sie einen filter angeben.

Parameter

  • Filter

    GetRulesFilter optional

    Chrome 111+

    Ein Objekt zum Filtern der Liste der abgerufenen Regeln.

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (rules: Rule[]) => void

Ausgabe

  • Promise<Rule[]>

    Chrome 91 oder höher

    Promise, das mit dem Satz dynamischer Regeln aufgelöst wird. Das Promise kann bei vorübergehenden internen Fehlern abgelehnt werden.

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getEnabledRulesets()

Promise 
chrome.declarativeNetRequest.getEnabledRulesets(
  callback?: function,
): Promise<string[]>

Gibt die IDs für die aktuellen aktivierten statischen Regelsätze zurück.

Parameter

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (rulesetIds: string[]) => void

    • rulesetIds

      String[]

Ausgabe

  • Promise<string[]>

    Chrome 91 oder höher

    Promise, das mit einer Liste von IDs aufgelöst wird, wobei jede ID einem aktivierten statischen Ruleset entspricht.

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getMatchedRules()

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

Gibt alle Regeln zurück, die für die Erweiterung übereinstimmen. Aufrufer können die Liste der übereinstimmenden Regeln optional filtern, indem sie einen filter angeben. Diese Methode ist nur für Erweiterungen mit der Berechtigung "declarativeNetRequestFeedback" oder mit 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

Ausgabe

  • Chrome 91 oder höher

    Promise, das aufgelöst wird, sobald die Liste der übereinstimmenden Regeln abgerufen wurde. Im Falle eines Fehlers wird das Promise abgelehnt. Dies kann verschiedene Gründe haben, z. B. unzureichende Berechtigungen oder Überschreitung des Kontingents.

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getSessionRules()

Promise Chrome 90+ 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
  callback?: function,
): Promise<Rule[]>

Gibt die aktuellen sitzungsbezogenen Regeln für die Erweiterung zurück. Aufrufer können die Liste der abgerufenen Regeln optional filtern, indem sie einen filter angeben.

Parameter

  • Filter

    GetRulesFilter optional

    Chrome 111+

    Ein Objekt zum Filtern der Liste der abgerufenen Regeln.

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (rules: Rule[]) => void

Ausgabe

  • Promise<Rule[]>

    Chrome 91 oder höher

    Promise, das mit dem Satz von Regeln für die Sitzung aufgelöst wird.

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

isRegexSupported()

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

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

Parameter

Ausgabe

  • Chrome 91 oder höher

    Promise, das mit Details aufgelöst wird, die angeben, ob der reguläre Ausdruck unterstützt wird, und den Grund, falls nicht.

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

setExtensionActionOptions()

Promise Chrome 88 oder höher 
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
  callback?: function,
): 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

  • callback

    function optional

    Chrome 89 oder höher

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 91 oder höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

testMatchOutcome()

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

Prüft, ob eine der declarativeNetRequest-Regeln der Erweiterung mit einer hypothetischen Anfrage übereinstimmt. Hinweis: Nur für entpackte Erweiterungen verfügbar, da dies nur für die Entwicklung von Erweiterungen vorgesehen ist.

Parameter

Ausgabe

  • Promise, das mit den Details der übereinstimmenden Regeln aufgelöst wird.

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

updateDynamicRules()

Promise 
chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
  callback?: function,
): 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 werden 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 sind, 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

  • Chrome 87 oder höher
  • callback

    function optional

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 91 oder höher

    Promise, das aufgelöst wird, sobald die Aktualisierung abgeschlossen ist. Im Falle eines Fehlers wird das Promise abgelehnt und es werden keine Änderungen am Regelsatz vorgenommen. Dies kann verschiedene Gründe haben, z. B. ein ungültiges Regelformat, eine doppelte Regel-ID, das Überschreiten der maximalen Anzahl von Regeln oder interne Fehler.

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

updateEnabledRulesets()

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

Aktualisiert die aktivierten statischen Regelsätze für die Erweiterung. Die Regelsätze mit den in options.disableRulesetIds aufgeführten IDs werden zuerst entfernt und dann werden die in options.enableRulesetIds aufgeführten Regelsätze hinzugefügt. Die aktivierten statischen Regelsätze bleiben über Sitzungen hinweg erhalten, aber nicht über Erweiterungsupdates hinweg. Das bedeutet, dass der Manifestschlüssel rule_resources bei jedem Erweiterungsupdate die aktivierten statischen Regelsätze bestimmt.

Parameter

  • Chrome 87 oder höher
  • callback

    function optional

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 91 oder höher

    Promise, das aufgelöst wird, sobald die Aktualisierung abgeschlossen ist. Im Falle eines Fehlers wird das Promise abgelehnt und es werden keine Änderungen an den aktivierten Regelsätzen vorgenommen. Dies kann verschiedene Gründe haben, z. B. ungültige Regelsatz-IDs, Überschreitung des Limits für die Anzahl der Regeln oder interne Fehler.

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

updateSessionRules()

Promise Chrome 90+ 
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
  callback?: function,
): 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 werden 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 über Sitzungen hinweg beibehalten und im Arbeitsspeicher gesichert.
  • MAX_NUMBER_OF_SESSION_RULES ist die maximale Anzahl von Sitzungsregeln, die eine Erweiterung hinzufügen kann.

Parameter

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 91 oder höher

    Promise, das aufgelöst wird, sobald die Aktualisierung abgeschlossen ist. Im Falle eines Fehlers wird das Promise abgelehnt und es werden keine Änderungen am Regelsatz vorgenommen. Dies kann verschiedene Gründe haben, z. B. ein ungültiges Regelformat, eine doppelte Regel-ID oder das Überschreiten der maximalen Anzahl von Regeln.

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

updateStaticRules()

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

Deaktiviert und aktiviert einzelne statische Regeln in einer Ruleset. Änderungen an Regeln, die zu einer deaktivierten Ruleset gehören, werden wirksam, wenn sie das nächste Mal aktiviert wird.

Parameter

Ausgabe

  • Promise<void>

    Promise, das aufgelöst wird, wenn die Aktualisierung abgeschlossen ist. Im Falle eines Fehlers wird das Promise abgelehnt und es werden keine Änderungen an den aktivierten statischen Regeln vorgenommen.

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

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 dies nur für die Fehlerbehebung vorgesehen ist.

Parameter