chrome.declarativeNetRequest

Beschrijving

De chrome.declarativeNetRequest API wordt gebruikt om netwerkverzoeken te blokkeren of te wijzigen door middel van declaratieve regels. Hierdoor kunnen extensies netwerkverzoeken aanpassen zonder ze te onderscheppen en de inhoud ervan te bekijken, wat zorgt voor meer privacy.

Toestemmingen

declarativeNetRequest
declarativeNetRequestWithHostAccess

De machtigingen " declarativeNetRequest " en " declarativeNetRequestWithHostAccess " bieden dezelfde mogelijkheden. Het verschil zit hem in het moment waarop de machtigingen worden aangevraagd of verleend.

"declarativeNetRequest"
Geeft een waarschuwing over machtigingen tijdens de installatie, maar biedt impliciet toegang tot de regels allow , allowAllRequests en block . Gebruik dit waar mogelijk om te voorkomen dat u volledige toegang tot hosts hoeft aan te vragen.
"declarativeNetRequestFeedback"
Schakelt debugfuncties in voor uitgepakte extensies , met name getMatchedRules() en onRuleMatchedDebug .
"declarativeNetRequestWithHostAccess"
Tijdens de installatie wordt geen waarschuwing over machtigingen weergegeven, maar u moet wel hostmachtigingen aanvragen voordat u acties op een host kunt uitvoeren. Dit is handig wanneer u declaratieve netwerkverzoekregels wilt gebruiken in een extensie die al hostmachtigingen heeft, zonder dat er extra waarschuwingen worden gegenereerd.

Beschikbaarheid

Chrome 84+

Manifest

Naast de eerder beschreven machtigingen vereisen bepaalde typen regelsets, met name statische regelsets, dat de manifestsleutel "declarative_net_request" wordt gedeclareerd. Deze sleutel moet een dictionary zijn met één sleutel genaamd "rule_resources" . Deze sleutel is een array die dictionaries van het type Ruleset bevat, zoals hieronder weergegeven. (Merk op dat de naam 'Ruleset' niet in de JSON van het manifest voorkomt, omdat het slechts een array is.) Statische regelsets worden later in dit document uitgelegd.

{
  "name": "My extension",
  ...

  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    }, {
      "id": "ruleset_2",
      "enabled": false,
      "path": "rules_2.json"
    }]
  },
  "permissions": [
    "declarativeNetRequest",
    "declarativeNetRequestFeedback"
  ],
  "host_permissions": [
    "http://www.blogger.com/*",
    "http://*.google.com/*"
  ],
  ...
}

Regels en regelsets

Om deze API te gebruiken, moet u een of meer regelsets specificeren. Een regelset bevat een array met regels. Een enkele regel doet een van de volgende dingen:

  • Blokkeer een netwerkverzoek.
  • Wijzig het schema (http naar https).
  • Voorkom dat een verzoek wordt geblokkeerd door alle overeenkomende blokkeringsregels te negeren.
  • Een netwerkverzoek omleiden.
  • Wijzig de headers van het verzoek of het antwoord.

Er zijn drie soorten regelsets, die op enigszins verschillende manieren worden beheerd.

Dynamisch
Deze instellingen blijven behouden tijdens browsersessies en extensie-updates en worden beheerd met JavaScript zolang een extensie in gebruik is.
Sessie
De instellingen worden gewist wanneer de browser wordt afgesloten en wanneer een nieuwe versie van de extensie wordt geïnstalleerd. Sessieregels worden beheerd met behulp van JavaScript zolang een extensie in gebruik is.
Statisch
De statische regels worden verpakt, geïnstalleerd en bijgewerkt wanneer een extensie wordt geïnstalleerd of geüpgraded. Ze worden opgeslagen in JSON-bestanden en vermeld in het manifestbestand.

Dynamische en sessiegebonden regelsets

Dynamische en sessieregels worden beheerd met behulp van JavaScript zolang een extensie in gebruik is.

  • Dynamische regels blijven behouden gedurende browsersessies en bij updates van extensies.
  • Sessieregels worden gewist wanneer de browser wordt afgesloten en wanneer een nieuwe versie van de extensie wordt geïnstalleerd.

Er is slechts één exemplaar van elk van deze regeltypen. Een extensie kan dynamisch regels toevoegen of verwijderen door de functies updateDynamicRules() en updateSessionRules() aan te roepen, mits de regellimieten niet worden overschreden. Zie Regellimieten voor meer informatie over regellimieten . Een voorbeeld hiervan is te vinden onder codevoorbeelden .

Statische regelsets

In tegenstelling tot dynamische en sessieregels worden statische regels verpakt, geïnstalleerd en bijgewerkt wanneer een extensie wordt geïnstalleerd of geüpgraded. Ze worden opgeslagen in regelbestanden in JSON-formaat, die aan de extensie worden doorgegeven via de sleutels "declarative_net_request" en "rule_resources" zoals hierboven beschreven , evenals een of meer Ruleset -woordenboeken. Een Ruleset -woordenboek bevat een pad naar het regelbestand, een ID voor de regelset in het bestand en of de regelset is ingeschakeld of uitgeschakeld. De laatste twee zijn belangrijk wanneer u een regelset programmatisch in- of uitschakelt.

{
  ...
  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    },
    ...
    ]
  }
  ...
}

Om regelbestanden te testen, laadt u uw extensie in uitgepakte toestand . Foutmeldingen en waarschuwingen over ongeldige statische regels worden alleen weergegeven voor uitgepakte extensies. Ongeldige statische regels in ingepakte extensies worden genegeerd.

Versnelde beoordeling

Wijzigingen in statische regelsets komen mogelijk in aanmerking voor een versnelde beoordeling. Zie 'Versnelde beoordeling' voor een overzicht van de in aanmerking komende wijzigingen .

Statische regels en regelsets in- en uitschakelen

Zowel individuele statische regels als complete sets statische regels kunnen tijdens de uitvoering worden in- of uitgeschakeld.

De set ingeschakelde statische regels en regelsets blijft behouden tussen browsersessies. Deze worden echter niet behouden bij updates van extensies, wat betekent dat na een update alleen de regels beschikbaar zijn die u in uw regelbestanden hebt laten staan.

Om prestatieproblemen te voorkomen, gelden er ook limieten voor het aantal regels en regelsets dat tegelijkertijd kan worden ingeschakeld. Roep getAvailableStaticRuleCount() aan om het aantal extra regels te controleren dat kan worden ingeschakeld. Zie Regellimieten voor meer informatie over regellimieten .

Om statische regels in of uit te schakelen, roept u updateStaticRules() aan. Deze methode accepteert een UpdateStaticRulesOptions object, dat arrays bevat met ID's van regels die moeten worden in- of uitgeschakeld. De ID's worden gedefinieerd met behulp van de sleutel "id" in het woordenboek Ruleset . Er geldt een maximumlimiet van 5000 uitgeschakelde statische regels.

Om statische regelsets in of uit te schakelen, roept u updateEnabledRulesets() aan. Deze methode accepteert een UpdateRulesetOptions object, dat arrays bevat met ID's van regelsets die moeten worden in- of uitgeschakeld. De ID's worden gedefinieerd met behulp van de sleutel "id" in het Ruleset -woordenboek.

Bouwregels

Ongeacht het type, begint een regel met vier velden, zoals hieronder weergegeven. De sleutels "id" en "priority" accepteren een getal, terwijl de sleutels "action" en "condition" meerdere blokkerings- en omleidingsvoorwaarden kunnen bevatten. De volgende regel blokkeert alle scriptverzoeken afkomstig van "foo.com" naar elke URL die "abc" als substring bevat.

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

URL-overeenkomst

Declarative Net Request biedt de mogelijkheid om URL's te matchen met behulp van een patroonherkenningssyntaxis of reguliere expressies.

Syntaxis van URL-filters

De sleutel "condition" van een regel maakt een "urlFilter" -sleutel mogelijk om acties uit te voeren op URL's binnen een specifiek domein. Je maakt patronen met behulp van patroonmatching-tokens . Hier volgen een paar voorbeelden.

urlFilter Wedstrijden Komt niet overeen
"abc" https://abcd.com
https://example.com/abcd		 https://ab.com
"abc*d" https://abcd.com
https://example.com/abcxyzd		 https://abc.com
"||a.example.com" https://a.example.com/
https://baexample.com/xyz
https://a.example.company		 https://example.com/
"|https*" https://example.com http://example.com/
http://https.com
"example*^123|" https://example.com/123
http://abc.com/example?123		 https://example.com/1234
https://abc.com/example0123

Reguliere expressies

Voorwaarden kunnen ook gebruikmaken van reguliere expressies. Zie de sleutel "regexFilter" . Voor meer informatie over de beperkingen die van toepassing zijn op deze voorwaarden, raadpleegt u Regels die gebruikmaken van reguliere expressies .

Schrijf goede URL-voorwaarden.

Wees voorzichtig bij het schrijven van regels die altijd een volledig domein moeten matchen. Anders kan je regel in onverwachte situaties van toepassing zijn. Bijvoorbeeld bij het gebruik van de patroonmatching-syntaxis:

  • google.com komt onjuist overeen met https://example.com/?param=google.com
  • ||google.com komt onjuist overeen met https://google.company
  • https://www.google.com komt onjuist overeen met https://example.com/?param=https://www.google.com

Overweeg het volgende:

  • ||google.com/ , wat overeenkomt met alle paden en alle subdomeinen.
  • |https://www.google.com/ die overeenkomt met alle paden en geen subdomeinen.

Gebruik op dezelfde manier de tekens ^ en / om een ​​reguliere expressie te verankeren. Bijvoorbeeld, ^https:\/\/www\.google\.com\/ komt overeen met elk pad op https://www.google.com.

Regelevaluatie

DNR-regels worden door de browser toegepast in verschillende fasen van de levenscyclus van een netwerkverzoek.

Vóór het verzoek

Voordat een verzoek wordt gedaan, kan een extensie het blokkeren of omleiden (inclusief het upgraden van het schema van HTTP naar HTTPS) met behulp van een overeenkomende regel.

Voor elke extensie bepaalt de browser een lijst met overeenkomende regels. Regels met een ` modifyHeaders -actie worden hier niet opgenomen, omdat deze later worden verwerkt. Regels met een responseHeaders -voorwaarde worden eveneens later (wanneer de responseheaders beschikbaar zijn) in overweging genomen en worden daarom niet vermeld.

Vervolgens selecteert Chrome voor elke extensie maximaal één kandidaat per verzoek. Chrome vindt een overeenkomende regel door alle overeenkomende regels op prioriteit te sorteren. Regels met dezelfde prioriteit worden gesorteerd op actie ( allow of allowAllRequests > block > upgradeScheme > redirect ).

Als de kandidaat een allow of allowAllRequests regel is, of als het frame waarin het verzoek wordt gedaan eerder overeenkwam met een allowAllRequests -regel van een hogere of gelijke prioriteit van deze extensie, wordt het verzoek "toegestaan" en heeft de extensie geen invloed op het verzoek.

Als meerdere extensies dit verzoek willen blokkeren of omleiden, wordt er één actie gekozen. Chrome doet dit door de regels te sorteren in de volgorde block > redirect of upgradeScheme > allow ​​of allowAllRequests . Als twee regels van hetzelfde type zijn, kiest Chrome de regel van de meest recent geïnstalleerde extensie.

Voordat de verzoekheaders worden verzonden

Voordat Chrome de verzoekheaders naar de server stuurt, worden de headers bijgewerkt op basis van overeenkomende modifyHeaders regels.

Binnen één enkele extensie stelt Chrome de lijst met uit te voeren wijzigingen samen door alle overeenkomende modifyHeaders -regels te vinden. Net als voorheen worden alleen regels opgenomen die een hogere prioriteit hebben dan overeenkomende allow of allowAllRequests -regels.

Deze regels worden door Chrome toegepast in een volgorde waarbij regels van een recent geïnstalleerde extensie altijd vóór regels van een oudere extensie worden geëvalueerd. Bovendien worden regels met een hogere prioriteit van een extensie altijd vóór regels met een lagere prioriteit van dezelfde extensie toegepast. Opvallend is dat dit zelfs geldt voor verschillende extensies:

  • Als een regel iets toevoegt aan een header, kunnen regels met een lagere prioriteit alleen iets toevoegen aan die header. Instellen en verwijderen zijn niet toegestaan.
  • Als een regel een koptekst instelt, kunnen alleen regels met een lagere prioriteit uit dezelfde extensie aan die koptekst worden toegevoegd. Andere wijzigingen zijn niet toegestaan.
  • Als een regel een koptekst verwijdert, kunnen regels met een lagere prioriteit die koptekst niet verder wijzigen.

Zodra een reactie is ontvangen

Zodra de responseheaders zijn ontvangen, evalueert Chrome de regels met een responseHeaders voorwaarde.

Nadat deze regels zijn gesorteerd op action en priority en alle regels zijn uitgesloten die overbodig zijn geworden door een overeenkomende allow of allowAllRequests -regel (dit gebeurt identiek aan de stappen in "Voor het verzoek"), kan Chrome het verzoek namens een extensie blokkeren of doorsturen.

Houd er rekening mee dat als een verzoek dit stadium heeft bereikt, het verzoek al naar de server is verzonden en de server gegevens zoals de verzoekbody heeft ontvangen. Een blokkeer- of omleidingsregel met een voorwaarde voor de responsheaders zal nog steeds worden uitgevoerd, maar kan het verzoek niet daadwerkelijk blokkeren of omleiden.

In het geval van een blokkeerregel wordt dit afgehandeld doordat de pagina die het verzoek heeft gedaan een geblokkeerd antwoord ontvangt en Chrome het verzoek voortijdig beëindigt. In het geval van een omleidingsregel doet Chrome een nieuw verzoek naar de omgeleide URL. Zorg ervoor dat u nagaat of dit gedrag voldoet aan de privacyverwachtingen van uw extensie.

Als het verzoek niet wordt geblokkeerd of omgeleid, past Chrome alle modifyHeaders -regels toe. Het toepassen van wijzigingen op de responseheaders werkt op dezelfde manier als beschreven in "Voordat de requestheaders worden verzonden". Het toepassen van wijzigingen op de requestheaders heeft geen effect, omdat het verzoek al is gedaan.

Veiligheidsregels

Veilige regels worden gedefinieerd als regels met een actie van block , allow , allowAllRequests ​​of upgradeScheme . Deze regels zijn onderworpen aan een verhoogd dynamisch regelquotum .

Regelgrenzen

Het laden en evalueren van regels in de browser brengt prestatieverlies met zich mee, waardoor er beperkingen gelden bij het gebruik van de API. Deze beperkingen zijn afhankelijk van het type regel dat u gebruikt.

Statische regels

Statische regels zijn regels die zijn gespecificeerd in regelbestanden die zijn gedeclareerd in het manifestbestand. Een extensie kan maximaal 100 statische regelsets specificeren als onderdeel van de manifestsleutel "rule_resources" , maar slechts 50 van deze regelsets kunnen tegelijkertijd worden ingeschakeld. Dit laatste wordt de MAX_NUMBER_OF_ENABLED_STATIC_RULESETS genoemd. Gezamenlijk zijn deze regelsets gegarandeerd minimaal 30.000 regels. Dit wordt de GUARANTEED_MINIMUM_STATIC_RULES genoemd.

Het aantal beschikbare regels daarna hangt af van hoeveel regels zijn ingeschakeld door alle extensies die in de browser van de gebruiker zijn geïnstalleerd. U kunt dit aantal tijdens de uitvoering achterhalen door de functie getAvailableStaticRuleCount() aan te roepen. Een voorbeeld hiervan vindt u in de codevoorbeelden .

Sessieregels

Een extensie kan maximaal 5000 sessieregels hebben. Dit wordt weergegeven als MAX_NUMBER_OF_SESSION_RULES .

Vóór Chrome 120 gold er een limiet van 5000 gecombineerde dynamische en sessieregels.

Dynamische regels

Een extensie kan minimaal 5000 dynamische regels bevatten. Dit wordt weergegeven als MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES .

Vanaf Chrome 121 is er een hogere limiet van 30.000 beschikbare veilige dynamische regels, weergegeven als MAX_NUMBER_OF_DYNAMIC_RULES . Alle onveilige regels die binnen de limiet van 5000 worden toegevoegd, tellen ook mee voor deze limiet.

Vóór Chrome 120 gold er een limiet van 5000 gecombineerde dynamische en sessieregels.

Regels die gebruikmaken van reguliere expressies

Alle soorten regels kunnen reguliere expressies gebruiken; het totale aantal reguliere expressieregels van elk type mag echter niet meer dan 1000 bedragen. Dit wordt de MAX_NUMBER_OF_REGEX_RULES genoemd.

Bovendien moet elke regel na compilatie kleiner zijn dan 2 KB. Dit hangt ruwweg samen met de complexiteit van de regel. Als u een regel probeert te laden die deze limiet overschrijdt, krijgt u een waarschuwing zoals hieronder te zien en wordt de regel genegeerd.

rules_1.json: Rule with id 1 specified a more complex regex than allowed
as part of the "regexFilter" key.

Interacties met servicemedewerkers

Een declarativeNetRequest is alleen van toepassing op verzoeken die de netwerkstack bereiken. Dit omvat reacties uit de HTTP-cache, maar mogelijk niet reacties die via de onfetch handler van een service worker gaan. DeclarativeNetRequest heeft geen invloed op reacties die door de service worker worden gegenereerd of die uit CacheStorage worden opgehaald, maar wel op aanroepen van fetch() in een service worker.

Webtoegankelijke bronnen

Een declarativeNetRequest-regel mag geen omleiding uitvoeren van een openbare resourceaanvraag naar een resource die niet via het web toegankelijk is. Dit leidt tot een foutmelding. Dit geldt zelfs als de opgegeven, via het web toegankelijke resource eigendom is van de omleidende extensie. Om resources voor declarativeNetRequest te declareren, gebruikt u de array "web_accessible_resources" in het manifest.

Wijziging van de header

De append-bewerking wordt alleen ondersteund voor de volgende requestheaders: accept , accept-encoding , accept-language , access-control-request-headers , cache-control , connection , content-language , cookie , forwarded , if-match , if-none-match , keep-alive , range , te , trailer , transfer-encoding , upgrade , user-agent , via , want-digest , x-forwarded-for . Deze lijst met toegestane headers is hoofdlettergevoelig ( bug 449152902 ).

Bij het toevoegen aan een verzoek- of antwoordheader gebruikt de browser, waar mogelijk, de juiste scheidingsteken.

Voorbeelden

Codevoorbeelden

Dynamische regels bijwerken

Het volgende voorbeeld laat zien hoe je updateDynamicRules() aanroept. De procedure voor updateSessionRules() is hetzelfde.

// Get arrays containing new and old rules
const newRules = await getNewRules();
const oldRules = await chrome.declarativeNetRequest.getDynamicRules();
const oldRuleIds = oldRules.map(rule => rule.id);

// Use the arrays to update the dynamic rules
await chrome.declarativeNetRequest.updateDynamicRules({
  removeRuleIds: oldRuleIds,
  addRules: newRules
});

Statische regelsets bijwerken

Het volgende voorbeeld laat zien hoe u regelsets kunt in- en uitschakelen, rekening houdend met het aantal beschikbare en het maximaal aantal ingeschakelde statische regelsets. Dit doet u wanneer het aantal benodigde statische regels het toegestane aantal overschrijdt. Om dit te laten werken, moeten sommige van uw regelsets geïnstalleerd zijn met een aantal uitgeschakeld (door "Enabled" op false te zetten in het manifestbestand).

async function updateStaticRules(enableRulesetIds, disableCandidateIds) {
  // Create the options structure for the call to updateEnabledRulesets()
  let options = { enableRulesetIds: enableRulesetIds }
  // Get the number of enabled static rules
  const enabledStaticCount = await chrome.declarativeNetRequest.getEnabledRulesets();
  // Compare rule counts to determine if anything needs to be disabled so that
  // new rules can be enabled
  const proposedCount = enableRulesetIds.length;
  if (enabledStaticCount + proposedCount > chrome.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS) {
    options.disableRulesetIds = disableCandidateIds
  }
  // Update the enabled static rules
  await chrome.declarativeNetRequest.updateEnabledRulesets(options);
}

Voorbeelden van regels

De volgende voorbeelden illustreren hoe Chrome prioriteit geeft aan regels in een extensie. Wanneer u deze regels bekijkt, kunt u ze het beste in een apart venster openen.

De "prioriteitssleutel"

Deze voorbeelden vereisen hosttoegang tot *://*.example.com/* .

Om de prioriteit van een bepaalde URL te bepalen, kijk je naar de (door de ontwikkelaar gedefinieerde) sleutel "priority" , de sleutel "action" en de sleutel "urlFilter" . Deze voorbeelden verwijzen naar het onderstaande voorbeeldregelbestand.

Navigatie naar https://google.com
Twee regels zijn van toepassing op deze URL: de regels met ID 1 en 4. Regel 1 is van toepassing omdat "block" -acties een hogere prioriteit hebben dan "redirect" -acties. De overige regels zijn niet van toepassing omdat ze bedoeld zijn voor langere URL's.
Navigatie naar https://google.com/1234
Vanwege de langere URL komt de regel met ID 2 nu overeen met de regels met ID 1 en 4. De regel met ID 2 is van toepassing omdat "allow" een hogere prioriteit heeft dan "block" en "redirect" .
Navigatie naar https://google.com/12345
Alle vier regels komen overeen met deze URL. De regel met ID 3 is van toepassing omdat de door de ontwikkelaar gedefinieerde prioriteit de hoogste van de groep is. 
[
  {
    "id": 1,
    "priority": 1,
    "action": { "type": "block" },
    "condition": {"urlFilter": "||google.com/", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 2,
    "priority": 1,
    "action": { "type": "allow" },
    "condition": { "urlFilter": "||google.com/123", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 3,
    "priority": 2,
    "action": { "type": "block" },
    "condition": { "urlFilter": "||google.com/12345", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 4,
    "priority": 1,
    "action": { "type": "redirect", "redirect": { "url": "https://example.com" } },
    "condition": { "urlFilter": "||google.com/", "resourceTypes": ["main_frame"] }
  },
]

Omleidingen

Het onderstaande voorbeeld vereist hosttoegang tot *://*.example.com/* .

Het volgende voorbeeld laat zien hoe je een verzoek van example.com kunt doorsturen naar een pagina binnen de extensie zelf. Het extensiepad /a.jpg wordt omgezet naar chrome-extension://EXTENSION_ID/a.jpg , waarbij EXTENSION_ID de ID van je extensie is. Om dit te laten werken, moet /a.jpg in het manifest als een webtoegankelijke bron worden gedeclareerd.

{
  "id": 1,
  "priority": 1,
  "action": { "type": "redirect", "redirect": { "extensionPath": "/a.jpg" } },
  "condition": {
    "urlFilter": "||https://www.example.com/",
    "resourceTypes": ["main_frame"]
  }
}

Het volgende voorbeeld gebruikt de sleutel "transform" om door te verwijzen naar een subdomein van example.com. Het gebruikt een domeinnaamanker ("||") om verzoeken met elk schema van example.com te onderscheppen. De sleutel "scheme" in "transform" geeft aan dat doorverwijzingen naar het subdomein altijd "https" zullen gebruiken.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": {
      "transform": { "scheme": "https", "host": "new.example.com" }
    }
  },
  "condition": {
    "urlFilter": "||example.com/",
    "resourceTypes": ["main_frame"]
  }
}

Het volgende voorbeeld gebruikt reguliere expressies om door te verwijzen van https://www.abc.xyz.com/path naar https://abc.xyz.com/path . Let in de sleutel "regexFilter" op hoe punten worden ontsnapt en dat de vastleggingsgroep "abc" of "def" selecteert. De sleutel "regexSubstitution" specificeert de eerste overeenkomst van de reguliere expressie met behulp van "\1". In dit geval wordt "abc" uit de omgeleide URL gehaald en in de vervanging geplaatst. 

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": {
      "regexSubstitution": "https://\\1.xyz.com/"
    }
  },
  "condition": {
    "regexFilter": "^https://www\\.(abc|def)\\.xyz\\.com/",
    "resourceTypes": [
      "main_frame"
    ]
  }
}

Kopteksten

Het volgende voorbeeld verwijdert alle cookies uit zowel een hoofdvenster als alle subvensters. 

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "modifyHeaders",
    "requestHeaders": [{ "header": "cookie", "operation": "remove" }]
  },
  "condition": { "resourceTypes": ["main_frame", "sub_frame"] }
}

Soorten

DomainType

Dit beschrijft of het verzoek afkomstig is van de eerste of derde partij van het frame waarin het is ontstaan. Een verzoek is afkomstig van de eerste partij als het hetzelfde domein (eTLD+1) heeft als het frame waarin het verzoek is ontstaan.

Enum

"firstParty"
Het netwerkverzoek is de eerste partij in het frame waarin het is ontstaan.

"derde partij"
Het netwerkverzoek is een derde partij ten opzichte van het frame waarin het is ontstaan.

ExtensionActionOptions

Chrome 88+

Eigenschappen

  • toonActieAantalAlsBadgeTekst

    boolean optioneel

    Of het aantal acties voor een pagina automatisch als badge-tekst van de extensie moet worden weergegeven. Deze voorkeur blijft behouden tussen sessies.

  • tabUpdate

    TabActionCountUpdate optioneel

    Chrome 89+

    Details over hoe het aantal acties op het tabblad moet worden aangepast.

GetDisabledRuleIdsOptions

Chrome 111+

Eigenschappen

  • regelssetId

    snaar

    De ID die overeenkomt met een statische Ruleset .

GetRulesFilter

Chrome 111+

Eigenschappen

  • regel-ID's

    nummer[] optioneel

    Indien gespecificeerd, worden alleen regels met overeenkomende ID's opgenomen.

HeaderInfo

Chrome 128+

Eigenschappen

  • uitgesloten waarden

    string[] optioneel

    Indien gespecificeerd, wordt aan deze voorwaarde niet voldaan als de koptekst bestaat, maar de waarde ervan ten minste één element uit deze lijst bevat. Hierbij wordt dezelfde syntaxis voor het matchpatroon gebruikt als values .

  • koptekst

    snaar

    De naam van de header. Deze voorwaarde komt alleen overeen met de naam als zowel values als excludedValues niet zijn gespecificeerd.

  • waarden

    string[] optioneel

    Indien gespecificeerd, komt deze voorwaarde overeen als de waarde van de header overeenkomt met ten minste één patroon in deze lijst. Dit ondersteunt hoofdletterongevoelige vergelijking van headerwaarden plus de volgende constructies:

    '*' : Komt overeen met een willekeurig aantal tekens.

    '?' : Komt overeen met nul of één teken(s).

    '*' en '?' kunnen worden ontsnapt met een backslash, bijvoorbeeld '\*' en '\?'

HeaderOperation

Chrome 86+

Dit beschrijft de mogelijke bewerkingen voor een "modifyHeaders"-regel.

Enum

"toevoegen"
Voegt een nieuwe vermelding toe voor de opgegeven header. Bij het wijzigen van de headers van een verzoek wordt deze bewerking alleen ondersteund voor specifieke headers .

"set"
Stelt een nieuwe waarde in voor de opgegeven header en verwijdert alle bestaande headers met dezelfde naam.

"verwijderen"
Verwijdert alle vermeldingen voor de opgegeven koptekst.

IsRegexSupportedResult

Chrome 87+

Eigenschappen

  • wordt ondersteund

    booleaans

  • reden

    UnsupportedRegexReason (optioneel )

    Geeft de reden aan waarom de reguliere expressie niet wordt ondersteund. Wordt alleen weergegeven als isSupported onwaar is.

MatchedRule

Eigenschappen

  • regel-ID

    nummer

    De ID van een overeenkomende regel.

  • regelssetId

    snaar

    De ID van de Ruleset waartoe deze regel behoort. Voor een regel afkomstig uit de set dynamische regels is dit gelijk aan DYNAMIC_RULESET_ID .

MatchedRuleInfo

Eigenschappen

  • regel

    MatchedRule

  • tabId

    nummer

    De tab-ID van het tabblad van waaruit het verzoek afkomstig is, indien het tabblad nog actief is. Anders -1.

  • tijdstempel

    nummer

    Het tijdstip waarop de regel werd gevonden. Tijdstempels komen overeen met de JavaScript-conventie voor tijden, oftewel het aantal milliseconden sinds de epoch.

MatchedRuleInfoDebug

Eigenschappen

MatchedRulesFilter

Eigenschappen

  • minTijdstempel

    nummer optioneel

    Indien gespecificeerd, worden alleen regels na het opgegeven tijdstempel gematcht.

  • tabId

    nummer optioneel

    Indien gespecificeerd, worden alleen regels voor het betreffende tabblad gematcht. Regels die niet aan een actief tabblad zijn gekoppeld, worden ook gematcht als de waarde -1 is ingesteld.

ModifyHeaderInfo

Chrome 86+

Eigenschappen

  • koptekst

    snaar

    De naam van de header die moet worden gewijzigd.

  • De handeling die op een header moet worden uitgevoerd.

  • waarde

    string optioneel

    De nieuwe waarde voor de header. Moet worden opgegeven voor append en set .

QueryKeyValue

Eigenschappen

  • sleutel

    snaar

  • alleen vervangen

    boolean optioneel

    Chrome 94+

    Indien waar, wordt de zoeksleutel alleen vervangen als deze al aanwezig is. Anders wordt de sleutel ook toegevoegd als deze ontbreekt. De standaardwaarde is onwaar.

  • waarde

    snaar

QueryTransform

Eigenschappen

  • addOrReplaceParams

    QueryKeyValue [] optioneel

    De lijst met sleutel-waardeparen die moeten worden toegevoegd of vervangen.

  • verwijderParams

    string[] optioneel

    De lijst met zoektermen die verwijderd moeten worden.

Redirect

Eigenschappen

  • uitbreidingspad

    string optioneel

    Pad relatief ten opzichte van de extensiemap. Moet beginnen met '/'.

  • regexSubstitution

    string optioneel

    Vervangingspatroon voor regels die een regexFilter specificeren. De eerste overeenkomst van regexFilter in de URL wordt vervangen door dit patroon. Binnen regexSubstitution kunnen backslash-escaped cijfers (\1 tot \9) worden gebruikt om de overeenkomstige vastleggingsgroepen in te voegen. \0 verwijst naar de volledige overeenkomende tekst.

  • transformeren

    URLTransform optioneel

    Uit te voeren URL-transformaties.

  • URL

    string optioneel

    De redirect-URL. Omleidingen naar JavaScript-URL's zijn niet toegestaan.

RegexOptions

Chrome 87+

Eigenschappen

  • isCaseSensitive

    boolean optioneel

    Of de opgegeven regex expressie hoofdlettergevoelig is. Standaard is dit waar.

  • reguliere expressie

    snaar

    De reguliere expressie om te controleren.

  • vereisen Vastleggen

    boolean optioneel

    Of de opgegeven regex vastlegging vereist. Vastlegging is alleen vereist voor omleidingsregels die een regexSubstition -actie specificeren. De standaardwaarde is false.

RequestDetails

Eigenschappen

  • documentId

    string optioneel

    Chrome 106+

    De unieke identificatiecode voor het document van het frame, indien dit verzoek betrekking heeft op een frame.

  • documentLevenscyclus

    DocumentLifecycle optioneel

    Chrome 106+

    De levenscyclus van het framedocument, indien dit verzoek betrekking heeft op een frame.

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

  • frameType

    FrameType optioneel

    Chrome 106+

    Het type frame, indien dit verzoek om een ​​frame gaat.

  • initiatiefnemer

    string optioneel

    De oorsprong waar het verzoek vandaan kwam. Deze verandert niet door omleidingen. Als dit een ondoorzichtige oorsprong is, wordt de tekenreeks 'null' gebruikt.

  • methode

    snaar

    Standaard HTTP-methode.

  • parentDocumentId

    string optioneel

    Chrome 106+

    De unieke identificatiecode voor het bovenliggende document van het frame, indien dit verzoek betrekking heeft op een frame en een bovenliggend document heeft.

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

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

  • Het resourcetype van het verzoek.

  • URL

    snaar

    De URL van het verzoek.

RequestMethod

Chrome 91+

Dit beschrijft de HTTP-verzoekmethode van een netwerkverzoek.

Enum

"verbinden"

"verwijderen"

"krijgen"

"hoofd"

"opties"

"lapje"

"na"

"neerzetten"

"ander"

ResourceType

Dit beschrijft het type bron van het netwerkverzoek.

Enum

"hoofdframe"

"sub_frame"

"stijlpagina"

"script"

"afbeelding"

"lettertype"

"voorwerp"

"xmlhttprequest"

"ping"

"csp_rapport"

"media"

"websocket"

"webtransport"

"webbundel"

"ander"

Rule

Eigenschappen

  • actie

    RegelActie

    De actie die moet worden ondernomen als aan deze regel wordt voldaan.

  • voorwaarde

    RegelVoorwaarde

    De voorwaarde waaronder deze regel van toepassing is.

  • id

    nummer

    Een ID die een regel uniek identificeert. Verplicht en moet >= 1 zijn.

  • prioriteit

    nummer optioneel

    Prioriteit van de regel. Standaardwaarde is 1. Indien gespecificeerd, moet deze waarde >= 1 zijn.

RuleAction

Eigenschappen

  • omleiding

    Doorverwijzing optioneel

    Beschrijft hoe de omleiding moet worden uitgevoerd. Alleen geldig voor omleidingsregels.

  • verzoekHeaders

    ModifyHeaderInfo [] optioneel

    Chrome 86+

    De aanvraagheaders die voor de aanvraag moeten worden gewijzigd. Alleen geldig als RuleActionType "modifyHeaders" is.

  • antwoordHeaders

    ModifyHeaderInfo [] optioneel

    Chrome 86+

    De responseheaders die voor het verzoek moeten worden aangepast. Alleen geldig als RuleActionType "modifyHeaders" is.

  • Het type actie dat moet worden uitgevoerd.

RuleActionType

Beschrijft het soort actie dat moet worden ondernomen als een bepaalde regelvoorwaarde overeenkomt.

Enum

"blok"
Blokkeer het netwerkverzoek.

"doorverwijzen"
Leid het netwerkverzoek om.

"toestaan"
Sta het netwerkverzoek toe. Het verzoek wordt niet onderschept als er een toegangsregel is die ermee overeenkomt.

"upgradeSchema"
Wijzig het schema van de netwerkverzoek-URL naar https als het verzoek http of ftp is.

"modifyHeaders"
Wijzig de request/response-headers van het netwerkverzoek.

"alle verzoeken toestaan"
Sta alle verzoeken binnen een framehiërarchie toe, inclusief het frameverzoek zelf.

RuleCondition

Eigenschappen

  • domeinType

    Domeintype optioneel

    Geeft aan of het netwerkverzoek afkomstig is van de eerste partij (first-party) of van een derde partij (third-party) ten opzichte van het domein waar het vandaan komt. Indien dit veld wordt weggelaten, worden alle verzoeken geaccepteerd.

  • domeinen

    string[] optioneel

    Verouderd sinds Chrome 101

    Gebruik in plaats daarvan initiatorDomains

    De regel komt alleen overeen met netwerkverzoeken afkomstig van de lijst met domains .

  • uitgesloten domeinen

    string[] optioneel

    Verouderd sinds Chrome 101

    Gebruik in plaats daarvan excludedInitiatorDomains

    De regel zal geen netwerkverzoeken matchen die afkomstig zijn van de lijst met excludedDomains .

  • uitgeslotenInitiatorDomains

    string[] optioneel

    Chrome 101+

    De regel zal geen netwerkverzoeken matchen die afkomstig zijn van de lijst met excludedInitiatorDomains . Als de lijst leeg is of ontbreekt, worden er geen domeinen uitgesloten. Dit heeft voorrang op initiatorDomains .

    Opmerkingen:

    • Subdomeinen zoals "a.example.com" zijn ook toegestaan.
    • De invoer mag uitsluitend uit ASCII-tekens bestaan.
    • Gebruik punycode-codering voor geïnternationaliseerde domeinen.
    • Dit wordt vergeleken met de initiatiefnemer van het verzoek en niet met de URL van het verzoek.
    • Subdomeinen van de vermelde domeinen zijn eveneens uitgesloten.
  • uitgesloten aanvraagdomeinen

    string[] optioneel

    Chrome 101+

    De regel zal geen netwerkverzoeken matchen wanneer de domeinen overeenkomen met een van de domeinen in de lijst excludedRequestDomains . Als de lijst leeg is of ontbreekt, worden er geen domeinen uitgesloten. Dit heeft voorrang op requestDomains .

    Opmerkingen:

    • Subdomeinen zoals "a.example.com" zijn ook toegestaan.
    • De invoer mag uitsluitend uit ASCII-tekens bestaan.
    • Gebruik punycode-codering voor geïnternationaliseerde domeinen.
    • Subdomeinen van de vermelde domeinen zijn eveneens uitgesloten.
  • uitgesloten aanvraagmethoden

    RequestMethod [] optioneel

    Chrome 91+

    Lijst met aanvraagmethoden die niet door de regel worden herkend. Slechts één van de twee opties, requestMethods of excludedRequestMethods moet worden opgegeven. Als geen van beide is opgegeven, worden alle aanvraagmethoden herkend.

  • uitgeslotenBrontypen

    ResourceType [] optioneel

    Lijst met resourcetypen die niet door de regel worden herkend. Slechts één van de resourceTypes en excludedResourceTypes mag worden opgegeven. Indien geen van beide is opgegeven, worden alle resourcetypen behalve "main_frame" geblokkeerd.

  • uitgeslotenResponseHeaders

    HeaderInfo [] optioneel

    Chrome 128+

    De regel is niet van toepassing als het verzoek overeenkomt met een van de voorwaarden in de antwoordheaders in deze lijst (indien gespecificeerd). Als zowel excludedResponseHeaders als responseHeaders zijn gespecificeerd, heeft de eigenschap excludedResponseHeaders voorrang.

  • uitgeslotenTabIds

    nummer[] optioneel

    Chrome 92+

    Lijst met tabs.Tab.id die niet door de regel mogen worden herkend. Een ID van tabs.TAB_ID_NONE sluit verzoeken uit die niet afkomstig zijn van een tabblad. Alleen ondersteund voor sessiegebonden regels.

  • uitgeslotenTopDomains

    string[] optioneel

    In behandeling

    De regel zal geen netwerkverzoeken matchen wanneer het domein van het bijbehorende top-level frame overeenkomt met een domein uit de lijst excludedTopDomains . Als de lijst leeg is of ontbreekt, worden er geen domeinen uitgesloten. Deze regel heeft voorrang op topDomains .

    Opmerkingen:

    • Subdomeinen zoals "a.example.com" zijn ook toegestaan.
    • De invoer mag uitsluitend uit ASCII-tekens bestaan.
    • Gebruik punycode-codering voor geïnternationaliseerde domeinen.
    • Subdomeinen van de vermelde domeinen zijn eveneens uitgesloten.
    • Voor verzoeken zonder bijbehorend topniveau-frame (bijvoorbeeld verzoeken geïnitieerd door ServiceWorker), wordt in plaats daarvan het domein van de verzoekinitiator gebruikt.
  • initiatorDomains

    string[] optioneel

    Chrome 101+

    De regel is alleen van toepassing op netwerkverzoeken afkomstig van de lijst met initiatorDomains . Als de lijst ontbreekt, is de regel van toepassing op verzoeken van alle domeinen. Een lege lijst is niet toegestaan.

    Opmerkingen:

    • Subdomeinen zoals "a.example.com" zijn ook toegestaan.
    • De invoer mag uitsluitend uit ASCII-tekens bestaan.
    • Gebruik punycode-codering voor geïnternationaliseerde domeinen.
    • Dit wordt vergeleken met de initiatiefnemer van het verzoek en niet met de URL van het verzoek.
    • Subdomeinen van de vermelde domeinen worden ook vergeleken.
  • isUrlFilterCaseSensitive

    boolean optioneel

    Of de urlFilter of regexFilter (afhankelijk van welke is opgegeven) hoofdlettergevoelig is. De standaardwaarde is false.

  • regexFilter

    string optioneel

    Reguliere expressie om te matchen met de URL van het netwerkverzoek. Deze volgt de RE2-syntaxis .

    Let op: slechts één van de twee, urlFilter of regexFilter kan worden opgegeven.

    Opmerking: Het regexFilter mag alleen uit ASCII-tekens bestaan. Dit wordt vergeleken met een URL waarbij de host is gecodeerd in het punycode-formaat (in het geval van geïnternationaliseerde domeinen) en alle andere niet-ASCII-tekens zijn URL-gecodeerd in UTF-8.

  • verzoekdomeinen

    string[] optioneel

    Chrome 101+

    De regel is alleen van toepassing op netwerkverzoeken wanneer het domein overeenkomt met een van de domeinen in de lijst ` requestDomains . Als de lijst ontbreekt, is de regel van toepassing op verzoeken van alle domeinen. Een lege lijst is niet toegestaan.

    Opmerkingen:

    • Subdomeinen zoals "a.example.com" zijn ook toegestaan.
    • De invoer mag uitsluitend uit ASCII-tekens bestaan.
    • Use punycode encoding for internationalized domains.
    • Sub-domains of the listed domains are also matched.
  • requestMethods

    RequestMethod [] optional

    Chrome 91+

    List of HTTP request methods which the rule can match. An empty list is not allowed.

    Note: Specifying a requestMethods rule condition will also exclude non-HTTP(s) requests, whereas specifying excludedRequestMethods will not.

  • resourceTypes

    ResourceType [] optional

    List of resource types which the rule can match. An empty list is not allowed.

    Note: this must be specified for allowAllRequests rules and may only include the sub_frame and main_frame resource types.

  • responseHeaders

    HeaderInfo [] optional

    Chrome 128+

    Rule matches if the request matches any response header condition in this list (if specified).

  • tabIds

    number[] optional

    Chrome 92+

    List of tabs.Tab.id which the rule should match. An ID of tabs.TAB_ID_NONE matches requests which don't originate from a tab. An empty list is not allowed. Only supported for session-scoped rules.

  • topDomains

    string[] optional

    In behandeling

    The rule will only match network requests when the associated top-level frame's domain matches one from the list of topDomains . If the list is omitted, the rule is applied to requests associated with all top-level frame domains. An empty list is not allowed.

    Opmerkingen:

    • Sub-domains like "a.example.com" are also allowed.
    • The entries must consist of only ascii characters.
    • Use punycode encoding for internationalized domains.
    • Sub-domains of the listed domains are also matched.
    • For requests with no associated top-level frame (eg ServiceWorker initiated requests, the request initiator's domain is considered instead.
  • urlFilter

    string optional

    The pattern which is matched against the network request url. Supported constructs:

    '*' : Wildcard: Matches any number of characters.

    '|' : Left/right anchor: If used at either end of the pattern, specifies the beginning/end of the url respectively.

    '||' : Domain name anchor: If used at the beginning of the pattern, specifies the start of a (sub-)domain of the URL.

    '^' : Separator character: This matches anything except a letter, a digit, or one of the following: _ , - , . , or % . This also match the end of the URL.

    Therefore urlFilter is composed of the following parts: (optional Left/Domain name anchor) + pattern + (optional Right anchor).

    If omitted, all urls are matched. An empty string is not allowed.

    A pattern beginning with ||* is not allowed. Use * instead.

    Note: Only one of urlFilter or regexFilter can be specified.

    Note: The urlFilter must be composed of only ASCII characters. This is matched against a url where the host is encoded in the punycode format (in case of internationalized domains) and any other non-ascii characters are url encoded in utf-8. For example, when the request url is http://abc.рф?q=ф, the urlFilter will be matched against the url http://abc.xn--p1ai/?q=%D1%84.

RuleConditionKeys

In behandeling

Enum

"urlFilter"

"regexFilter"

"isUrlFilterCaseSensitive"

"initiatorDomains"

"excludedInitiatorDomains"

"requestDomains"

"excludedRequestDomains"

"topDomains"

"excludedTopDomains"

"domains"

"excludedDomains"

"resourceTypes"

"excludedResourceTypes"

"requestMethods"

"excludedRequestMethods"

"domainType"

"tabIds"

"excludedTabIds"

"responseHeaders"

"excludedResponseHeaders"

Ruleset

Eigenschappen

  • ingeschakeld

    booleaans

    Whether the ruleset is enabled by default.

  • id

    snaar

    A non-empty string uniquely identifying the ruleset. IDs beginning with '_' are reserved for internal use.

  • pad

    snaar

    The path of the JSON ruleset relative to the extension directory.

RulesMatchedDetails

Eigenschappen

TabActionCountUpdate

Chrome 89+

Eigenschappen

  • verhoging

    nummer

    The amount to increment the tab's action count by. Negative values will decrement the count.

  • tabId

    nummer

    The tab for which to update the action count.

TestMatchOutcomeResult

Chrome 103+

Eigenschappen

  • matchedRules

    MatchedRule []

    The rules (if any) that match the hypothetical request.

TestMatchRequestDetails

Chrome 103+

Eigenschappen

  • initiatiefnemer

    string optional

    The initiator URL (if any) for the hypothetical request.

  • methode

    RequestMethod optional

    Standard HTTP method of the hypothetical request. Defaults to "get" for HTTP requests and is ignored for non-HTTP requests.

  • responseHeaders

    object optional

    Chrome 129+

    The headers provided by a hypothetical response if the request does not get blocked or redirected before it is sent. Represented as an object which maps a header name to a list of string values. If not specified, the hypothetical response would return empty response headers, which can match rules which match on the non-existence of headers. Eg {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}

  • tabId

    number optional

    The ID of the tab in which the hypothetical request takes place. Does not need to correspond to a real tab ID. Default is -1, meaning that the request isn't related to a tab.

  • topUrl

    string optional

    In behandeling

    The associated top-level frame URL (if any) for the request.

  • The resource type of the hypothetical request.

  • URL

    snaar

    The URL of the hypothetical request.

UnsupportedRegexReason

Chrome 87+

Describes the reason why a given regular expression isn't supported.

Enum

"syntaxError"
The regular expression is syntactically incorrect, or uses features not available in the RE2 syntax .

"memoryLimitExceeded"
The regular expression exceeds the memory limit.

UpdateRuleOptions

Chrome 87+

Eigenschappen

  • addRules

    Rule [] optional

    Rules to add.

  • removeRuleIds

    number[] optional

    IDs of the rules to remove. Any invalid IDs will be ignored.

UpdateRulesetOptions

Chrome 87+

Eigenschappen

  • disableRulesetIds

    string[] optional

    The set of ids corresponding to a static Ruleset that should be disabled.

  • enableRulesetIds

    string[] optional

    The set of ids corresponding to a static Ruleset that should be enabled.

UpdateStaticRulesOptions

Chrome 111+

Eigenschappen

  • disableRuleIds

    number[] optional

    Set of ids corresponding to rules in the Ruleset to disable.

  • enableRuleIds

    number[] optional

    Set of ids corresponding to rules in the Ruleset to enable.

  • rulesetId

    snaar

    The id corresponding to a static Ruleset .

URLTransform

Eigenschappen

  • fragment

    string optional

    The new fragment for the request. Should be either empty, in which case the existing fragment is cleared; or should begin with '#'.

  • gastheer

    string optional

    The new host for the request.

  • wachtwoord

    string optional

    The new password for the request.

  • pad

    string optional

    The new path for the request. If empty, the existing path is cleared.

  • haven

    string optional

    The new port for the request. If empty, the existing port is cleared.

  • vraag

    string optional

    The new query for the request. Should be either empty, in which case the existing query is cleared; or should begin with '?'.

  • queryTransform

    QueryTransform optional

    Add, remove or replace query key-value pairs.

  • scheme

    string optional

    The new scheme for the request. Allowed values are "http", "https", "ftp" and "chrome-extension".

  • gebruikersnaam

    string optional

    The new username for the request.

Eigenschappen

DYNAMIC_RULESET_ID

Ruleset ID for the dynamic rules added by the extension.

Waarde

"_dynamisch"

GETMATCHEDRULES_QUOTA_INTERVAL

Time interval within which MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules calls can be made, specified in minutes. Additional calls will fail immediately and set runtime.lastError . Note: getMatchedRules calls associated with a user gesture are exempt from the quota.

Waarde

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89+

The minimum number of static rules guaranteed to an extension across its enabled static rulesets. Any rules above this limit will count towards the global static rule limit .

Waarde

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

The number of times getMatchedRules can be called within a period of GETMATCHEDRULES_QUOTA_INTERVAL .

Waarde

20

MAX_NUMBER_OF_DYNAMIC_RULES

The maximum number of dynamic rules that an extension can add.

Waarde

30000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94+

The maximum number of static Rulesets an extension can enable at any one time.

Waarde

50

MAX_NUMBER_OF_REGEX_RULES

The maximum number of regular expression rules that an extension can add. This limit is evaluated separately for the set of dynamic rules and those specified in the rule resources file.

Waarde

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120+

The maximum number of session scoped rules that an extension can add.

Waarde

5000

MAX_NUMBER_OF_STATIC_RULESETS

The maximum number of static Rulesets an extension can specify as part of the "rule_resources" manifest key.

Waarde

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120+

The maximum number of "unsafe" dynamic rules that an extension can add.

Waarde

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120+

The maximum number of "unsafe" session scoped rules that an extension can add.

Waarde

5000

SESSION_RULESET_ID

Chrome 90+

Ruleset ID for the session-scoped rules added by the extension.

Waarde

"_sessie"

Methoden

getAvailableStaticRuleCount()

Chrome 89+
chrome.declarativeNetRequest.getAvailableStaticRuleCount(): Promise<number>

Returns the number of static rules an extension can enable before the global static rule limit is reached.

Retourneert

  • Promise<number>

    Chrome 91+

getDisabledRuleIds()

Chrome 111+
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
): Promise<number[]>

Returns the list of static rules in the given Ruleset that are currently disabled.

Parameters

Retourneert

  • Promise<number[]>

getDynamicRules()

chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
): Promise<Rule[]>

Returns the current set of dynamic rules for the extension. Callers can optionally filter the list of fetched rules by specifying a filter .

Parameters

  • filter

    GetRulesFilter optional

    Chrome 111+

    An object to filter the list of fetched rules.

Retourneert

  • Promise< Rule []>

    Chrome 91+

getEnabledRulesets()

chrome.declarativeNetRequest.getEnabledRulesets(): Promise<string[]>

Returns the ids for the current set of enabled static rulesets.

Retourneert

  • Promise<string[]>

    Chrome 91+

getMatchedRules()

chrome.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
): Promise<RulesMatchedDetails>

Returns all rules matched for the extension. Callers can optionally filter the list of matched rules by specifying a filter . This method is only available to extensions with the "declarativeNetRequestFeedback" permission or having the "activeTab" permission granted for the tabId specified in filter . Note: Rules not associated with an active document that were matched more than five minutes ago will not be returned.

Parameters

Retourneert

getSessionRules()

Chrome 90+
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
): Promise<Rule[]>

Returns the current set of session scoped rules for the extension. Callers can optionally filter the list of fetched rules by specifying a filter .

Parameters

  • filter

    GetRulesFilter optional

    Chrome 111+

    An object to filter the list of fetched rules.

Retourneert

  • Promise< Rule []>

    Chrome 91+

isRegexSupported()

Chrome 87+
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
): Promise<IsRegexSupportedResult>

Checks if the given regular expression will be supported as a regexFilter rule condition.

Parameters

  • regexOptions

    RegexOptions

    The regular expression to check.

Retourneert

setExtensionActionOptions()

Chrome 88+
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
): Promise<void>

Configures if the action count for tabs should be displayed as the extension action's badge text and provides a way for that action count to be incremented.

Parameters

Retourneert

  • Promise<void>

    Chrome 91+

testMatchOutcome()

Chrome 103+
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
): Promise<TestMatchOutcomeResult>

Checks if any of the extension's declarativeNetRequest rules would match a hypothetical request. Note: Only available for unpacked extensions as this is only intended to be used during extension development.

Parameters

Retourneert

updateDynamicRules()

chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
): Promise<void>

Modifies the current set of dynamic rules for the extension. The rules with IDs listed in options.removeRuleIds are first removed, and then the rules given in options.addRules are added. Notes:

  • This update happens as a single atomic operation: either all specified rules are added and removed, or an error is returned.
  • These rules are persisted across browser sessions and across extension updates.
  • Static rules specified as part of the extension package can not be removed using this function.
  • MAX_NUMBER_OF_DYNAMIC_RULES is the maximum number of dynamic rules an extension can add. The number of unsafe rules must not exceed MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES .

Parameters

Retourneert

  • Promise<void>

    Chrome 91+

updateEnabledRulesets()

chrome.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
): Promise<void>

Updates the set of enabled static rulesets for the extension. The rulesets with IDs listed in options.disableRulesetIds are first removed, and then the rulesets listed in options.enableRulesetIds are added. Note that the set of enabled static rulesets is persisted across sessions but not across extension updates, ie the rule_resources manifest key will determine the set of enabled static rulesets on each extension update.

Parameters

Retourneert

  • Promise<void>

    Chrome 91+

updateSessionRules()

Chrome 90+
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
): Promise<void>

Modifies the current set of session scoped rules for the extension. The rules with IDs listed in options.removeRuleIds are first removed, and then the rules given in options.addRules are added. Notes:

  • This update happens as a single atomic operation: either all specified rules are added and removed, or an error is returned.
  • These rules are not persisted across sessions and are backed in memory.
  • MAX_NUMBER_OF_SESSION_RULES is the maximum number of session rules an extension can add.

Parameters

Retourneert

  • Promise<void>

    Chrome 91+

updateStaticRules()

Chrome 111+
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
): Promise<void>

Disables and enables individual static rules in a Ruleset . Changes to rules belonging to a disabled Ruleset will take effect the next time that it becomes enabled.

Parameters

Retourneert

  • Promise<void>

Evenementen

onRuleMatchedDebug

chrome.declarativeNetRequest.onRuleMatchedDebug.addListener(
  callback: function,
)

Fired when a rule is matched with a request. Only available for unpacked extensions with the "declarativeNetRequestFeedback" permission as this is intended to be used for debugging purposes only.

Parameters