chrome.declarativeWebRequest

Beschreibung

Hinweis: Diese API wurde verworfen. Sehen Sie sich stattdessen die declarativeNetRequest API an. Verwenden Sie die chrome.declarativeWebRequest API, um laufende Anfragen abzufangen, zu blockieren oder zu ändern. Sie ist deutlich schneller als die chrome.webRequest API, da Sie Regeln registrieren können, die im Browser statt in der JavaScript-Engine ausgewertet werden. Dadurch werden Roundtrip-Latenzen reduziert und eine höhere Effizienz ermöglicht.

Berechtigungen

declarativeWebRequest

Sie müssen „declarativeWebRequest“ im Erweiterungsmanifest, um dies zu verwenden API und Hostberechtigungen.

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

Verfügbarkeit

<ph type="x-smartling-placeholder"></ph> Betaversion &amp;leq; MV2

Manifest

Für bestimmte Arten nicht sensibler Aktionen sind keine Hostberechtigungen erforderlich:

  • CancelRequest
  • IgnoreRules
  • RedirectToEmptyDocument
  • RedirectToTransparentImage

Die Aktion SendMessageToExtension() erfordert Hostberechtigungen für alle Hosts, deren Netzwerkanfragen bei dem Sie eine Nachricht auslösen möchten.

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

Wenn beispielsweise "https://*.google.com/*" die einzige Hostberechtigung einer Erweiterung ist, hat eine solche Erweiterung eine Regel für Folgendes einrichten:

  • Anfrage an https://www.google.com oder https://anything.else.com abbrechen
  • Beim Navigieren zu https://www.google.com, aber nicht zu https://something.else.com eine Nachricht senden.

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

Regeln

Die Declarative Web Request API entspricht den Konzepten der Declarative API. Sie können sich registrieren, an das chrome.declarativeWebRequest.onRequest-Ereignisobjekt übergeben.

Die Declarative Web Request API unterstützt nur einen Übereinstimmungskriterientyp: RequestMatcher. Die RequestMatcher stimmt nur dann mit Netzwerkanfragen überein, wenn alle aufgeführten Kriterien erfüllt sind. Die folgenden RequestMatcher stimmt mit einer Netzwerkanfrage überein, wenn der Nutzer https://www.example.com in das Feld Ominibox:

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

Anfragen an https://www.example.com werden aufgrund des Schemas vom RequestMatcher abgelehnt. Außerdem werden alle Anfragen für einen eingebetteten iFrame aufgrund des resourceType abgelehnt.

Wenn Sie alle Anfragen an „beispiel.de“ abbrechen möchten, können Sie die folgende Regel 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()
  ]
};

Registrieren Sie die Regeln wie folgt:

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

Auswertung von Bedingungen und Maßnahmen

Die Declarative Web Request API richtet sich nach dem Lebenszyklusmodell für Webanfragen des Web- API anfordern Das bedeutet, dass Bedingungen nur in bestimmten Phasen einer Webanfrage getestet werden können Und dementsprechend können auch Aktionen nur in bestimmten Phasen ausgeführt werden. In den folgenden Tabellen sind die Anfragephasen, die mit Bedingungen und Aktionen kompatibel sind.

Anfragephasen, in denen Bedingungsattribute verarbeitet werden können.
Zustandsattribut 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

Prioritäten zum Überschreiben von Regeln verwenden

Regeln können Prioritäten zugeordnet werden, wie in der Events API beschrieben. Dieser Mechanismus kann um Ausnahmen auszudrücken. Im folgenden Beispiel werden alle Anfragen an Images mit dem Namen evil.jpg blockiert außer auf dem Server „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]);

Die Aktion IgnoreRules wird in der Anfrage nicht beibehalten. . Alle Bedingungen aller Regeln werden in jeder Phase einer Webanfrage ausgewertet. Wenn ein IgnoreRules-Aktion ausgeführt wird, gilt nur für andere Aktionen, die für dieselbe Web-Anfrage in derselben Phase.

Typen

AddRequestCookie

Fügt der Anfrage ein Cookie hinzu oder überschreibt ein Cookie für den Fall, dass bereits ein anderes Cookie mit demselben Namen vorhanden ist. Es wird empfohlen, das Cookies API zu verwenden, da dies rechenintensiv ist.

Attribute

AddResponseCookie

Fügt der Antwort ein Cookie hinzu oder überschreibt ein Cookie für den Fall, dass bereits ein anderes Cookie mit demselben Namen vorhanden ist. Es wird empfohlen, das Cookies API zu verwenden, da dies rechenintensiv ist.

Attribute

AddResponseHeader

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

Attribute

  • Konstruktor

    voidm

    Die Funktion constructor sieht so aus: <ph type="x-smartling-placeholder"></ph>

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

  • Name

    String

    Name des HTTP-Antwortheaders.

  • Wert

    String

    HTTP-Antwortheaderwert.

CancelRequest

Deklarative Ereignisaktion, die eine Netzwerkanfrage storniert.

Attribute

EditRequestCookie

Bearbeitet ein oder mehrere Cookies der Anfrage. Es wird empfohlen, das Cookies API zu verwenden, da dies rechenintensiv ist.

Attribute

  • Konstruktor

    voidm

    Die Funktion constructor sieht so aus: <ph type="x-smartling-placeholder"></ph>

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

  • Filter

    Filtern Sie nach Cookies, die geändert werden. Alle leeren Einträge werden ignoriert.

  • modification

    Attribute, die in den Cookies, auf denen der Filter basiert, überschrieben werden sollen. Attribute, für die ein leerer String festgelegt ist, werden entfernt.

EditResponseCookie

Bearbeitet ein oder mehrere Cookies der Antwort. Es wird empfohlen, das Cookies API zu verwenden, da dies rechenintensiv ist.

Attribute

  • Konstruktor

    voidm

    Die Funktion constructor sieht so aus: <ph type="x-smartling-placeholder"></ph>

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

  • Filtern Sie nach Cookies, die geändert werden. Alle leeren Einträge werden ignoriert.

  • modification

    Attribute, die in den Cookies, auf denen der Filter basiert, überschrieben werden sollen. Attribute, für die ein leerer String festgelegt ist, werden entfernt.

FilterResponseCookie

Filter eines Cookies in HTTP-Antworten.

Attribute

  • ageLowerBound

    Zahl optional

    Einschließende Untergrenze für die Cookie-Lebensdauer (angegeben in Sekunden nach der aktuellen Zeit). Nur Cookies, deren Ablaufdatum und -uhrzeit auf „jetzt + ageLowerBound“ gesetzt sind oder später dieses Kriterium erfüllen. Sitzungscookies erfüllen die Kriterien dieses Filters nicht. Die Cookie-Lebensdauer wird entweder anhand von "max-age" oder „läuft ab“ Cookie-Attributen. Wenn beide angegeben sind, gilt „max-age“. wird die Lebensdauer von Cookies berechnet.

  • ageUpperBound

    Zahl optional

    Inklusive Obergrenze für die Cookie-Lebensdauer (angegeben in Sekunden nach der aktuellen Zeit). Nur Cookies, deren Ablaufdatum und -uhrzeit im Intervall [now, now + ageUpperBound] liegen, erfüllen dieses Kriterium. Sitzungscookies und Cookies, deren Ablaufdatum und -uhrzeit in der Vergangenheit liegt, erfüllen die Kriterien dieses Filters nicht. Die Cookie-Lebensdauer wird entweder anhand von "max-age" oder „läuft ab“ Cookie-Attributen. Wenn beide angegeben sind, gilt „max-age“. wird die Lebensdauer von Cookies berechnet.

  • Domain

    String optional

    Wert des Attributs „Domain-Cookie“.

  • Gültig bis

    String optional

    Wert des Attributs „Läuft ab am Cookie“

  • httpOnly

    String optional

    Vorhandensein des HttpOnly-Cookie-Attributs.

  • maxAge

    Zahl optional

    Wert des Attributs „Max-Age-Cookie“

  • Name

    String optional

    Name eines Cookies.

  • Pfad

    String optional

    Wert des Pfad-Cookie-Attributs.

  • sicher

    String optional

    Vorhandensein des Attributs „Sicheres Cookie“.

  • sessionCookie

    Boolescher Wert optional

    Sitzungscookies werden gefiltert. Für Sitzungscookies ist keine Lebensdauer in „max-age“ angegeben. oder „läuft ab“ Attribute.

  • Wert

    String optional

    Wert eines Cookies, kann in doppelte Anführungszeichen aufgefüllt werden.

HeaderFilter

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

Attribute

  • nameContains

    string | string[] optional

    Stimmt überein, wenn der Headername alle angegebenen Strings enthält.

  • nameEquals

    String optional

    Stimmt überein, wenn der Headername dem angegebenen String entspricht.

  • namePrefix

    String optional

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

  • nameSuffix

    String optional

    Stimmt überein, wenn der Headername mit dem angegebenen String endet.

  • valueContains

    string | string[] optional

    Stimmt überein, wenn der Headerwert alle angegebenen Strings enthält.

  • valueEquals

    String optional

    Stimmt überein, wenn der Headerwert dem angegebenen String entspricht.

  • valuePrefix

    String optional

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

  • valueSuffix

    String optional

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

IgnoreRules

Maskiert alle Regeln, die den angegebenen Kriterien entsprechen.

Attribute

  • Konstruktor

    voidm

    Die Funktion constructor sieht so aus: <ph type="x-smartling-placeholder"></ph>

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

  • hasTag

    String optional

    Wenn diese Option festgelegt ist, werden Regeln mit dem angegebenen Tag ignoriert. Dieses Ignorieren wird nicht beibehalten, sondern wirkt sich nur auf Regeln und deren Aktionen in derselben Netzwerkanfragephase aus. Die Regeln werden in absteigender Reihenfolge nach ihrer Priorität ausgeführt. Diese Aktion wirkt sich auf Regeln aus, die eine niedrigere Priorität haben als die aktuelle Regel. Regeln mit derselben Priorität können ignoriert werden oder nicht.

  • lowerPriorityThan

    Zahl optional

    Wenn diese Richtlinie konfiguriert ist, werden Regeln mit einer niedrigeren Priorität als dem angegebenen Wert ignoriert. Diese Begrenzung bleibt nicht bestehen. Sie wirkt sich nur auf Regeln und ihre Aktionen in derselben Netzwerkanfragephase aus.

RedirectByRegEx

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

Attribute

  • Konstruktor

    voidm

    Die Funktion constructor sieht so aus: <ph type="x-smartling-placeholder"></ph>

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

  • von

    String

    Ein Übereinstimmungsmuster, das Erfassungsgruppen enthalten kann. Auf Erfassungsgruppen wird in der Perl-Syntax ($1, $2, ...) anstelle der RE2-Syntax (\1, \2, ...) verwiesen, um näher an regulären JavaScript-Ausdrücken zu sein.

  • zu

    String

    Zielmuster.

RedirectRequest

Deklarative Ereignisaktion, die eine Netzwerkanfrage weiterleitet.

Attribute

  • Konstruktor

    voidm

    Die Funktion constructor sieht so aus: <ph type="x-smartling-placeholder"></ph>

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

  • redirectUrl

    String

    Ziel, an das die Anfrage weitergeleitet wird.

RedirectToEmptyDocument

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

Attribute

RedirectToTransparentImage

Deklarative Ereignisaktion, die eine Netzwerkanfrage an ein transparentes Bild weiterleitet.

Attribute

RemoveRequestCookie

Entfernt ein oder mehrere Anfrage-Cookies. Es wird empfohlen, das Cookies API zu verwenden, da dies rechenintensiv ist.

Attribute

RemoveRequestHeader

Entfernt den Anfrageheader des angegebenen Namens. Verwenden Sie „SetRequestHeader“ und „RemoveRequestHeader“ nicht mit demselben Header-Namen für dieselbe Anfrage. Jeder Anfrageheadername kommt in jeder Anfrage nur einmal vor.

Attribute

  • Konstruktor

    voidm

    Die Funktion constructor sieht so aus: <ph type="x-smartling-placeholder"></ph>

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

  • Name

    String

    Name des HTTP-Anfrageheaders (Groß-/Kleinschreibung nicht berücksichtigend)

RemoveResponseCookie

Entfernt ein oder mehrere Cookies der Antwort. Es wird empfohlen, das Cookies API zu verwenden, da dies rechenintensiv ist.

Attribute

RemoveResponseHeader

Entfernt alle Antwortheader der angegebenen Namen und Werte.

Attribute

  • Konstruktor

    voidm

    Die Funktion constructor sieht so aus: <ph type="x-smartling-placeholder"></ph>

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

  • Name

    String

    Name des HTTP-Anfrageheaders (Groß-/Kleinschreibung nicht berücksichtigend)

  • Wert

    String optional

    HTTP-Anfrageheaderwert (Groß-/Kleinschreibung nicht berücksichtigend)

RequestCookie

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

Attribute

  • Name

    String optional

    Name eines Cookies.

  • Wert

    String optional

    Wert eines Cookies, kann in doppelte Anführungszeichen aufgefüllt werden.

RequestMatcher

Gleicht Netzwerkereignisse anhand verschiedener Kriterien ab.

Attribute

  • Konstruktor

    voidm

    Die Funktion constructor sieht so aus: <ph type="x-smartling-placeholder"></ph>

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

  • contentType

    string[] optional

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

  • excludeContentType

    string[] optional

    Stimmt überein, wenn der MIME-Medientyp einer Antwort (aus dem HTTP Content-Type-Header) nicht in der Liste enthalten ist.

  • excludeRequestHeaders

    HeaderFilter[] optional

    Stimmt überein, wenn keiner der Anfrageheader mit einem der HeaderFilters übereinstimmt.

  • excludeResponseHeaders

    HeaderFilter[] optional

    Stimmt überein, wenn keiner der Antwortheader mit einem der HeaderFilters übereinstimmt.

  • firstPartyForCookiesUrl

    UrlFilter optional

    <ph type="x-smartling-placeholder"></ph> Eingestellt

    Ignoriert seit Version 82.

    Übereinstimmung mit der Bedingung, dass die Bedingungen des UrlFilter für die Erstanbieterfunktion erfüllt sind URL des Antrags. Erstanbieter Die URL eines Ersuchens, sofern vorhanden, kann sich von der Ziel-URL des Ersuchens unterscheiden und beschreibt, was als eigene URL angesehen wird damit Drittanbieter auf Cookies überprüfen können.

  • requestHeaders

    HeaderFilter[] optional

    Stimmt überein, wenn einige Anfrageheader mit einem der HeaderFilters übereinstimmen.

  • resourceType

    ResourceType[] optional

    Stimmt überein, wenn der Anfragetyp einer Anfrage in der Liste enthalten ist. Anfragen, die mit keinem der Typen übereinstimmen, werden herausgefiltert.

  • responseHeaders

    HeaderFilter[] optional

    Stimmt überein, wenn einige der Antwortheader mit einem der HeaderFilters übereinstimmen.

  • Bühnen

    Phase[] 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 begrenzt. Die gesamte Bedingung ist nur in Phasen anwendbar, die mit allen Attributen kompatibel sind.

  • thirdPartyForCookies

    Boolescher Wert optional

    <ph type="x-smartling-placeholder"></ph> Eingestellt

    Ignoriert seit Version 87.

    Wenn die Richtlinie auf „true“ gesetzt ist, werden Anfragen abgeglichen, die den Richtlinien für Drittanbieter-Cookies unterliegen. Wird auf „false“ gesetzt, erfolgt eine Übereinstimmung mit allen anderen Anfragen.

  • URL

    UrlFilter optional

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

ResponseCookie

Eine Spezifikation eines Cookies in HTTP-Antworten.

Attribute

  • Domain

    String optional

    Wert des Attributs „Domain-Cookie“.

  • Gültig bis

    String optional

    Wert des Attributs „Läuft ab am Cookie“

  • httpOnly

    String optional

    Vorhandensein des HttpOnly-Cookie-Attributs.

  • maxAge

    Zahl optional

    Wert des Attributs „Max-Age-Cookie“

  • Name

    String optional

    Name eines Cookies.

  • Pfad

    String optional

    Wert des Pfad-Cookie-Attributs.

  • sicher

    String optional

    Vorhandensein des Attributs „Sicheres Cookie“.

  • Wert

    String optional

    Wert eines Cookies, kann in doppelte Anführungszeichen aufgefüllt werden.

SendMessageToExtension

Löst das Ereignis declarativeWebRequest.onMessage aus.

Attribute

  • Konstruktor

    voidm

    Die Funktion constructor sieht so aus: <ph type="x-smartling-placeholder"></ph>

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

  • Nachricht

    String

    Der Wert, der im Attribut message des Wörterbuchs übergeben wird, das an den Event-Handler übergeben wird.

SetRequestHeader

Legt den Anfrageheader des angegebenen Namens auf den angegebenen Wert fest. Wenn noch kein Header mit dem angegebenen Namen vorhanden ist, wird ein neuer erstellt. Beim Headernamenvergleich wird immer die Groß-/Kleinschreibung nicht berücksichtigt. Jeder Anfrageheadername kommt in jeder Anfrage nur einmal vor.

Attribute

  • Konstruktor

    voidm

    Die Funktion constructor sieht so aus: <ph type="x-smartling-placeholder"></ph>

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

  • Name

    String

    Name des HTTP-Anfrageheaders.

  • Wert

    String

    Wert für den HTTP-Anfrageheader.

Stage

Enum

"onBeforeRequest"

"onBeforeSendHeaders"

"onHeadersReceived"

"onAuthRequired"

Ereignisse

onMessage

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

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

Parameter

  • callback

    Funktion

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

    (details: object) => void

    • Details

      Objekt

      • documentId

        String optional

        Eine UUID des Dokuments, von dem die Anfrage stammt.

      • Der Lebenszyklus, in dem sich das Dokument befindet.

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

      • Der Frame-Typ, in dem die Navigation erfolgte.

      • Nachricht

        String

        Die vom Anrufskript gesendete Nachricht.

      • method

        String

        Standard-HTTP-Methode.

      • parentDocumentId

        String optional

        Eine UUID des übergeordneten Dokuments, zu dem dieser Frame gehört. Dieser Wert wird nicht festgelegt, wenn kein übergeordnetes Element vorhanden ist.

      • 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. Daher können sie verwendet werden, um verschiedene Ereignisse derselben Anfrage zuzuordnen.

      • Phase

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

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

      • 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

Stellt die Declarative Event API bereit, die aus addRules, removeRules und getRules besteht.

Bedingungen