chrome.declarativeWebRequest

Beschreibung

Hinweis:Diese API wird nicht mehr unterstützt. Sehen Sie sich stattdessen die declarativeNetRequest API an. Verwenden Sie die chrome.declarativeWebRequest API, um Anfragen während der Übertragung abzufangen, zu blockieren oder zu ändern. Sie ist deutlich schneller als die chrome.webRequest API, da Sie Regeln registrieren können, die im Browser und nicht in der JavaScript-Engine ausgewertet werden. Dadurch werden Roundtrip-Latenzen reduziert und die Effizienz gesteigert.

Berechtigungen

declarativeWebRequest

Sie müssen die Berechtigung „declarativeWebRequest“ im Erweiterungsmanifest deklarieren, um diese API zusammen mit Hostberechtigungen verwenden zu können.

{
  "name": "My extension",
  ...
  "permissions": [
    "declarativeWebRequest",
    "*://*/*"
  ],
  ...
}

Verfügbarkeit

Betaversion ≤ MV2

Manifest

Bestimmte Arten von nicht sensiblen Aktionen erfordern keine Hostberechtigungen:

  • CancelRequest
  • IgnoreRules
  • RedirectToEmptyDocument
  • RedirectToTransparentImage

Für die Aktion SendMessageToExtension() sind Hostberechtigungen für alle Hosts erforderlich, für deren Netzwerkanfragen eine Nachricht ausgelöst werden soll.

Für alle anderen Aktionen sind Hostberechtigungen für alle URLs erforderlich.

Wenn "https://*.google.com/*" beispielsweise die einzige Hostberechtigung ist, die eine Erweiterung hat, kann sie eine Regel einrichten, um:

  • Anfrage an https://www.google.com oder https://anything.else.com abbrechen
  • Eine Nachricht senden, wenn Sie zu https://www.google.com navigieren, aber nicht zu https://something.else.com.

Die Erweiterung kann keine Regel zum Weiterleiten von https://www.google.com zu https://mail.google.com einrichten.

Regeln

Die Declarative Web Request API folgt den Konzepten der Declarative API. Sie können Regeln für das Ereignisobjekt chrome.declarativeWebRequest.onRequest registrieren.

Die Declarative Web Request API unterstützt nur einen Typ von Abgleichskriterien, nämlich RequestMatcher. Die RequestMatcher-Bedingung stimmt mit Netzwerkanfragen überein, wenn und nur wenn alle aufgeführten Kriterien erfüllt sind. Der folgende RequestMatcher würde einer Netzwerkanfrage entsprechen, wenn der Nutzer https://www.example.com in die Omnibox eingibt:

var matcher = new chrome.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com', schemes: ['http'] },
  resourceType: ['main_frame']
});

Anfragen an https://www.example.com würden aufgrund des Schemas von RequestMatcher abgelehnt. Auch alle Anfragen für ein eingebettetes iFrame würden aufgrund der resourceType abgelehnt.

Wenn Sie alle Anfragen an „example.com“ abbrechen möchten, können Sie eine Regel so definieren:

var rule = {
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'example.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]
};

Wenn Sie alle Anfragen an example.com und foobar.com abbrechen möchten, können Sie eine zweite Bedingung hinzufügen, da jede Bedingung ausreicht, um alle angegebenen Aktionen auszulösen:

var rule2 = {
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'example.com' } }),
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'foobar.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]
};

So registrieren Sie Regeln:

chrome.declarativeWebRequest.onRequest.addRules([rule2]);

Bewertung von Bedingungen und Aktionen

Die Declarative Web Request API folgt dem Lebenszyklusmodell für Webanfragen der Web Request API. Das bedeutet, dass Bedingungen nur in bestimmten Phasen einer Webanfrage getestet und Aktionen auch nur in bestimmten Phasen ausgeführt werden können. In den folgenden Tabellen sind die Anforderungsphasen aufgeführt, die mit Bedingungen und Aktionen kompatibel sind.

Anfragephasen, in denen Bedingungsattribute verarbeitet werden können.
Bedingungsattribut onBeforeRequest onBeforeSendHeaders onHeadersReceived onAuthRequired
url ✓ ✓ ✓ ✓
resourceType ✓ ✓ ✓ ✓
contentType ✓
excludeContentType ✓
responseHeaders ✓
excludeResponseHeaders ✓
requestHeaders ✓
excludeRequestHeaders ✓
thirdPartyForCookies ✓ ✓ ✓ ✓
Anfragephasen, in denen Aktionen ausgeführt werden können.
Ereignis onBeforeRequest onBeforeSendHeaders onHeadersReceived onAuthRequired
AddRequestCookie ✓
AddResponseCookie ✓
AddResponseHeader ✓
CancelRequest ✓ ✓ ✓ ✓
EditRequestCookie ✓
EditResponseCookie ✓
IgnoreRules ✓ ✓ ✓ ✓
RedirectByRegEx ✓ ✓
RedirectRequest ✓ ✓
RedirectToEmptyDocument ✓ ✓
RedirectToTransparentImage ✓ ✓
RemoveRequestCookie ✓
RemoveRequestHeader ✓
RemoveResponseCookie ✓
RemoveResponseHeader ✓
SendMessageToExtension ✓ ✓ ✓ ✓
SetRequestHeader ✓

Regeln mit Prioritäten überschreiben

Regeln können Prioritäten zugewiesen werden, wie in der Events API beschrieben. Mit diesem Mechanismus können Ausnahmen ausgedrückt werden. Im folgenden Beispiel werden alle Anfragen an Bilder mit dem Namen evil.jpg blockiert, mit Ausnahme des Servers „myserver.com“.

var rule1 = {
  priority: 100,
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
        url: { pathEquals: 'evil.jpg' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]
};
var rule2 = {
  priority: 1000,
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: '.myserver.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.IgnoreRules({
      lowerPriorityThan: 1000 })
  ]
};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

Es ist wichtig zu wissen, dass die IgnoreRules-Aktion nicht über Anfragephasen hinweg beibehalten wird. Alle Bedingungen aller Regeln werden in jeder Phase einer Webanfrage ausgewertet. Wenn eine IgnoreRules-Aktion ausgeführt wird, gilt sie nur für andere Aktionen, die für dieselbe Webanfrage in derselben Phase ausgeführt werden.

Typen

AddRequestCookie

Fügt der Anfrage ein Cookie hinzu oder überschreibt ein Cookie, falls bereits ein anderes Cookie mit demselben Namen vorhanden ist. Es wird empfohlen, die Cookies API zu verwenden, da dies rechentechnisch weniger aufwendig ist.

Properties

AddResponseCookie

Fügt der Antwort ein Cookie hinzu oder überschreibt ein Cookie, falls bereits ein anderes Cookie mit demselben Namen vorhanden ist. Es wird empfohlen, die Cookies API zu verwenden, da dies rechentechnisch weniger aufwendig ist.

Properties

AddResponseHeader

Fügt der Antwort auf diese Webanfrage den Antwortheader hinzu. Da mehrere Antwortheader denselben Namen haben können, müssen Sie zuerst einen vorhandenen Antwortheader entfernen und dann einen neuen hinzufügen, um ihn zu ersetzen.

Properties

CancelRequest

Deklarative Ereignisaktion, mit der eine Netzwerkanfrage abgebrochen wird.

Properties

EditRequestCookie

Bearbeitet einen oder mehrere Cookies der Anfrage. Es wird empfohlen, die Cookies API zu verwenden, da dies rechentechnisch weniger aufwendig ist.

Properties

  • Konstruktor

    void

    Die constructor-Funktion sieht so aus: 

    (arg: EditRequestCookie) => {...}

  • filtern

    RequestCookie

    Filter für Cookies, die geändert werden sollen. Alle leeren Einträge werden ignoriert.

  • Änderung

    RequestCookie

    Attribute, die in Cookies überschrieben werden sollen, die dem Filter entsprechen. Attribute, die auf einen leeren String gesetzt sind, werden entfernt.

EditResponseCookie

Bearbeitet einen oder mehrere Cookies der Antwort. Es wird empfohlen, die Cookies API zu verwenden, da dies rechentechnisch weniger aufwendig ist.

Properties

  • Konstruktor

    void

    Die constructor-Funktion sieht so aus: 

    (arg: EditResponseCookie) => {...}

  • Filter für Cookies, die geändert werden sollen. Alle leeren Einträge werden ignoriert.

  • Änderung

    ResponseCookie

    Attribute, die in Cookies überschrieben werden sollen, die dem Filter entsprechen. Attribute, die auf einen leeren String gesetzt sind, werden entfernt.

FilterResponseCookie

Ein Filter für ein Cookie in HTTP-Antworten.

Properties

  • ageLowerBound

    number optional

    Inklusive Untergrenze für die Cookie-Lebensdauer (in Sekunden nach der aktuellen Zeit). Nur Cookies, deren Ablaufdatum auf „now + ageLowerBound“ oder später festgelegt ist, erfüllen dieses Kriterium. Sitzungscookies erfüllen das Kriterium dieses Filters nicht. Die Cookie-Lebensdauer wird anhand der Cookie-Attribute „max-age“ oder „expires“ berechnet. Wenn beide angegeben sind, wird „max-age“ verwendet, um die Cookie-Lebensdauer zu berechnen.

  • ageUpperBound

    number optional

    Inklusive Obergrenze für die Cookie-Lebensdauer (in Sekunden nach der aktuellen Zeit). Nur Cookies, deren Ablaufdatum im Intervall [jetzt, jetzt + ageUpperBound] liegt, erfüllen dieses Kriterium. Sitzungscookies und Cookies, deren Ablaufdatum in der Vergangenheit liegt, erfüllen das Kriterium dieses Filters nicht. Die Cookie-Lebensdauer wird anhand der Cookie-Attribute „max-age“ oder „expires“ berechnet. Wenn beide angegeben sind, wird „max-age“ verwendet, um die Cookie-Lebensdauer zu berechnen.

  • Domain

    String optional

    Wert des Cookie-Attributs „Domain“.

  • Gültig bis

    String optional

    Wert des Cookie-Attributs „Expires“.

  • httpOnly

    String optional

    Vorhandensein des HttpOnly-Cookie-Attributs.

  • maxAge

    number optional

    Wert des Cookie-Attributs „Max-Age“

  • name

    String optional

    Name eines Cookies.

  • Pfad

    String optional

    Wert des Cookie-Attributs „Path“.

  • sicher

    String optional

    Vorhandensein des Secure-Cookie-Attributs.

  • sessionCookie

    Boolesch optional

    Filtert Sitzungscookies. Für Sitzungscookies ist in den Attributen „max-age“ oder „expires“ keine Lebensdauer angegeben.

  • Wert

    String optional

    Wert eines Cookies, der in doppelte Anführungszeichen gesetzt werden kann.

HeaderFilter

Filtert Anfrageheader nach verschiedenen Kriterien. Mehrere Kriterien werden als Konjunktion ausgewertet.

Properties

  • nameContains

    String | String[] optional

    Die Bedingung wird erfüllt, wenn der Headername alle angegebenen Strings enthält.

  • nameEquals

    String optional

    Wird abgeglichen, wenn der Headername dem angegebenen String entspricht.

  • namePrefix

    String optional

    Entspricht, wenn der Headername mit dem angegebenen String beginnt.

  • nameSuffix

    String optional

    Entspricht, wenn der Headername mit dem angegebenen String endet.

  • valueContains

    String | String[] optional

    Die Bedingung wird erfüllt, wenn der Headerwert alle angegebenen Strings enthält.

  • valueEquals

    String optional

    Trifft zu, wenn der Headerwert mit dem angegebenen String übereinstimmt.

  • valuePrefix

    String optional

    Stimmt überein, wenn der Headerwert mit dem angegebenen String beginnt.

  • valueSuffix

    String optional

    Trifft zu, wenn der Headerwert mit dem angegebenen String endet.

IgnoreRules

Maskiert alle Regeln, die den angegebenen Kriterien entsprechen.

Properties

  • Konstruktor

    void

    Die constructor-Funktion sieht so aus: 

    (arg: IgnoreRules) => {...}

  • hasTag

    String optional

    Wenn diese Option festgelegt ist, werden Regeln mit dem angegebenen Tag ignoriert. Das Ignorieren wird nicht beibehalten, sondern wirkt sich nur auf Regeln und ihre Aktionen in derselben Phase der Netzwerkanfrage aus. Regeln werden in absteigender Reihenfolge ihrer Prioritäten ausgeführt. Diese Aktion wirkt sich auf Regeln mit niedrigerer Priorität als die aktuelle Regel aus. Regeln mit derselben Priorität werden möglicherweise ignoriert.

  • lowerPriorityThan

    number optional

    Wenn diese Option festgelegt ist, werden Regeln mit einer niedrigeren Priorität als dem angegebenen Wert ignoriert. Diese Grenze wird nicht beibehalten, sondern wirkt sich nur auf Regeln und ihre Aktionen in derselben Phase der Netzwerkanfrage aus.

RedirectByRegEx

Leitet eine Anfrage weiter, indem ein regulärer Ausdruck auf die URL angewendet wird. Für die regulären Ausdrücke wird die RE2-Syntax verwendet.

Properties

  • Konstruktor

    void

    Die constructor-Funktion sieht so aus: 

    (arg: RedirectByRegEx) => {...}

  • von

    String

    Ein Abgleichsmuster, das Erfassungsgruppen enthalten kann. Auf Erfassungsgruppen wird in der Perl-Syntax ($1, $2 usw.) anstelle der RE2-Syntax (\1, \2 usw.) verwiesen, um sich an JavaScript-reguläre Ausdrücke anzunähern.

  • zu

    String

    Zielmuster.

RedirectRequest

Deklarative Ereignisaktion, die eine Netzwerkanfrage weiterleitet.

Properties

RedirectToEmptyDocument

Deklarative Ereignisaktion, die eine Netzwerkanfrage an ein leeres Dokument weiterleitet.

Properties

RedirectToTransparentImage

Deklarative Ereignisaktion, die eine Netzwerkanfrage zu einem transparenten Bild umleitet.

Properties

RemoveRequestCookie

Entfernt einen oder mehrere Cookies der Anfrage. Es wird empfohlen, die Cookies API zu verwenden, da dies rechentechnisch weniger aufwendig ist.

Properties

RemoveRequestHeader

Entfernt den Anfrageheader mit dem angegebenen Namen. Verwenden Sie SetRequestHeader und RemoveRequestHeader nicht mit demselben Headernamen für dieselbe Anfrage. Jeder Name eines Anfrageheaders kommt in jeder Anfrage nur einmal vor.

Properties

RemoveResponseCookie

Entfernt einen oder mehrere Cookies aus der Antwort. Es wird empfohlen, die Cookies API zu verwenden, da dies rechentechnisch weniger aufwendig ist.

Properties

RemoveResponseHeader

Entfernt alle Antwortheader mit den angegebenen Namen und Werten.

Properties

  • Konstruktor

    void

    Die constructor-Funktion sieht so aus: 

    (arg: RemoveResponseHeader) => {...}

  • name

    String

    Name des HTTP-Anfrageheaders (Groß-/Kleinschreibung wird nicht berücksichtigt).

  • Wert

    String optional

    Wert des HTTP-Anfrageheaders (Groß-/Kleinschreibung wird nicht beachtet).

RequestCookie

Ein Filter oder eine Spezifikation eines Cookies in HTTP-Anfragen.

Properties

  • name

    String optional

    Name eines Cookies.

  • Wert

    String optional

    Wert eines Cookies, der in doppelte Anführungszeichen gesetzt werden kann.

RequestMatcher

Gleicht Netzwerkereignisse anhand verschiedener Kriterien ab.

Properties

  • Konstruktor

    void

    Die constructor-Funktion sieht so aus: 

    (arg: RequestMatcher) => {...}

  • contentType

    string[] optional

    Wird abgeglichen, wenn der MIME-Medientyp einer Antwort (aus dem HTTP-Content-Type-Header) in der Liste enthalten ist.

  • excludeContentType

    string[] optional

    Die Bedingung wird erfüllt, wenn der MIME-Medientyp einer Antwort (aus dem HTTP-Content-Type-Header) nicht in der Liste enthalten ist.

  • excludeRequestHeaders

    HeaderFilter[] optional

    Wird abgeglichen, wenn keiner der Anfrageheader mit einem der HeaderFilter übereinstimmt.

  • excludeResponseHeaders

    HeaderFilter[] optional

    Entspricht, wenn keiner der Antwortheader mit einem der HeaderFilter übereinstimmt.

  • firstPartyForCookiesUrl

    UrlFilter optional

    Eingestellt

    Wird seit Release 82 ignoriert.

    Wird abgeglichen, wenn die Bedingungen des UrlFilter für die „Erstanbieter“-URL der Anfrage erfüllt sind. Die URL des Erstanbieters einer Anfrage kann, sofern vorhanden, von der Ziel-URL der Anfrage abweichen. Sie beschreibt, was im Rahmen von Drittanbieterprüfungen für Cookies als Erstanbieter gilt.

  • requestHeaders

    HeaderFilter[] optional

    Wird abgeglichen, wenn einer der Anfrageheader mit einem der HeaderFilter übereinstimmt.

  • resourceType

    ResourceType[] optional

    Entspricht, wenn der Anfragetyp einer Anfrage in der Liste enthalten ist. Anfragen, die keinem der Typen entsprechen, werden herausgefiltert.

  • responseHeaders

    HeaderFilter[] optional

    Wird ausgelöst, wenn einer der Antwortheader mit einem der HeaderFilter übereinstimmt.

  • Bühnen

    Stage[] optional

    Enthält eine Liste von Strings, die Phasen beschreiben. Zulässige Werte sind „onBeforeRequest“, „onBeforeSendHeaders“, „onHeadersReceived“ und „onAuthRequired“. Wenn dieses Attribut vorhanden ist, werden die anwendbaren Phasen auf die aufgeführten beschränkt. Die gesamte Bedingung gilt nur in Phasen, die mit allen Attributen kompatibel sind.

  • thirdPartyForCookies

    Boolesch optional

    Eingestellt

    Wird seit Version 87 ignoriert.

    Bei „true“ werden Anfragen abgeglichen, die den Richtlinien für Drittanbieter-Cookies unterliegen. Wenn „false“ festgelegt ist, werden alle anderen Anfragen abgeglichen.

  • URL

    UrlFilter optional

    Wird abgeglichen, wenn die Bedingungen des UrlFilter für die URL der Anfrage erfüllt sind.

ResponseCookie

Eine Spezifikation eines Cookies in HTTP-Antworten.

Properties

  • Domain

    String optional

    Wert des Cookie-Attributs „Domain“.

  • Gültig bis

    String optional

    Wert des Cookie-Attributs „Expires“.

  • httpOnly

    String optional

    Vorhandensein des HttpOnly-Cookie-Attributs.

  • maxAge

    number optional

    Wert des Cookie-Attributs „Max-Age“

  • name

    String optional

    Name eines Cookies.

  • Pfad

    String optional

    Wert des Cookie-Attributs „Path“.

  • sicher

    String optional

    Vorhandensein des Secure-Cookie-Attributs.

  • Wert

    String optional

    Wert eines Cookies, der in doppelte Anführungszeichen gesetzt werden kann.

SendMessageToExtension

Löst das Ereignis declarativeWebRequest.onMessage aus.

Properties

SetRequestHeader

Legt den Anfrageheader mit dem angegebenen Namen auf den angegebenen Wert fest. Wenn es zuvor keinen Header mit dem angegebenen Namen gab, wird ein neuer erstellt. Beim Vergleich von Header-Namen wird die Groß-/Kleinschreibung nicht berücksichtigt. Jeder Name eines Anfrageheaders kommt in jeder Anfrage nur einmal vor.

Properties

Stage

Enum

"onBeforeRequest"

"onBeforeSendHeaders"

"onHeadersReceived"

"onAuthRequired"

Ereignisse

onMessage

chrome.declarativeWebRequest.onMessage.addListener(
  callback: function,
)

Wird ausgelöst, wenn eine Nachricht über declarativeWebRequest.SendMessageToExtension von einer Aktion der deklarativen Webanfrage-API gesendet wird.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (details: object) => void

    • Details

      Objekt

      • documentId

        String optional

        Eine UUID des Dokuments, das die Anfrage gestellt hat.

      • Die Lebenszyklusphase des Dokuments.

      • frameId

        Zahl

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

      • Der Typ des Frames, in dem die Navigation stattgefunden hat.

      • Nachricht

        String

        Die vom aufrufenden Skript gesendete Nachricht.

      • method

        String

        Standard-HTTP-Methode.

      • parentDocumentId

        String optional

        Eine UUID des übergeordneten Dokuments, das diesen Frame enthält. Dieser Wert wird nicht festgelegt, wenn es kein übergeordnetes Element gibt.

      • parentFrameId

        Zahl

        ID des Frames, der den Frame umschließt, der die Anfrage gesendet hat. Wird auf -1 gesetzt, wenn kein übergeordneter Frame vorhanden ist.

      • requestId

        String

        Die ID der Anfrage. Anfrage-IDs sind innerhalb einer Browsersitzung eindeutig. Daher können sie verwendet werden, um verschiedene Ereignisse derselben Anfrage in Beziehung zu setzen.

      • Phase

        Bühne

        Die Phase der Netzwerkanfrage, in der das Ereignis ausgelöst wurde.

      • tabId

        Zahl

        Die ID des Tabs, auf dem die Anfrage erfolgt. Auf -1 gesetzt, wenn die Anfrage nicht mit einem Tab zusammenhängt.

      • timeStamp

        Zahl

        Die Zeit, zu der dieses Signal ausgelöst wird, in Millisekunden seit der Epoche.

      • Wie die angeforderte Ressource verwendet wird.

      • URL

        String

onRequest

Bietet die Declarative Event API mit addRules, removeRules und getRules.

Bedingungen

RequestMatcher

Aktionen

AddRequestCookie

AddResponseCookie

AddResponseHeader

CancelRequest

EditRequestCookie

EditResponseCookie

RedirectRequest

RedirectToTransparentImage

RedirectToEmptyDocument

RedirectByRegEx

RemoveRequestCookie

RemoveResponseCookie

RemoveRequestHeader

RemoveResponseHeader

SetRequestHeader

SendMessageToExtension

IgnoreRules