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 una maggiore privacy.

Autorizzazioni

declarativeNetRequest
declarativeNetRequestWithHostAccess

Le autorizzazioni "declarativeNetRequest" e "declarativeNetRequestWithHostAccess" offrono le stesse funzionalità. La differenza tra le due è il momento in cui le autorizzazioni vengono richieste o concesse.

"declarativeNetRequest"

Attiva un avviso di autorizzazione al momento dell'installazione, ma fornisce 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 scompattate, in particolare getMatchedRules() e onRuleMatchedDebug.

"declarativeNetRequestWithHostAccess"

Non viene visualizzato un avviso relativo alle autorizzazioni al momento dell'installazione, ma devi richiedere le autorizzazioni dell'host prima di poter eseguire qualsiasi azione su un host. Questa opzione è appropriata quando vuoi utilizzare regole di richiesta di rete declarative 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 quelli 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 file JSON del manifest perché si tratta semplicemente di un array. Le regole di base statiche sono spiegate 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 set di regole

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

• Bloccare una richiesta di rete.
• Esegui l'upgrade dello schema (da http a https).
• Per impedire il blocco di una richiesta, nega le regole bloccate corrispondenti.
• Reindirizza 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

Rimangono invariate nelle sessioni del browser e negli upgrade delle estensioni e vengono gestite utilizzando JavaScript mentre un'estensione è in uso.

Sessione

Viene cancellato quando il browser si spegne e quando viene installata una nuova versione dell'estensione. Le regole della sessione vengono gestite utilizzando JavaScript mentre è in uso un'estensione.

Statica

Pacchettizzate, installate e aggiornate quando viene installata un'estensione o viene eseguito l'upgrade. Le regole statiche vengono archiviate in file di regole in formato JSON e elencate nel file manifest.

Regole basate su sessioni e dinamiche

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

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

Esistono un solo tipo di ciascuno di questi set di regole. Un'estensione può aggiungere o rimuovere regole in modo dinamico chiamando updateDynamicRules() e updateSessionRules(), a condizione che i limiti di regole non vengano superati. Per informazioni sui limiti delle regole, consulta Limiti delle regole. Puoi vedere un esempio in Esempi di codice.

Regole statiche

A differenza delle regole dinamiche e di sessione, le regole statiche vengono pacchettizzate, installate e aggiornate quando viene installata un'estensione o viene eseguito l'upgrade. Vengono memorizzati 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 il percorso del file delle regole, un ID per il set di regole contenuto nel file e se il set di regole è attivo o disattivato. 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 scompattata. Gli errori e gli avvisi relativi a regole statiche non valide vengono visualizzati solo per le estensioni non scompattate. Le regole statiche non valide nelle estensioni pacchettizzate vengono ignorate.

Revisione rapida

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

Attivare e disattivare regole e set di regole statici

Sia le singole regole statiche sia i set di regole statiche completi possono essere attivati o disattivati in fase di esecuzione.

L'insieme di regole e serie di regole statiche abilitate viene mantenuto nelle sessioni del browser. Nessuna delle due viene mantenuta negli aggiornamenti dell'estensione, il che significa che dopo un aggiornamento sono disponibili solo le regole che hai scelto di lasciare nei file delle regole.

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

Per attivare o disattivare le regole statiche, chiama 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. Esiste un limite massimo di 5000 regole statiche disattivate.

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

Regole di compilazione

Indipendentemente dal tipo, una regola inizia con quattro campi, come mostrato di seguito. Mentre le chiavi "id" e "priority" accettano un numero, le chiavi "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

La richiesta di rete dichiarativa consente di associare gli URL a una sintassi di corrispondenza dei pattern o a espressioni regolari.

Sintassi del filtro URL

La chiave "condition" di una regola consente una chiave "urlFilter" per intervenire sugli URL di un dominio specificato. Puoi creare 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. Consulta la chiave "regexFilter". Per informazioni sui limiti che si applicano a queste condizioni, consulta Regole che utilizzano espressioni regolari.

Scrivere condizioni degli URL efficaci

Fai attenzione quando scrivi le regole per fare 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 della 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 la possibilità di utilizzare:

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

Analogamente, utilizza i caratteri ^ e / per ancorare un'espressione regolare. Ad esempio, ^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 di corrispondenza.

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

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

Se il candidato è una regola allow o allowAllRequests o se il frame in cui viene effettuata la richiesta ha precedentemente soddisfatto 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 ordina 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.

Attenzione: i fornitori di browser hanno accettato di non standardizzare l'ordine in cui vengono eseguite le regole con la stessa azione e priorità. Questo può variare da una corsa all'altra o da una versione del browser all'altra, anche se distribuito tra più tipi di set di regole (ad esempio una regola statica e una regola della sessione). Quando l'ordine è importante, devi sempre specificare esplicitamente una priorità.

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 un'unica 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 quella di qualsiasi regola allow o allowAllRequests corrispondente.

Queste regole vengono applicate da Chrome in modo che le regole di un'estensione installata di recente vengano sempre valutate prima delle regole di un'estensione precedente. Inoltre, le regole con una priorità più alta di un'estensione vengono sempre applicate prima delle regole con una 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 quell'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 di risposta, Chrome valuta le regole con una condizione responseHeaders.

Dopo aver ordinato queste regole in base a action e priority ed escluso eventuali 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, significa che è già stata inviata al server e che il server ha ricevuto dati come il corpo della richiesta. Una regola di blocco o reindirizzamento con una condizione delle intestazioni di risposta verrà comunque eseguita, ma non potrà 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 termina la richiesta in anticipo. Nel caso di una regola di reindirizzamento, Chrome invia una nuova richiesta all'URL reindirizzato. Assicurati di valutare se questi comportamenti soddisfano le aspettative relative alla privacy per la tua estensione.

Se la richiesta non viene bloccata o reindirizzata, Chrome applica eventuali regole modifyHeaders. L'applicazione di modifiche alle intestazioni di risposta funziona nello stesso modo descritto in "Prima dell'invio delle intestazioni di 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 un aumento della quota delle regole dinamiche.

Limiti delle regole

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

Regole statiche

Le regole statiche sono quelle specificate nei file delle regole dichiarati nel file manifest. Un'estensione può specificare fino a 100 set di regole statici all'interno della chiave manifest "rule_resources", ma è possibile attivare solo 50 di questi set di regole alla volta. Quest'ultimo è chiamato MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. Nel complesso, questi set di regole garantiscono almeno 30.000 regole. Questo valore è chiamato GUARANTEED_MINIMUM_STATIC_RULES.

Nota: prima di Chrome 120, le estensioni erano limitate a un totale di 50 set di regole statiche e solo 10 di queste potevano essere attivate contemporaneamente. Utilizza il campo manifest minimum_chrome_version per limitare le versioni di Chrome che possono installare l'estensione.

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

Nota: a partire da Chrome 128, se un utente disattiva un'estensione tramite chrome://extensions, le regole statiche dell'estensione non verranno più conteggiate ai fini del limite di regole statiche globali. In questo modo, è possibile liberare la quota di regole statiche per altre estensioni, ma significa anche che, quando l'estensione viene riattivata, potrebbe avere meno regole statiche disponibili rispetto a prima.

Regole sessione

Un'estensione può avere fino a 5000 regole di sessione. Viene visualizzato come MAX_NUMBER_OF_SESSION_RULES.

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

Regole dinamiche

Un'estensione può avere almeno 5000 regole dinamiche. Viene visualizzato come MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES.

A partire da Chrome 121, è disponibile un limite maggiore 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 per questo limite.

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

Regole che utilizzano espressioni regolari

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

Inoltre, ogni regola deve avere dimensioni inferiori a 2 KB una volta compilata. Questo valore è approssimativamente correlato alla complessità della regola. Se provi a caricare una regola che supera questo limite, viene visualizzato un avviso come quello riportato di seguito e la regola viene ignorata.

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

Interazioni con i worker di servizio

Un'istruzione 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 per l'handler 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 tramite il web

Una regola declarativeNetRequest non può reindirizzare da una richiesta di risorsa pubblica a una risorsa non accessibile tramite il web. In questo modo viene attivato un errore. Ciò vale anche se la risorsa accessibile via 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 accodamento è 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 statiche

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 abilitati. Questo accade quando il numero di regole statiche necessarie supera il numero consentito. Affinché ciò funzioni, alcuni set di regole devono essere installati con altri 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 seguenti mostrano in che modo Chrome assegna la priorità alle regole in un'estensione. Quando le esamini, ti consigliamo di aprire le regole di priorità in una finestra separata.

La chiave "priority"

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

Per calcolare la priorità di un determinato URL, controlla la chiave "priority" (definita dallo sviluppatore), la chiave "action" e la chiave "urlFilter". Questi esempi fanno riferimento al file di regole di esempio mostrato di seguito.

Navigazione alla pagina 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é sono destinate a URL più lunghi.

Navigazione all'indirizzo https://google.com/1234

A causa dell'URL più lungo, la regola con ID 2 ora corrisponde anche alle regole con ID 1 e 4. Viene applicata la regola con ID 2 perché "allow" ha una priorità maggiore di "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 sua 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 si risolve in chrome-extension://EXTENSION_ID/a.jpg, dove EXTENSION_ID è l'ID dell'estensione. Affinché funzioni, il file manifest deve dichiarare /a.jpg come risorsa accessibile tramite web.

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

Il codice seguente utilizza la chiave "transform" per reindirizzare a un sottodominio di example.com. Utilizza un'ancora 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", notate come i punti siano preceduti da un carattere di escape e che il gruppo di cattura selezioni "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 eventuali 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 è proprietaria o di terze parti rispetto al frame in cui ha avuto origine. Una richiesta è considerata proprietaria se ha lo stesso dominio (eTLD+1) del frame da cui ha avuto origine.

Enum

"firstParty"
La richiesta di rete è proprietaria del frame in cui ha avuto origine.

"thirdParty"
La richiesta di rete è di terze parti rispetto al frame in cui ha avuto origine.

ExtensionActionOptions

Chrome 88 e versioni successive

Proprietà

• displayActionCountAsBadgeText

  booleano facoltativo

  Indica se visualizzare automaticamente il conteggio delle azioni per una pagina come testo del badge dell'estensione. Questa preferenza viene mantenuta nelle sessioni.

• tabUpdate

  TabActionCountUpdate facoltativo

  Chrome 89 e versioni successive

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

GetDisabledRuleIdsOptions

Chrome 111 e versioni successive

Proprietà

• rulesetId

  stringa

  L'ID corrispondente a un Ruleset statico.

GetRulesFilter

Chrome 111 e versioni successive

Proprietà

• ruleIds

  number[] facoltativo

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

HeaderInfo

Chrome 128 e versioni successive

Proprietà

• excludedValues

  stringa[] facoltativo

  Se specificato, questa condizione non corrisponde se l'intestazione esiste, ma il relativo 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 non sono specificati sia values sia excludedValues.

• valori

  stringa[] facoltativo

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

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

  '?' : corrisponde a zero o un carattere.

  Per "*" e "?" è possibile utilizzare la barra inversa, ad esempio "\*" e "\?"

HeaderOperation

Chrome 86 e versioni successive

Questa sezione 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 e versioni successive

Proprietà

• isSupported

  booleano

• motivo

  UnsupportedRegexReason facoltativo

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

MatchedRule

Proprietà

• ruleId

  numero

  L'ID di una regola corrispondente.

• rulesetId

  stringa

  L'ID dell'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

  L'ID della scheda da cui ha avuto origine la richiesta, se la scheda è ancora attiva. In caso contrario, -1.

• timeStamp

  numero

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

MatchedRuleInfoDebug

Proprietà

• richiesta

  RequestDetails

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

• regola

  MatchedRule

MatchedRulesFilter

Proprietà

• minTimeStamp

  number facoltativo

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

• tabId

  number facoltativo

  Se specificato, corrisponde solo alle regole per la scheda specificata. Corrisponde alle regole non associate a nessuna scheda attiva se impostato su -1.

ModifyHeaderInfo

Chrome 86 e versioni successive

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 e versioni successive

  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 di coppie chiave-valore della query da aggiungere o sostituire.

• removeParams

  stringa[] 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 (da \1 a \9) per inserire i gruppi di cattura corrispondenti. \0 fa riferimento all'intero testo corrispondente.

• trasformazione

  URLTransform facoltativo

  Trasformazioni degli URL da eseguire.

• url

  stringa facoltativa

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

RegexOptions

Chrome 87 e versioni successive

Proprietà

• isCaseSensitive

  booleano facoltativo

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

• regex

  stringa

  L'espressione regolare da controllare.

• requireCapturing

  booleano facoltativo

  Indica se il valore regex specificato richiede l'acquisizione. La cattura è obbligatoria solo per le regole di reindirizzamento che specificano un'azione regexSubstition. Il valore predefinito è false.

RequestDetails

Proprietà

• documentId

  stringa facoltativa

  Chrome 106 e versioni successive

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

• documentLifecycle

  DocumentLifecycle facoltativo

  Chrome 106 e versioni successive

  Il ciclo di vita del documento della Cornice, se la richiesta riguarda una Cornice.

• frameId

  numero

  Il valore 0 indica che la richiesta viene eseguita nel frame principale; un valore positivo indica l'ID di un frame secondario in cui viene eseguita la richiesta. Se il documento di un (sotto)frame è 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 e versioni successive

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

• iniziatore

  stringa facoltativa

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

• method

  stringa

  Metodo HTTP standard.

• parentDocumentId

  stringa facoltativa

  Chrome 106 e versioni successive

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

• parentFrameId

  numero

  ID del frame che racchiude 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. Impostato su -1 se la richiesta non è correlata a una scheda.

• tipo

  ResourceType

  Il tipo di risorsa della richiesta.

• url

  stringa

  L'URL della richiesta.

RequestMethod

Chrome 91 e versioni successive

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

Enum

"connect"

"delete"

"get"

"head"

"options"

"patch"

"post"

"put"

"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 viene trovata una corrispondenza per questa regola.

• 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 maggiore o uguale a 1.

• priorità

  number facoltativo

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

RuleAction

Proprietà

• reindirizzamento

  Reindirizzamento facoltativo

  Descrive in che modo deve essere eseguito il reindirizzamento. Valido solo per le regole di reindirizzamento.

• requestHeaders

  ModifyHeaderInfo[] facoltativo

  Chrome 86 e versioni successive

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

• responseHeaders

  ModifyHeaderInfo[] facoltativo

  Chrome 86 e versioni successive

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

• tipo

  RuleActionType

  Il tipo di azione da eseguire.

RuleActionType

Descrive il tipo di azione da eseguire se una determinata condizione della regola corrisponde.

Enum

"block"
Bloccare la richiesta di rete.

"redirect"
Rindirizza la richiesta di rete.

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

"upgradeScheme"
Esegui l'upgrade dello 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"
Consenti tutte le richieste all'interno di una gerarchia di frame, inclusa la richiesta del frame stesso.

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

  stringa[] facoltativo

  Ritirato da Chrome 101

  Utilizza initiatorDomains

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

• excludedDomains

  stringa[] facoltativo

  Ritirato da Chrome 101

  Utilizza excludedInitiatorDomains

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

• excludedInitiatorDomains

  stringa[] facoltativo

  Chrome 101 e versioni successive

  La regola non corrisponderà alle richieste di rete provenienti dall'elenco di excludedInitiatorDomains. Se l'elenco è vuoto o omesso, non vengono esclusi domini. 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.
  • La corrispondenza viene effettuata con l'iniziatore della richiesta e non con l'URL della richiesta.
  • Sono esclusi anche i sottodomini dei domini elencati.
• excludedRequestDomains

  stringa[] facoltativo

  Chrome 101 e versioni successive

  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. 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 e versioni successive

  Elenco dei metodi di richiesta per i quali la regola non corrisponde. È necessario specificare solo uno dei valori requestMethods e excludedRequestMethods. Se non viene specificato nessuno dei due, vengono trovati corrispondenze per tutti i metodi di richiesta.

• excludedResourceTypes

  ResourceType[] facoltativo

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

• excludedResponseHeaders

  HeaderInfo[] facoltativo

  Chrome 128 e versioni successive

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

• excludedTabIds

  number[] facoltativo

  Chrome 92 o versioni successive

  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 basate sulla sessione.

• initiatorDomains

  stringa[] facoltativo

  Chrome 101 e versioni successive

  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.
  • La corrispondenza viene effettuata con l'iniziatore della richiesta e non con l'URL della richiesta.
  • Vengono trovati corrispondenti anche i sottodomini dei domini elencati.
• isUrlFilterCaseSensitive

  booleano facoltativo

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

• regexFilter

  stringa facoltativa

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

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

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

• requestDomains

  stringa[] facoltativo

  Chrome 101 e versioni successive

  La regola corrisponderà alle richieste di rete solo se 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 trovati corrispondenti anche i sottodomini dei domini elencati.
• requestMethods

  RequestMethod[] facoltativo

  Chrome 91 e versioni successive

  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 lo faranno.

• resourceTypes

  ResourceType[] facoltativo

  Elenco dei tipi di risorse a cui la regola può corrispondere. 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 e versioni successive

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

• tabIds

  number[] facoltativo

  Chrome 92 o versioni successive

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

• urlFilter

  stringa facoltativa

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

  '*': carattere jolly che corrisponde a un numero qualsiasi di caratteri.

  '|' : ancoraggio sinistro/destro: se utilizzato alle 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 dominio (sottodominio) dell'URL.

  '^': carattere separatore. Corrisponde a qualsiasi carattere, ad eccezione di una lettera, un numero o uno dei seguenti: _, -, . o %. Corrisponde anche alla fine dell'URL.

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

  Se omesso, vengono trovati corrispondenze per 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: urlFilter deve essere composto solo da caratteri ASCII. Viene confrontato con un URL in cui l'host è codificato nel formato Punycode (in caso di domini internazionalizzati) e tutti gli altri caratteri non ASCII sono codificati in UTF-8. Ad esempio, quando l'URL della richiesta è http://abc.рф?q=ф, urlFilter verrà associato all'URL http://abc.xn--p1ai/?q=%D1%84.

Ruleset

Proprietà

• abilitata

  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 rispetto alla directory dell'estensione.

RulesMatchedDetails

Proprietà

• rulesMatchedInfo

  MatchedRuleInfo[]

  Regole corrispondenti al filtro specificato.

TabActionCountUpdate

Chrome 89 e versioni successive

Proprietà

• aumenta

  numero

  L'importo per cui aumentare 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 e versioni successive

Proprietà

• matchedRules

  MatchedRule[]

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

TestMatchRequestDetails

Chrome 103 e versioni successive

Proprietà

• iniziatore

  stringa facoltativa

  L'URL 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 e versioni successive

  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 di stringa. Se non specificato, la risposta ipotetica restituirà intestazioni di risposta vuote, che possono corrispondere a regole che corrispondono all'assenza di intestazioni. Ad esempio {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}

• tabId

  number facoltativo

  L'ID della scheda in cui avviene 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.

• tipo

  ResourceType

  Il tipo di risorsa della richiesta ipotetica.

• url

  stringa

  L'URL della richiesta ipotetica.

UnsupportedRegexReason

Chrome 87 e versioni successive

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 e versioni successive

Proprietà

• addRules

  Rule[] facoltativo

  Regole da aggiungere.

• removeRuleIds

  number[] facoltativo

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

UpdateRulesetOptions

Chrome 87 e versioni successive

Proprietà

• disableRulesetIds

  stringa[] facoltativo

  L'insieme di ID corrispondenti a un Ruleset statico che deve essere disattivato.

• enableRulesetIds

  stringa[] facoltativo

  L'insieme di ID corrispondenti a un Ruleset statico da attivare.

UpdateStaticRulesOptions

Chrome 111 e versioni successive

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 le 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 insieme di regole per le regole dinamiche aggiunte dall'estensione.

Valore

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

Intervallo di tempo entro il quale è possibile effettuare chiamate 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 e versioni successive

Il numero minimo di regole statiche garantite a un'estensione nei relativi set di regole statiche abilitati. Le regole superiori a questo limite verranno conteggiate ai fini del limite di regole statiche globali.

Valore

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

Il numero di volte in cui getMatchedRules può essere chiamato 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

30000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94 e versioni successive

Il numero massimo di Rulesets statici che un'estensione può attivare contemporaneamente.

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 e versioni successive

Il numero massimo di regole basate sulla 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 e versioni successive

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

Valore

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120 e versioni successive

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

Valore

5000

SESSION_RULESET_ID

Chrome 90 o versioni successive

ID insieme di regole per le regole basate sulla sessione aggiunte dall'estensione.

Valore

"_session"

Metodi

getAvailableStaticRuleCount()

Promessa Chrome 89 e versioni successive

chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
)

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

Parametri

• callback

  function facoltativa

  Il parametro callback ha il seguente aspetto:

  (count: number) => void

  • conteggio

    numero

Resi

• Promise<number>

  Chrome 91 e versioni successive

  Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

getDisabledRuleIds()

Promessa Chrome 111 e versioni successive

chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
  callback?: function,
)

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

Parametri

• opzioni

  GetDisabledRuleIdsOptions

  Specifica il set di regole su cui eseguire la query.

• callback

  function facoltativa

  Il parametro callback ha il seguente aspetto:

  (disabledRuleIds: number[]) => void

  • disabledRuleIds

    number[]

Resi

• Promise<number[]>

  Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

getDynamicRules()

Promessa

chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
  callback?: function,
)

Restituisce l'insieme corrente di regole dinamiche per l'estensione. Se vuoi, i chiamanti possono filtrare l'elenco delle regole recuperate specificando un filter.

Parametri

• filtro

  GetRulesFilter facoltativo

  Chrome 111 e versioni successive

  Un oggetto per filtrare l'elenco delle regole recuperate.

• callback

  function facoltativa

  Il parametro callback ha il seguente aspetto:

  (rules: Rule[]) => void

  • regole

    Rule[]

Resi

• Promise<Rule[]>

  Chrome 91 e versioni successive

  Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

getEnabledRulesets()

Promessa

chrome.declarativeNetRequest.getEnabledRulesets(
  callback?: function,
)

Restituisce gli ID per l'insieme corrente di set di regole statiche abilitati.

Parametri

• callback

  function facoltativa

  Il parametro callback ha il seguente aspetto:

  (rulesetIds: string[]) => void

  • rulesetIds

    stringa[]

Resi

• Promise<string[]>

  Chrome 91 e versioni successive

  Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

getMatchedRules()

Promessa

chrome.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
  callback?: function,
)

Restituisce tutte le regole corrispondenti per l'estensione. Se lo desiderano, i chiamanti possono filtrare l'elenco delle regole corrispondenti specificando un filter. Questo metodo è disponibile solo per le estensioni con l'autorizzazione "declarativeNetRequestFeedback" o che hanno l'autorizzazione "activeTab" concessa per il tabId specificato in filter. Nota: le regole non associate a un documento attivo che hanno trovato una corrispondenza più di cinque minuti fa non verranno restituite.

Parametri

• filtro

  MatchedRulesFilter facoltativo

  Un oggetto per filtrare l'elenco delle regole corrispondenti.

• callback

  function facoltativa

  Il parametro callback ha il seguente aspetto:

  (details: RulesMatchedDetails) => void

  • dettagli

    RulesMatchedDetails

Resi

• Promise<RulesMatchedDetails>

  Chrome 91 e versioni successive

  Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

getSessionRules()

Promessa Chrome 90 e versioni successive

chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
  callback?: function,
)

Restituisce l'insieme corrente di regole basate sulla sessione per l'estensione. Se vuoi, i chiamanti possono filtrare l'elenco delle regole recuperate specificando un filter.

Parametri

• filtro

  GetRulesFilter facoltativo

  Chrome 111 e versioni successive

  Un oggetto per filtrare l'elenco delle regole recuperate.

• callback

  function facoltativa

  Il parametro callback ha il seguente aspetto:

  (rules: Rule[]) => void

  • regole

    Rule[]

Resi

• Promise<Rule[]>

  Chrome 91 e versioni successive

  Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

isRegexSupported()

Promessa Chrome 87 e versioni successive

chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
  callback?: function,
)

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

Parametri

• regexOptions

  RegexOptions

  L'espressione regolare da controllare.

• callback

  function facoltativa

  Il parametro callback ha il seguente aspetto:

  (result: IsRegexSupportedResult) => void

  • risultato

    IsRegexSupportedResult

Resi

• Promise<IsRegexSupportedResult>

  Chrome 91 e versioni successive

  Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

setExtensionActionOptions()

Promessa Chrome 88 e versioni successive

chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
  callback?: function,
)

Consente di configurare 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

• opzioni

  ExtensionActionOptions

• callback

  function facoltativa

  Chrome 89 e versioni successive

  Il parametro callback ha il seguente aspetto:

  () => void

Resi

• Promise<void>

  Chrome 91 e versioni successive

  Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

testMatchOutcome()

Promessa Chrome 103 e versioni successive

chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
)

Controlla se una delle regole declarativeNetRequest dell'estensione corrisponde a una richiesta ipotetica. Nota: disponibile solo per le estensioni non scompattate, in quanto deve essere utilizzata solo durante lo sviluppo delle estensioni.

Parametri

• richiesta

  TestMatchRequestDetails

• callback

  function facoltativa

  Il parametro callback ha il seguente aspetto:

  (result: TestMatchOutcomeResult) => void

  • risultato

    TestMatchOutcomeResult

Resi

• Promise<TestMatchOutcomeResult>

  Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

updateDynamicRules()

Promessa

chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
  callback?: function,
)

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

• Questo aggiornamento avviene come una singola operazione atomica: tutte le regole specificate vengono aggiunte e rimosse oppure viene restituito un errore.
• Queste regole vengono mantenute nelle sessioni del browser e negli 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

• opzioni

  UpdateRuleOptions

  Chrome 87 e versioni successive
• callback

  function facoltativa

  Il parametro callback ha il seguente aspetto:

  () => void

Resi

• Promise<void>

  Chrome 91 e versioni successive

  Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

updateEnabledRulesets()

Promessa

chrome.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
  callback?: function,
)

Aggiorna l'insieme di set di regole statiche abilitati per l'estensione. Innanzitutto vengono rimosse le regole con gli ID elencati in options.disableRulesetIds, quindi vengono aggiunte le regole elencate in options.enableRulesetIds. Tieni presente che l'insieme di set di regole statiche abilitati viene mantenuto nelle sessioni, ma non negli aggiornamenti delle estensioni, ovvero la chiave manifest rule_resources determinerà l'insieme di set di regole statiche abilitati in ogni aggiornamento dell'estensione.

Parametri

• opzioni

  UpdateRulesetOptions

  Chrome 87 e versioni successive
• callback

  function facoltativa

  Il parametro callback ha il seguente aspetto:

  () => void

Resi

• Promise<void>

  Chrome 91 e versioni successive

  Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

updateSessionRules()

Promessa Chrome 90 e versioni successive

chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
  callback?: function,
)

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

• Questo aggiornamento avviene come una singola operazione atomica: tutte le regole specificate vengono aggiunte e rimosse oppure viene restituito un errore.
• Queste regole non vengono conservate nelle sessioni e vengono sottoposte a backup in memoria.
• MAX_NUMBER_OF_SESSION_RULES è il numero massimo di regole di sessione che un'estensione può aggiungere.

Parametri

• opzioni

  UpdateRuleOptions

• callback

  function facoltativa

  Il parametro callback ha il seguente aspetto:

  () => void

Resi

• Promise<void>

  Chrome 91 e versioni successive

  Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

updateStaticRules()

Promessa Chrome 111 e versioni successive

chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
  callback?: function,
)

Disattiva e attiva le singole regole statiche in un Ruleset. Le modifiche alle regole appartenenti a un Ruleset disattivato verranno applicate alla successiva attivazione.

Parametri

• opzioni

  UpdateStaticRulesOptions

• callback

  function facoltativa

  Il parametro callback ha il seguente aspetto:

  () => void

Resi

• Promise<void>

  Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

Eventi

onRuleMatchedDebug

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

Viene attivato quando una regola corrisponde a una richiesta. Disponibile solo per le estensioni non imballate con l'autorizzazione "declarativeNetRequestFeedback", in quanto è destinata esclusivamente al debug.

Parametri

• callback

  funzione

  Il parametro callback ha il seguente aspetto:

  (info: MatchedRuleInfoDebug) => void

  • informazioni

    MatchedRuleInfoDebug