chrome.declarativeWebRequest

Beschrijving

Let op: deze API is verouderd. Bekijk in plaats daarvan de declarativeNetRequest API. Gebruik de chrome.declarativeWebRequest API om verzoeken tijdens de vlucht te onderscheppen, blokkeren of wijzigen. Het is aanzienlijk sneller dan de chrome.webRequest API omdat u regels kunt registreren die in de browser worden geëvalueerd in plaats van in de JavaScript-engine, waardoor de roundtrip-latency wordt verminderd en een hogere efficiëntie mogelijk is.

Rechten

declarativeWebRequest

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

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

Beschikbaarheid

Bètakanaal ≤ MV2

Manifest

Houd er rekening mee dat voor bepaalde soorten niet-gevoelige acties geen hostmachtigingen nodig zijn:

  • CancelRequest
  • IgnoreRules
  • RedirectToEmptyDocument
  • RedirectToTransparentImage

Voor de actie SendMessageToExtension() zijn hostmachtigingen vereist voor alle hosts op wiens netwerkverzoeken u een bericht wilt activeren.

Voor alle andere acties zijn hostmachtigingen voor alle URL's vereist.

Als "https://*.google.com/*" bijvoorbeeld de enige hosttoestemming is die een extensie heeft, kan een dergelijke extensie een regel instellen om:

  • Annuleer een verzoek aan https://www.google.com of https://anything.else.com .
  • Stuur 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 om te leiden naar https://mail.google.com .

Reglement

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

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

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

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

Om alle verzoeken aan "example.com" te annuleren, kunt u als volgt een regel definiëren:

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 voldoende is om alle gespecificeerde 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()
  ]
};

Registratieregels 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 ook alleen in specifieke fasen kunnen worden uitgevoerd. In de volgende tabellen worden de aanvraagfasen vermeld die compatibel zijn met voorwaarden en acties.

Aanvraagfasen waarin conditieattributen kunnen worden verwerkt.
Conditie attribuut opBeforeRequest onBeforeSendHeaders opHeadersOntvangen onAuthVereist
url ✓ ✓ ✓ ✓
resourceType ✓ ✓ ✓ ✓
contentType ✓
excludeContentType ✓
responseHeaders ✓
excludeResponseHeaders ✓
requestHeaders ✓
excludeRequestHeaders ✓
thirdPartyForCookies ✓ ✓ ✓ ✓
Vraag fasen aan waarin acties kunnen worden uitgevoerd.
Evenement opBeforeRequest onBeforeSendHeaders opHeadersOntvangen onAuthVereist
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 worden gekoppeld aan prioriteiten, zoals beschreven in de Events API . Dit mechanisme kan worden gebruikt om uitzonderingen uit te drukken. Het volgende voorbeeld blokkeert alle verzoeken aan 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 om te beseffen dat de actie IgnoreRules niet in alle aanvraagfasen wordt gehandhaafd. Alle voorwaarden van alle regels worden in elke fase van een webverzoek geëvalueerd. Als een actie IgnoreRules 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, voor het geval er al een andere cookie met dezelfde naam bestaat. Houd er rekening mee dat het de voorkeur verdient om de Cookies API te gebruiken, omdat dit rekentechnisch goedkoper is.

Eigenschappen

AddResponseCookie

Voegt een cookie toe aan het antwoord of overschrijft een cookie, voor het geval er al een andere cookie met dezelfde naam bestaat. Houd er rekening mee dat het de voorkeur verdient om de Cookies API te gebruiken, omdat dit rekentechnisch goedkoper is.

Eigenschappen

AddResponseHeader

Voegt de responsheader toe aan het antwoord van dit webverzoek. Omdat meerdere antwoordheaders dezelfde naam kunnen hebben, moet u eerst een nieuwe antwoordheader verwijderen en vervolgens toevoegen om er een te vervangen.

Eigenschappen

CancelRequest

Declaratieve gebeurtenisactie die een netwerkverzoek annuleert.

Eigenschappen

EditRequestCookie

Bewerkt een of meer verzoekcookies. Houd er rekening mee dat het de voorkeur verdient om de Cookies API te gebruiken, omdat dit rekentechnisch goedkoper is.

Eigenschappen

EditResponseCookie

Bewerkt een of meer responscookies. Houd er rekening mee dat het de voorkeur verdient om de Cookies API te gebruiken, omdat dit rekentechnisch goedkoper is.

Eigenschappen

FilterResponseCookie

Een filter van een cookie in HTTP-reacties.

Eigenschappen

  • leeftijdOndergrens

    nummer optioneel

    Inclusief ondergrens voor de levensduur van de cookie (gespecificeerd in seconden na de huidige tijd). Alleen cookies waarvan de vervaldatum-tijd 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 cookiekenmerken 'max-age' of 'expires'. Als beide zijn opgegeven, wordt 'max-age' gebruikt om de levensduur van de cookie te berekenen.

  • leeftijdUpperBound

    nummer optioneel

    Inclusief bovengrens voor de levensduur van cookies (gespecificeerd in seconden na de huidige tijd). Alleen cookies waarvan de vervaldatum en -tijd in het interval [nu, nu + ageUpperBound] liggen, voldoen aan dit criterium. Sessiecookies en cookies waarvan de vervaldatum/-tijd in het verleden ligt, voldoen niet aan het criterium van dit filter. De levensduur van de cookie wordt berekend op basis van de cookiekenmerken 'max-age' of 'expires'. Als beide zijn opgegeven, wordt 'max-age' gebruikt om de levensduur van de cookie te berekenen.

  • domein

    tekenreeks optioneel

    Waarde van het domeincookiekenmerk.

  • verloopt

    tekenreeks optioneel

    Waarde van het cookiekenmerk Expires.

  • httpAlleen

    tekenreeks optioneel

    Bestaan ​​van het HttpOnly-cookiekenmerk.

  • maxLeeftijd

    nummer optioneel

    Waarde van het cookiekenmerk Max-Age

  • naam

    tekenreeks optioneel

    Naam van een koekje.

  • pad

    tekenreeks optioneel

    Waarde van het padcookie-attribuut.

  • zeker

    tekenreeks optioneel

    Bestaan ​​van het Secure cookie attribuut.

  • sessieCookie

    Booleaans optioneel

    Filtert sessiecookies. Voor sessiecookies is geen levensduur gespecificeerd in de kenmerken 'max-age' of 'expires'.

  • waarde

    tekenreeks optioneel

    De waarde van een cookie kan tussen dubbele aanhalingstekens worden geplaatst.

HeaderFilter

Filtert verzoekheaders op verschillende criteria. Meerdere criteria worden als een conjunctie geëvalueerd.

Eigenschappen

  • naamBevat

    tekenreeks|tekenreeks[] optioneel

    Komt overeen als de headernaam alle opgegeven tekenreeksen bevat.

  • naamGelijk

    tekenreeks optioneel

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

  • naamVoorvoegsel

    tekenreeks optioneel

    Komt overeen als de headernaam begint met de opgegeven tekenreeks.

  • naamAchtervoegsel

    tekenreeks optioneel

    Komt overeen als de headernaam eindigt met de opgegeven tekenreeks.

  • waardeBevat

    tekenreeks|tekenreeks[] optioneel

    Komt overeen als de headerwaarde alle opgegeven tekenreeksen bevat.

  • waardeGelijk

    tekenreeks optioneel

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

  • waardeVoorvoegsel

    tekenreeks optioneel

    Komt overeen als de headerwaarde begint met de opgegeven tekenreeks.

  • waardeAchtervoegsel

    tekenreeks optioneel

    Komt overeen als de headerwaarde eindigt met de opgegeven tekenreeks.

IgnoreRules

Maskert alle regels die voldoen aan de opgegeven criteria.

Eigenschappen

  • bouwer

    leegte

    De constructor ziet er als volgt uit: 

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

  • heeftTag

    tekenreeks optioneel

    Indien ingesteld, worden regels met de opgegeven tag genegeerd. Dit negeren wordt niet voortgezet; het heeft alleen invloed op regels en hun acties in dezelfde netwerkverzoekfase. Houd er rekening mee dat regels worden uitgevoerd in aflopende volgorde van hun prioriteiten. Deze actie is van invloed op regels met een lagere prioriteit dan de huidige regel. Regels met dezelfde prioriteit kunnen wel of niet worden genegeerd.

  • lagere prioriteit dan

    nummer optioneel

    Indien ingesteld, worden regels met een lagere prioriteit dan de opgegeven waarde genegeerd. Deze grens blijft niet bestaan, maar heeft alleen invloed op regels en hun acties in dezelfde netwerkverzoekfase.

RedirectByRegEx

Leidt een verzoek om door een reguliere expressie op de URL toe te passen. De reguliere expressies gebruiken de RE2-syntaxis .

Eigenschappen

  • bouwer

    leegte

    De constructor ziet er als volgt uit: 

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

  • van

    snaar

    Een matchpatroon dat vanggroepen kan bevatten. Er wordt naar capture-groepen verwezen in de Perl-syntaxis ($1, $2, ...) in plaats van de RE2-syntaxis (\1, \2, ...) om dichter bij JavaScript reguliere expressies te komen.

  • naar

    snaar

    Bestemmingspatroon.

RedirectRequest

Declaratieve gebeurtenisactie die een netwerkverzoek omleidt.

Eigenschappen

RedirectToEmptyDocument

Declaratieve gebeurtenisactie die een netwerkverzoek omleidt naar een leeg document.

Eigenschappen

RedirectToTransparentImage

Declaratieve gebeurtenisactie die een netwerkverzoek omleidt naar een transparante afbeelding.

Eigenschappen

RemoveRequestCookie

Verwijdert één of meerdere verzoekcookies. Houd er rekening mee dat het de voorkeur verdient om de Cookies API te gebruiken, omdat dit rekentechnisch goedkoper is.

Eigenschappen

RemoveRequestHeader

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

Eigenschappen

RemoveResponseCookie

Verwijdert een of meer responscookies. Houd er rekening mee dat het de voorkeur verdient om de Cookies API te gebruiken, omdat dit rekentechnisch goedkoper is.

Eigenschappen

RemoveResponseHeader

Verwijdert alle antwoordheaders van de opgegeven namen en waarden.

Eigenschappen

RequestCookie

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

Eigenschappen

  • naam

    tekenreeks optioneel

    Naam van een koekje.

  • waarde

    tekenreeks optioneel

    De waarde van een cookie kan tussen dubbele aanhalingstekens worden geplaatst.

RequestMatcher

Matcht netwerkgebeurtenissen op basis van verschillende criteria.

Eigenschappen

  • bouwer

    leegte

    De constructor ziet er als volgt uit: 

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

  • inhoudType

    tekenreeks[] optioneel

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

  • sluitContentType uit

    tekenreeks[] optioneel

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

  • sluitRequestHeaders uit

    HeaderFilter [] optioneel

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

  • sluitResponseHeaders uit

    HeaderFilter [] optioneel

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

  • firstPartyForCookiesUrl

    UrlFilter optioneel

    Verouderd

    Genegeerd sinds release 82.

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

  • verzoekHeaders

    HeaderFilter [] optioneel

    Komt overeen als sommige van de verzoekheaders overeenkomen met een van de HeaderFilters.

  • brontype

    ResourceType [] optioneel

    Komt overeen als het verzoektype van een verzoek in de lijst voorkomt. Verzoeken die niet aan een van de typen kunnen voldoen, worden eruit gefilterd.

  • reactieHeaders

    HeaderFilter [] optioneel

    Komt overeen als sommige van de antwoordheaders overeenkomen met een van de HeaderFilters.

  • stadia

    Fase [] optioneel

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

  • thirdPartyForCookies

    Booleaans optioneel

    Verouderd

    Genegeerd sinds release 87.

    Indien ingesteld op true, komen verzoeken overeen die onderworpen zijn aan het cookiebeleid van derden. Indien ingesteld op false, komt dit overeen met alle andere verzoeken.

  • URL

    UrlFilter optioneel

    Komt overeen als aan de voorwaarden van het UrlFilter is voldaan voor de URL van het verzoek.

ResponseCookie

Een specificatie van een cookie in HTTP-antwoorden.

Eigenschappen

  • domein

    tekenreeks optioneel

    Waarde van het domeincookiekenmerk.

  • verloopt

    tekenreeks optioneel

    Waarde van het cookiekenmerk Expires.

  • httpAlleen

    tekenreeks optioneel

    Bestaan ​​van het HttpOnly-cookiekenmerk.

  • maxLeeftijd

    nummer optioneel

    Waarde van het cookiekenmerk Max-Age

  • naam

    tekenreeks optioneel

    Naam van een koekje.

  • pad

    tekenreeks optioneel

    Waarde van het padcookie-attribuut.

  • zeker

    tekenreeks optioneel

    Bestaan ​​van het Secure cookie attribuut.

  • waarde

    tekenreeks optioneel

    De waarde van een cookie kan tussen dubbele aanhalingstekens worden geplaatst.

SendMessageToExtension

Activeert de declarativeWebRequest.onMessage gebeurtenis.

Eigenschappen

SetRequestHeader

Stelt de aanvraagheader van de opgegeven naam in op de opgegeven waarde. Als een header met de opgegeven naam nog niet eerder bestond, wordt er een nieuwe gemaakt. Het vergelijken van headernamen is altijd hoofdlettergevoelig. Elke verzoekheadernaam komt slechts één keer voor in elk verzoek.

Eigenschappen

Stage

Enum

"opBeforeRequest"

"onBeforeSendHeaders"

"onHeadersReceived"

"onAuthVereist"

Evenementen

onMessage

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

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

Parameters

  • Bel terug

    functie

    De callback parameter ziet er als volgt uit: 

    (details: object)=>void

    • details

      voorwerp

      • documentId

        tekenreeks optioneel

        Een UUID van het document dat het verzoek heeft ingediend.

      • documentLevenscyclus

        extensionTypes.DocumentLifecycle

        De levenscyclus waarin het document zich bevindt.

      • frameId

        nummer

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

      • Het type frame waarin de navigatie heeft plaatsgevonden.

      • bericht

        snaar

        Het bericht dat door het aanroepscript wordt verzonden.

      • methode

        snaar

        Standaard HTTP-methode.

      • parentDocumentId

        tekenreeks optioneel

        Een UUID van het bovenliggende document dat eigenaar is van dit frame. Dit wordt niet ingesteld als er geen ouder is.

      • ouderFrameId

        nummer

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

      • Aanvraag ID

        snaar

        De ID van het verzoek. Verzoek-ID's zijn uniek binnen een browsersessie. Als gevolg hiervan kunnen ze worden gebruikt om verschillende gebeurtenissen van hetzelfde verzoek met elkaar in verband te brengen.

      • fase

        Fase

        De fase van het netwerkverzoek waarin de gebeurtenis werd geactiveerd.

      • tabId

        nummer

        De ID van het tabblad waarop de aanvraag plaatsvindt. Stel in op -1 als het verzoek niet gerelateerd is aan een tabblad.

      • tijdstempel

        nummer

        Het tijdstip waarop dit signaal wordt geactiveerd, in milliseconden sinds het tijdperk.

      • Hoe de gevraagde bron zal worden gebruikt.

      • URL

        snaar

onRequest

Biedt de Declaratieve gebeurtenis-API die bestaat uit addRules , removeRules en getRules .

Voorwaarden

RequestMatcher

Acties

VoegRequestCookie toe

ReactieCookie toevoegen

ReactieHeader toevoegen

Annuleer verzoek

BewerkAanvraagCookie

BewerkResponseCookie

Omleidingsverzoek

RedirectToTransparentImage

Omleiden naar leeg document

RedirectByRegEx

VerwijderRequestCookie

VerwijderResponseCookie

VerwijderRequestHeader

VerwijderResponseHeader

SetRequestHeader

Bericht verzenden naar extensie

Negeer regels