chrome.declarativeNetRequest

Beschreibung

Mit der chrome.declarativeNetRequest API können Sie Netzwerkanfragen blockieren oder ändern, indem Sie deklarative Regeln angeben. So können Erweiterungen Netzwerkanfragen ändern, ohne sie abzufangen und ihren Inhalt anzusehen. Das erhöht den Datenschutz.

Berechtigungen

declarativeNetRequest
declarativeNetRequestWithHostAccess

Die Berechtigungen „declarativeNetRequest“ und „declarativeNetRequestWithHostAccess“ bieten dieselben Funktionen. Der Unterschied 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 nicht den vollständigen Zugriff auf Hosts anfordern zu müssen.
"declarativeNetRequestFeedback"
Aktiviert Funktionen zur Fehlerbehebung für entpackte Erweiterungen, insbesondere getMatchedRules() und onRuleMatchedDebug.
"declarativeNetRequestWithHostAccess"
Bei der Installation wird keine Berechtigungswarnung angezeigt. Sie müssen jedoch Hostberechtigungen anfordern, bevor Sie eine Aktion auf einem Host ausführen können. Dies ist sinnvoll, wenn Sie deklarative Regeln für Netzwerkanfragen 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 oben beschriebenen Berechtigungen müssen für bestimmte Arten von Regelsätzen, insbesondere für 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 mit Wörterbüchern vom Typ Ruleset, wie unten dargestellt. Hinweis: Der Name „Ruleset“ ist im JSON-Manifest nicht enthalten, 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

Geben Sie zum Verwenden dieser API eine oder mehrere Regelsätze an. Eine Regelsammlung enthält mehrere Regeln. Eine einzelne Regel führt einen der folgenden Schritte aus:

  • Blockieren Sie eine Netzwerkanfrage.
  • Aktualisieren Sie das Schema (von http zu https).
  • Sie können verhindern, dass eine Anfrage blockiert wird, indem Sie alle übereinstimmenden blockierten Regeln negieren.
  • Netzwerkanfrage weiterleiten
  • Anfrage- oder Antwortheader ändern

Es gibt drei Arten von Regelsätzen, die auf 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 heruntergefahren wird 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.

Regelsätze auf dynamischer und Sitzungsebene

Dynamische und Sitzungs-Regeln 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 heruntergefahren wird und wenn eine neue Version der Erweiterung installiert wird.

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

Statische Regelsätze

Im Gegensatz zu dynamischen 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 über die Schlüssel "declarative_net_request" und "rule_resources" wie oben beschrieben sowie über ein oder mehrere Ruleset-Wörterbücher angegeben werden. Ein Ruleset-Wörterbuch enthält einen Pfad zur Regeldatei, eine ID für die in der Datei enthaltene Regelsatz und ob der Regelsatz aktiviert oder deaktiviert ist. Die letzten beiden sind wichtig, wenn Sie eine Regelgruppe 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 die Erweiterung entpackt hoch. Fehler und Warnungen zu ungültigen Static-Regeln werden nur für entpackte Erweiterungen angezeigt. Ungültige Static-Regeln in gepackten Erweiterungen werden ignoriert.

Beschleunigte Überprüfung

Änderungen an statischen Regelsätzen können eine beschleunigte Überprüfung erhalten. Weitere Informationen finden Sie unter Beschleunigte Überprüfung für infrage kommende Änderungen.

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 sitzungsübergreifend erhalten. Beide werden nicht über Erweiterungsupdates hinweg beibehalten. Das bedeutet, dass nach einem Update nur die Regeln verfügbar sind, die Sie in Ihren Regeldateien belassen haben.

Aus Leistungsgründen ist auch die Anzahl der Regeln und Regelsätze, die gleichzeitig aktiviert werden können, begrenzt. Rufe getAvailableStaticRuleCount() auf, um die Anzahl der zusätzlichen Regeln zu prüfen, die aktiviert werden können. Informationen zu den Limits für Regeln finden Sie unter Limits für Regeln.

Wenn Sie statische Regeln aktivieren oder deaktivieren möchten, geben Sie updateStaticRules() ein. Diese Methode nimmt ein UpdateStaticRulesOptions-Objekt an, das Arrays von IDs der Regeln enthält, die aktiviert oder deaktiviert werden sollen. Die IDs werden mit dem Schlüssel "id" des Ruleset-Wörterbuchs definiert. Es können maximal 5.000 deaktivierte statische Regeln vorhanden sein.

Wenn Sie statische Regelnsätze aktivieren oder deaktivieren möchten, geben Sie updateEnabledRulesets() ein. Diese Methode nimmt ein UpdateRulesetOptions-Objekt an, das Arrays von IDs der zu aktivierenden oder zu deaktivierenden Regelsätze enthält. Die IDs werden mit dem Schlüssel "id" des Ruleset-Wörterbuchs 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 Blockierungs- und Weiterleitungsbedingungen enthalten. Mit der folgenden Regel werden alle Scriptanfragen blockiert, die von "foo.com" an eine URL mit "abc" als Teilstring gesendet werden.

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

URL-Übereinstimmung

Mit deklarativen Net-Anfragen können URLs entweder mit einer Syntax für Musterabgleiche oder mit regulären Ausdrücken abgeglichen werden.

Syntax für URL-Filter

Der "condition"-Schlüssel einer Regel erlaubt einem "urlFilter"-Schlüssel, Aktionen auf URLs unter einer bestimmten Domain auszuführen. Muster werden mithilfe von Musterabgleichstokens erstellt. 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

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

Gute URL-Bedingungen schreiben

Achten Sie beim Erstellen von Regeln darauf, dass immer eine ganze Domain übereinstimmt. Andernfalls wird Ihre Regel möglicherweise in Situationen ausgelöst, in denen das nicht beabsichtigt ist. Beispiel für die Verwendung der Syntax für den Musterabgleich:

  • google.com stimmt nicht mit https://example.com/?param=google.com überein
  • ||google.com stimmt nicht mit https://google.company überein
  • https://www.google.com stimmt nicht mit https://example.com/?param=https://www.google.com überein

Geeignete Methoden:

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

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

Regelauswertung

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

Vor der Anfrage

Vor einer Anfrage kann eine Erweiterung diese mit einer übereinstimmenden Regel blockieren oder weiterleiten (einschließlich eines Upgrades des Protokolls von HTTP auf HTTPS).

Für jede Erweiterung ermittelt der Browser eine Liste von Abgleichsregeln. Regeln mit der Aktion modifyHeaders sind hier nicht enthalten, da sie später verarbeitet werden. Außerdem werden Regeln mit einer responseHeaders-Bedingung erst 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 sucht eine übereinstimmende Regel, indem alle übereinstimmenden 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, bereits mit einer allowAllRequests-Regel mit höherer oder gleicher Priorität aus dieser Erweiterung abgeglichen wurde, wird die Anfrage „zugelassen“ und die Erweiterung hat keine Auswirkungen auf die Anfrage.

Wenn mehrere Erweiterungen diese Anfrage blockieren oder weiterleiten möchten, wird eine einzelne Aktion ausgewählt. Dazu werden die Regeln in Chrome in der Reihenfolge block > redirect oder upgradeScheme > allow oder allowAllRequests sortiert. Wenn zwei Regeln vom selben Typ sind, wählt Chrome die Regel aus der am häufigsten installierten Erweiterung aus.

Bevor Anfrageheader gesendet werden

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

Innerhalb einer einzelnen Erweiterung erstellt Chrome die Liste der durchzuführenden Änderungen, indem alle übereinstimmenden modifyHeaders-Regeln gefunden werden. Ähnlich wie zuvor werden nur Regeln berücksichtigt, die eine höhere Priorität als alle übereinstimmenden allow- oder allowAllRequests-Regeln haben.

Diese Regeln werden von Chrome in einer Reihenfolge angewendet, bei der Regeln einer neuer installierten 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 nur Regeln mit niedrigerer Priorität an diesen Header angehängt werden. Die Vorgänge „Set“ und „Remove“ sind nicht zulässig.
  • Wenn eine Regel einen Header festlegt, können diesem Header nur Regeln mit niedrigerer Priorität aus derselben Erweiterung 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.

Sobald eine Antwort eingegangen ist

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

Nachdem diese Regeln nach action und priority sortiert und alle Regeln ausgeschlossen wurden, die durch eine übereinstimmende allow- oder allowAllRequests-Regel redundant geworden sind (dies geschieht genau wie in den Schritten unter „Vor der Anfrage“), blockiert oder leitet Chrome die Anfrage im Namen einer Erweiterung möglicherweise weiter.

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 jedoch nicht blockieren oder weiterleiten.

Bei einer Blockierungsregel wird dies von der Seite verarbeitet, die die Anfrage gesendet hat. Diese erhält eine blockierte Antwort und Chrome beendet die Anfrage vorzeitig. Bei einer Weiterleitungsregel stellt Chrome eine neue Anfrage an die weitergeleitete URL. Überlegen Sie, ob diese Verhaltensweisen den Datenschutzanforderungen für Ihre Erweiterung entsprechen.

Wenn die Anfrage nicht blockiert oder weitergeleitet wird, werden in Chrome alle modifyHeaders-Regeln angewendet. Die Änderungen an Antwortheadern werden auf die gleiche Weise angewendet wie unter „Vor dem Senden von Anfrageheadern“ beschrieben. Änderungen an Anfrageheadern haben keine Auswirkungen, da die Anfrage bereits gesendet wurde.

Sichere Regeln

Sichere Regeln sind 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 Bewerten von Regeln im Browser ist mit einem Leistungsoverhead verbunden. Daher gelten bei der Verwendung der API einige Einschränkungen. Die Limits hängen von der Art der verwendeten Regel ab.

Statische Regeln

Statische Regeln sind in Regeldateien angegeben, die in der Manifestdatei deklariert sind. Eine Erweiterung kann im Manifest-Schlüssel "rule_resources" bis zu 100 statische Regelnsätze angeben. Es können jedoch jeweils nur 50 dieser Regelsätze aktiviert werden. Letzteres wird als MAX_NUMBER_OF_ENABLED_STATIC_RULESETS bezeichnet. Zusammengenommen 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 von allen im Browser des Nutzers installierten Erweiterungen aktiviert 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. Dieser wird als MAX_NUMBER_OF_SESSION_RULES angezeigt.

Vor Chrome 120 war die Anzahl der dynamischen und Sitzungsregeln auf 5.000 begrenzt.

Dynamische Regeln

Eine Erweiterung kann mindestens 5.000 dynamische Regeln haben. Dieser wird als MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES angezeigt.

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

Vor Chrome 120 gab es eine Obergrenze von 5.000 kombinierten dynamischen 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 regulären Ausdrucksregeln jedes Typs darf jedoch 1.000 nicht überschreiten. Dieser Wert wird als MAX_NUMBER_OF_REGEX_RULES bezeichnet.

Außerdem muss jede Regel nach der Kompilierung kleiner als 2 KB sein. Dies hängt ungefähr 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 Dienstmitarbeitern

Eine declarativeNetRequest gilt nur für Anfragen, die den Netzwerkstack erreichen. Dazu gehören 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 von CacheStorage abgerufen werden, aber auf Aufrufe von fetch(), die in einem Service Worker erfolgen.

Webzugriff auf Ressourcen

Mit einer declarativeNetRequest-Regel kann nicht von einer öffentlichen Ressourcenanfrage zu einer Ressource weitergeleitet werden, 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. Verwenden Sie das Array "web_accessible_resources" des Manifests, um Ressourcen für declarativeNetRequest zu deklarieren.

Header-Änderung

Der Vorgang „Anhängen“ wird nur für die folgenden Überschriften 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 und x-forwarded-for.

Beispiele

Codebeispiele

Dynamische Regeln aktualisieren

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

// 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 wird. Das ist der Fall, wenn die Anzahl der benötigten statischen Regeln die zulässige Anzahl überschreitet. Damit dies funktioniert, sollten einige Ihrer Regelsätze installiert und andere deaktiviert sein. Legen Sie dazu in der Manifestdatei "Enabled" auf false fest.

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, können Sie die Regeln für die Priorisierung in einem separaten Fenster öffnen.

Der Schlüssel „priority“

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

Die Priorität einer bestimmten URL ergibt sich aus den (vom Entwickler definierten) Schlüsseln "priority", "action" und "urlFilter". Diese Beispiele beziehen sich auf die Beispielregeldatei, die unten angezeigt wird.

Rufen Sie https://google.com auf.
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 übrigen Regeln gelten nicht, da sie für längere URLs gelten.
Rufen Sie https://google.com/1234 auf.
Aufgrund der längeren URL stimmt die Regel mit der ID 2 jetzt zusätzlich zu den Regeln mit den IDs 1 und 4. Die Regel mit der ID 2 gilt, da "allow" eine höhere Priorität als "block" und "redirect" hat.
Rufen Sie https://google.com/12345 auf.
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.

Im folgenden Beispiel wird gezeigt, wie eine Anfrage von beispiel.de auf eine Seite innerhalb der Erweiterung weitergeleitet wird. Der Erweiterungspfad /a.jpg wird in chrome-extension://EXTENSION_ID/a.jpg aufgelöst, wobei EXTENSION_ID die ID Ihrer Erweiterung ist. Damit dies funktioniert, 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 Beispiel wird der Schlüssel "transform" verwendet, um eine Weiterleitung zu einer Subdomain von beispiel.de vorzunehmen. Dabei wird ein Domainnamen-Anchor („||“) verwendet, um Anfragen mit beliebigem Schema von beispiel.de abzufangen. Der Schlüssel "scheme" in "transform" gibt an, dass für 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 wird mithilfe von regulären Ausdrücken von https://www.abc.xyz.com/path zu https://abc.xyz.com/path weitergeleitet. Beachten Sie im Schlüssel "regexFilter", dass Punkte mit einem Escape-Zeichen versehen sind und dass die Erfassungsgruppe entweder „abc“ oder „def“ auswählt. Der Schlüssel "regexSubstitution" gibt die erste zurückgegebene Übereinstimmung des regulären Ausdrucks mithilfe von „\1“ an. In diesem Fall wird „abc“ aus der weitergeleiteten URL erfasst und in die Substitution 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 angegeben, ob die Anfrage vom Frame stammt, in dem sie ihren Ursprung hat, oder von einem Drittanbieter. Eine Anfrage gilt als selbst erhoben, wenn sie dieselbe Domain (eTLD+1) wie der Frame hat, von dem aus sie stammt.

Enum

„firstParty“
Die Netzwerkanfrage stammt aus dem Frame, in dem sie gestartet wurde.

„thirdParty“
Die Netzwerkanfrage stammt von einem Drittanbieter des Frames, in dem sie ihren Ursprung hat.

ExtensionActionOptions

Chrome 88 und höher

Attribute

  • displayActionCountAsBadgeText

    boolescher Wert optional

    Gibt an, ob die Aktionszahl für eine Seite automatisch als Logotext der Erweiterung angezeigt werden soll. Diese Einstellung bleibt sitzungsübergreifend erhalten.

  • tabUpdate

    TabActionCountUpdate optional

    Chrome 89 und höher

    Details dazu, wie die Aktionszahl des Tabs angepasst werden sollte.

GetDisabledRuleIdsOptions

Chrome 111 und höher

Attribute

  • rulesetId

    String

    Die ID, die einer statischen Ruleset entspricht.

GetRulesFilter

Chrome 111 und höher

Attribute

  • ruleIds

    number[] optional

    Wenn Sie eine ID angeben, 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 die Überschrift vorhanden ist, ihr Wert aber mindestens ein Element in dieser Liste enthält. Dabei wird dieselbe Syntax wie für values verwendet.

  • Header

    String

    Der Name der Kopfzeile. Diese Bedingung stimmt nur mit dem Namen überein, wenn weder values noch excludedValues angegeben sind.

  • Werte

    string[] optional

    Wenn diese Bedingung angegeben ist, ist sie erfüllt, wenn der Wert der Überschrift mit mindestens einem Muster in dieser Liste übereinstimmt. Dabei wird die Groß- und Kleinschreibung bei Headerwerten ignoriert und die folgenden Konstrukte werden unterstützt:

    * : Entspricht einer beliebigen Anzahl von Zeichen.

    '?' : Entspricht null oder einem Zeichen.

    „*“ und „?“ können mit einem umgekehrten Schrägstrich 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 die angegebene Überschrift 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 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 der Ruleset, zu der diese Regel gehört. Bei einer Regel aus den dynamischen Regeln entspricht dies DYNAMIC_RULESET_ID.

MatchedRuleInfo

Attribute

  • Regel

    MatchedRule

  • tabId

    Zahl

    Die Tab-ID des Tabs, von dem die Anfrage stammt, sofern der Tab noch aktiv ist. Andernfalls -1.

  • timeStamp

    Zahl

    Der Zeitpunkt, zu dem die Regel übereinstimmt hat. Zeitstempel entsprechen der Javascript-Konvention für Zeiten, d.h. die Anzahl der Millisekunden seit der Epoche.

MatchedRuleInfoDebug

Attribute

MatchedRulesFilter

Attribute

  • minTimeStamp

    number optional

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

  • tabId

    number optional

    Wenn angegeben, werden nur Regeln für den angegebenen Tab berücksichtigt. Wenn „-1“ festgelegt ist, werden Regeln angewendet, die keinem aktiven Tab zugeordnet sind.

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

    boolescher Wert optional

    Chrome 94 und höher

    Wenn „wahr“ ist, 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 Suchschlüssel.

Redirect

Attribute

  • extensionPath

    String optional

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

  • regexSubstitution

    String optional

    Substitutionsmuster für Regeln, die eine regexFilter angeben. 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

    Auszuführende URL-Transformationen.

  • URL

    String optional

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

RegexOptions

Chrome 87 und höher

Attribute

  • isCaseSensitive

    boolescher Wert optional

    Ob bei der angegebenen regex zwischen Groß- und Kleinschreibung unterschieden wird. Standardwert ist True.

  • regex

    String

    Der zu prüfende reguläre Ausdruck.

  • requireCapturing

    boolescher Wert optional

    Gibt an, ob die angegebene regex erfasst werden muss. Die Erfassung ist nur für Weiterleitungsregeln erforderlich, für die 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, falls diese Anfrage für einen Frame erfolgt.

  • 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 (untergeordneten) Frames geladen ist (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, falls es sich bei dieser Anfrage um einen Frame handelt.

  • Initiator

    String optional

    Der Ursprung, an dem die Anfrage gestartet wurde. Das ändert sich auch nicht durch Weiterleitungen. Bei einem nicht transparenten Ursprung 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, falls diese Anfrage für einen Frame erfolgt und er ein übergeordnetes Element hat.

  • parentFrameId

    Zahl

    ID des Frames, der den Frame umschließt, von dem die Anfrage gesendet wurde. Setzen Sie den Wert auf -1, wenn kein übergeordneter Frame vorhanden ist.

  • requestId

    String

    Die ID der Anfrage. Anfrage-IDs sind innerhalb einer Browser-Sitzung eindeutig.

  • tabId

    Zahl

    Die ID des Tabs, auf dem die Anfrage erfolgt. Setze „-1“, wenn die Anfrage nicht mit einem Tab verknüpft ist.

  • 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"

„Sonstiges“

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"

„Sonstiges“

Rule

Attribute

  • Aktion

    RuleAction

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

  • condition

    RuleCondition

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

  • id

    Zahl

    Eine ID, die eine Regel eindeutig identifiziert. Muss angegeben werden und muss >= 1 sein.

  • priorität

    number optional

    Regelpriorität. Der Standardfaktor ist 1. Muss >= 1 sein, wenn angegeben.

RuleAction

Attribute

  • weiterleiten

    Weiterleitung optional

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

  • requestHeaders

    ModifyHeaderInfo[] optional

    Chrome 86 und höher

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

  • responseHeaders

    ModifyHeaderInfo[] optional

    Chrome 86 und höher

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

  • Die Art der auszuführenden Aktion.

RuleActionType

Beschreibt die Art der Aktion, die ausgeführt werden soll, wenn eine bestimmte Regelbedingung erfüllt ist.

Enum

„block“
Blockiert die Netzwerkanfrage.

„redirect“
Netzwerkanfrage weiterleiten.

„allow“
Netzwerkanfrage zulassen. Die Anfrage wird nicht abgefangen, wenn es eine zu ihr passende Regel gibt, die die Anfrage zulässt.

„upgradeScheme“
Aktualisiert das Schema der URL der Netzwerkanfrage auf https, 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, zu der sie gehört, oder von einem Drittanbieter. Wird dieser Parameter weggelassen, werden alle Anfragen akzeptiert.

  • Domains

    string[] optional

    Seit Chrome 101 eingestellt

    Verwenden Sie stattdessen initiatorDomains.

    Die Regel wird nur auf Netzwerkanfragen angewendet, die aus der Liste der domains stammen.

  • excludedDomains

    string[] optional

    Seit Chrome 101 eingestellt

    Verwenden Sie stattdessen excludedInitiatorDomains.

    Die Regel wird nicht mit Netzwerkanfragen abgeglichen, die aus der Liste der excludedDomains stammen.

  • excludedInitiatorDomains

    string[] optional

    Chrome 101 und höher

    Die Regel wird nicht mit Netzwerkanfragen abgeglichen, die aus der Liste der excludedInitiatorDomains stammen. Wenn die Liste leer ist oder fehlt, werden keine Domains ausgeschlossen. Diese hat Vorrang vor initiatorDomains.

    Hinweise:

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

    string[] optional

    Chrome 101 und höher

    Die Regel wird nicht mit Netzwerkanfragen abgeglichen, wenn die Domains mit einer Domain aus der Liste von excludedRequestDomains übereinstimmen. Wenn die Liste leer ist oder fehlt, werden keine Domains ausgeschlossen. Diese hat Vorrang vor requestDomains.

    Hinweise:

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

    RequestMethod[] optional

    Chrome 91 und höher

    Liste der Anfragemethoden, für die die Regel nicht gilt. Es sollte nur eines von requestMethods und excludedRequestMethods angegeben werden. Wenn keine davon angegeben ist, werden alle Anfragemethoden abgeglichen.

  • excludedResourceTypes

    ResourceType[] optional

    Liste der Ressourcentypen, auf die die Regel nicht zutrifft. Es sollte nur eines von resourceTypes und excludedResourceTypes angegeben werden. Wenn keiner der beiden angegeben ist, werden alle Ressourcentypen mit Ausnahme von „main_frame“ blockiert.

  • excludedResponseHeaders

    HeaderInfo[] optional

    Chrome 128 und höher

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

  • excludedTabIds

    number[] optional

    Chrome 92 und höher

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

  • initiatorDomains

    string[] optional

    Chrome 101 und höher

    Die Regel wird nur auf Netzwerkanfragen angewendet, die aus der Liste der initiatorDomains stammen. Wird die Liste weggelassen, gilt die Regel für Anfragen von allen Domains. Eine leere Liste ist nicht zulässig.

    Hinweise:

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

    boolescher Wert optional

    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 urlFilter oder regexFilter angegeben werden.

    Hinweis: regexFilter darf nur aus ASCII-Zeichen bestehen. Dieser wird mit einer URL verglichen, 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 und höher

    Die Regel wird nur auf Netzwerkanfragen angewendet, wenn die Domain mit einer Domain aus der Liste requestDomains übereinstimmt. Wird die Liste weggelassen, gilt die Regel für Anfragen von allen Domains. Eine leere Liste ist nicht zulässig.

    Hinweise:

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

    RequestMethod[] optional

    Chrome 91 und höher

    Liste der HTTP-Anfragemethoden, mit denen die Regel übereinstimmen kann. Eine leere Liste ist nicht zulässig.

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

  • resourceTypes

    ResourceType[] optional

    Liste der Ressourcentypen, mit denen die Regel übereinstimmen kann. Eine leere Liste ist nicht zulässig.

    Hinweis: Diese Angabe muss für allowAllRequests-Regeln erfolgen und darf nur die Ressourcentypen sub_frame und main_frame enthalten.

  • responseHeaders

    HeaderInfo[] optional

    Chrome 128 und höher

    Die Regel wird angewendet, wenn die Anfrage mit einer der Antwortheaderbedingungen 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 Regeln auf Sitzungsebene unterstützt.

  • urlFilter

    String optional

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

    * : Platzhalter: Entspricht einer beliebigen Anzahl von Zeichen.

    '|' : Links-/Rechtsanker: Wenn er an einem Ende des Musters verwendet wird, gibt er den Anfang bzw. das Ende der URL an.

    '||' : Domainnamen-Anker: Wenn dieser Anker am Anfang des Musters verwendet wird, gibt er den Beginn einer (untergeordneten) Domain der URL an.

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

    Daher besteht urlFilter aus den folgenden Teilen: (optionaler Anker „Links“/Domainname) + Muster + (optionaler Anker „Rechts“).

    Wenn Sie diesen Parameter weglassen, 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 urlFilter oder regexFilter angegeben werden.

    Hinweis: urlFilter darf nur aus ASCII-Zeichen bestehen. Dieser wird mit einer URL verglichen, 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 urlFilter mit der URL http://abc.xn--p1ai/?q=%D1%84 abgeglichen.

Ruleset

Attribute

  • aktiviert

    boolean

    Gibt an, ob die Regelliste standardmäßig aktiviert ist.

  • id

    String

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

  • Pfad

    String

    Der Pfad der JSON-Regeldatei relativ zum Erweiterungsverzeichnis.

RulesMatchedDetails

Attribute

  • rulesMatchedInfo

    MatchedRuleInfo[]

    Regeln, die mit dem angegebenen Filter übereinstimmen.

TabActionCountUpdate

Chrome 89 und höher

Attribute

  • increment

    Zahl

    Der Wert, um den die Aktionszahl des Tabs erhöht werden soll. Bei negativen Werten wird die Anzahl verringert.

  • tabId

    Zahl

    Der Tab, für den die Aktionsanzahl aktualisiert werden soll.

TestMatchOutcomeResult

Chrome 103 und höher

Attribute

  • matchedRules

    MatchedRule[]

    Die Regeln (falls vorhanden), die mit der hypothetischen Anfrage übereinstimmen.

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 ist „get“ für HTTP-Anfragen festgelegt und wird für Nicht-HTTP-Anfragen ignoriert.

  • responseHeaders

    object optional

    Chrome 129 und höher

    Die Header einer hypothetischen Antwort, wenn die Anfrage nicht blockiert oder umgeleitet wird, bevor sie gesendet wird. Wird als Objekt dargestellt, das einem Headernamen eine Liste von Stringwerten zuordnet. Wenn keine Angabe gemacht wird, werden für die hypothetische Antwort leere Antwortheader zurückgegeben, die mit Regeln übereinstimmen können, die auf das Nichtvorhandensein von Headern abzielen. Beispiel: {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}

  • tabId

    number optional

    Die ID des Tabs, auf dem die hypothetische Anfrage erfolgt. Muss keiner tatsächlichen Tab-ID entsprechen. Der Standardwert ist -1, was 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

    Regel[] optional

    Zu hinzufügende Regeln.

  • removeRuleIds

    number[] optional

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

UpdateRulesetOptions

Chrome 87 und höher

Attribute

  • disableRulesetIds

    string[] optional

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

  • enableRulesetIds

    string[] optional

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

UpdateStaticRulesOptions

Chrome 111 und höher

Attribute

  • disableRuleIds

    number[] optional

    IDs, die den Regeln in Ruleset entsprechen, die deaktiviert werden sollen.

  • enableRuleIds

    number[] optional

    IDs, die den Regeln in Ruleset entsprechen und aktiviert werden sollen.

  • rulesetId

    String

    Die ID, die einer statischen Ruleset entspricht.

URLTransform

Attribute

  • Fragment

    String optional

    Das neue Fragment für die Anfrage. Muss 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 Anschluss 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. Das Feld muss entweder leer sein, in diesem Fall wird die vorhandene Abfrage gelöscht, oder mit „?“ beginnen.

  • queryTransform

    QueryTransform optional

    Fügen Sie Schlüssel/Wert-Paare zur Abfrage hinzu, entfernen Sie sie oder ersetzen Sie sie.

  • 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 dem MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules Aufrufe gesendet werden können, angegeben in Minuten. Zusätzliche Anrufe schlagen sofort fehl und runtime.lastError wird festgelegt. Hinweis: getMatchedRules Aufrufe, die mit einer Nutzergeste verknüpft sind, sind vom Kontingent ausgenommen.

Wert

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89 und höher

Die Mindestanzahl an Static-Regeln, die einer Erweiterung in ihren aktivierten Static-Regeln garantiert wird. Alle Regeln, die über dieses Limit hinausgehen, 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 regulären Ausdrucksregeln, die eine Erweiterung hinzufügen kann. Dieses Limit wird separat für die dynamischen Regeln und die in der Ressourcendatei für Regeln angegebenen Regeln ausgewertet.

Wert

1.000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120 und höher

Die maximale Anzahl von Regeln auf Sitzungsebene, 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 „unsicherer“ dynamischer 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“ Regeln auf Sitzungsebene, die eine Erweiterung hinzufügen kann.

Wert

5.000

SESSION_RULESET_ID

Chrome 90 und höher

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

Wert

„_session“

Methoden

getAvailableStaticRuleCount()

Promise Chrome 89 und höher 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
)

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

Parameter

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (count: number) => void

    • Anzahl

      Zahl

Gibt Folgendes zurück:

  • Promise<number>

    Chrome 91 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks werden aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

getDisabledRuleIds()

Versprechen Chrome 111 und höher 
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
  callback?: function,
)

Gibt die Liste der derzeit deaktivierten statischen Regeln in der angegebenen Ruleset zurück.

Parameter

  • Gibt die Regelsatz fest, der abgefragt werden soll.

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      number[]

Gibt Folgendes zurück:

  • Promise<number[]>

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks werden aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

getDynamicRules()

Promise 
chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
  callback?: function,
)

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

Parameter

  • Filter

    GetRulesFilter optional

    Chrome 111 und höher

    Ein Objekt, mit dem die Liste der abgerufenen Regeln gefiltert wird.

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (rules: Rule[]) => void

Gibt Folgendes zurück:

  • Promise<Rule[]>

    Chrome 91 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks werden aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

getEnabledRulesets()

Promise 
chrome.declarativeNetRequest.getEnabledRulesets(
  callback?: function,
)

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

Parameter

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (rulesetIds: string[]) => void

    • rulesetIds

      String[]

Gibt Folgendes zurück:

  • Promise<string[]>

    Chrome 91 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks werden aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

getMatchedRules()

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

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

Parameter

Gibt Folgendes zurück:

  • Chrome 91 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks werden aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

getSessionRules()

Versprechen Chrome 90 und höher 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
  callback?: function,
)

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

Parameter

  • Filter

    GetRulesFilter optional

    Chrome 111 und höher

    Ein Objekt, mit dem die Liste der abgerufenen Regeln gefiltert wird.

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (rules: Rule[]) => void

Gibt Folgendes zurück:

  • Promise<Rule[]>

    Chrome 91 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks werden aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

isRegexSupported()

Versprechen Chrome 87 und höher 
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
  callback?: function,
)

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

Parameter

Gibt Folgendes zurück:

  • Chrome 91 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks werden aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

setExtensionActionOptions()

Promise Chrome 88 und höher 
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
  callback?: function,
)

Hiermit wird konfiguriert, ob die Aktionszahl für Tabs als Badge-Text der Erweiterungsaktion angezeigt werden soll. Außerdem wird eine Möglichkeit zum Erhöhen dieser Aktionszahl festgelegt.

Parameter

  • callback

    function optional

    Chrome 89 und höher

    Der Parameter callback sieht so aus: 

    () => void

Gibt Folgendes zurück:

  • Promise<void>

    Chrome 91 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks werden aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

testMatchOutcome()

Versprechen Chrome 103 und höher 
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
)

Prüft, ob eine der declarativeNetRequest-Regeln der Erweiterung mit einer hypothetischen Anfrage übereinstimmt. Hinweis: Diese Funktion ist nur für entpackte Erweiterungen verfügbar, da sie nur während der Erweiterungsentwicklung verwendet werden soll.

Parameter

Gibt Folgendes zurück:

  • Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks werden aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

updateDynamicRules()

Promise 
chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
  callback?: function,
)

Ä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 im Erweiterungspaket 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 und höher
  • callback

    function optional

    Der Parameter callback sieht so aus: 

    () => void

Gibt Folgendes zurück:

  • Promise<void>

    Chrome 91 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks werden aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

updateEnabledRulesets()

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

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 die in options.enableRulesetIds aufgeführten Regelsätze hinzugefügt. Die aktivierten statischen Regelsätze werden zwischen Sitzungen beibehalten, aber nicht über Erweiterungsupdates hinweg. Das bedeutet, dass der Manifestschlüssel rule_resources die aktivierten statischen Regelsätze bei jedem Erweiterungsupdate bestimmt.

Parameter

  • Chrome 87 und höher
  • callback

    function optional

    Der Parameter callback sieht so aus: 

    () => void

Gibt Folgendes zurück:

  • Promise<void>

    Chrome 91 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks werden aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

updateSessionRules()

Versprechen Chrome 90 und höher 
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
  callback?: function,
)

Ändert die aktuellen Regeln auf Sitzungsebene 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 ü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

Gibt Folgendes zurück:

  • Promise<void>

    Chrome 91 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks werden aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

updateStaticRules()

Versprechen Chrome 111 und höher 
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
  callback?: function,
)

Deaktiviert und aktiviert einzelne statische Regeln in einer Ruleset. Änderungen an Regeln, die zu einer deaktivierten Ruleset gehören, werden bei der nächsten Aktivierung wirksam.

Parameter

Gibt Folgendes zurück:

  • Promise<void>

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks werden aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

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 gedacht ist.

Parameter