declarativeNetRequest

Um diese API zu nutzen, muss eine Erweiterung die Berechtigung "declarativeNetRequest" oder "declarativeNetRequestWithHostAccess" in ihrer manifest.json Datei anfordern.

Die "declarativeNetRequest"-Berechtigung erlaubt es Erweiterungen, Anfragen zu blockieren und zu upgraden, ohne jegliche Host-Berechtigungen. Host-Berechtigungen sind erforderlich, wenn die Erweiterung Anfragen umleiten oder Header auf Anfragen ändern möchte oder wenn die Berechtigung "declarativeNetRequestWithHostAccess" anstelle der "declarativeNetRequest"-Berechtigung verwendet wird. Um in diesen Fällen auf Anfragen zu reagieren, sind Host-Berechtigungen für die Anfrage-URL erforderlich. Für alle Anfragen, außer für Navigationsanfragen (d.h. Ressourcentyp main_frame und sub_frame), sind Host-Berechtigungen 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 von Erweiterungen nicht abgeglichen werden. Dazu gehören privilegierte Browser-Anfragen, Anfragen zu oder von eingeschränkten Domains und Anfragen von anderen Erweiterungen.

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

Die deklarativen Regeln sind durch vier Felder definiert:

• id – Eine ID, die eine Regel innerhalb eines Regelsets eindeutig identifiziert. Erforderlich und sollte >= 1 sein.
• priority – Die Regelpriorität. Wenn spezifiziert, sollte sie >= 1 sein. Standardwert ist 1. Details, wie die Priorität beeinflusst, welche Regeln angewendet werden, finden Sie unter Matching-Priorität.
• condition – Die condition, unter der diese Regel ausgelöst wird.
• action – Die action, die ergriffen werden soll, wenn die Regel übereinstimmt. Regeln können eines dieser Dinge tun:
  • eine Netzwerk-Anfrage blockieren.
  • eine Netzwerk-Anfrage umleiten.
  • Header von einer Netzwerk-Anfrage ändern.
  • verhindern, dass eine andere übereinstimmende Regel angewendet wird.

Dies ist ein Beispiel für eine Regel, die alle Skript-Anfragen blockiert, die von "foo.com" zu jeder URL mit "abc" als Substring stammen:

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

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

Regeln sind in Regelsets organisiert:

• statische Regelsets: Sammlungen von Regeln, die mit dem Manifestschlüssel"declarative_net_request" definiert und in der Erweiterung gespeichert sind. Eine Erweiterung kann statische Regelsets mit updateEnabledRulesets aktivieren und deaktivieren. Das Set der aktivierten statischen Regelsets wird über Sitzungen gespeichert, aber nicht über Erweiterungsupdates hinweg. Die statischen Regelsets, die bei der Installation und dem Update der Erweiterung aktiviert sind, werden durch den Inhalt des Manifestsclüssels "declarative_net_request" bestimmt.
• dynamische Regelsets: Regeln, die mit updateDynamicRules hinzugefügt oder entfernt werden. Diese Regeln bleiben über Sitzungen und Erweiterungsupdates hinweg bestehen.
• Session-Regelsets: Regeln, die mit updateSessionRules hinzugefügt oder entfernt werden. Diese Regeln werden nicht über Browsersitzungen hinweg beibehalten.

Eine Erweiterung kann:

• statische Regelsets im Manifestschlüssel "declarative_net_request" bis zum Wert von MAX_NUMBER_OF_STATIC_RULESETS spezifizieren.
• statische Regelsets (im Manifestschlüssel "declarative_net_request" oder programmatisch) aktivieren, 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 den Wert von MAX_NUMBER_OF_ENABLED_STATIC_RULESETS nicht überschreitet.

  Hinweis: Die Anzahl der Regeln in aktivierten statischen Regelsets für alle Erweiterungen darf das globale Limit nicht überschreiten. Erweiterungen sollten sich nicht darauf verlassen, dass das globale Limit einen bestimmten Wert hat; stattdessen sollten sie getAvailableStaticRuleCount verwenden, um die Anzahl zusätzlicher Regeln zu finden, 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.

Die Anzahl der dynamischen und sitzungsumfassenden Regeln, die eine Erweiterung hinzufügen kann, ist begrenzt 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, den Wert von MAX_NUMBER_OF_DYNAMIC_RULES und MAX_NUMBER_OF_SESSION_RULES

Wenn der Browser evaluiert, wie Anfragen gehandhabt werden sollen, überprüft er die Regeln jeder Erweiterung, die eine Bedingung haben, die mit der Anfrage übereinstimmt, und wählt diejenige aus, die wie folgt angewendet werden soll:

1. die Regelpriorität, wobei 1 die niedrigste Priorität ist (und Regeln standardmäßig den Wert 1 haben, wenn die Priorität nicht festgelegt ist).
   Wenn dies nicht zu einer Regelanwendung führt:
2. 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 denselben Effekt wie "allow" gilt jedoch auch für zukünftige Subressourcen-Ladevorgänge im Dokument (einschließlich nachrangiger Frames), die von der Anfrage generiert werden.
   3. "block" hebt die Anfrage auf.
   4. "upgradeScheme" aktualisiert das Schema der Anfrage.
   5. "redirect" leitet die Anfrage um.
   6. "modifyHeaders" ändert die Anforderungsoptionen oder Antwortheader oder beides.

Wenn nur eine Erweiterung eine Regel für die Anfrage liefert, wird diese Regel angewendet. Wenn jedoch mehr als eine Erweiterung eine übereinstimmende Regel hat, wählt der Browser diese in folgender Prioritätsreihenfolge aus:

1. "block"
2. "Umleitung" und "upgradeScheme"
3. "allow" und "allowAllRequests"

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

testMatchOutcome, getMatchedRules, und onRuleMatchedDebug sind verfügbar, um das Testen von Regeln und Regelsets zu unterstützen. Diese APIs erfordern die Berechtigungen "declarativeNetRequestFeedback". Zudem:

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

• Die declarativeNetRequest API evaluiert Netzwerk-Anfragen direkt im Browser. Dies macht sie leistungsfähiger als die webRequest API, bei der jede Netzwerk-Anfrage in JavaScript im Erweiterungsprozess bewertet wird.
• Da die Anfragen nicht durch den Erweiterungsprozess abgefangen werden, entfällt bei der deklarativen Netzwerk-Anfrage die Notwendigkeit für Erweiterungen, eine Hintergrundseite zu haben.
• Im Gegensatz zur webRequest API erfordert das Blockieren oder Upgraden von Anfragen mit der declarativeNetRequest API keine Host-Berechtigungen, wenn sie mit der declarativeNetRequest-Berechtigung verwendet wird.
• Die declarativeNetRequest API bietet den Nutzern besseren Datenschutz, da Erweiterungen die im Namen des Nutzers gestellten Netzwerk-Anfragen nicht lesen.
• (Nur Chrome:) Im Gegensatz zur webRequest API werden alle Bilder oder iframes, die mit der declarativeNetRequest API blockiert werden, automatisch im DOM zusammengeklappt.
• Bei der Entscheidung, ob eine Anfrage blockiert oder umgeleitet werden soll, wird der declarativeNetRequest API Vorrang vor der webRequest API eingeräumt, da sie eine synchrone Abfangmöglichkeit bietet. Ebenso sind alle Header, die über die declarativeNetRequest API entfernt werden, für Webanfrage-Erweiterungen nicht sichtbar.
• Die webRequest API ist flexibler als die declarativeNetRequest API, da sie es Erweiterungen ermöglicht, eine Anfrage programmgesteuert zu evaluieren.

declarativeNetRequest.MatchedRule

Details einer abgeglichenen Regel.

declarativeNetRequest.ModifyHeaderInfo

Die Anforderungs- oder Antwortheader, die für die Anfrage zu ändern sind.

declarativeNetRequest.Redirect

Details, wie die Umleitung durchgeführt werden sollte. Nur gültig für Umleitungsregeln.

declarativeNetRequest.ResourceType

Der Ressourcentyp einer Anfrage.

declarativeNetRequest.Rule

Ein Objekt mit Details zu einer Regel.

declarativeNetRequest.RuleAction

Ein Objekt, das die Aktion definiert, die ergriffen werden soll, wenn eine Regel übereinstimmt.

declarativeNetRequest.RuleCondition

Ein Objekt, das die Bedingung definiert, unter der eine Regel ausgelöst wird.

declarativeNetRequest.URLTransform

Ein Objekt mit Details zu einer URL-Transformation, die für eine Umleitungsaktion durchgeführt werden soll.

declarativeNetRequest.DYNAMIC_RULESET_ID

Regelset-ID für die von der Erweiterung hinzugefügten dynamischen Regeln.

declarativeNetRequest.GETMATCHEDRULES_QUOTA_INTERVAL

Der Zeitinterval, 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 über ihre aktivierten statischen Regelsets garantiert werden.

declarativeNetRequest.MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

Die Anzahl der Male, die declarativeNetRequest.getMatchedRules innerhalb eines Zeitraums von declarativeNetRequest.GETMATCHEDRULES_QUOTA_INTERVAL aufgerufen werden kann.

declarativeNetRequest.MAX_NUMBER_OF_DISABLED_STATIC_RULES

Die maximale Anzahl an statischen Regeln, die in jedem statischen Regelset deaktiviert werden können.

declarativeNetRequest.MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES Veraltet

Die maximale Anzahl an dynamischen und sitzungsumfassenden 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 sitzungsumfassenden 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 declarative_net_request.rule_resources-Manifestschlüssels spezifizieren kann.

declarativeNetRequest.SESSION_RULESET_ID

Die Regelset-ID für die von der Erweiterung hinzugefügten sitzungsumfassenden Regeln.

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 der 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 abgeglichenen Regeln zurück.

declarativeNetRequest.getSessionRules()

Gibt die Menge der sitzungsumfassenden Regeln für die Erweiterung zurück.

declarativeNetRequest.isRegexSupported()

Überprü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()

Überprüft, ob eine der declarativeNetRequest-Regeln der Erweiterung eine hypothetische Anfrage übereinstimmen würde.

declarativeNetRequest.updateDynamicRules()

Modifiziert 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()

Modifiziert die Menge der sitzungsumfassenden Regeln für die Erweiterung.

declarativeNetRequest.updateStaticRules()

Modifiziert den aktivierten Zustand von Regeln in einem statischen Regelset.

declarativeNetRequest.onRuleMatchedDebug

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

• dnr-block-only
• dnr-dynamic-with-options
• dnr-redirect-url