chrome.declarativeNetRequest

Descrizione

L'API chrome.declarativeNetRequest viene utilizzata per bloccare o modificare le richieste di rete specificando regole dichiarative. In questo modo, le estensioni possono modificare le richieste di rete senza intercettarle e visualizzarne i contenuti, garantendo così una maggiore privacy.

Autorizzazioni

declarativeNetRequest
declarativeNetRequestWithHostAccess

Le autorizzazioni "declarativeNetRequest" e "declarativeNetRequestWithHostAccess" offrono le stesse funzionalità. La differenza tra questi servizi è determinata dal momento in cui le autorizzazioni vengono richieste o concesse.

"declarativeNetRequest"
Attiva un avviso di autorizzazione al momento dell'installazione, ma fornisce l'accesso implicito alle regole allow, allowAllRequests e block. Utilizza questa opzione, se possibile, per evitare di dover richiedere l'accesso completo agli host.
"declarativeNetRequestFeedback"
Attiva le funzionalità di debug per le estensioni non compresse, in particolare getMatchedRules() e onRuleMatchedDebug.
"declarativeNetRequestWithHostAccess"
Un avviso di autorizzazione non viene visualizzato al momento dell'installazione, ma devi richiedere le autorizzazioni host prima di poter eseguire qualsiasi azione su un host. Questo è appropriato quando vuoi utilizzare regole di richiesta di rete dichiarative in un'estensione che dispone già delle autorizzazioni host senza generare ulteriori avvisi.

Disponibilità

Chrome 84 e versioni successive

Manifest

Oltre alle autorizzazioni descritte in precedenza, alcuni tipi di set di regole, in particolare i set di regole statici, richiedono la dichiarazione della chiave manifest "declarative_net_request", che deve essere un dizionario con una singola chiave denominata "rule_resources". Questa chiave è un array contenente dizionari di tipo Ruleset, come mostrato di seguito. Tieni presente che il nome "Ruleset" non viene visualizzato nel JSON del manifest poiché è semplicemente un array. I set di regole statiche sono spiegati più avanti in questo documento.

{
  "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/*"
  ],
  ...
}

Regole e insiemi di regole

Per utilizzare questa API, specifica uno o più insiemi di regole. Un insieme di regole contiene un array di regole. Una singola regola esegue una delle seguenti operazioni:

  • Blocca una richiesta di rete.
  • Esegui l'upgrade dello schema (da http a https).
  • Impedisci il blocco di una richiesta negando le regole bloccate corrispondenti.
  • Reindirizzare una richiesta di rete.
  • Modifica le intestazioni della richiesta o della risposta.

Esistono tre tipi di set di regole, gestiti in modi leggermente diversi.

Dinamico
Persistono nelle sessioni del browser e negli upgrade delle estensioni e vengono gestite utilizzando JavaScript mentre un'estensione è in uso.
Sessione
Cancellati quando il browser si chiude e quando viene installata una nuova versione dell'estensione. Le regole di sessione vengono gestite utilizzando JavaScript mentre è in uso un'estensione.
Statica
Pacchettizzato, installato e aggiornato quando un'estensione viene installata o aggiornata. Le regole statiche vengono archiviate in file di regole in formato JSON ed elencate nel file manifest.

Set di regole dinamici e basati sulle sessioni

I set di regole dinamici e di sessione vengono gestiti utilizzando JavaScript mentre un'estensione è in uso.

  • Le regole dinamiche vengono mantenute tra le sessioni del browser e gli upgrade delle estensioni.
  • Le regole della sessione vengono cancellate quando il browser viene chiuso e quando viene installata una nuova versione dell'estensione.

Esiste un solo tipo di ciascun insieme di regole. Un'estensione può aggiungere o rimuovere regole in modo dinamico chiamando updateDynamicRules() e updateSessionRules(), a condizione che non vengano superati i limiti delle regole. Per informazioni sui limiti delle regole, vedi Limiti delle regole. Puoi vedere un esempio nella sezione Esempi di codice.

Set di regole statici

A differenza delle regole dinamiche e di sessione, le regole statiche vengono pacchettizzate, installate e aggiornate quando un'estensione viene installata o aggiornata. Vengono memorizzate in file di regole in formato JSON, che vengono indicati all'estensione utilizzando le chiavi "declarative_net_request" e "rule_resources" come descritto sopra, nonché uno o più dizionari Ruleset. Un dizionario Ruleset contiene un percorso al file di regole, un ID per il set di regole contenuto nel file e indica se il set di regole è abilitato o disabilitato. Gli ultimi due sono importanti quando attivi o disattivi un insieme di regole in modo programmatico.

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

Per testare i file delle regole, carica l'estensione decompressa. Gli errori e gli avvisi relativi alle regole statiche non valide vengono visualizzati solo per le estensioni non compresse. Le regole statiche non valide nelle estensioni compresse vengono ignorate.

Revisione rapida

Le modifiche ai set di regole statiche potrebbero essere idonee per la revisione rapida. Consulta la revisione rapida per le modifiche idonee.

Attivare e disattivare regole e set di regole statici

Sia le singole regole statiche sia gli insiemi di regole statiche completi possono essere attivati o disattivati in fase di runtime.

L'insieme di regole statiche e serie di regole abilitate viene mantenuto tra le sessioni del browser. Nessuno dei due viene mantenuto dopo gli aggiornamenti delle estensioni, il che significa che dopo un aggiornamento sono disponibili solo le regole che hai scelto di lasciare nei file di regole.

Per motivi di prestazioni, esistono anche limiti al numero di regole e set di regole che possono essere attivati contemporaneamente. Chiama il numero getAvailableStaticRuleCount() per verificare il numero di regole aggiuntive che possono essere attivate. Per informazioni sui limiti delle regole, vedi Limiti delle regole.

Per attivare o disattivare le regole statiche, chiama il numero updateStaticRules(). Questo metodo accetta un oggetto UpdateStaticRulesOptions, che contiene array di ID delle regole da attivare o disattivare. Gli ID vengono definiti utilizzando la chiave "id" del dizionario Ruleset. Il limite massimo di regole statiche disattivate è 5000.

Per attivare o disattivare i ruleset statici, chiama il numero updateEnabledRulesets(). Questo metodo accetta un oggetto UpdateRulesetOptions, che contiene array di ID di insiemi di regole da attivare o disattivare. Gli ID vengono definiti utilizzando la chiave "id" del dizionario Ruleset.

Creare regole

Indipendentemente dal tipo, una regola inizia con quattro campi, come mostrato di seguito. Mentre i tasti "id" e "priority" richiedono un numero, i tasti "action" e "condition" possono fornire diverse condizioni di blocco e reindirizzamento. La seguente regola blocca tutte le richieste di script provenienti da "foo.com" a qualsiasi URL con "abc" come sottostringa.

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

Corrispondenza URL

Declarative Net Request consente di trovare corrispondenze tra gli URL con una sintassi di corrispondenza dei pattern o con espressioni regolari.

Sintassi del filtro URL

La chiave "condition" di una regola consente una chiave "urlFilter" per intervenire sugli URL di un dominio specificato. Crea pattern utilizzando i token di corrispondenza di pattern. Ecco alcuni esempi.

urlFilter Corrisponde a Non corrisponde a
"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://b.a.example.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

Espressioni regolari

Le condizioni possono utilizzare anche espressioni regolari. Vedi il tasto "regexFilter". Per informazioni sui limiti che si applicano a queste condizioni, consulta Regole che utilizzano espressioni regolari.

Scrivere condizioni per gli URL efficaci

Presta attenzione quando scrivi le regole in modo che corrispondano sempre a un intero dominio. In caso contrario, la regola potrebbe corrispondere a situazioni impreviste. Ad esempio, quando utilizzi la sintassi di corrispondenza dei pattern:

  • google.com corrisponde erroneamente a https://example.com/?param=google.com
  • ||google.com corrisponde erroneamente a https://google.company
  • https://www.google.com corrisponde erroneamente a https://example.com/?param=https://www.google.com

Valuta l'uso di:

  • ||google.com/, che corrisponde a tutti i percorsi e a tutti i sottodomini.
  • |https://www.google.com/ che corrisponde a tutti i percorsi e a nessun sottodominio.

Allo stesso modo, utilizza i caratteri ^ e / per ancorare un'espressione regolare. Ad esempio, ^https:\/\/p.rizon.top:443\/https\/www\.google\.com\/ corrisponde a qualsiasi percorso su https://www.google.com.

Valutazione delle regole

Le regole DNR vengono applicate dal browser in varie fasi del ciclo di vita della richiesta di rete.

Prima della richiesta

Prima che venga effettuata una richiesta, un'estensione può bloccarla o reindirizzarla (incluso l'upgrade dello schema da HTTP a HTTPS) con una regola corrispondente.

Per ogni estensione, il browser determina un elenco di regole corrispondenti. Le regole con un'azione modifyHeaders non sono incluse qui, in quanto verranno gestite in un secondo momento. Inoltre, le regole con una condizione responseHeaders verranno prese in considerazione in un secondo momento (quando le intestazioni della risposta saranno disponibili) e non sono incluse.

Poi, per ogni estensione, Chrome sceglie al massimo un candidato per richiesta. Chrome trova una regola corrispondente ordinando tutte le regole corrispondenti in base alla priorità. Le regole con la stessa priorità sono ordinate per azione (allow o allowAllRequests > block > upgradeScheme > redirect).

Se il candidato è una regola allow o allowAllRequests oppure se il frame in cui viene effettuata la richiesta corrispondeva in precedenza a una regola allowAllRequests di priorità superiore o uguale di questa estensione, la richiesta è "consentita" e l'estensione non avrà alcun effetto sulla richiesta.

Se più di un'estensione vuole bloccare o reindirizzare questa richiesta, viene scelta una singola azione da intraprendere. Chrome lo fa ordinando le regole nell'ordine block > redirect o upgradeScheme > allow o allowAllRequests. Se due regole sono dello stesso tipo, Chrome sceglie la regola dell'estensione installata più di recente.

Prima dell'invio delle intestazioni delle richieste

Prima che Chrome invii le intestazioni delle richieste al server, queste vengono aggiornate in base alle regole modifyHeaders corrispondenti.

All'interno di una singola estensione, Chrome crea l'elenco delle modifiche da eseguire trovando tutte le regole modifyHeaders corrispondenti. Come in precedenza, vengono incluse solo le regole con una priorità superiore a qualsiasi regola allow o allowAllRequests corrispondente.

Queste regole vengono applicate da Chrome in modo che le regole di un'estensione installata più di recente vengano sempre valutate prima di quelle di un'estensione meno recente. Inoltre, le regole con priorità maggiore di un'estensione vengono sempre applicate prima delle regole con priorità inferiore della stessa estensione. In particolare, anche tra le estensioni:

  • Se una regola viene aggiunta a un'intestazione, le regole con priorità inferiore possono essere aggiunte solo a quell'intestazione. Le operazioni di impostazione e rimozione non sono consentite.
  • Se una regola imposta un'intestazione, solo le regole con priorità inferiore della stessa estensione possono essere aggiunte a questa intestazione. Non sono consentite altre modifiche.
  • Se una regola rimuove un'intestazione, le regole con priorità inferiore non possono modificarla ulteriormente.

Una volta ricevuta una risposta

Una volta ricevute le intestazioni della risposta, Chrome valuta le regole con una condizione responseHeaders.

Dopo aver ordinato queste regole per action e priority ed escluso le regole rese ridondanti da una regola allow o allowAllRequests corrispondente (questo avviene in modo identico ai passaggi descritti in "Prima della richiesta"), Chrome potrebbe bloccare o reindirizzare la richiesta per conto di un'estensione.

Tieni presente che se una richiesta è arrivata a questa fase, è già stata inviata al server e il server ha ricevuto dati come il corpo della richiesta. Una regola di blocco o reindirizzamento con una condizione di intestazioni della risposta verrà comunque eseguita, ma non potrà effettivamente bloccare o reindirizzare la richiesta.

Nel caso di una regola di blocco, questa viene gestita dalla pagina che ha effettuato la richiesta ricevendo una risposta bloccata e Chrome interrompendo la richiesta in anticipo. Nel caso di una regola di reindirizzamento, Chrome effettua una nuova richiesta all'URL reindirizzato. Assicurati di valutare se questi comportamenti soddisfano le aspettative di privacy per la tua estensione.

Se la richiesta non viene bloccata o reindirizzata, Chrome applica le regole di modifyHeaders. L'applicazione delle modifiche alle intestazioni della risposta funziona allo stesso modo di quanto descritto in "Prima dell'invio delle intestazioni della richiesta". L'applicazione di modifiche alle intestazioni delle richieste non ha alcun effetto, poiché la richiesta è già stata effettuata.

Regole sicure

Le regole sicure sono definite come regole con un'azione di block, allow, allowAllRequests o upgradeScheme. Queste regole sono soggette a una quota maggiore per le regole dinamiche.

Limiti delle regole

Il caricamento e la valutazione delle regole nel browser comportano un overhead delle prestazioni, pertanto si applicano alcuni limiti quando si utilizza l'API. I limiti dipendono dal tipo di regola che utilizzi.

Regole statiche

Le regole statiche sono quelle specificate nei file di regole dichiarati nel file manifest. Un'estensione può specificare fino a 100 ruleset statici come parte della chiave manifest "rule_resources", ma solo 50 di questi ruleset possono essere attivati contemporaneamente. Quest'ultimo è chiamato MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. Complessivamente, questi insiemi di regole garantiscono almeno 30.000 regole. Questo è chiamato GUARANTEED_MINIMUM_STATIC_RULES.

Il numero di regole disponibili dopo dipende da quante regole sono attivate da tutte le estensioni installate nel browser di un utente. Puoi trovare questo numero in fase di runtime chiamando getAvailableStaticRuleCount(). Puoi vedere un esempio nella sezione Esempi di codice.

Regole per le sessioni

Un'estensione può avere fino a 5000 regole di sessione. Questo valore viene esposto come MAX_NUMBER_OF_SESSION_RULES.

Prima di Chrome 120, era previsto un limite di 5000 regole dinamiche e di sessione combinate.

Regole dinamiche

Un'estensione può avere almeno 5000 regole dinamiche. Questo valore viene esposto come MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES.

A partire da Chrome 121, è disponibile un limite più elevato di 30.000 regole per le regole dinamiche sicure, esposte come MAX_NUMBER_OF_DYNAMIC_RULES. Anche le regole non sicure aggiunte entro il limite di 5000 verranno conteggiate ai fini di questo limite.

Prima di Chrome 120, esisteva un limite combinato di 5000 regole dinamiche e di sessione.

Regole che utilizzano espressioni regolari

Tutti i tipi di regole possono utilizzare espressioni regolari; tuttavia, il numero totale di regole di espressioni regolari di ogni tipo non può superare 1000. Questo limite è chiamato MAX_NUMBER_OF_REGEX_RULES.

Inoltre, ogni regola deve avere dimensioni inferiori a 2 KB una volta compilata. Ciò corrisponde approssimativamente alla complessità della regola. Se tenti di caricare una regola che supera questo limite, visualizzerai un avviso come il seguente e la regola verrà ignorata.

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

Interazioni con i service worker

Una declarativeNetRequest si applica solo alle richieste che raggiungono lo stack di rete. Sono incluse le risposte della cache HTTP, ma potrebbero non essere incluse le risposte che passano attraverso il gestore onfetch di un service worker. declarativeNetRequest non influisce sulle risposte generate dal service worker o recuperate da CacheStorage, ma influisce sulle chiamate a fetch() effettuate in un service worker.

Risorse accessibili dal web

Una regola declarativeNetRequest non può reindirizzare una richiesta di risorse pubbliche a una risorsa non accessibile dal web. In questo modo viene attivato un errore. Ciò vale anche se la risorsa accessibile dal web specificata è di proprietà dell'estensione di reindirizzamento. Per dichiarare le risorse per declarativeNetRequest, utilizza l'array "web_accessible_resources" del manifest.

Modifica dell'intestazione

L'operazione di aggiunta è supportata solo per le seguenti intestazioni: 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.

Esempi

Esempi di codice

Aggiornare le regole dinamiche

L'esempio seguente mostra come chiamare updateDynamicRules(). La procedura per updateSessionRules() è la stessa.

// 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
});

Aggiornare i set di regole statici

L'esempio seguente mostra come attivare e disattivare i set di regole tenendo conto del numero di set di regole statiche disponibili e del numero massimo di set di regole statiche attivati. Puoi farlo quando il numero di regole statiche che ti servono supera il numero consentito. Affinché funzioni, alcuni dei tuoi set di regole devono essere installati con alcuni disattivati (impostando "Enabled" su false all'interno del file manifest).

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);
}

Esempi di regole

Gli esempi riportati di seguito illustrano in che modo Chrome assegna la priorità alle regole in un'estensione. Quando le esamini, ti consigliamo di aprire le regole di assegnazione delle priorità in una finestra separata.

La chiave "priority"

Questi esempi richiedono l'autorizzazione host per *://*.example.com/*.

Per determinare la priorità di un determinato URL, esamina la chiave "priority" (definita dallo sviluppatore), la chiave "action" e la chiave "urlFilter". Questi esempi si riferiscono al file di regole di esempio mostrato di seguito.

Navigazione fino a https://google.com
Due regole coprono questo URL: le regole con ID 1 e 4. Viene applicata la regola con ID 1 perché le azioni "block" hanno una priorità più alta rispetto alle azioni "redirect". Le regole rimanenti non si applicano perché riguardano URL più lunghi.
Navigazione alla pagina https://google.com/1234
A causa dell'URL più lungo, ora la regola con ID 2 corrisponde anche alle regole con ID 1 e 4. Viene applicata la regola con ID 2 perché "allow" ha una priorità maggiore rispetto a "block" e "redirect".
Navigazione all'indirizzo https://google.com/12345
Tutte e quattro le regole corrispondono a questo URL. Viene applicata la regola con ID 3 perché la priorità definita dallo sviluppatore è la più alta del gruppo.
[
  {
    "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"] }
  },
]

Reindirizzamenti

L'esempio seguente richiede l'autorizzazione host per *://*.example.com/*.

L'esempio seguente mostra come reindirizzare una richiesta da example.com a una pagina all'interno dell'estensione stessa. Il percorso dell'estensione /a.jpg viene risolto in chrome-extension://EXTENSION_ID/a.jpg, dove EXTENSION_ID è l'ID dell'estensione. Affinché questa operazione funzioni, il manifest deve dichiarare /a.jpg come risorsa accessibile dal web.

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

Di seguito viene utilizzata la chiave "transform" per reindirizzare a un sottodominio di example.com. Viene utilizzato un ancoraggio del nome di dominio ("||") per intercettare le richieste con qualsiasi schema da example.com. La chiave "scheme" in "transform" specifica che i reindirizzamenti al sottodominio utilizzeranno sempre "https".

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

L'esempio seguente utilizza le espressioni regolari per reindirizzare da https://www.abc.xyz.com/path a https://abc.xyz.com/path. Nella chiave "regexFilter", nota come i punti vengono sottoposti a escape e che il gruppo di acquisizione seleziona "abc" o "def". La chiave "regexSubstitution" specifica la prima corrispondenza restituita dell'espressione regolare utilizzando "\1". In questo caso, "abc" viene acquisito dall'URL reindirizzato e inserito nella sostituzione.

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

Intestazioni

L'esempio seguente rimuove tutti i cookie da un frame principale e da tutti i frame secondari.

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

Tipi

DomainType

Indica se la richiesta è di prima o terza parte rispetto al frame in cui è stata generata. Una richiesta è considerata proprietaria se ha lo stesso dominio (eTLD+1) del frame in cui è stata generata.

Enum

"firstParty"
La richiesta di rete è proprietaria del frame in cui è stata generata.

"thirdParty"
La richiesta di rete è di terze parti rispetto al frame in cui è stata generata.

ExtensionActionOptions

Chrome 88+

Proprietà

  • displayActionCountAsBadgeText

    booleano facoltativo

    Se visualizzare automaticamente il conteggio delle azioni per una pagina come testo del badge dell'estensione. Questa preferenza viene mantenuta tra le sessioni.

  • tabUpdate

    TabActionCountUpdate facoltativo

    Chrome 89+

    Dettagli su come deve essere aggiustato il conteggio delle azioni della scheda.

GetDisabledRuleIdsOptions

Chrome 111+

Proprietà

  • rulesetId

    stringa

    L'ID corrispondente a un Ruleset statico.

GetRulesFilter

Chrome 111+

Proprietà

  • ruleIds

    number[] facoltativo

    Se specificate, vengono incluse solo le regole con ID corrispondenti.

HeaderInfo

Chrome 128+

Proprietà

  • excludedValues

    string[] facoltativo

    Se specificata, questa condizione non viene soddisfatta se l'intestazione esiste, ma il suo valore contiene almeno un elemento in questo elenco. Utilizza la stessa sintassi del pattern di corrispondenza di values.

  • intestazione

    stringa

    Il nome dell'intestazione. Questa condizione corrisponde al nome solo se values e excludedValues non sono specificati.

  • valori

    string[] facoltativo

    Se specificata, questa condizione corrisponde se il valore dell'intestazione corrisponde ad almeno un pattern in questo elenco. Supporta la corrispondenza dei valori di intestazione senza distinzione tra maiuscole e minuscole, oltre ai seguenti costrutti:

    "*" : corrisponde a un numero qualsiasi di caratteri.

    "?" : corrisponde a zero o uno o più caratteri.

    "*" e "?" possono essere preceduti da una barra rovesciata, ad esempio "\*" e "\?".

HeaderOperation

Chrome 86+

Descrive le possibili operazioni per una regola "modifyHeaders".

Enum

"append"
Aggiunge una nuova voce per l'intestazione specificata. Questa operazione non è supportata per le intestazioni delle richieste.

"set"
Imposta un nuovo valore per l'intestazione specificata, rimuovendo eventuali intestazioni esistenti con lo stesso nome.

"remove"
Rimuove tutte le voci per l'intestazione specificata.

IsRegexSupportedResult

Chrome 87+

Proprietà

  • isSupported

    booleano

  • motivo

    UnsupportedRegexReason facoltativo

    Specifica il motivo per cui l'espressione regolare non è supportata. Fornito solo se isSupported è false.

MatchedRule

Proprietà

  • ruleId

    numero

    L'ID di una regola corrispondente.

  • rulesetId

    stringa

    ID del Ruleset a cui appartiene questa regola. Per una regola proveniente dall'insieme di regole dinamiche, questo valore sarà uguale a DYNAMIC_RULESET_ID.

MatchedRuleInfo

Proprietà

  • regola

    MatchedRule

  • tabId

    numero

    Il tabId della scheda da cui ha avuto origine la richiesta, se la scheda è ancora attiva. Else -1.

  • timeStamp

    numero

    L'ora in cui è stata trovata una corrispondenza con la regola. I timestamp corrisponderanno alla convenzione JavaScript per gli orari, ovvero il numero di millisecondi trascorsi dall'epoca.

MatchedRuleInfoDebug

Proprietà

  • richiesta

    RequestDetails

    Dettagli sulla richiesta per cui è stata trovata una corrispondenza con la regola.

  • regola

    MatchedRule

MatchedRulesFilter

Proprietà

  • minTimeStamp

    number (facoltativo)

    Se specificato, corrisponde solo alle regole dopo il timestamp indicato.

  • tabId

    number (facoltativo)

    Se specificato, vengono abbinate solo le regole per la scheda indicata. Corrisponde alle regole non associate ad alcuna scheda attiva se impostato su -1.

ModifyHeaderInfo

Chrome 86+

Proprietà

  • intestazione

    stringa

    Il nome dell'intestazione da modificare.

  • operazione

    HeaderOperation

    L'operazione da eseguire su un'intestazione.

  • valore

    stringa facoltativa

    Il nuovo valore per l'intestazione. Deve essere specificato per le operazioni append e set.

QueryKeyValue

Proprietà

  • chiave

    stringa

  • replaceOnly

    booleano facoltativo

    Chrome 94+

    Se true, la chiave di query viene sostituita solo se è già presente. In caso contrario, la chiave viene aggiunta anche se manca. Il valore predefinito è false.

  • valore

    stringa

QueryTransform

Proprietà

  • addOrReplaceParams

    QueryKeyValue[] facoltativo

    L'elenco delle coppie chiave-valore della query da aggiungere o sostituire.

  • removeParams

    string[] facoltativo

    L'elenco delle chiavi di query da rimuovere.

Redirect

Proprietà

  • extensionPath

    stringa facoltativa

    Percorso relativo alla directory dell'estensione. Deve iniziare con "/".

  • regexSubstitution

    stringa facoltativa

    Pattern di sostituzione per le regole che specificano un regexFilter. La prima corrispondenza di regexFilter all'interno dell'URL verrà sostituita con questo pattern. All'interno di regexSubstitution, è possibile utilizzare cifre con interpretazione letterale a una barra rovesciata (da \1 a \9) per inserire i gruppi di acquisizione corrispondenti. \0 si riferisce all'intero testo corrispondente.

  • trasformazione

    URLTransform facoltativo

    Trasformazioni URL da eseguire.

  • url

    stringa facoltativa

    L'URL di reindirizzamento. I reindirizzamenti agli URL JavaScript non sono consentiti.

RegexOptions

Chrome 87+

Proprietà

  • isCaseSensitive

    booleano facoltativo

    Indica se il regex specificato è sensibile alle maiuscole. Il valore predefinito è true.

  • regex

    stringa

    L'espressione regolare da controllare.

  • requireCapturing

    booleano facoltativo

    Se è necessario acquisire il regex specificato. L'acquisizione è necessaria solo per le regole di reindirizzamento che specificano un'azione regexSubstition. Il valore predefinito è false.

RequestDetails

Proprietà

  • documentId

    stringa facoltativa

    Chrome 106+

    L'identificatore univoco del documento del frame, se questa richiesta riguarda un frame.

  • documentLifecycle

    DocumentLifecycle facoltativo

    Chrome 106+

    Il ciclo di vita del documento del frame, se questa richiesta riguarda un frame.

  • frameId

    numero

    Il valore 0 indica che la richiesta viene eseguita nel frame principale; un valore positivo indica l'ID di un subframe in cui viene eseguita la richiesta. Se il documento di un (sotto)frame viene caricato (type è main_frame o sub_frame), frameId indica l'ID di questo frame, non l'ID del frame esterno. Gli ID frame sono univoci all'interno di una scheda.

  • frameType

    FrameType facoltativo

    Chrome 106+

    Il tipo di frame, se questa richiesta riguarda un frame.

  • iniziatore

    stringa facoltativa

    L'origine da cui è stata avviata la richiesta. Questo valore non cambia con i reindirizzamenti. Se si tratta di un'origine opaca, verrà utilizzata la stringa "null".

  • method

    stringa

    Metodo HTTP standard.

  • parentDocumentId

    stringa facoltativa

    Chrome 106+

    L'identificatore univoco del documento principale del frame, se questa richiesta riguarda un frame e ha un elemento principale.

  • parentFrameId

    numero

    ID del frame che contiene il frame che ha inviato la richiesta. Imposta su -1 se non esiste un frame principale.

  • requestId

    stringa

    L'ID della richiesta. Gli ID richiesta sono univoci all'interno di una sessione del browser.

  • tabId

    numero

    L'ID della scheda in cui viene eseguita la richiesta. Imposta il valore su -1 se la richiesta non è correlata a una scheda.

  • Il tipo di risorsa della richiesta.

  • url

    stringa

    L'URL della richiesta.

RequestMethod

Chrome 91+

Descrive il metodo di richiesta HTTP di una richiesta di rete.

Enum

"connect"

"delete"

"get"

"head"

"options"

"patch"

"post"

"metti"

"other"

ResourceType

Descrive il tipo di risorsa della richiesta di rete.

Enum

"main_frame"

"sub_frame"

"stylesheet"

"script"

"image"

"font"

"object"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"webtransport"

"webbundle"

"other"

Rule

Proprietà

  • azione

    RuleAction

    L'azione da eseguire se questa regola viene trovata.

  • condizione

    RuleCondition

    La condizione in base alla quale viene attivata questa regola.

  • id

    numero

    Un ID che identifica in modo univoco una regola. Obbligatorio e deve essere >= 1.

  • priorità

    number (facoltativo)

    Priorità regola. Il valore predefinito è 1. Se specificato, deve essere maggiore o uguale a 1.

RuleAction

Proprietà

  • reindirizzamento

    Reindirizzamento opzionale

    Descrive come deve essere eseguito il reindirizzamento. Valido solo per le regole di reindirizzamento.

  • requestHeaders

    ModifyHeaderInfo[] facoltativo

    Chrome 86+

    Le intestazioni della richiesta da modificare per la richiesta. Valido solo se RuleActionType è "modifyHeaders".

  • responseHeaders

    ModifyHeaderInfo[] facoltativo

    Chrome 86+

    Le intestazioni della risposta da modificare per la richiesta. Valido solo se RuleActionType è "modifyHeaders".

  • Il tipo di azione da eseguire.

RuleActionType

Descrive il tipo di azione da intraprendere se una determinata RuleCondition corrisponde.

Enum

"block" (blocca)
Blocca la richiesta di rete.

"redirect"
Reindirizza la richiesta di rete.

"allow"
Consenti la richiesta di rete. La richiesta non verrà intercettata se esiste una regola di autorizzazione che corrisponde.

"upgradeScheme"
Aggiorna lo schema dell'URL della richiesta di rete a https se la richiesta è http o ftp.

"modifyHeaders"
Modifica le intestazioni di richiesta/risposta dalla richiesta di rete.

"allowAllRequests"
Consente tutte le richieste all'interno di una gerarchia di frame, inclusa la richiesta di frame stessa.

RuleCondition

Proprietà

  • domainType

    DomainType facoltativo

    Specifica se la richiesta di rete è proprietaria o di terze parti rispetto al dominio da cui ha avuto origine. Se omesso, tutte le richieste vengono accettate.

  • domini

    string[] facoltativo

    Ritirato a partire da Chrome 101

    Usa invece initiatorDomains

    La regola corrisponderà solo alle richieste di rete provenienti dall'elenco di domains.

  • excludedDomains

    string[] facoltativo

    Ritirato a partire da Chrome 101

    Usa invece excludedInitiatorDomains

    La regola non corrisponderà alle richieste di rete provenienti dall'elenco di excludedDomains.

  • excludedInitiatorDomains

    string[] facoltativo

    Chrome 101+

    La regola non corrisponderà alle richieste di rete provenienti dall'elenco di excludedInitiatorDomains. Se l'elenco è vuoto o omesso, non vengono esclusi domini. Questa azione ha la precedenza su initiatorDomains.

    Note:

    • Sono consentiti anche i sottodomini come "a.example.com".
    • Le voci devono essere costituite solo da caratteri ASCII.
    • Utilizza la codifica Punycode per i domini internazionalizzati.
    • Questa corrispondenza si basa sull'iniziatore della richiesta e non sull'URL della richiesta.
    • Sono esclusi anche i sottodomini dei domini elencati.
  • excludedRequestDomains

    string[] facoltativo

    Chrome 101+

    La regola non corrisponderà alle richieste di rete quando i domini corrispondono a uno dell'elenco di excludedRequestDomains. Se l'elenco è vuoto o omesso, non vengono esclusi domini. Questa azione ha la precedenza su requestDomains.

    Note:

    • Sono consentiti anche i sottodomini come "a.example.com".
    • Le voci devono essere costituite solo da caratteri ASCII.
    • Utilizza la codifica Punycode per i domini internazionalizzati.
    • Sono esclusi anche i sottodomini dei domini elencati.
  • excludedRequestMethods

    RequestMethod[] facoltativo

    Chrome 91+

    Elenco dei metodi di richiesta a cui la regola non corrisponderà. È necessario specificare solo una delle proprietà requestMethods e excludedRequestMethods. Se non viene specificato nessuno dei due, vengono abbinati tutti i metodi di richiesta.

  • excludedResourceTypes

    ResourceType[] facoltativo

    Elenco dei tipi di risorse a cui la regola non corrisponderà. È necessario specificare solo una delle proprietà resourceTypes e excludedResourceTypes. Se non viene specificato nessuno dei due, vengono bloccati tutti i tipi di risorse, ad eccezione di "main_frame".

  • excludedResponseHeaders

    HeaderInfo[] facoltativo

    Chrome 128+

    La regola non corrisponde se la richiesta corrisponde a una condizione di intestazione della risposta in questo elenco (se specificata). Se vengono specificati sia excludedResponseHeaders che responseHeaders, la proprietà excludedResponseHeaders ha la precedenza.

  • excludedTabIds

    number[] facoltativo

    Chrome 92+

    Elenco di tabs.Tab.id a cui la regola non deve corrispondere. Un ID di tabs.TAB_ID_NONE esclude le richieste che non provengono da una scheda. Supportato solo per le regole con ambito sessione.

  • initiatorDomains

    string[] facoltativo

    Chrome 101+

    La regola corrisponderà solo alle richieste di rete provenienti dall'elenco di initiatorDomains. Se l'elenco viene omesso, la regola viene applicata alle richieste provenienti da tutti i domini. Non è consentito utilizzare un elenco vuoto.

    Note:

    • Sono consentiti anche i sottodomini come "a.example.com".
    • Le voci devono essere costituite solo da caratteri ASCII.
    • Utilizza la codifica Punycode per i domini internazionalizzati.
    • Questa corrispondenza si basa sull'iniziatore della richiesta e non sull'URL della richiesta.
    • Vengono abbinati anche i sottodomini dei domini elencati.
  • isUrlFilterCaseSensitive

    booleano facoltativo

    Indica se urlFilter o regexFilter (a seconda di quale è specificato) è sensibile alle maiuscole. Il valore predefinito è false.

  • regexFilter

    stringa facoltativa

    Espressione regolare per trovare corrispondenze con l'URL della richiesta di rete. che segue la sintassi RE2.

    Nota: è possibile specificare un solo elemento (urlFilter o regexFilter).

    Nota: il regexFilter deve essere composto solo da caratteri ASCII. Questo valore viene confrontato con un URL in cui l'host è codificato nel formato Punycode (nel caso di domini internazionalizzati) e tutti gli altri caratteri non ASCII sono codificati nell'URL in UTF-8.

  • requestDomains

    string[] facoltativo

    Chrome 101+

    La regola corrisponderà alle richieste di rete solo quando il dominio corrisponde a uno dell'elenco di requestDomains. Se l'elenco viene omesso, la regola viene applicata alle richieste provenienti da tutti i domini. Non è consentito utilizzare un elenco vuoto.

    Note:

    • Sono consentiti anche i sottodomini come "a.example.com".
    • Le voci devono essere costituite solo da caratteri ASCII.
    • Utilizza la codifica Punycode per i domini internazionalizzati.
    • Vengono abbinati anche i sottodomini dei domini elencati.
  • requestMethods

    RequestMethod[] facoltativo

    Chrome 91+

    Elenco dei metodi di richiesta HTTP a cui la regola può corrispondere. Non è consentito utilizzare un elenco vuoto.

    Nota: se specifichi una condizione della regola requestMethods, verranno escluse anche le richieste non HTTP(S), mentre se specifichi excludedRequestMethods, non verranno escluse.

  • resourceTypes

    ResourceType[] facoltativo

    Elenco dei tipi di risorse a cui può corrispondere la regola. Non è consentito utilizzare un elenco vuoto.

    Nota: questo valore deve essere specificato per le regole allowAllRequests e può includere solo i tipi di risorse sub_frame e main_frame.

  • responseHeaders

    HeaderInfo[] facoltativo

    Chrome 128+

    La regola corrisponde se la richiesta corrisponde a una condizione di intestazione della risposta in questo elenco (se specificata).

  • tabIds

    number[] facoltativo

    Chrome 92+

    Elenco di tabs.Tab.id a cui deve corrispondere la regola. Un ID di tabs.TAB_ID_NONE corrisponde alle richieste che non provengono da una scheda. Non è consentito utilizzare un elenco vuoto. Supportato solo per le regole con ambito sessione.

  • urlFilter

    stringa facoltativa

    Il pattern che viene confrontato con l'URL della richiesta di rete. Costrutti supportati:

    "*": carattere jolly. Corrisponde a un numero qualsiasi di caratteri.

    '|': ancora a sinistra/destra. Se utilizzato a una delle estremità del pattern, specifica rispettivamente l'inizio/la fine dell'URL.

    '||': ancora del nome di dominio. Se utilizzato all'inizio del pattern, specifica l'inizio di un (sotto)dominio dell'URL.

    '^': carattere separatore. Corrisponde a qualsiasi carattere diverso da una lettera, una cifra o uno dei seguenti: _, -, . o %. Corrisponde anche alla fine dell'URL.

    Pertanto, urlFilter è composto dalle seguenti parti: (ancoraggio facoltativo a sinistra/nome di dominio) + pattern + (ancoraggio facoltativo a destra).

    Se omesso, vengono abbinati tutti gli URL. Non è consentita una stringa vuota.

    Un pattern che inizia con ||* non è consentito. Utilizza invece *.

    Nota: è possibile specificare un solo elemento (urlFilter o regexFilter).

    Nota: il urlFilter deve essere composto solo da caratteri ASCII. Questo valore viene confrontato con un URL in cui l'host è codificato nel formato Punycode (nel caso di domini internazionalizzati) e tutti gli altri caratteri non ASCII sono codificati nell'URL in UTF-8. Ad esempio, quando l'URL della richiesta è http://abc.рф?q=ф, urlFilter verrà confrontato con l'URL http://abc.xn--p1ai/?q=%D1%84.

Ruleset

Proprietà

  • attivato

    booleano

    Indica se il set di regole è attivo per impostazione predefinita.

  • id

    stringa

    Una stringa non vuota che identifica in modo univoco il set di regole. Gli ID che iniziano con "_" sono riservati per uso interno.

  • percorso

    stringa

    Il percorso del set di regole JSON relativo alla directory delle estensioni.

RulesMatchedDetails

Proprietà

  • rulesMatchedInfo

    MatchedRuleInfo[]

    Regole corrispondenti al filtro specificato.

TabActionCountUpdate

Chrome 89+

Proprietà

  • aumenta

    numero

    L'importo di cui incrementare il conteggio delle azioni della scheda. I valori negativi decrementano il conteggio.

  • tabId

    numero

    La scheda per cui aggiornare il conteggio delle azioni.

TestMatchOutcomeResult

Chrome 103+

Proprietà

  • matchedRules

    MatchedRule[]

    Le regole (se presenti) che corrispondono alla richiesta ipotetica.

TestMatchRequestDetails

Chrome 103+

Proprietà

  • iniziatore

    stringa facoltativa

    L'URL dell'iniziatore (se presente) per la richiesta ipotetica.

  • method

    RequestMethod facoltativo

    Metodo HTTP standard della richiesta ipotetica. Il valore predefinito è "get" per le richieste HTTP e viene ignorato per le richieste non HTTP.

  • responseHeaders

    oggetto facoltativo

    Chrome 129+

    Le intestazioni fornite da una risposta ipotetica se la richiesta non viene bloccata o reindirizzata prima dell'invio. Rappresentato come un oggetto che mappa un nome di intestazione a un elenco di valori stringa. Se non specificata, la risposta ipotetica restituirebbe intestazioni di risposta vuote, che possono corrispondere a regole che corrispondono alla non esistenza di intestazioni. Ad esempio {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}

  • tabId

    number (facoltativo)

    L'ID della scheda in cui viene effettuata la richiesta ipotetica. Non deve corrispondere a un ID scheda reale. Il valore predefinito è -1, il che significa che la richiesta non è correlata a una scheda.

  • Il tipo di risorsa della richiesta ipotetica.

  • url

    stringa

    L'URL della richiesta ipotetica.

UnsupportedRegexReason

Chrome 87+

Descrive il motivo per cui una determinata espressione regolare non è supportata.

Enum

"syntaxError"
L'espressione regolare è sintatticamente errata o utilizza funzionalità non disponibili nella sintassi RE2.

"memoryLimitExceeded"
L'espressione regolare supera il limite di memoria.

UpdateRuleOptions

Chrome 87+

Proprietà

  • addRules

    Rule[] facoltativo

    Regole da aggiungere.

  • removeRuleIds

    number[] facoltativo

    ID delle regole da rimuovere. Gli ID non validi verranno ignorati.

UpdateRulesetOptions

Chrome 87+

Proprietà

  • disableRulesetIds

    string[] facoltativo

    Il set di ID corrispondente a un Ruleset statico che deve essere disattivato.

  • enableRulesetIds

    string[] facoltativo

    Il set di ID corrispondente a un Ruleset statico che deve essere attivato.

UpdateStaticRulesOptions

Chrome 111+

Proprietà

  • disableRuleIds

    number[] facoltativo

    Set di ID corrispondenti alle regole in Ruleset da disattivare.

  • enableRuleIds

    number[] facoltativo

    Set di ID corrispondenti alle regole in Ruleset da attivare.

  • rulesetId

    stringa

    L'ID corrispondente a un Ruleset statico.

URLTransform

Proprietà

  • frammento

    stringa facoltativa

    Il nuovo frammento per la richiesta. Deve essere vuoto, nel qual caso il frammento esistente viene cancellato, oppure deve iniziare con "#".

  • host

    stringa facoltativa

    Il nuovo host della richiesta.

  • password

    stringa facoltativa

    La nuova password per la richiesta.

  • percorso

    stringa facoltativa

    Il nuovo percorso per la richiesta. Se è vuoto, il percorso esistente viene cancellato.

  • porta

    stringa facoltativa

    La nuova porta per la richiesta. Se è vuoto, la porta esistente viene cancellata.

  • query

    stringa facoltativa

    La nuova query per la richiesta. Deve essere vuoto, nel qual caso la query esistente viene cancellata, oppure deve iniziare con "?".

  • queryTransform

    QueryTransform (facoltativo)

    Aggiungi, rimuovi o sostituisci coppie chiave-valore della query.

  • schema

    stringa facoltativa

    Il nuovo schema per la richiesta. I valori consentiti sono "http", "https", "ftp" e "chrome-extension".

  • nome utente

    stringa facoltativa

    Il nuovo nome utente per la richiesta.

Proprietà

DYNAMIC_RULESET_ID

ID del set di regole per le regole dinamiche aggiunte dall'estensione.

Valore

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

Intervallo di tempo entro il quale è possibile effettuare chiamate al MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules, specificato in minuti. Le chiamate aggiuntive non andranno a buon fine immediatamente e verrà impostato runtime.lastError. Nota: le chiamate getMatchedRules associate a un gesto dell'utente sono esenti dalla quota.

Valore

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89+

Il numero minimo di regole statiche garantite per un'estensione nei relativi insiemi di regole statiche attivati. Le regole che superano questo limite verranno conteggiate ai fini del limite globale delle regole statiche.

Valore

30.000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

Il numero di volte in cui è possibile chiamare getMatchedRules in un periodo di GETMATCHEDRULES_QUOTA_INTERVAL.

Valore

20

MAX_NUMBER_OF_DYNAMIC_RULES

Il numero massimo di regole dinamiche che un'estensione può aggiungere.

Valore

30.000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94+

Il numero massimo di Rulesets statici che un'estensione può attivare in un dato momento.

Valore

50

MAX_NUMBER_OF_REGEX_RULES

Il numero massimo di regole di espressioni regolari che un'estensione può aggiungere. Questo limite viene valutato separatamente per l'insieme di regole dinamiche e per quelle specificate nel file delle risorse delle regole.

Valore

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120+

Il numero massimo di regole con ambito sessione che un'estensione può aggiungere.

Valore

5000

MAX_NUMBER_OF_STATIC_RULESETS

Il numero massimo di Rulesets statici che un'estensione può specificare come parte della chiave manifest "rule_resources".

Valore

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120+

Il numero massimo di regole dinamiche "non sicure" che un'estensione può aggiungere.

Valore

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120+

Il numero massimo di regole "non sicure" con ambito di sessione che un'estensione può aggiungere.

Valore

5000

SESSION_RULESET_ID

Chrome 90+

ID del set di regole per le regole con ambito sessione aggiunte dall'estensione.

Valore

"_session"

Metodi

getAvailableStaticRuleCount()

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

Restituisce il numero di regole statiche che un'estensione può attivare prima di raggiungere il limite globale delle regole statiche.

Resi

  • Promise<number>

    Chrome 91+

getDisabledRuleIds()

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

Restituisce l'elenco delle regole statiche nel Ruleset specificato attualmente disattivate.

Parametri

Resi

  • Promise<number[]>

getDynamicRules()

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

Restituisce l'insieme corrente di regole dinamiche per l'estensione. I chiamanti possono facoltativamente filtrare l'elenco delle regole recuperate specificando un filter.

Parametri

  • filtro

    GetRulesFilter facoltativo

    Chrome 111+

    Un oggetto per filtrare l'elenco delle regole recuperate.

Resi

  • Promise<Rule[]>

    Chrome 91+

getEnabledRulesets()

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

Restituisce gli ID dell'insieme corrente di regole statiche abilitate.

Resi

  • Promise<string[]>

    Chrome 91+

getMatchedRules()

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

Restituisce tutte le regole corrispondenti per l'estensione. I chiamanti possono facoltativamente filtrare l'elenco delle regole corrispondenti specificando un filter. Questo metodo è disponibile solo per le estensioni con l'autorizzazione "declarativeNetRequestFeedback" o con l'autorizzazione "activeTab" concessa per tabId specificato in filter. Nota: le regole non associate a un documento attivo che sono state abbinate più di cinque minuti fa non verranno restituite.

Parametri

  • filtro

    MatchedRulesFilter facoltativo

    Un oggetto per filtrare l'elenco delle regole corrispondenti.

Resi

getSessionRules()

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

Restituisce l'insieme corrente di regole con ambito di sessione per l'estensione. I chiamanti possono facoltativamente filtrare l'elenco delle regole recuperate specificando un filter.

Parametri

  • filtro

    GetRulesFilter facoltativo

    Chrome 111+

    Un oggetto per filtrare l'elenco delle regole recuperate.

Resi

  • Promise<Rule[]>

    Chrome 91+

isRegexSupported()

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

Verifica se l'espressione regolare specificata sarà supportata come condizione della regola regexFilter.

Parametri

  • regexOptions

    RegexOptions

    L'espressione regolare da controllare.

Resi

setExtensionActionOptions()

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

Configura se il conteggio delle azioni per le schede deve essere visualizzato come testo del badge dell'azione dell'estensione e fornisce un modo per incrementare il conteggio delle azioni.

Parametri

Resi

  • Promise<void>

    Chrome 91+

testMatchOutcome()

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

Controlla se una delle regole declarativeNetRequest dell'estensione corrisponderebbe a una richiesta ipotetica. Nota: disponibile solo per le estensioni non compresse, in quanto è destinato all'uso solo durante lo sviluppo delle estensioni.

Parametri

Resi

updateDynamicRules()

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

Modifica l'insieme corrente di regole dinamiche per l'estensione. Vengono prima rimosse le regole con gli ID elencati in options.removeRuleIds, poi vengono aggiunte le regole indicate in options.addRules. Note:

  • Questo aggiornamento viene eseguito come singola operazione atomica: vengono aggiunte e rimosse tutte le regole specificate oppure viene restituito un errore.
  • Queste regole vengono mantenute tra le sessioni del browser e tra gli aggiornamenti delle estensioni.
  • Le regole statiche specificate come parte del pacchetto di estensioni non possono essere rimosse utilizzando questa funzione.
  • MAX_NUMBER_OF_DYNAMIC_RULES è il numero massimo di regole dinamiche che un'estensione può aggiungere. Il numero di regole non sicure non deve superare MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES.

Parametri

Resi

  • Promise<void>

    Chrome 91+

updateEnabledRulesets()

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

Aggiorna l'insieme di regole statiche abilitate per l'estensione. I set di regole con gli ID elencati in options.disableRulesetIds vengono rimossi per primi, dopodiché vengono aggiunti i set di regole elencati in options.enableRulesetIds. Tieni presente che l'insieme di regole statiche abilitate viene mantenuto tra le sessioni, ma non tra gli aggiornamenti delle estensioni. In altre parole, la chiave manifest rule_resources determinerà l'insieme di regole statiche abilitate a ogni aggiornamento dell'estensione.

Parametri

Resi

  • Promise<void>

    Chrome 91+

updateSessionRules()

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

Modifica l'attuale insieme di regole con ambito di sessione per l'estensione. Vengono prima rimosse le regole con gli ID elencati in options.removeRuleIds, poi vengono aggiunte le regole indicate in options.addRules. Note:

  • Questo aggiornamento viene eseguito come singola operazione atomica: vengono aggiunte e rimosse tutte le regole specificate oppure viene restituito un errore.
  • Queste regole non vengono mantenute tra le sessioni e vengono memorizzate in memoria.
  • MAX_NUMBER_OF_SESSION_RULES è il numero massimo di regole di sessione che un'estensione può aggiungere.

Parametri

Resi

  • Promise<void>

    Chrome 91+

updateStaticRules()

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

Disattiva e attiva le singole regole statiche in un Ruleset. Le modifiche alle regole appartenenti a un Ruleset disattivato diventeranno effettive la volta successiva che verrà attivato.

Parametri

Resi

  • Promise<void>

Eventi

onRuleMatchedDebug

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

Attivato quando una regola corrisponde a una richiesta. Disponibile solo per le estensioni non compresse con l'autorizzazione "declarativeNetRequestFeedback", in quanto è destinata esclusivamente a scopi di debug.

Parametri