declarativeNetRequest

Diese API ermöglicht es Erweiterungen, Bedingungen und Aktionen zu spezifizieren, die beschreiben, wie Netzwerk-Anfragen behandelt werden sollen. Diese deklarativen Regeln ermöglichen es dem Browser, Netzwerk-Anfragen zu bewerten und zu modifizieren, ohne die Erweiterungen über einzelne Netzwerk-Anfragen zu benachrichtigen.

Berechtigungen

Um diese API zu nutzen, muss eine Erweiterung entweder die Berechtigung "declarativeNetRequest" oder "declarativeNetRequestWithHostAccess" in ihrer manifest.json Datei anfordern. Die Berechtigung "declarativeNetRequest" wird den Benutzern in den Berechtigungsaufforderungen angezeigt, die Berechtigung "declarativeNetRequestWithHostAccess" nicht.

Die Berechtigung "declarativeNetRequest" erlaubt es Erweiterungen, Anfragen zu blockieren und zu aktualisieren, ohne Hostberechtigungen. Hostberechtigungen sind erforderlich, wenn die Erweiterung Anfragen umleiten oder Header in Anfragen modifizieren möchte oder wenn die Berechtigung "declarativeNetRequestWithHostAccess" statt der Berechtigung "declarativeNetRequest" verwendet wird. Um auf Anfragen in diesen Fällen zu reagieren, sind Hostberechtigungen für die Anforderungs-URL erforderlich. Für alle Anfragen, außer Navigationsanfragen (d.h. Ressourcentyp main_frame und sub_frame), sind Hostberechtigungen auch für den Initiator der Anfrage erforderlich. Der Initiator einer Anfrage ist in der Regel das Dokument oder der Worker, der die Anfrage ausgelöst hat.

Einige Anfragen sind eingeschränkt und können nicht von Erweiterungen abgeglichen werden. Dazu gehören privilegierte Browser-Anfragen, Anfragen zu oder von eingeschränkten Domänen und Anfragen von anderen Erweiterungen.

Die Berechtigung "declarativeNetRequestFeedback" ist erforderlich, um getMatchedRules und onRuleMatchedDebug zu verwenden, da diese Informationen über abgeglichene deklarative Regeln zurückgeben. Weitere Informationen finden Sie unter Testen.

Regeln

Die deklarativen Regeln werden durch vier Felder definiert:

id – Eine ID, die eine Regel innerhalb eines Regelsets eindeutig identifiziert. Obligatorisch und sollte >= 1 sein.
priority – Die Priorität der Regel. Wenn angegeben, sollte sie >= 1 sein. Standardwert ist 1. Siehe Übereinstimmungspriorität für Details, wie die Priorität beeinflusst, welche Regeln angewendet werden.
condition – Die condition, unter der diese Regel ausgelöst wird.
action – Die action, die ergriffen wird, wenn die Regel übereinstimmt. Regeln können eines der folgenden Dinge tun:
- eine Netzwerk-Anfrage blockieren.
- eine Netzwerk-Anfrage umleiten.
- Header von einer Netzwerk-Anfrage modifizieren.
- verhindern, dass eine andere passende Regel angewendet wird.

Hinweis: Eine Umleitungsaktion leitet die Anfrage nicht um und die Anfrage wird wie gewohnt fortgesetzt, wenn:

die Aktion die Anfrage nicht ändert.
die Umleitungs-URL ungültig ist (z.B. der Wert von redirect.regexSubstitution ist keine gültige URL).

Dies ist eine Beispielregel, die alle Skriptanfragen blockiert, die von "foo.com" zu jeder URL mit "abc" als Teilstring stammen:

json

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

Das Feld urlFilter einer Regelbedingung wird verwendet, um das Muster zu spezifizieren, das mit der Anforderungs-URL abgeglichen wird. Siehe RuleCondition für Details. Einige Beispiele für URL-Filter sind:

`urlFilter`	Passt zu	Passt nicht zu
`"abc"`	https://abcd.com https://example.com/abcd	https://ab.com
`"abc*d"`	https://abcd.com https://example.com/abcxyzd	https://abc.com
`"\|\|a.example.com"`	https://a.example.com/ https://b.a.example.com/xyz	https://example.com/
`"\|https*"`	https://example.com	http://example.com/ http://https.com

Regelsets

Regeln sind in Regelsets organisiert:

statische Regelsets: Sammlungen von Regeln, die mit dem Manifest-Schlüssel "declarative_net_request" definiert und in der Erweiterung gespeichert sind. Eine Erweiterung kann statische Regelsets mit updateEnabledRulesets aktivieren und deaktivieren. Die Menge der aktivierten statischen Regelsets bleibt über Sitzungen hinweg bestehen, jedoch nicht über Erweiterungs-Updates. Die bei der Installation und dem Update der Erweiterung aktivierten statischen Regelsets werden durch den Inhalt des Manifest-Schlüssels "declarative_net_request" bestimmt.
dynamisches Regelset: Regeln, die mit updateDynamicRules hinzugefügt oder entfernt werden. Diese Regeln bleiben über Sitzungen und Erweiterungs-Updates hinweg erhalten.
Sitzungsregelset: Regeln, die mit updateSessionRules hinzugefügt oder entfernt werden. Diese Regeln bleiben nicht über Browser-Sitzungen hinweg erhalten.

Hinweis: Fehler und Warnungen über ungültige statische Regeln werden nur während des Tests angezeigt. Ungültige statische Regeln in dauerhaft installierten Erweiterungen werden ignoriert. Daher ist es wichtig, sicherzustellen, dass Ihre statischen Regelsets durch Tests gültig sind.

Grenzen

Statik-Regelset-Grenzen

Eine Erweiterung kann:

statische Regelsets im Manifest-Schlüssel "declarative_net_request" bis zum Wert von MAX_NUMBER_OF_STATIC_RULESETS angeben.
statische Regelsets aktivieren (im Manifest-Schlüssel "declarative_net_request" oder programmatisch), sodass die Anzahl der Regeln (aktiviert oder deaktiviert), die sie enthalten, den Wert von GUARANTEED_MINIMUM_STATIC_RULES nicht überschreitet und die Anzahl der aktivierten statischen Regelsets nicht den Wert von MAX_NUMBER_OF_ENABLED_STATIC_RULESETS überschreitet.

Hinweis: Die Anzahl der Regeln in aktivierten statischen Regelsets für alle Erweiterungen darf das globale Limit nicht überschreiten. Erweiterungen sollten nicht davon ausgehen, dass das globale Limit einen bestimmten Wert hat; stattdessen sollten sie getAvailableStaticRuleCount verwenden, um die Anzahl der zusätzlichen Regeln zu ermitteln, die sie aktivieren können.
Regeln in statischen Regelsets bis zum Wert von MAX_NUMBER_OF_DISABLED_STATIC_RULES deaktivieren. Diese deaktivierten Regeln zählen jedoch zu den GUARANTEED_MINIMUM_STATIC_RULES.

Dynamische und sitzungsgesteuerte Regeln

Die Anzahl der dynamischen und sitzungsgesteuerten Regeln, die eine Erweiterung hinzufügen kann, ist beschränkt auf:

In Safari und bis Chrome 119 und Firefox 127 den Wert von MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES.
Ab Chrome 120 und Firefox 128 die Werte von MAX_NUMBER_OF_DYNAMIC_RULES und MAX_NUMBER_OF_SESSION_RULES.

Übereinstimmungspriorität

Wenn der Browser bewertet, wie Anfragen behandelt werden sollen, prüft er die Regeln jeder Erweiterung, die eine Bedingung haben, die zur Anfrage passt, und wählt die aus, die in folgender Reihenfolge angewendet werden soll:

die Regelpriorität, wobei 1 die niedrigste Priorität ist (und Regeln auf 1 standardsetzen, wenn keine Priorität festgelegt ist).
Wenn dies nicht zu einer Regel führt, die angewendet werden soll:
die Regelaktion, in der folgenden Reihenfolge der Priorität:
1. "allow", was bedeutet, dass alle anderen verbleibenden Regeln ignoriert werden.
2. "allowAllRequests" (nur für die Ressourcentypen main_frame und sub_frame) hat den gleichen Effekt wie "allow", gilt jedoch auch für zukünftige Subressourcen-Ladungen im Dokument (einschließlich der Nachkommen-Frames), die aus der Anfrage generiert werden.
3. "block" storniert die Anfrage.
4. "upgradeScheme" aktualisiert das Schema der Anfrage.
5. "redirect" leitet die Anfrage um.
6. "modifyHeaders" schreibt Anforderungs- oder Antwort-Header oder beide um.

Hinweis: Wenn mehrere übereinstimmende Regeln die gleiche Regelpriorität und den gleichen Regelaktionstyp haben, kann das Ergebnis unklar sein, wenn die übereinstimmende Aktion zusätzliche Eigenschaften unterstützt. Diese Eigenschaften können zu Ergebnissen führen, die nicht kombiniert werden können. Beispielsweise:

Die Aktion "block" unterstützt keine zusätzlichen Eigenschaften und daher besteht keine Uneinigkeit: Alle übereinstimmenden "block"-Aktionen würden zum gleichen Ergebnis führen.
Die "redirect"-Aktion leitet eine Anfrage an ein Ziel um. Wenn mehrere "redirect"-Aktionen übereinstimmen, wird alle außer einer "redirect"-Aktion ignoriert. Es ist jedoch weiterhin möglich, wiederholt umzuleiten, wenn die umgeleitete Anfrage eine weitere Regelbedingung erfüllt.
Mehrere "modifyHeaders"-Aktionen können unabhängig voneinander angewendet werden, wenn sie unterschiedliche Header betreffen. Das Ergebnis ist unklar, wenn sie denselben Header betreffen, da einige Kombinationen von Operationen nicht erlaubt sind (wie bei declarativeNetRequest.ModifyHeaderInfo erklärt). Die Evaluierungsreihenfolge der "modifyHeaders"-Aktionen ist daher wichtig.

Um die Reihenfolge zu steuern, in der Aktionen angewendet werden, weisen Sie den Regeln, deren Prioritätsreihenfolge wichtig ist, unterschiedliche priority-Werte zu.

Hinweis: Nach Regelpriorität und Regelaktion berücksichtigt Firefox das Regelset, zu dem die Regel gehört, in dieser Prioritätsordnung: Sitzung > dynamisch > Sitzungsregelsets. Dies kann nicht über alle Browser hinweg als gegeben angesehen werden, siehe WECG Issue 280.

Wenn nur eine Erweiterung eine Regel für die Anfrage vorgibt, wird diese Regel angewendet. Wenn jedoch mehr als eine Erweiterung eine passende Regel hat, wählt der Browser die zu anwendende Regel in dieser Prioritätsreihenfolge aus:

"block"
"redirect" und "upgradeScheme"
"allow" und "allowAllRequests"

Wenn die Anfrage nicht blockiert oder umgeleitet wurde, werden die übereinstimmenden modifyHeaders-Aktionen angewendet, wie in declarativeNetRequest.ModifyHeaderInfo dokumentiert.

Testen

testMatchOutcome, getMatchedRules und onRuleMatchedDebug stehen zur Verfügung, um beim Testen von Regeln und Regelsets zu helfen. Diese APIs erfordern die Berechtigung "declarativeNetRequestFeedback". Zusätzlich:

in Chrome sind diese APIs nur für nicht geparkte Erweiterungen verfügbar.
in Firefox sind diese APIs nur verfügbar, nachdem die extensions.dnr.feedback-Einstellung auf true gesetzt wurde. Diese Einstellung kann mit about:config oder dem --pref-Flag des web-ext-CLI-Werkzeugs gesetzt werden.

Vergleich mit der webRequest API

Die API declarativeNetRequest bewertet Netzwerk-Anfragen direkt im Browser. Dies macht sie leistungsstärker als die webRequest API, bei der jede Netzwerk-Anfrage in JavaScript im Erweiterungsprozess ausgewertet wird.
Da die Anfragen nicht vom Erweiterungsprozess abgefangen werden, entfernt declarativeNetRequest die Notwendigkeit für Erweiterungen, eine Hintergrundseite zu haben.
Anders als die webRequest API erfordert das Blockieren oder Aktualisieren von Anfragen mit der API declarativeNetRequest keine Hostberechtigungen, wenn sie mit der Berechtigung declarativeNetRequest verwendet wird.
Die API declarativeNetRequest bietet den Nutzern besseren Datenschutz, da Erweiterungen die im Namen des Nutzers durchgeführten Netzwerk-Anfragen nicht lesen.
(Nur Chrome:) Im Gegensatz zur webRequest API werden alle Bilder oder Iframes, die mit der API declarativeNetRequest blockiert werden, automatisch im DOM geschlossen.
Beim Entscheiden, ob eine Anfrage blockiert oder umgeleitet werden soll, erhält die API declarativeNetRequest gegenüber der webRequest API Vorrang, da sie eine synchrone Abfangmöglichkeit bietet. Ebenso werden alle mittels der API declarativeNetRequest entfernten Header nicht für Webanfrage-Erweiterungen sichtbar gemacht.
Die webRequest API ist flexibler als die declarativeNetRequest API, da sie es Erweiterungen ermöglicht, eine Anfrage programmatisch zu bewerten.

Typen

declarativeNetRequest.HeaderInfo: Der Antwort-Header, der für die Anfrage zu übereinstimmen ist, deklariert im Array rule.condition.excludedResponseHeaders oder im Array rule.condition.responseHeaders.
declarativeNetRequest.MatchedRule: Details einer übereinstimmenden Regel.
declarativeNetRequest.ModifyHeaderInfo: Die Anforderungs- oder Antwort-Header, die für die Anfrage modifiziert werden sollten.
declarativeNetRequest.Redirect: Details, wie die Umleitung erfolgen sollte. Nur gültig für Umleitungsregeln.
declarativeNetRequest.ResourceType: Der Ressourcentyp einer Anfrage.
declarativeNetRequest.Rule: Ein Objekt, das die Details einer Regel enthält.
declarativeNetRequest.RuleAction: Ein Objekt, das die zu ergreifende Aktion beschreibt, wenn eine Regel übereinstimmt.
declarativeNetRequest.RuleCondition: Ein Objekt, das die Bedingung beschreibt, unter der eine Regel ausgelöst wird.
declarativeNetRequest.URLTransform: Ein Objekt, das die Details einer URL-Transformation enthält, die für eine Umleitungsaktion durchgeführt werden soll.

Eigenschaften

declarativeNetRequest.DYNAMIC_RULESET_ID: Regelset-ID für die dynamischen Regeln, die von der Erweiterung hinzugefügt wurden.
declarativeNetRequest.GETMATCHEDRULES_QUOTA_INTERVAL: Das Zeitintervall, innerhalb dessen declarativeNetRequest.MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL declarativeNetRequest.getMatchedRules-Aufrufe gemacht werden können.
declarativeNetRequest.GUARANTEED_MINIMUM_STATIC_RULES: Die minimale Anzahl an statischen Regeln, die einer Erweiterung in ihren aktivierten statischen Regelsets garantiert wird.
declarativeNetRequest.MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL: Die Anzahl der für declarativeNetRequest.getMatchedRules erlaubten Aufrufe innerhalb eines Zeitraums von declarativeNetRequest.GETMATCHEDRULES_QUOTA_INTERVAL.
declarativeNetRequest.MAX_NUMBER_OF_DISABLED_STATIC_RULES: Die maximale Anzahl an statischen Regeln, die auf jedem statischen Regelset deaktiviert werden können.
declarativeNetRequest.MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES Veraltet: Die maximale Anzahl an dynamischen und sitzungsgesteuerten Regeln, die eine Erweiterung hinzufügen kann.
declarativeNetRequest.MAX_NUMBER_OF_DYNAMIC_RULES: Die maximale Anzahl an dynamischen Regeln, die eine Erweiterung hinzufügen kann.
declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS: Die maximale Anzahl an statischen Regelsets, die eine Erweiterung aktivieren kann.
declarativeNetRequest.MAX_NUMBER_OF_REGEX_RULES: Die maximale Anzahl an regulären Ausdrucksregeln, die eine Erweiterung hinzufügen kann.
declarativeNetRequest.MAX_NUMBER_OF_SESSION_RULES: Die maximale Anzahl an sitzungsgesteuerten Regeln, die eine Erweiterung hinzufügen kann.
declarativeNetRequest.MAX_NUMBER_OF_STATIC_RULESETS: Die maximale Anzahl an statischen Regelsets, die eine Erweiterung als Teil des Manifests declarative_net_request.rule_resources angeben kann.
declarativeNetRequest.SESSION_RULESET_ID: Die Regelset-ID für die von der Erweiterung hinzugefügten sitzungsgesteuerten Regeln.

Funktionen

declarativeNetRequest.getAvailableStaticRuleCount(): Gibt die Anzahl der statischen Regeln zurück, die eine Erweiterung aktivieren kann, bevor das globale statische Regel-Limit erreicht ist.
declarativeNetRequest.getDisabledRuleIds(): Gibt die IDs der deaktivierten Regeln in einem statischen Regelset zurück.
declarativeNetRequest.getDynamicRules(): Gibt die Menge an dynamischen Regeln für die Erweiterung zurück.
declarativeNetRequest.getEnabledRulesets(): Gibt die IDs für die Menge der aktivierten statischen Regelsets zurück.
declarativeNetRequest.getMatchedRules(): Gibt alle für die Erweiterung übereinstimmenden Regeln zurück.
declarativeNetRequest.getSessionRules(): Gibt die Menge der sitzungsgesteuerten Regeln für die Erweiterung zurück.
declarativeNetRequest.isRegexSupported(): Prüft, ob ein regulärer Ausdruck als declarativeNetRequest.RuleCondition.regexFilter Regelbedingung unterstützt wird.
declarativeNetRequest.setExtensionActionOptions(): Konfiguriert, wie die Aktionsanzahl für Tabs gehandhabt wird.
declarativeNetRequest.testMatchOutcome(): Prüft, ob eine der declarativeNetRequest-Regeln der Erweiterung zu einer hypothetischen Anfrage passen würde.
declarativeNetRequest.updateDynamicRules(): Ändert die aktive Menge an dynamischen Regeln für die Erweiterung.
declarativeNetRequest.updateEnabledRulesets(): Aktualisiert die Menge der aktiven statischen Regelsets für die Erweiterung.
declarativeNetRequest.updateSessionRules(): Ändert die Menge der sitzungsgesteuerten Regeln für die Erweiterung.
declarativeNetRequest.updateStaticRules(): Ändert den aktivierten Zustand von Regeln in einem statischen Regelset.

Ereignisse

declarativeNetRequest.onRuleMatchedDebug: Wird ausgelöst, wenn eine Regel mit einer Anfrage übereinstimmt, wenn eine Erweiterung mit der Berechtigung "declarativeNetRequestFeedback" debuggt wird.