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 visualizzare i relativi contenuti, garantendo così maggiore privacy.

Autorizzazioni

declarativeNetRequest
declarativeNetRequestWithHostAccess

Le autorizzazioni "declarativeNetRequest" e "declarativeNetRequestWithHostAccess" forniscono le stesse funzionalità. La differenza è quando le autorizzazioni vengono richieste o concesse.

"declarativeNetRequest"
Attiva un avviso relativo alle autorizzazioni al momento dell'installazione, ma fornisce un accesso implicito alle regole allow, allowAllRequests e block. Utilizza questa opzione quando possibile per evitare di richiedere l'accesso completo agli host.
"declarativeNetRequestFeedback"
Attiva le funzionalità di debug per le estensioni non pacchettizzate, in particolare per getMatchedRules() e onRuleMatchedDebug.
"declarativeNetRequestWithHostAccess"
Al momento dell'installazione non viene visualizzato un avviso relativo alle autorizzazioni, ma devi richiedere le autorizzazioni dell'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à di autorizzazioni per l'host senza generare avvisi aggiuntivi.

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 JSON del file manifest, poiché si tratta semplicemente di un array. I set di regole statici vengono illustrati 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/*"
  ],
  ...
}

Concetti e utilizzo

Per utilizzare questa API, specifica uno o più set di regole. Un set 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).
  • Per evitare che una richiesta venga bloccata, annullando qualsiasi regola bloccata corrispondente.
  • 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
Persiste tra le sessioni del browser e gli upgrade delle estensioni e vengono gestite tramite JavaScript mentre un'estensione è in uso.
Sessione
Questa estensione è stata cancellata quando il browser si chiude e quando viene installata una nuova versione dell'estensione. Le regole di sessione vengono gestite tramite JavaScript mentre è in uso un'estensione.
Statiche
Pacchetti, installati e aggiornati quando un'estensione viene installata o aggiornata. Le regole statiche vengono archiviate in file di regole in formato JSON ed elencate nel file manifest.

Le prossime sezioni spiegano i tipi di set di regole in dettaglio.

Set di regole dinamici e con ambito sessione

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

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

Esiste solo uno di questi tipi di serie 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 vederne un esempio alla voce 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. Sono archiviati in file di regole in formato JSON, che vengono indicati all'estensione utilizzando le chiavi "declarative_net_request" e "rule_resources" come descritto in precedenza, nonché uno o più dizionari Ruleset. Un dizionario Ruleset contiene un percorso al file delle regole, un ID per la serie di regole contenuta nel file e indica se la serie di regole è attivata o disattivata. Le ultime due sono importanti quando abiliti o disattivi un set 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 a regole statiche non valide vengono visualizzati solo per le estensioni non pacchettizzate. Le regole statiche non valide nelle estensioni in pacchetto vengono ignorate.

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

L'insieme di regole e set di regole statici abilitati è mantenuto in tutte le sessioni del browser. Nessuna delle due opzioni è persistente negli aggiornamenti delle estensioni, 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 dei limiti anche 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 updateStaticRules(). Questo metodo richiede un oggetto UpdateStaticRulesOptions, che contiene array di ID di regole da attivare o disattivare. Gli ID vengono definiti utilizzando la chiave "id" del dizionario Ruleset.

Per attivare o disattivare rulesets statici, chiama updateEnabledRulesets(). Questo metodo richiede 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.

Crea regole

Indipendentemente dal tipo, una regola inizia con quattro campi, come mostrato di seguito. Mentre le chiavi "id" e "priority" prendono 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" verso qualsiasi URL con "abc" come sottostringa.

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

Caratteri corrispondenti del filtro url

La chiave "condition" di una regola consente a una chiave "urlFilter" di agire sugli URL in un dominio specificato. Puoi creare pattern utilizzando i token di corrispondenza dei 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://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

Assegnazione delle priorità alle regole

Le regole vengono attivate dalle richieste inviate dalle pagine web. Se a una determinata richiesta corrispondono più regole, queste devono avere la priorità. In questa sezione viene spiegato in che modo viene assegnata la priorità. L'assegnazione delle priorità avviene in due fasi.

  1. La priorità viene determinata per le regole all'interno di un'estensione.
  2. Se più estensioni possono applicare una regola a una richiesta, la priorità viene determinata per tutte le estensioni corrispondenti a una determinata richiesta.

Pensando alla corrispondenza in questo modo, qualsiasi regola assegnata a una determinata estensione avrà la priorità rispetto alle regole di altre estensioni.

Assegnazione della priorità alle regole all'interno di un'estensione

All'interno di una singola estensione, la priorità viene determinata nel seguente processo:

  1. Viene restituita la regola con la priorità definita dallo sviluppatore più alta (in altre parole, il campo "priority").

  2. Se è presente più di una regola con la priorità definita dallo sviluppatore più elevata, la priorità delle regole viene assegnata utilizzando il campo "action", nel seguente ordine:

    1. allow
    2. allowAllRequests
    3. block
    4. upgradeScheme
    5. redirect

  3. Se il tipo di azione non è block o redirect, vengono valutate tutte le regole modifyHeaders corrispondenti. Tieni presente che, se esistono regole con una priorità definita dallo sviluppatore inferiore a quella specificata per allow e allowAllRequests, queste vengono ignorate.

  4. Se più regole modificano la stessa intestazione, questa modifica viene determinata dal campo "priority" definito dallo sviluppatore e dalle operazioni specificate.

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

Assegnazione della priorità alle regole tra le estensioni

Se solo un'estensione ha una regola che corrisponde a una richiesta, viene applicata questa regola. Tuttavia, se più estensioni corrispondono a una richiesta, viene utilizzato il seguente processo:

  1. La priorità delle regole viene assegnata utilizzando il campo "action", nel seguente ordine:

    1. block
    2. redirect o upgradeScheme
    3. allow o allowAllRequests

  2. Se più di una regola corrisponde, all'estensione installata più di recente viene assegnata la priorità.

Limiti delle regole

Per il caricamento e la valutazione delle regole nel browser esiste un sovraccarico delle prestazioni, pertanto alcuni limiti si applicano quando si utilizza l'API. I limiti dipendono dal tipo di regola che stai utilizzando.

Regole statiche

Le regole statiche sono quelle specificate nei file delle regole dichiarati nel file manifest. Un'estensione può specificare fino a 100 rulesets statiche come parte della chiave manifest "rule_resources", ma è possibile attivarne solo 50 alla volta. La seconda opzione è MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. Collettivamente, a questi set di regole sono garantite almeno 30.000 regole. Questo è chiamato GUARANTEED_MINIMUM_STATIC_RULES.

Il numero di regole disponibili successivamente dipende da quante regole sono attivate da tutte le estensioni installate sul browser di un utente. Puoi trovare questo numero in fase di runtime chiamando il numero getAvailableStaticRuleCount(). Puoi vederne un esempio alla voce Esempi di codice.

Regole sessione

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

Prima di Chrome 120, esisteva un limite di 5000 regole combinate dinamiche e per le sessioni.

Regole dinamiche

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

A partire da Chrome 121, è disponibile un limite superiore di 30.000 regole disponibili per le regole dinamiche sicure, esposto come MAX_NUMBER_OF_DYNAMIC_RULES. Le regole di sicurezza sono definite come regole con un'azione di block, allow, allowAllRequests o upgradeScheme. Anche eventuali regole non sicure aggiunte entro il limite di 5000 verranno conteggiate per 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ò essere maggiore di 1000. denominata MAX_NUMBER_OF_REGEX_RULES.

Inoltre, una volta compilata, ogni regola deve avere dimensioni inferiori a 2 kB. Questo è correlato in modo approssimativo con la complessità della regola. Se tenti di caricare una regola che supera questo limite, verrà visualizzato 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 richiesta declarativeNetRequest si applica solo alle richieste che raggiungono lo stack di rete. Ciò include le risposte provenienti dalla cache HTTP, ma potrebbe non includere risposte che passano attraverso il gestore onfetch di un service worker. declarativeNetRequest non incide sulle risposte generate dal service worker o recuperate da CacheStorage, ma influisce sulle chiamate a fetch() effettuate in un service worker.

Risorse accessibili sul web

Una regola dichiarativaNetRequest non può reindirizzare da una richiesta di risorsa pubblica a una risorsa non accessibile sul web. In questo modo si verifica un errore. Questo vale anche se la risorsa accessibile al web specificata è di proprietà dell'estensione di reindirizzamento. Per dichiarare le risorse per declarativeNetRequest, utilizza l'array "web_accessible_resources" del manifest.

Esempi

Esempi di codice

Aggiornamento delle regole dinamiche

Nell'esempio seguente viene illustrato 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
});

Aggiornamento set di regole statici

L'esempio seguente mostra come abilitare e disabilitare i set di regole statici considerando il numero di insiemi di regole statiche disponibili e il numero massimo di insiemi di regole statici attivati. Puoi eseguire questa operazione quando il numero di regole statiche necessarie supera il numero consentito. Affinché questo comando funzioni, è necessario installare alcuni set di regole e disattivarne altre (impostando "Enabled" su false nel 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

I seguenti esempi mostrano come 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.

Il tasto "Priorità"

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

Per calcolare 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 riportato sotto.

Navigazione su https://google.com
Questo URL è coperto da due regole: le regole con ID 1 e 4. La regola con ID 1 si applica perché le azioni "block" hanno una priorità maggiore rispetto alle azioni "redirect". Le altre regole non si applicano perché si riferiscono a URL più lunghi.
Navigazione su https://google.com/1234
A causa dell'URL più lungo, ora la regola con ID 2 corrisponde alle regole con ID 1 e 4. La regola con ID 2 si applica perché "allow" ha una priorità più elevata rispetto a "block" e "redirect".
Navigazione su https://google.com/12345
Tutte e quattro le regole corrispondono a questo URL. Si applica 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 diventa chrome-extension://EXTENSION_ID/a.jpg, dove EXTENSION_ID è l'ID dell'estensione. Affinché questo comando 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"]
  }
}

Quanto segue utilizza la chiave "transform" per reindirizzare a un sottodominio di example.com. Utilizza 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 espressioni regolari per il reindirizzamento da https://www.abc.xyz.com/path a https://abc.xyz.com/path. Nella chiave "regexFilter", osserva come i punti vengono preceduti da caratteri di escape e 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 sia da un frame principale sia 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 è di prima o terza parte del frame in cui ha avuto origine. Una richiesta è considerata proprietaria se ha lo stesso dominio (eTLD+1) del frame in 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 mostrare automaticamente il conteggio delle azioni per una pagina come testo del badge dell'estensione. Questa preferenza è persistente in tutte le sessioni.

  • tabUpdate

    TabActionCountUpdate facoltativo

    Chrome 89 e versioni successive

    Dettagli di come modificare il numero di azioni della scheda.

GetDisabledRuleIdsOptions

Chrome 111 e versioni successive

Proprietà

  • rulesetId

    stringa

    L'ID corrispondente a una Ruleset statica.

GetRulesFilter

Chrome 111 e versioni successive

Proprietà

  • ruleIds

    number[] facoltativo

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

HeaderOperation

Chrome 86 e versioni successive

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 tutte le intestazioni esistenti con lo stesso nome.

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

IsRegexSupportedResult

Chrome 87 e versioni successive

Proprietà

  • isSupported

    boolean

  • motivo

    UnsupportedRegexReason Facoltativo

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

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, il valore sarà 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. Altrimenti -1.

  • timeStamp

    numero

    L'ora in cui è stata soddisfatta la regola. I timestamp corrispondono alla convenzione JavaScript per i tempi, ovvero il numero di millisecondi dall'epoca.

MatchedRuleInfoDebug

Proprietà

  • richiesta

    RequestDetails

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

  • regola

    MatchedRule

MatchedRulesFilter

Proprietà

  • minTimeStamp

    numero facoltativo

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

  • tabId

    numero 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 facoltativo

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

QueryKeyValue

Proprietà

  • chiave

    stringa

  • replaceOnly

    booleano facoltativo

    Chrome 94 e versioni successive

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

  • valore

    stringa

QueryTransform

Proprietà

  • addOrReplaceParams

    QueryKeyValue[] facoltativo

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

  • removeParams

    string[] facoltativo

    L'elenco di chiavi di query da rimuovere.

Redirect

Proprietà

  • extensionPath

    stringa facoltativo

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

  • regexSubstitution

    stringa facoltativo

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

  • e trasformerai

    URLTransform facoltativo

    Trasformazioni dell'URL da eseguire.

  • url

    stringa facoltativo

    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 campo regex specificato è sensibile alle maiuscole. Il valore predefinito è true.

  • regex

    stringa

    L'espressione regolare da controllare.

  • requireCapturing

    booleano facoltativo

    Indica se regex specificato deve essere acquisito. L'acquisizione è obbligatoria solo per le regole di reindirizzamento che specificano un'azione regexSubstition. Il valore predefinito è false.

RequestDetails

Proprietà

  • documentId

    stringa facoltativo

    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 del frame, se la richiesta riguarda un frame.

  • frameId

    numero

    Il valore 0 indica che la richiesta avviene nel frame principale, mentre un valore positivo indica l'ID di un frame secondario in cui si verifica la richiesta. Se il documento di un (sub-)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

    Facoltativo FrameType

    Chrome 106 e versioni successive

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

  • iniziatore

    stringa facoltativo

    L'origine in cui è stata avviata la richiesta. Questo non cambia tramite i reindirizzamenti. Se questa è un'origine opaca, verrà utilizzata la stringa "null".

  • method

    stringa

    Metodo HTTP standard.

  • parentDocumentId

    stringa facoltativo

    Chrome 106 e versioni successive

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

  • parentFrameId

    numero

    ID del frame che aggrega il frame che ha inviato la richiesta. Imposta il valore su -1 se non esiste alcun 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 si verifica 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 e versioni successive

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

Enum

"head"

"patch"

"post"

"put"

ResourceType

Descrive il tipo di risorsa della richiesta di rete.

Enum

"main_frame"

"sub_frame"

"script"

"xmlhttprequest"

"ping"

"csp_report"

"websocket"

"webbundle"

Rule

Proprietà

  • azione

    RuleAction

    L'azione da eseguire in caso di corrispondenza a 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à

    numero facoltativo

    Priorità regola. Il valore predefinito è 1. Se specificato, deve essere >= 1.

RuleAction

Proprietà

  • reindirizzamento

    Reindirizzamento facoltativo

    Descrive come 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. Valido solo se RuleActionType è "modifyHeaders".

  • responseHeaders

    ModifyHeaderInfo[] facoltativo

    Chrome 86 e versioni successive

    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 condizione RuleCondition corrisponde.

Enum

"block"
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 corrispondente.

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

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

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

RuleCondition

Proprietà

  • domainType

    DomainType facoltativo

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

  • domini

    string[] facoltativo

    Deprecata da Chrome 101

    Usa invece initiatorDomains

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

  • excludedDomains

    string[] facoltativo

    Deprecata da Chrome 101

    Usa invece excludedInitiatorDomains

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

  • excludedInitiatorDomains

    string[] 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 viene escluso nessun dominio. Ha la precedenza su initiatorDomains.

    Note:

    • Sono consentiti anche i sottodomini come "a.example.com".
    • Le voci devono essere composte solo da caratteri ASCII.
    • Usa la codifica Punycode per i domini internazionalizzati.
    • Questo valore corrisponde all'autore della richiesta e non all'URL della richiesta.
    • Sono esclusi anche i sottodomini dei domini elencati.
  • excludedRequestDomains

    string[] 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 viene escluso nessun dominio. Ha la precedenza su requestDomains.

    Note:

    • Sono consentiti anche i sottodomini come "a.example.com".
    • Le voci devono essere composte solo da caratteri ASCII.
    • Usa 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 a cui la regola non corrisponde. Deve essere specificato solo uno tra requestMethods e excludedRequestMethods. Se nessuno dei due viene specificato, vengono trovati tutti i metodi di richiesta.

  • excludedResourceTypes

    Facoltativo ResourceType[]

    Elenco dei tipi di risorse a cui la regola non corrisponde. Deve essere specificato solo uno tra resourceTypes e excludedResourceTypes. Se nessuna di queste opzioni è specificata, tutti i tipi di risorsa tranne "main_frame" vengono bloccati.

  • excludedTabIds

    number[] facoltativo

    Chrome 92 e versioni successive

    Elenco di elementi tabs.Tab.id a cui la regola non deve corrispondere. Un ID tabs.TAB_ID_NONE esclude le richieste che non provengono da una scheda. Funzionalità supportata solo per le regole basate sulle sessioni.

  • initiatorDomains

    string[] 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 di tutti i domini. Non è consentito un elenco vuoto.

    Note:

    • Sono consentiti anche i sottodomini come "a.example.com".
    • Le voci devono essere composte solo da caratteri ASCII.
    • Usa la codifica Punycode per i domini internazionalizzati.
    • Questo valore corrisponde all'autore della richiesta e non all'URL della richiesta.
    • Vengono abbinati anche i sottodomini dei domini elencati.
  • isUrlFilterCaseSensitive

    booleano facoltativo

    Se urlFilter o regexFilter (a seconda di quello specificato) è sensibile alle maiuscole. Il valore predefinito è false.

  • regexFilter

    stringa facoltativo

    Espressione regolare per creare una corrispondenza con l'URL della richiesta di rete. segue la sintassi RE2.

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

    Nota: regexFilter deve essere composto solo da caratteri ASCII. Questo 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 URL codificati in utf-8.

  • requestDomains

    string[] facoltativo

    Chrome 101 e versioni successive

    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 di tutti i domini. Non è consentito un elenco vuoto.

    Note:

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

    RequestMethod[] facoltativo

    Chrome 91 e versioni successive

    Elenco dei metodi di richiesta HTTP che possono corrispondere alla regola. Non è consentito un elenco vuoto.

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

  • resourceTypes

    Facoltativo ResourceType[]

    Elenco dei tipi di risorse corrispondenti alla regola. Non è consentito un elenco vuoto.

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

  • tabIds

    number[] facoltativo

    Chrome 92 e 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 un elenco vuoto. Funzionalità supportata solo per le regole basate sulle sessioni.

  • urlFilter

    stringa facoltativo

    Il pattern che viene abbinato all'URL della richiesta di rete. Costrutti supportati:

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

    '|' : ancoraggio sinistra/destra: se utilizzato alle estremità del pattern, specifica rispettivamente l'inizio/la fine dell'URL.

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

    '^' : carattere separatore: corrisponde a qualsiasi cosa tranne una lettera, una cifra o una delle seguenti: _, -, . o %. Questo valore corrisponde anche alla fine dell'URL.

    Pertanto urlFilter è composto dalle parti seguenti: (ancoraggio sinistro/nome di dominio facoltativo) + pattern + (ancoraggio destro facoltativo).

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

    Non è consentito un pattern che inizia con ||*. Usa invece il criterio *.

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

    Nota: urlFilter deve essere composto solo da caratteri ASCII. Questo 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 URL codificati in utf-8. Ad esempio, se l'URL della richiesta è http://abc.рello?q=spa, urlFilter verrà confrontato con l'URL http://abc.xn--p1ai/?q=%D1%84.

Ruleset

Proprietà

  • abilitata

    boolean

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

  • id

    stringa

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

  • percorso

    stringa

    Il percorso del set di regole JSON relativo alla directory dell'estensione.

RulesMatchedDetails

Proprietà

  • rulesMatchedInfo

    MatchedRuleInfo[]

    Regole corrispondenti al filtro specificato.

TabActionCountUpdate

Chrome 89 e versioni successive

Proprietà

  • aumenta

    numero

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

  • tabId

    numero

    La scheda per la quale aggiornare il conteggio delle azioni.

TestMatchOutcomeResult

Chrome 103 e versioni successive

Proprietà

  • matchedRules

    MatchedRule[]

    Le eventuali regole che corrispondono alla richiesta ipotetica.

TestMatchRequestDetails

Chrome 103 e versioni successive

Proprietà

  • iniziatore

    stringa facoltativo

    L'URL che ha avviato la richiesta ipotetica (se presente).

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

  • tabId

    numero facoltativo

    L'ID della scheda in cui si verifica la richiesta ipotetica. Non deve necessariamente 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 e versioni successive

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

Enum

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

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

UpdateRuleOptions

Chrome 87 e versioni successive

Proprietà

  • addRules

    Regola[] facoltativa

    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

    string[] facoltativo

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

  • enableRulesetIds

    string[] facoltativo

    L'insieme di ID corrispondente a una Ruleset statica che deve essere attivata.

UpdateStaticRulesOptions

Chrome 111 e versioni successive

Proprietà

  • disableRuleIds

    number[] facoltativo

    Insieme di ID corrispondenti alle regole in Ruleset da disabilitare.

  • enableRuleIds

    number[] facoltativo

    Insieme di ID corrispondenti alle regole in Ruleset da attivare.

  • rulesetId

    stringa

    L'ID corrispondente a una Ruleset statica.

URLTransform

Proprietà

  • frammento

    stringa facoltativo

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

  • organizzatore

    stringa facoltativo

    Il nuovo host per la richiesta.

  • password

    stringa facoltativo

    La nuova password per la richiesta.

  • percorso

    stringa facoltativo

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

  • porta

    stringa facoltativo

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

  • query

    stringa facoltativo

    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 di query.

  • schema

    stringa facoltativo

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

  • nome utente

    stringa facoltativo

    Il nuovo nome utente per la richiesta.

Proprietà

DYNAMIC_RULESET_ID

ID set 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 verranno impostate 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 per un'estensione nei relativi set di regole statiche attivate. Qualsiasi regola oltre questo limite verrà conteggiata ai fini del limite globale di 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 e versioni successive

Il numero massimo di Rulesets statici che un'estensione può attivare in qualsiasi 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 di risorse delle regole.

Valore

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120 e versioni successive

Il numero massimo di regole con ambito a livello di 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 con ambito sessione "non sicure" che un'estensione può aggiungere.

Valore

5000

SESSION_RULESET_ID

Chrome 90 e versioni successive

ID set di regole per le regole basate sulle sessioni aggiunte dall'estensione.

Valore

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 che venga raggiunto il limite globale di regole statiche.

Parametri

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (count: number)=>void

    • conteggio

      numero

Ritorni

  • Promessa<numero>

    Chrome 91 e versioni successive

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

getDisabledRuleIds()

Promessa Chrome 111 e versioni successive 
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
  callback?: function,
)

Restituisce l'elenco di regole statiche nella classe Ruleset specificata che sono attualmente disattivate.

Parametri

  • Specifica il set di regole su cui eseguire query.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (disabledRuleIds: number[])=>void

    • disabledRuleIds

      numero[]

Ritorni

  • Promessa<number[]>

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

getDynamicRules()

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

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

Parametri

  • filter

    GetRulesFilter facoltativo

    Chrome 111 e versioni successive

    Un oggetto per filtrare l'elenco delle regole recuperate.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (rules: Rule[])=>void

Ritorni

  • Promessa<Regola[]>

    Chrome 91 e versioni successive

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

getEnabledRulesets()

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

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

Parametri

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (rulesetIds: string[])=>void

    • rulesetIds

      stringa[]

Ritorni

  • Promessa<string[]>

    Chrome 91 e versioni successive

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

getMatchedRules()

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

Restituisce tutte le regole corrispondenti all'estensione. Facoltativamente, 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 tipo di estensione tabId specificato in filter. Nota: le regole non associate a un documento attivo la cui corrispondenza è stata trovata più di cinque minuti prima non verranno restituite.

Parametri

Ritorni

  • Chrome 91 e versioni successive

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

getSessionRules()

Promessa Chrome 90 e versioni successive 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
  callback?: function,
)

Restituisce l'insieme corrente di regole con ambito a livello di sessione per l'estensione. Facoltativamente, i chiamanti possono filtrare l'elenco delle regole recuperate specificando un filter.

Parametri

  • filter

    GetRulesFilter facoltativo

    Chrome 111 e versioni successive

    Un oggetto per filtrare l'elenco delle regole recuperate.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (rules: Rule[])=>void

Ritorni

  • Promessa<Regola[]>

    Chrome 91 e versioni successive

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

isRegexSupported()

Promessa Chrome 87 e versioni successive 
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
  callback?: function,
)

Consente di verificare se l'espressione regolare specificata sarà supportata come condizione della regola regexFilter.

Parametri

Ritorni

  • Chrome 91 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso 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 di estensione e fornisce un modo per incrementarlo.

Parametri

  • callback

    funzione facoltativa

    Chrome 89 e versioni successive

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

    Chrome 91 e versioni successive

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

testMatchOutcome()

Promessa Chrome 103 e versioni successive 
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
)

Controlla se una delle regole dichiarativeNetRequest dell'estensione corrisponde a una richiesta ipotetica. Nota: disponibile solo per le estensioni non pacchettizzate perché devono essere utilizzate solo durante lo sviluppo delle estensioni.

Parametri

Ritorni

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

updateDynamicRules()

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

Modifica l'insieme corrente di regole dinamiche per l'estensione. Le regole con ID elencati in options.removeRuleIds vengono prima rimosse, dopodiché vengono aggiunte le regole specificate in options.addRules. Note:

  • Questo aggiornamento avviene come una singola operazione atomica: vengono aggiunte e rimosse tutte le regole specificate oppure viene restituito un errore.
  • Queste regole sono persistenti in tutte le sessioni del browser e negli aggiornamenti delle estensioni.
  • Le regole statiche specificate come parte del pacchetto dell'estensione non possono essere rimosse utilizzando questa funzione.
  • MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES è il numero massimo di regole combinate dinamiche e per le sessioni che un'estensione può aggiungere.

Parametri

  • Chrome 87 e versioni successive
  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

    Chrome 91 e versioni successive

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

updateEnabledRulesets()

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

Aggiorna il set di set di regole statiche abilitate per l'estensione. I set di regole con ID elencati in options.disableRulesetIds vengono prima rimossi, dopodiché vengono aggiunti i set di regole elencati in options.enableRulesetIds. Tieni presente che l'insieme di set di regole statiche abilitate è mantenuto in tutte le sessioni, ma non negli aggiornamenti delle estensioni, pertanto la chiave manifest rule_resources determinerà l'insieme di set di regole statiche attivate a ogni aggiornamento dell'estensione.

Parametri

  • Chrome 87 e versioni successive
  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

    Chrome 91 e versioni successive

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

updateSessionRules()

Promessa Chrome 90 e versioni successive 
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
  callback?: function,
)

Modifica l'insieme corrente di regole con ambito a livello di sessione per l'estensione. Le regole con ID elencati in options.removeRuleIds vengono prima rimosse, dopodiché vengono aggiunte le regole specificate in options.addRules. Note:

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

Parametri

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

    Chrome 91 e versioni successive

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

updateStaticRules()

Promessa Chrome 111 e versioni successive 
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
  callback?: function,
)

Disattiva e attiva le singole regole statiche in una Ruleset. Le modifiche alle regole appartenenti a una Ruleset disattivata verranno applicate alla successiva attivazione di quest'ultima.

Parametri

Ritorni

  • Promise<void>

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

Eventi

onRuleMatchedDebug

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

Attivato quando viene abbinata una regola a una richiesta. Disponibile solo per le estensioni non pacchettizzate con l'autorizzazione "declarativeNetRequestFeedback", destinata a essere utilizzata solo a scopo di debug.

Parametri