chrome.declarativeNetRequest

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 zu sehen, was für mehr Datenschutz sorgt.

Berechtigungen

declarativeNetRequest
declarativeNetRequestWithHostAccess

„declarativeNetRequest“ und "declarativeNetRequestWithHostAccess" Berechtigungen bieten die gleichen Funktionen. Der Unterschied besteht darin, dass Berechtigungen angefordert oder gewährt wurde.

"declarativeNetRequest"
Löst bei der Installation eine Berechtigungswarnung aus, bietet aber impliziten Zugriff auf allow-, allowAllRequests- und block-Regeln. Verwenden Sie diese Option, wenn möglich, um weil er vollen Zugriff auf Hosts anfordern muss.
"declarativeNetRequestFeedback"
Aktiviert Debugging-Funktionen für entpackte Erweiterungen, insbesondere getMatchedRules() und onRuleMatchedDebug.
"declarativeNetRequestWithHostAccess"
Bei der Installation wird keine Berechtigungswarnung angezeigt, du musst aber den Host anfordern Berechtigungen, bevor Sie auf einem Host eine Aktion ausführen können. Dieses wenn Sie deklarative Nettoanfrageregeln in einem Erweiterung, die bereits Hostberechtigungen hat, ohne zusätzliche Warnungen.

Verfügbarkeit

Chrome (ab Version 84)

Manifest

Zusätzlich zu den oben beschriebenen Berechtigungen erfordern bestimmte Regelsätze, insbesondere statische Regelsätze, die Deklaration des Manifestschlüssels "declarative_net_request". Dabei sollte es sich um ein Wörterbuch mit einem einzelnen Schlüssel namens "rule_resources" handeln. Dieser Schlüssel ist ein Array, das Wörterbücher vom Typ Ruleset enthält, wie im Folgenden dargestellt. Beachten Sie, dass der Name „Ruleset“ nicht im JSON-Format des Manifests vorkommt, da es sich dabei nur 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 einen oder mehrere Regelsätze an, um diese API zu verwenden. Ein Regelsatz enthält ein Array mit Regeln. Eine einzelne Regel führt einen der folgenden Schritte aus:

  • Netzwerkanfrage blockieren
  • Aktualisieren Sie das Schema (http auf https).
  • Verhindern Sie, dass eine Anfrage blockiert wird, indem Sie übereinstimmende blockierte Regeln ablehnen.
  • Eine Netzwerkanfrage weiterleiten
  • Ändern Sie Anfrage- oder Antwortheader.

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

Dynamisch
Die Apps bleiben über alle 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 gepackt, installiert und aktualisiert, wenn eine Erweiterung installiert oder aktualisiert wird. Statische Regeln werden in Regeldateien im JSON-Format gespeichert und in der Manifestdatei aufgelistet.

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 bestehen.
  • Sitzungsregeln werden gelöscht, wenn der Browser geschlossen wird und eine neue Version der Erweiterung installiert wird.

Für jeden dieser Regelsatztypen gibt es nur einen. Über eine Erweiterung können Regeln dynamisch hinzugefügt oder entfernt werden. Dazu werden updateDynamicRules() und updateSessionRules() aufgerufen, sofern die Regellimits nicht überschritten werden. Informationen zu Regelbeschränkungen finden Sie unter Regelbeschränkungen. Ein Beispiel dafür finden Sie unter Codebeispiele.

Statische Regelsätze

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

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

Lade deine entpackte Erweiterung, um Regeldateien zu testen. Fehler und Warnungen zu ungültigen statischen Regeln werden nur für entpackte Erweiterungen angezeigt. Ungültige statische Regeln in gepackten Erweiterungen werden ignoriert.

Beschleunigte Überprüfung

Für Änderungen an statischen Regelsätzen ist möglicherweise eine beschleunigte Überprüfung möglich. Weitere Informationen finden Sie unter beschleunigte Überprüfung möglicher Ä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 werden über mehrere Browsersitzungen hinweg beibehalten. Beides bleibt über die Aktualisierung der Erweiterung hinweg bestehen. Das bedeutet, dass nach einer Aktualisierung nur die Regeln verfügbar sind, die Sie in Ihren Regeldateien belassen haben.

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

Rufen Sie updateStaticRules() auf, um statische Regeln zu aktivieren oder zu deaktivieren. Diese Methode verwendet ein UpdateStaticRulesOptions-Objekt, das Arrays mit IDs der Regeln enthält, die aktiviert oder deaktiviert werden sollen. Die IDs werden mit dem Schlüssel "id" des Wörterbuchs Ruleset definiert. Es sind maximal 5.000 deaktivierte statische Regeln zulässig.

Rufen Sie zum Aktivieren oder Deaktivieren statischer Regelsätze 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 Wörterbuchs Ruleset definiert.

Regeln erstellen

Unabhängig vom Typ beginnt eine Regel mit vier Feldern, wie im Folgenden dargestellt. Während die Schlüssel "id" und "priority" eine Zahl enthalten, bieten die Schlüssel "action" und "condition" möglicherweise mehrere Blockierungs- und Weiterleitungsbedingungen. Mit der folgenden Regel werden alle Skriptanfragen von "foo.com" an URLs mit "abc" als Teilstring blockiert.

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

URL-Abgleich

Mit der deklarativen Nettoanfrage lassen sich URLs entweder anhand eines Musters übereinstimmende Syntax oder reguläre Ausdrücke.

Syntax für URL-Filter

Mit dem Schlüssel "condition" einer Regel kann ein "urlFilter"-Schlüssel auf URLs unter einer angegebenen Domain angewendet werden. Muster werden mithilfe von Tokens für den Musterabgleich erstellt. Hier sind 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 in der "regexFilter"-Schlüssel. Um mehr über die die für diese Bedingungen gelten, finden Sie unter Regeln, die reguläre Ausdrücke verwenden

Gute URL-Bedingungen schreiben

Achten Sie beim Schreiben von Regeln darauf, dass immer eine ganze Domain abgleicht. Andernfalls werden Ihre kann in unerwarteten Situationen als Übereinstimmung auftreten. Wenn Sie beispielsweise Musterabgleichssyntax:

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

Sie können Folgendes verwenden:

  • ||google.com/, die mit allen Pfaden und Subdomains übereinstimmt.
  • |https://www.google.com/, der mit allen Pfaden und ohne Subdomains übereinstimmt.

Analog können Sie die Zeichen ^ und / verwenden, um einen regulären Ausdruck zu verankern. Für Beispiel: ^https:\/\/www\.google\.com\/ stimmt mit jedem Pfad auf https://www.google.com.

Regelauswertung

DNR-Regeln werden vom Browser auf verschiedene Phasen des Lebenszyklus von Netzwerkanfragen angewendet.

Vor dem Antrag

Bevor eine Anfrage gestellt wird, kann eine Erweiterung sie mit einer Abgleichsregel blockieren oder weiterleiten (einschließlich Upgrade des Schemas von HTTP auf HTTPS).

Für jede Erweiterung bestimmt der Browser eine Liste mit übereinstimmenden Regeln. Regeln mit der Aktion modifyHeaders sind hier nicht enthalten. Sie werden später behandelt. Außerdem werden Regeln mit einer responseHeaders-Bedingung später berücksichtigt (sofern Antwortheader verfügbar sind) und sind nicht eingeschlossen.

Anschließend wählt Chrome für jede Erweiterung maximal einen Kandidaten pro Anfrage aus. Chrome sucht eine Übereinstimmungsregel, 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 der Kandidat eine allow- oder allowAllRequests-Regel ist oder der Frame, in dem die Anfrage gesendet wurde, zuvor mit einer allowAllRequests-Regel höherer oder gleicher Priorität dieser Erweiterung übereinstimmte, ist die Anfrage „zugelassen“. ohne Auswirkungen auf den Antrag.

Wenn diese Anfrage von mehreren Erweiterungen blockiert oder weitergeleitet werden soll, wird eine einzige Maßnahme ergriffen. Dazu sortiert Chrome die Regeln in der Reihenfolge block > redirect oder upgradeScheme > allow oder allowAllRequests. Wenn zwei Regeln denselben Typ haben, wählt Chrome die Regel aus der zuletzt installierten Erweiterung aus.

Bevor Anfrageheader gesendet werden

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

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

Diese Regeln werden von Chrome in der Reihenfolge angewendet, dass die Regeln einer kürzlich installierten Erweiterung immer vor den 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. Vorgänge zum Festlegen und Entfernen sind nicht zulässig.
  • Wenn eine Regel eine Kopfzeile festlegt, können nur Regeln mit niedrigerer Priorität aus derselben Erweiterung an diesen Header angehängt werden. Andere Änderungen sind nicht zulässig.
  • Wenn eine Regel eine Kopfzeile entfernt, können Regeln mit niedrigerer Priorität den Header nicht mehr ändern.

Nach Eingang einer Antwort

Nachdem 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 passende allow- oder allowAllRequests-Regel redundant gemacht wurden (dies geschieht genau wie unter „Vor der Anfrage“), kann Chrome die Anfrage im Namen einer Erweiterung blockieren oder weiterleiten.

Wenn eine Anfrage diesen Schritt erreicht hat, wurde die Anfrage bereits an den Server gesendet und der Server hat Daten wie den Anfragetext erhalten. Eine Blockier- oder Weiterleitungsregel mit einer Bedingung für Antwortheader wird zwar ausgeführt, aber die Anfrage kann nicht tatsächlich blockiert oder weitergeleitet werden.

Bei einer Blockierregel wird dies von der Seite durchgeführt, die die Anfrage veranlasst hat, eine blockierte Antwort zu erhalten, und Chrome die Anfrage vorzeitig beendet. Bei einer Weiterleitungsregel sendet Chrome eine neue Anfrage an die weitergeleitete URL. Überlegen Sie, ob diese Verhaltensweisen den Erwartungen an den Datenschutz für Ihre Erweiterung entsprechen.

Wenn die Anfrage nicht blockiert oder weitergeleitet wird, wendet Chrome alle modifyHeaders-Regeln an. Das Anwenden von Änderungen an Antwortheadern funktioniert genauso wie unter „Vor dem Senden von Anfrageheadern“ beschrieben. Änderungen an Anfrageheadern bewirken nichts, da die Anfrage bereits gestellt wurde.

Sichere Regeln

Sichere Regeln werden als Regeln mit der Aktion block, allow, allowAllRequests oder upgradeScheme. Diese Regeln unterliegen einem erhöhten Kontingent für dynamische Regeln.

Limits für Regeln

Das Laden und Auswerten von Regeln ist ein Mehr an Leistung, Daher gelten bei der Nutzung der API einige Einschränkungen. Limits hängen von der Art der der von Ihnen verwendeten Regel.

Statische Regeln

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

Wie viele Regeln danach verfügbar sind, hängt davon ab, wie viele Regeln von allen Erweiterungen, die im Browser eines Nutzers installiert sind, aktiviert werden. Sie finden diese Nummer zur Laufzeit, indem Sie getAvailableStaticRuleCount() aufrufen. Ein Beispiel dafür finden Sie unter Codebeispiele.

Sitzungsregeln

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

Vor Chrome 120 galt ein Limit von 5.000 kombinierten dynamischen und Sitzungsregeln.

Dynamische Regeln

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

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

Vor Chrome 120 galt ein Limit von 5.000 kombinierten dynamischen und Sitzungsregeln.

Regeln, die reguläre Ausdrücke verwenden

Alle Regeltypen können reguläre Ausdrücke verwenden. Die Gesamtzahl der Regeln für reguläre Ausdrücke 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 ungefähr 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

Ein deklarativeNetRequest gilt nur für Anfragen, die den Netzwerkstack erreichen. Dazu gehören Antworten aus dem HTTP-Cache, möglicherweise aber keine Antworten, die über den onfetch-Handler eines Service Workers gesendet werden. deklarativeNetRequest wirkt sich nicht auf Antworten aus, die vom Service Worker generiert oder aus CacheStorage abgerufen wurden, aber es wirkt sich auf Aufrufe von fetch() aus, die in einem Service Worker erfolgen.

Über das Internet zugängliche Ressourcen

Eine deklarativeNetRequest-Regel kann nicht von einer öffentlichen Ressourcenanfrage an eine Ressource weiterleiten, die nicht über das Internet zugänglich ist. Dadurch wird ein Fehler ausgelöst. Dies gilt auch dann, wenn die angegebene über das Web zugängliche Ressource der Weiterleitungserweiterung gehört. Mit dem Array "web_accessible_resources" des Manifests können Sie Ressourcen für deklarativeNetRequest deklarieren.

Headeränderung

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

Beispiele

Codebeispiele

Dynamische Regeln aktualisieren

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

// Get arrays containing new and old rules
const newRules = await getNewRules();
const oldRules = await chrome.declarativeNetRequest.getDynamicRules();
const oldRuleIds = oldRules.map(rule => rule.id);

// Use the arrays to update the dynamic rules
await chrome.declarativeNetRequest.updateDynamicRules({
  removeRuleIds: oldRuleIds,
  addRules: newRules
});

Statische Regelsätze aktualisieren

Das folgende Beispiel zeigt, wie Regelsätze unter Berücksichtigung der Anzahl der verfügbaren und der maximalen Anzahl aktivierter statischer Regelsätze aktiviert und deaktiviert werden. Dies ist sinnvoll, wenn die Anzahl der benötigten statischen Regeln die zulässige Anzahl überschreitet. Dazu müssen einige Ihrer Regelsätze installiert werden und einige davon deaktiviert sein. In der Manifestdatei muss "Enabled" auf false gesetzt sein.

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. Beim Überprüfen der Regeln empfiehlt es sich, die Priorisierungsregeln in einem separaten Fenster zu öffnen.

Die „Priorität“ Taste

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

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

Navigation zu https://google.com
Diese URL wird von zwei Regeln abgedeckt: den Regeln mit den IDs 1 und 4. Die Regel mit der ID 1 wird angewendet, weil "block" Aktionen eine höhere Priorität als "redirect" Aktionen haben. Die übrigen 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

Im folgenden Beispiel ist eine Hostberechtigung für *://*.example.com/* erforderlich.

Das folgende Beispiel zeigt, wie eine Anfrage von example.com an eine Seite in der Erweiterung selbst weitergeleitet wird. Der Erweiterungspfad /a.jpg wird in chrome-extension://EXTENSION_ID/a.jpg aufgelöst, wobei EXTENSION_ID die ID der Erweiterung ist. Damit dies funktioniert, sollte 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 wird der Schlüssel "transform" für die Weiterleitung zu einer Subdomain von beispiel.de verwendet. Dabei wird ein Domainname-Anker („||“) verwendet, um Anfragen mit einem beliebigen 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 werden reguläre Ausdrücke für die Weiterleitung von https://www.abc.xyz.com/path zu https://abc.xyz.com/path verwendet. Achten Sie im Schlüssel "regexFilter" darauf, wie Punkte maskiert werden und dass die Erfassungsgruppe entweder „abc“ auswählt oder „def“. Der Schlüssel "regexSubstitution" gibt die erste zurückgegebene Übereinstimmung des regulären Ausdrucks mithilfe von „\1“ an. In diesem Fall ist „abc“. wird 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 Subframes entfernt.

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

Typen

DomainType

Gibt an, ob die Anfrage der erste oder Drittanbieter des Frames ist, aus dem sie stammt. Eine Anfrage gilt als Erstanbieter, wenn sie dieselbe Domain (eTLD+1) wie der Frame hat, von dem die Anfrage stammt.

Enum

"firstParty"
Bei der Netzwerkanfrage handelt es sich um den Erstanbieter des Frames, aus dem sie stammt.

"thirdParty"
Die Netzwerkanfrage ist ein Drittanbieter des Frames, aus dem sie stammt.

ExtensionActionOptions

Chrome (ab Version 88)

Attribute

  • displayActionCountAsBadgeText

    Boolescher Wert optional

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

  • tabUpdate

    TabActionCountUpdate optional

    Chrome (ab Version 89)

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

GetDisabledRuleIdsOptions

Chrome 111 und höher

Attribute

  • rulesetId

    String

    Die ID, die einem statischen Ruleset entspricht.

GetRulesFilter

Chrome 111 und höher

Attribute

  • ruleIds

    number[] optional

    Wenn angegeben, werden nur Regeln mit übereinstimmenden IDs eingeschlossen.

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 bei values verwendet.

  • Header

    String

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

  • Werte

    string[] optional

    Wenn angegeben, wird diese Bedingung erfüllt, wenn der Wert des Headers mit mindestens einem Muster in dieser Liste übereinstimmt. Dies unterstützt den Abgleich von Header-Werten ohne Berücksichtigung der Groß-/Kleinschreibung sowie folgende Konstrukte:

    '*' : Stimmt mit einer beliebigen Anzahl von Zeichen überein.

    '?' : entspricht null oder einem Zeichen.

    * und "?" kann mit einem umgekehrten Schrägstrich maskiert werden, z.B. „\*“ und "\?"

HeaderOperation

Chrome (ab Version 86)

Dies beschreibt die möglichen Vorgänge für "modifyHeaders". Regel.

Enum

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

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

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

IsRegexSupportedResult

Chrome (ab Version 87)

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 von Ruleset, zu der diese Regel gehört. Bei einer Regel aus der Gruppe dynamischer Regeln entspricht dieser Wert DYNAMIC_RULESET_ID.

MatchedRuleInfo

Attribute

  • Regel

    MatchedRule

  • tabId

    Zahl

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

  • timeStamp

    Zahl

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

MatchedRuleInfoDebug

Attribute

MatchedRulesFilter

Attribute

  • minTimeStamp

    Zahl optional

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

  • tabId

    Zahl optional

    Wenn angegeben, werden nur Regeln für den angegebenen Tab abgeglichen. Stimmt mit Regeln überein, die mit keinem aktiven Tab verknüpft sind, wenn der Wert auf -1 gesetzt ist.

ModifyHeaderInfo

Chrome (ab Version 86)

Attribute

  • Header

    String

    Der Name des zu ändernden Headers.

  • Vorgang

    HeaderOperation

    Der für einen Header auszuführende Vorgang.

  • 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

    Falls wahr, wird der Abfrageschlüssel nur ersetzt, wenn er bereits vorhanden ist. Andernfalls wird der Schlüssel ebenfalls hinzugefügt, falls er fehlt. Die Standardeinstellung ist "false".

  • Wert

    String

QueryTransform

Attribute

  • addOrReplaceParams

    QueryKeyValue[] optional

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

  • removeParams

    string[] optional

    Die Liste der zu entfernenden Abfrageschlüssel.

Redirect

Attribute

  • extensionPath

    String optional

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

  • regexSubstitution

    String optional

    Ersetzungsmuster 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 umgekehrtem Schrägstrich (\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 an JavaScript-URLs sind nicht zulässig.

RegexOptions

Chrome (ab Version 87)

Attribute

  • isCaseSensitive

    Boolescher Wert optional

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

  • regex

    String

    Der normale Expresson, den es prüfen soll.

  • requireCapturing

    Boolescher Wert optional

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

RequestDetails

Attribute

  • documentId

    String optional

    Chrome 106 und höher

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

  • documentLifecycle

    DocumentLifecycle optional

    Chrome 106 und höher

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

  • frameId

    Zahl

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

  • frameType

    FrameType optional

    Chrome 106 und höher

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

  • Initiator

    String optional

    Der Ursprung, von dem die Anfrage initiiert wurde. Dies ändert sich durch Weiterleitungen nicht. Wenn dies ein undurchsichtiger Ursprung ist, wird der String „null“ verwendet werden.

  • method

    String

    Standard-HTTP-Methode.

  • parentDocumentId

    String optional

    Chrome 106 und höher

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

  • parentFrameId

    Zahl

    ID des Frames, der den Frame umschließt, der die Anfrage gesendet hat. Legen Sie diesen Wert auf -1 fest, wenn kein übergeordneter Frame vorhanden ist.

  • requestId

    String

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

  • tabId

    Zahl

    Die ID des Tabs, auf dem die Anfrage ausgeführt wird. Legen Sie den Wert auf -1 fest, wenn sich die Anfrage nicht auf einen Tab bezieht.

  • Der Ressourcentyp der Anfrage.

  • URL

    String

    Die URL der Anfrage.

RequestMethod

Chrome 91 und höher

Dies beschreibt die HTTP-Anfragemethode einer Netzwerkanfrage.

Enum

"verbinden"

„Löschen“

"get"

"head"

"Optionen"

"Patch"

"Beitrag"

"put"

"Sonstiges"

ResourceType

Dies beschreibt den Ressourcentyp der Netzwerkanfrage.

Enum

"main_frame"

"sub_frame"

"Stylesheet"

"script"

"Bild"

"Schriftart"

"Objekt"

"xmlhttprequest"

"ping"

"csp_report"

"Medien"

"websocket"

"webtransport"

"Webbundle"

"Sonstiges"

Rule

Attribute

  • Aktion

    RuleAction

    Die auszuführende Aktion bei einer Übereinstimmung mit dieser Regel.

  • condition

    RuleCondition

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

  • id

    Zahl

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

  • priorität

    Zahl optional

    Regelpriorität. Der Standardfaktor ist 1. Wenn dieses Flag angegeben wird, muss >= 1 sein.

RuleAction

Attribute

  • weiterleiten

    Weiterleitung optional

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

  • requestHeaders

    ModifyHeaderInfo[] optional

    Chrome (ab Version 86)

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

  • responseHeaders

    ModifyHeaderInfo[] optional

    Chrome (ab Version 86)

    Die Antwortheader, die für die Anfrage geändert werden sollen. Nur gültig, wenn RuleActionType auf „modifyHeaders“ festgelegt 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"
Netzwerkanfrage blockieren

"redirect"
Leitet die Netzwerkanfrage weiter.

"allow"
Lassen Sie die Netzwerkanfrage zu. Die Anfrage wird nicht abgefangen, wenn es eine Zulassungsregel gibt, die mit ihr übereinstimmt.

"upgradeScheme"
Stellen Sie das Schema der Netzwerkanfrage-URL auf "https" um, wenn die Anfrage HTTP oder FTP ist.

"modifyHeaders"
Anfrage-/Antwortheader aus der Netzwerkanfrage ändern

"allowAllRequests"
Alle Anfragen innerhalb einer Framehierarchie zulassen, einschließlich der Frameanfrage selbst.

RuleCondition

Attribute

  • domainType

    DomainType optional

    Gibt an, ob die Netzwerkanfrage eine Erstanbieter- oder Drittanbieteranfrage für die Domain ist, aus der sie stammt. Wenn keine Angabe gemacht wird, werden alle Anfragen akzeptiert.

  • Domains

    string[] optional

    <ph type="x-smartling-placeholder"></ph> Seit Chrome 101 verworfen

    Verwende stattdessen initiatorDomains

    Die Regel gleicht nur Netzwerkanfragen ab, die aus der Liste der domains stammen.

  • excludedDomains

    string[] optional

    <ph type="x-smartling-placeholder"></ph> Seit Chrome 101 verworfen

    Verwenden Sie stattdessen excludedInitiatorDomains.

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

  • excludedInitiatorDomains

    string[] optional

    Chrome 101 oder höher

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

    Hinweise:

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

    string[] optional

    Chrome 101 oder höher

    Die Regel gleicht keine Netzwerkanfragen ab, wenn die Domains mit einer Domain aus der Liste der excludedRequestDomains übereinstimmen. Wenn die Liste leer ist oder weggelassen wird, werden keine Domains ausgeschlossen. Dies hat Vorrang vor requestDomains.

    Hinweise:

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

    RequestMethod[] optional

    Chrome 91 und höher

    Liste der Anfragemethoden, die von der Regel nicht übereinstimmen. Es darf nur entweder requestMethods oder excludedRequestMethods angegeben werden. Wenn keine von beiden angegeben ist, werden alle Anfragemethoden als übereinstimmend eingestuft.

  • excludedResourceTypes

    ResourceType[] optional

    Liste der Ressourcentypen, auf die die Regel nicht zutrifft. Es darf nur entweder resourceTypes oder excludedResourceTypes angegeben werden. Wenn keiner von beiden angegeben ist, werden alle Ressourcentypen außer „main_frame“ blockiert sind.

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

    Liste mit tabs.Tab.id, denen die Regel nicht entsprechen soll. Die ID tabs.TAB_ID_NONE schließt Anfragen aus, die nicht von einem Tab stammen. Wird nur für Regeln auf Sitzungsebene unterstützt.

  • initiatorDomains

    string[] optional

    Chrome 101 oder höher

    Die Regel gleicht nur Netzwerkanfragen ab, die aus der Liste der initiatorDomains stammen. Wird die Liste nicht angegeben, 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 für internationalisierte Domains die Punycode-Codierung.
    • Dieser wird mit dem Initiator der Anfrage und nicht mit der Anfrage-URL abgeglichen.
    • Sub-Domains der aufgeführten Domains werden ebenfalls abgeglichen.
  • isUrlFilterCaseSensitive

    Boolescher Wert 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 zum Abgleich mit der Netzwerkanfrage-URL. Dies entspricht der RE2-Syntax.

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

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

  • requestDomains

    string[] optional

    Chrome 101 oder höher

    Die Regel gleicht nur dann Netzwerkanfragen ab, wenn die Domain mit einer Domain aus der Liste der requestDomains übereinstimmt. Wird die Liste nicht angegeben, 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 für internationalisierte Domains die Punycode-Codierung.
    • Sub-Domains der aufgeführten Domains werden ebenfalls abgeglichen.
  • requestMethods

    RequestMethod[] optional

    Chrome 91 und höher

    Liste der HTTP-Anfragemethoden, denen die Regel zugeordnet werden kann. Eine leere Liste ist nicht zulässig.

    Hinweis: Wenn Sie eine requestMethods-Regelbedingung angeben, werden auch Nicht-HTTP(s)-Anfragen ausgeschlossen. Dies gilt jedoch nicht für Anfragen von excludedRequestMethods.

  • resourceTypes

    ResourceType[] optional

    Liste der Ressourcentypen, denen die Regel zugeordnet werden kann. 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 stimmt überein, wenn die Anfrage einer Antwortheaderbedingung in dieser Liste entspricht (falls angegeben).

  • tabIds

    number[] optional

    Chrome 92 und höher

    Liste der tabs.Tab.id, denen die Regel entsprechen soll. Die ID 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 Netzwerkanfrage-URL abgeglichen wird. Unterstützte Konstrukte:

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

    '|' : Linker/rechter Anker: Bei Verwendung an beiden Enden des Musters wird der Anfang bzw. das Ende der URL angegeben.

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

    ^ : Trennzeichen: Damit wird nach allen Zeichen gesucht, mit Ausnahme von Buchstaben, Ziffern und folgenden Zeichen: _, -, . oder %. Er stimmt auch mit dem Ende der URL überein.

    Daher setzt sich urlFilter aus den folgenden Teilen zusammen: (optionaler linker Anker/Domainname-Anker) + Muster + (optionaler Anker rechts).

    Wenn keine Angabe gemacht wird, werden alle URLs abgeglichen. Ein leerer String ist nicht zulässig.

    Muster, die mit „||*“ beginnen, sind nicht zulässig. Verwenden Sie stattdessen *.

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

    Hinweis: urlFilter darf nur ASCII-Zeichen enthalten. Dieser wird mit einer URL abgeglichen, bei der der Host im Punycode-Format (bei internationalisierten Domains) und alle anderen Nicht-ASCII-Zeichen in utf-8 codiert sind. Wenn die Anforderungs-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 der Regelsatz standardmäßig aktiviert ist.

  • id

    String

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

  • Pfad

    String

    Der Pfad des JSON-Regelsatzes relativ zum Erweiterungsverzeichnis.

RulesMatchedDetails

Attribute

  • rulesMatchedInfo

    MatchedRuleInfo[]

    Regeln, die dem angegebenen Filter entsprechen.

TabActionCountUpdate

Chrome (ab Version 89)

Attribute

  • increment

    Zahl

    Der Wert, um den die Anzahl der Aktionen auf dem Tab erhöht werden soll. Negative Werte verringern die Anzahl.

  • 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 der hypothetischen Anfrage entsprechen.

TestMatchRequestDetails

Chrome 103 und höher

Attribute

  • Initiator

    String optional

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

  • method

    RequestMethod optional

    Standard-HTTP-Methode der hypothetischen Anfrage. Die Standardeinstellung ist „get“. für HTTP-Anfragen und wird für Nicht-HTTP-Anfragen ignoriert.

  • responseHeaders

    Objekt optional

    Ausstehend

    Die Header, die von einer hypothetischen Antwort ausgegeben werden, wenn die Anfrage vor dem Senden nicht blockiert oder weitergeleitet wird. Wird als Objekt dargestellt, das einen Headernamen einer Liste von Stringwerten zuordnet. Wenn nicht angegeben, würde die hypothetische Antwort leere Antwortheader zurückgeben, die Regeln entsprechen können, die Übereinstimmungen mit dem Fehlen von Headern aufweisen. Beispiel: {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}

  • tabId

    Zahl optional

    Die ID des Tabs, auf dem die hypothetische Anfrage ausgeführt wird. Muss nicht einer echten Tab-ID entsprechen. Der Standardwert ist -1, was bedeutet, dass sich die Anfrage nicht auf einen Tab bezieht.

  • Der Ressourcentyp der hypothetischen Anfrage.

  • URL

    String

    Die URL der hypothetischen Anfrage.

UnsupportedRegexReason

Chrome (ab Version 87)

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.

&quot;memoryLimitExceeded&quot;
Der reguläre Ausdruck überschreitet das Arbeitsspeicherlimit.

UpdateRuleOptions

Chrome (ab Version 87)

Attribute

  • addRules

    Regel[] optional

    Regeln, die hinzugefügt werden sollen.

  • removeRuleIds

    number[] optional

    IDs der zu entfernenden Regeln. Alle ungültigen IDs werden ignoriert.

UpdateRulesetOptions

Chrome (ab Version 87)

Attribute

  • disableRulesetIds

    string[] optional

    Die IDs, die einem statischen Ruleset entsprechen, das deaktiviert werden soll.

  • enableRulesetIds

    string[] optional

    Die IDs, die einem statischen Ruleset entsprechen, das aktiviert werden soll.

UpdateStaticRulesOptions

Chrome 111 und höher

Attribute

  • disableRuleIds

    number[] optional

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

  • 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; in diesem Fall wird das vorhandene Fragment gelöscht; oder mit „#“ beginnen.

  • Host

    String optional

    Der neue Host für die Anfrage.

  • Passwort

    String optional

    Das neue Passwort für die Anfrage.

  • Pfad

    String optional

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

  • Port

    String optional

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

  • Abfrage

    String optional

    Die neue Abfrage für die Anfrage. Sollte entweder leer sein; in diesem Fall wird die vorhandene Abfrage gelöscht; oder mit einem Fragezeichen beginnen soll.

  • queryTransform

    QueryTransform optional

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

  • Schema

    String optional

    Das neue Schema für die Anfrage. Zulässige Werte sind „http“, „https“ und „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 ausgeführt werden können (in Minuten angegeben). Weitere Aufrufe schlagen sofort fehl und es wird runtime.lastError festgelegt. Hinweis: getMatchedRules-Aufrufe, die mit einer Nutzergeste verknüpft sind, sind vom Kontingent ausgenommen.

Wert

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome (ab Version 89)

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

Wert

30.000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

Gibt an, wie oft 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

30.000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94 und höher

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

Wert

50

MAX_NUMBER_OF_REGEX_RULES

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

Wert

1.000

MAX_NUMBER_OF_SESSION_RULES

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

Die maximale Anzahl von „unsicher“ dynamische 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 „unsicher“ sitzungsbezogene Regeln, die eine Erweiterung hinzufügen kann.

Wert

5.000

SESSION_RULESET_ID

Chrome 90 und höher

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

Wert

"_session"

Methoden

getAvailableStaticRuleCount()

<ph type="x-smartling-placeholder"></ph> Versprechen Chrome (ab Version 89) 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
)

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

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (count: number) => void

    • Anzahl

      Zahl

Gibt Folgendes zurück:

  • Promise&lt;number&gt;

    Chrome 91 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

getDisabledRuleIds()

<ph type="x-smartling-placeholder"></ph> Versprechen Chrome 111 oder höher 
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
  callback?: function,
)

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

Parameter

  • Gibt den abzufragenden Regelsatz an.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      Zahl[]

Gibt Folgendes zurück:

  • Versprechen<number[]>

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

getDynamicRules()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
  callback?: function,
)

Gibt den aktuellen Satz dynamischer Regeln für die Erweiterung zurück. Aufrufer können die Liste der abgerufenen Regeln filtern, indem sie eine filter angeben.

Parameter

  • Filter

    GetRulesFilter optional

    Chrome 111 und höher

    Ein Objekt zum Filtern der Liste der abgerufenen Regeln.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (rules: Rule[]) => void

Gibt Folgendes zurück:

  • Promise<Regel[]>

    Chrome 91 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

getEnabledRulesets()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.declarativeNetRequest.getEnabledRulesets(
  callback?: function,
)

Gibt die IDs für den aktuellen Satz aktivierter statischer Regelsätze zurück.

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (rulesetIds: string[]) => void

    • rulesetIds

      String[]

Gibt Folgendes zurück:

  • Promise&lt;string[]&gt;

    Chrome 91 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

getMatchedRules()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
  callback?: function,
)

Gibt alle Regeln zurück, die mit der Erweiterung übereinstimmen. Aufrufer können die Liste übereinstimmender Regeln filtern, indem sie eine 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, für das vor mehr als fünf Minuten eine Übereinstimmung gefunden wurde, werden nicht zurückgegeben.

Parameter

Gibt Folgendes zurück:

  • Promise&lt;RulesMatchedDetails&gt;

    Chrome 91 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

getSessionRules()

<ph type="x-smartling-placeholder"></ph> Versprechen Chrome 90 oder höher 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
  callback?: function,
)

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

Parameter

  • Filter

    GetRulesFilter optional

    Chrome 111 und höher

    Ein Objekt zum Filtern der Liste der abgerufenen Regeln.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (rules: Rule[]) => void

Gibt Folgendes zurück:

  • Promise<Regel[]>

    Chrome 91 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

isRegexSupported()

<ph type="x-smartling-placeholder"></ph> Versprechen Chrome 87 oder 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:

  • Promise&lt;IsRegexSupportedResult&gt;

    Chrome 91 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

setExtensionActionOptions()

<ph type="x-smartling-placeholder"></ph> Versprechen Chrome (ab Version 88) 
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
  callback?: function,
)

Mit dieser Richtlinie wird konfiguriert, ob die Anzahl der Aktionen für Tabs als Badge-Text der Erweiterungsaktion angezeigt werden soll. So kann die Anzahl der Aktionen erhöht werden.

Parameter

  • callback

    Funktion optional

    Chrome (ab Version 89)

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome 91 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

testMatchOutcome()

<ph type="x-smartling-placeholder"></ph> Versprechen Chrome 103 und höher 
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
)

Prüft, ob eine der deklarativeNetRequest-Regeln der Erweiterung mit einer hypothetischen Anfrage übereinstimmt. Hinweis: Nur für entpackte Erweiterungen verfügbar, da diese ausschließlich für die Verwendung während der Entwicklung von Erweiterungen vorgesehen sind.

Parameter

Gibt Folgendes zurück:

  • Promise&lt;TestMatchOutcomeResult&gt;

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

updateDynamicRules()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
  callback?: function,
)

Ändert den aktuellen Satz dynamischer Regeln für die Erweiterung. Die in options.removeRuleIds aufgeführten Regeln mit den IDs werden zuerst entfernt. Anschließend 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 über mehrere Browsersitzungen hinweg und bei allen Erweiterungsupdates beibehalten.
  • Statische Regeln, die als Teil des Erweiterungspakets festgelegt wurden, können nicht mit dieser Funktion 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 (ab Version 87)
  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome 91 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

updateEnabledRulesets()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
  callback?: function,
)

Aktualisiert den Satz aktivierter statischer Regelsätze für die Erweiterung. Die in options.disableRulesetIds aufgeführten Regelsätze mit IDs werden zuerst entfernt und dann werden die in options.enableRulesetIds aufgeführten Regelsätze hinzugefügt. Beachten Sie, dass der Satz aktivierter statischer Regelsätze über mehrere Sitzungen hinweg beibehalten wird, jedoch nicht über Erweiterungsupdates hinweg. Das heißt, der Manifestschlüssel rule_resources bestimmt den Satz aktivierter statischer Regelsätze bei jeder Erweiterungsaktualisierung.

Parameter

  • Chrome (ab Version 87)
  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome 91 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

updateSessionRules()

<ph type="x-smartling-placeholder"></ph> Versprechen Chrome 90 oder höher 
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
  callback?: function,
)

Ändert den aktuellen Satz von sitzungsbezogenen Regeln für die Erweiterung. Die in options.removeRuleIds aufgeführten Regeln mit den IDs werden zuerst entfernt. Anschließend 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 sitzungsübergreifend, sondern im Arbeitsspeicher gesichert.
  • MAX_NUMBER_OF_SESSION_RULES ist die maximale Anzahl von Sitzungsregeln, die eine Erweiterung hinzufügen kann.

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome 91 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

updateStaticRules()

<ph type="x-smartling-placeholder"></ph> Versprechen Chrome 111 oder höher 
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
  callback?: function,
)

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

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback ü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 diese ausschließlich für die Fehlerbehebung vorgesehen ist.

Parameter