chrome.declarativeWebRequest

Beschrijving

Let op: deze API is verouderd. Bekijk in plaats daarvan de declarativeNetRequest API. Gebruik de chrome.declarativeWebRequest API om lopende verzoeken te onderscheppen, blokkeren of wijzigen. Deze is aanzienlijk sneller dan de chrome.webRequest API omdat u regels kunt registreren die in de browser worden geëvalueerd in plaats van door de JavaScript-engine. Dit vermindert de latentie en zorgt voor een hogere efficiëntie.

Toestemmingen

declarativeWebRequest

Om deze API te kunnen gebruiken, moet u de machtiging "declarativeWebRequest" in het extensiemanifest declareren, samen met de hostmachtigingen .

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

Beschikbaarheid

Betakanaal ≤ MV2

Manifest

Houd er rekening mee dat voor bepaalde soorten niet-gevoelige acties geen hostrechten vereist zijn:

  • CancelRequest
  • IgnoreRules
  • RedirectToEmptyDocument
  • RedirectToTransparentImage

De actie SendMessageToExtension() vereist hostmachtigingen voor alle hosts waarvan u de netwerkverzoeken wilt activeren voor een bericht.

Voor alle overige acties zijn hostrechten voor alle URL's vereist.

Als voorbeeld: als "https://*.google.com/*" de enige hosttoegangsmachtiging is die een extensie heeft, dan kan een dergelijke extensie een regel instellen om:

  • Een verzoek aan https://www.google.com of https://anything.else.com annuleren.
  • Verzend een bericht wanneer u naar https://www.google.com navigeert, maar niet naar https://something.else.com .

De extensie kan geen regel instellen om https://www.google.com door te verwijzen naar https://mail.google.com .

Regels

De Declarative Web Request API volgt de concepten van de Declarative API . Je kunt regels registreren voor het gebeurtenisobject chrome.declarativeWebRequest.onRequest .

De Declarative Web Request API ondersteunt één type overeenkomstcriterium, de RequestMatcher . De RequestMatcher komt alleen overeen met netwerkverzoeken als aan alle vermelde criteria is voldaan. De volgende RequestMatcher komt overeen met een netwerkverzoek wanneer de gebruiker https://www.example.com in de adresbalk invoert:

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

Verzoeken aan https://www.example.com zouden door de RequestMatcher worden afgewezen vanwege het schema. Ook alle verzoeken voor een ingesloten iframe zouden worden afgewezen vanwege het resourceType .

Om alle verzoeken aan "example.com" te annuleren, kunt u een regel definiëren zoals hieronder beschreven:

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

Om alle verzoeken aan example.com en foobar.com te annuleren, kunt u een tweede voorwaarde toevoegen, aangezien elke voorwaarde op zich voldoende is om alle opgegeven acties te activeren:

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

De registratieregels zijn als volgt:

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

Evaluatie van omstandigheden en acties

De Declarative Web Request API volgt het levenscyclusmodel voor webverzoeken van de Web Request API . Dit betekent dat voorwaarden alleen in specifieke fasen van een webverzoek kunnen worden getest en dat acties eveneens alleen in specifieke fasen kunnen worden uitgevoerd. De volgende tabellen geven een overzicht van de verzoekfasen die compatibel zijn met voorwaarden en acties.

Aanvraagfasen waarin conditiekenmerken kunnen worden verwerkt.
Voorwaarde-attribuut onBeforeRequest onBeforeSendHeaders onHeadersReceived onAuthRequired
url ✓ ✓ ✓ ✓
resourceType ✓ ✓ ✓ ✓
contentType ✓
excludeContentType ✓
responseHeaders ✓
excludeResponseHeaders ✓
requestHeaders ✓
excludeRequestHeaders ✓
thirdPartyForCookies ✓ ✓ ✓ ✓
Verzoekfasen waarin acties kunnen worden uitgevoerd.
Evenement onBeforeRequest onBeforeSendHeaders onHeadersReceived onAuthRequired
AddRequestCookie ✓
AddResponseCookie ✓
AddResponseHeader ✓
CancelRequest ✓ ✓ ✓ ✓
EditRequestCookie ✓
EditResponseCookie ✓
IgnoreRules ✓ ✓ ✓ ✓
RedirectByRegEx ✓ ✓
RedirectRequest ✓ ✓
RedirectToEmptyDocument ✓ ✓
RedirectToTransparentImage ✓ ✓
RemoveRequestCookie ✓
RemoveRequestHeader ✓
RemoveResponseCookie ✓
RemoveResponseHeader ✓
SendMessageToExtension ✓ ✓ ✓ ✓
SetRequestHeader ✓

Gebruik prioriteiten om regels te overschrijven.

Regels kunnen aan prioriteiten worden gekoppeld zoals beschreven in de Events API . Dit mechanisme kan worden gebruikt om uitzonderingen uit te drukken. Het volgende voorbeeld blokkeert alle verzoeken voor afbeeldingen met de naam evil.jpg , behalve op de 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]);

Het is belangrijk te beseffen dat de actie IgnoreRules niet behouden blijft tussen de verschillende fasen van een verzoek . Alle voorwaarden van alle regels worden in elke fase van een webverzoek geëvalueerd. Als een IgnoreRules actie wordt uitgevoerd, is deze alleen van toepassing op andere acties die voor hetzelfde webverzoek in dezelfde fase worden uitgevoerd.

Soorten

AddRequestCookie

Voegt een cookie toe aan het verzoek of overschrijft een cookie, indien er al een cookie met dezelfde naam bestaat. Merk op dat het de voorkeur verdient om de Cookies API te gebruiken, omdat dit rekenkundig minder kostbaar is.

Eigenschappen

AddResponseCookie

Voegt een cookie toe aan het antwoord of overschrijft een cookie, indien er al een cookie met dezelfde naam bestaat. Merk op dat het de voorkeur verdient om de Cookies API te gebruiken, omdat dit rekenkundig minder belastend is.

Eigenschappen

AddResponseHeader

Voegt de responseheader toe aan het antwoord van dit webverzoek. Omdat meerdere responseheaders dezelfde naam kunnen hebben, moet u eerst een bestaande responseheader verwijderen en vervolgens een nieuwe toevoegen om deze te vervangen.

Eigenschappen

CancelRequest

Een declaratieve gebeurtenisactie die een netwerkverzoek annuleert.

Eigenschappen

EditRequestCookie

Hiermee kunt u een of meer cookies van het verzoek bewerken. Houd er rekening mee dat het gebruik van de Cookies API de voorkeur verdient, omdat dit rekenkundig minder belastend is.

Eigenschappen

  • constructeur

    leegte

    De constructor ziet er als volgt uit: 

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

  • Filter op cookies die gewijzigd zullen worden. Alle lege velden worden genegeerd.

  • wijziging

    Verzoekcookie

    Attributen die moeten worden overschreven in cookies die aan het filter voldoen. Attributen die zijn ingesteld op een lege tekenreeks worden verwijderd.

EditResponseCookie

Hiermee kunt u een of meer cookies van het antwoord bewerken. Houd er rekening mee dat het gebruik van de Cookies API de voorkeur heeft, omdat dit rekenkundig minder belastend is.

Eigenschappen

FilterResponseCookie

Een cookiefilter in HTTP-reacties.

Eigenschappen

  • leeftijdOndergrens

    nummer optioneel

    Inclusieve ondergrens voor de levensduur van de cookie (gespecificeerd in seconden na de huidige tijd). Alleen cookies waarvan de vervaldatum is ingesteld op 'nu + ageLowerBound' of later, voldoen aan dit criterium. Sessiecookies voldoen niet aan het criterium van dit filter. De levensduur van de cookie wordt berekend op basis van de cookie-attributen 'max-age' of 'expires'. Indien beide zijn gespecificeerd, wordt 'max-age' gebruikt om de levensduur van de cookie te berekenen.

  • leeftijdBovengrens

    nummer optioneel

    Inclusieve bovengrens voor de levensduur van de cookie (gespecificeerd in seconden na de huidige tijd). Alleen cookies waarvan de vervaldatum en -tijd binnen het interval [nu, nu + bovengrens leeftijd] vallen, voldoen aan dit criterium. Sessiecookies en cookies waarvan de vervaldatum en -tijd in het verleden liggen, voldoen niet aan dit filtercriterium. De levensduur van de cookie wordt berekend op basis van de cookie-attributen 'max-age' of 'expires'. Indien beide zijn gespecificeerd, wordt 'max-age' gebruikt om de levensduur van de cookie te berekenen.

  • domein

    string optioneel

    Waarde van het domein-cookiekenmerk.

  • verloopt

    string optioneel

    Waarde van het Expires-cookiekenmerk.

  • httpOnly

    string optioneel

    Het bestaan ​​van het HttpOnly-cookiekenmerk.

  • maxAge

    nummer optioneel

    Waarde van het Max-Age cookie-attribuut

  • naam

    string optioneel

    Naam van een cookie.

  • pad

    string optioneel

    Waarde van het Path-cookiekenmerk.

  • zeker

    string optioneel

    Het bestaan ​​van het Secure cookie-attribuut.

  • sessiecookie

    boolean optioneel

    Filtert sessiecookies. Sessiecookies hebben geen levensduur gespecificeerd in de attributen 'max-age' of 'expires'.

  • waarde

    string optioneel

    De waarde van een cookie kan tussen dubbele aanhalingstekens staan.

HeaderFilter

Filtert verzoekheaders op basis van verschillende criteria. Meerdere criteria worden als een combinatie geëvalueerd.

Eigenschappen

  • naamBevat

    string | string[] optioneel

    Komt overeen als de headernaam alle opgegeven tekenreeksen bevat.

  • naamGelijk aan

    string optioneel

    Komt overeen als de headernaam gelijk is aan de opgegeven tekenreeks.

  • naamVoorvoegsel

    string optioneel

    Komt overeen als de headernaam begint met de opgegeven tekenreeks.

  • naamSuffix

    string optioneel

    Komt overeen als de headernaam eindigt met de opgegeven tekenreeks.

  • waardeBevat

    string | string[] optioneel

    Komt overeen als de headerwaarde alle opgegeven tekenreeksen bevat.

  • waarde is gelijk aan

    string optioneel

    Komt overeen als de waarde in de header gelijk is aan de opgegeven tekenreeks.

  • waardeVoorvoegsel

    string optioneel

    Komt overeen als de waarde in de header begint met de opgegeven tekenreeks.

  • waardeSuffix

    string optioneel

    Komt overeen als de waarde in de header eindigt met de opgegeven tekenreeks.

IgnoreRules

Maskeert alle regels die aan de opgegeven criteria voldoen.

Eigenschappen

  • constructeur

    leegte

    De constructor ziet er als volgt uit: 

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

  • hasTag

    string optioneel

    Indien ingesteld, worden regels met de opgegeven tag genegeerd. Deze negering is niet permanent; deze heeft alleen invloed op regels en hun acties in dezelfde fase van het netwerkverzoek. Houd er rekening mee dat regels worden uitgevoerd in aflopende volgorde van hun prioriteit. Deze actie heeft gevolgen voor regels met een lagere prioriteit dan de huidige regel. Regels met dezelfde prioriteit kunnen al dan niet worden genegeerd.

  • lagere PrioriteitDan

    nummer optioneel

    Indien ingesteld, worden regels met een lagere prioriteit dan de opgegeven waarde genegeerd. Deze grens wordt niet permanent opgeslagen; deze is alleen van invloed op regels en hun acties binnen dezelfde fase van het netwerkverzoek.

RedirectByRegEx

Een verzoek wordt omgeleid door een reguliere expressie op de URL toe te passen. De reguliere expressies gebruiken de RE2-syntaxis .

Eigenschappen

  • constructeur

    leegte

    De constructor ziet er als volgt uit: 

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

  • van

    snaar

    Een matchpatroon dat vastleggingsgroepen kan bevatten. Vastleggingsgroepen worden in de Perl-syntaxis ($1, $2, ...) gebruikt in plaats van de RE2-syntaxis (\1, \2, ...) om dichter bij de reguliere expressies van JavaScript te staan.

  • naar

    snaar

    Bestemmingspatroon.

RedirectRequest

Een declaratieve gebeurtenisactie die een netwerkverzoek omleidt.

Eigenschappen

RedirectToEmptyDocument

Een declaratieve gebeurtenisactie die een netwerkverzoek doorstuurt naar een leeg document.

Eigenschappen

RedirectToTransparentImage

Een declaratieve gebeurtenisactie die een netwerkverzoek doorstuurt naar een transparante afbeelding.

Eigenschappen

RemoveRequestCookie

Verwijdert een of meer cookies van het verzoek. Houd er rekening mee dat het de voorkeur verdient om de Cookies API te gebruiken, omdat dit rekenkundig minder belastend is.

Eigenschappen

RemoveRequestHeader

Verwijdert de requestheader met de opgegeven naam. Gebruik SetRequestHeader en RemoveRequestHeader niet met dezelfde headernaam in hetzelfde verzoek. Elke requestheadernaam komt slechts één keer voor in elk verzoek.

Eigenschappen

RemoveResponseCookie

Verwijdert een of meer cookies uit het antwoord. Houd er rekening mee dat het de voorkeur verdient om de Cookies API te gebruiken, omdat dit rekenkundig minder belastend is.

Eigenschappen

RemoveResponseHeader

Verwijdert alle responsheaders met de opgegeven namen en waarden.

Eigenschappen

  • constructeur

    leegte

    De constructor ziet er als volgt uit: 

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

  • naam

    snaar

    Naam van de HTTP-verzoekheader (niet hoofdlettergevoelig).

  • waarde

    string optioneel

    Waarde van de HTTP-verzoekheader (hoofdlettergevoeligheid speelt geen rol).

RequestCookie

Een filter of specificatie van een cookie in HTTP-verzoeken.

Eigenschappen

  • naam

    string optioneel

    Naam van een cookie.

  • waarde

    string optioneel

    De waarde van een cookie kan tussen dubbele aanhalingstekens staan.

RequestMatcher

Koppelt netwerkgebeurtenissen aan verschillende criteria.

Eigenschappen

  • constructeur

    leegte

    De constructor ziet er als volgt uit: 

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

  • contentType

    string[] optioneel

    Komt overeen als het MIME-mediatype van een reactie (afkomstig uit de HTTP Content-Type-header) in de lijst voorkomt.

  • excludeContentType

    string[] optioneel

    Komt overeen als het MIME-mediatype van een reactie (afkomstig uit de HTTP Content-Type-header) niet in de lijst voorkomt.

  • uitsluiten van aanvraagheaders

    HeaderFilter [] optioneel

    Komt overeen als geen van de aanvraagheaders overeenkomt met een van de HeaderFilters.

  • excludeResponseHeaders

    HeaderFilter [] optioneel

    Komt overeen als geen van de responseheaders overeenkomt met een van de HeaderFilters.

  • firstPartyForCookiesUrl

    UrlFilter optioneel

    Verouderd

    Genegeerd sinds release 82.

    Komt overeen als aan de voorwaarden van de UrlFilter is voldaan voor de 'first party'-URL van het verzoek. De 'first party'-URL van een verzoek kan, indien aanwezig, verschillen van de doel-URL van het verzoek en beschrijft wat als 'first party' wordt beschouwd voor controles op cookies van derden.

  • verzoekHeaders

    HeaderFilter [] optioneel

    Komt overeen als een van de headers van het verzoek overeenkomt met een van de headerfilters.

  • resourceType

    ResourceType [] optioneel

    Er wordt gecontroleerd of het type verzoek in de lijst voorkomt. Verzoeken die niet aan een van de typen voldoen, worden gefilterd.

  • antwoordHeaders

    HeaderFilter [] optioneel

    Er wordt een match gevonden als een van de headers in het antwoord overeenkomt met een van de headerfilters.

  • fasen

    Podium [] optioneel

    Bevat een lijst met tekenreeksen die de fasen beschrijven. Toegestane waarden zijn 'onBeforeRequest', 'onBeforeSendHeaders', 'onHeadersReceived' en 'onAuthRequired'. Als dit attribuut aanwezig is, worden de toepasselijke fasen beperkt tot de vermelde fasen. Houd er rekening mee dat de volledige voorwaarde alleen van toepassing is op fasen die compatibel zijn met alle attributen.

  • thirdPartyForCookies

    boolean optioneel

    Verouderd

    Genegeerd sinds release 87.

    Indien ingesteld op 'true', worden verzoeken gematcht die onderworpen zijn aan het cookiebeleid van derden. Indien ingesteld op 'false', worden alle andere verzoeken gematcht.

  • URL

    UrlFilter optioneel

    Komt overeen als de voorwaarden van de UrlFilter voor de URL van het verzoek zijn vervuld.

ResponseCookie

Een specificatie van een cookie in HTTP-reacties.

Eigenschappen

  • domein

    string optioneel

    Waarde van het domein-cookiekenmerk.

  • verloopt

    string optioneel

    Waarde van het Expires-cookiekenmerk.

  • httpOnly

    string optioneel

    Het bestaan ​​van het HttpOnly-cookiekenmerk.

  • maxAge

    nummer optioneel

    Waarde van het Max-Age cookie-attribuut

  • naam

    string optioneel

    Naam van een cookie.

  • pad

    string optioneel

    Waarde van het Path-cookiekenmerk.

  • zeker

    string optioneel

    Het bestaan ​​van het Secure cookie-attribuut.

  • waarde

    string optioneel

    De waarde van een cookie kan tussen dubbele aanhalingstekens staan.

SendMessageToExtension

Activeert de declarativeWebRequest.onMessage -gebeurtenis.

Eigenschappen

SetRequestHeader

Stelt de aanvraagheader met de opgegeven naam in op de opgegeven waarde. Als er nog geen header met de opgegeven naam bestond, wordt er een nieuwe aangemaakt. De vergelijking van headernamen is altijd niet hoofdlettergevoelig. Elke aanvraagheadernaam komt slechts één keer voor in elk verzoek.

Eigenschappen

Stage

Enum

"onBeforeRequest"

"onBeforeSendHeaders"

"onHeadersReceived"

"onAuthRequired"

Evenementen

onMessage

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

Deze functie wordt geactiveerd wanneer een bericht wordt verzonden via declarativeWebRequest.SendMessageToExtension vanuit een actie van de declaratieve webverzoek-API.

Parameters

  • terugbelverzoek

    functie

    De callback parameter ziet er als volgt uit: 

    (details: object) => void

    • details

      voorwerp

      • documentId

        string optioneel

        De UUID van het document waarmee het verzoek is ingediend.

      • documentLevenscyclus

        extensionTypes.DocumentLifecycle

        De levenscyclus waarin het document zich bevindt.

      • frameId

        nummer

        De waarde 0 geeft aan dat het verzoek plaatsvindt in het hoofdvenster; een positieve waarde geeft de ID aan van een subvenster waarin het verzoek plaatsvindt. Als het document van een (sub)venster wordt geladen ( type is main_frame of sub_frame ), geeft frameId de ID van dit venster aan, niet de ID van het buitenste venster. Venster-ID's zijn uniek binnen een tabblad.

      • Het type frame waarin de navigatie plaatsvond.

      • bericht

        snaar

        Het bericht verzonden door het aanroepende script.

      • methode

        snaar

        Standaard HTTP-methode.

      • parentDocumentId

        string optioneel

        De UUID van het bovenliggende document waartoe dit frame behoort. Deze wordt niet ingesteld als er geen bovenliggend document is.

      • parentFrameId

        nummer

        ID van het frame dat het frame omsluit dat het verzoek heeft verzonden. Stel in op -1 als er geen ouderframe bestaat.

      • verzoek-ID

        snaar

        Het ID van het verzoek. Verzoek-ID's zijn uniek binnen een browsersessie. Daardoor kunnen ze worden gebruikt om verschillende gebeurtenissen van hetzelfde verzoek aan elkaar te koppelen.

      • fase

        Fase

        De fase van het netwerkverzoek waarin de gebeurtenis werd geactiveerd.

      • tabId

        nummer

        De ID van het tabblad waarop het verzoek plaatsvindt. Stel deze in op -1 als het verzoek niet aan een tabblad is gekoppeld.

      • tijdstempel

        nummer

        Het tijdstip waarop dit signaal wordt geactiveerd, in milliseconden sinds het begin van het tijdvak.

      • Hoe de aangevraagde bron zal worden gebruikt.

      • URL

        snaar

onRequest

Biedt de Declarative Event API, bestaande uit addRules , removeRules en getRules .

Voorwaarden

RequestMatcher

Acties

AddRequestCookie

Reactiecookie toevoegen

AddResponseHeader

Annuleerverzoek

EditRequestCookie

Bewerk reactiecookie

Omleidingsverzoek

RedirectToTransparentImage

RedirectToEmptyDocument

RedirectByRegEx

RemoveRequestCookie

Reactiecookie verwijderen

RemoveRequestHeader

RemoveResponseHeader

SetRequestHeader

Bericht verzenden naar extensie

Regels negeren