chrome.declarativeNetRequest

Descrizione

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

Autorizzazioni

declarativeNetRequest
declarativeNetRequestWithHostAccess

"declarativeNetRequest" e "declarativeNetRequestWithHostAccess" autorizzazioni offrono le stesse funzionalità. La differenza è quando le autorizzazioni richiesta o concessa.

"declarativeNetRequest"
Attiva un avviso di autorizzazione al momento dell'installazione, ma fornisce accesso implicito a Regole allow, allowAllRequests e block. Usa questa opzione quando possibile per evitare che richiedono l'accesso completo agli host.
"declarativeNetRequestFeedback"
Abilita le funzionalità di debug per le estensioni non pacchettizzate, in particolare getMatchedRules() e onRuleMatchedDebug.
"declarativeNetRequestWithHostAccess"
Al momento dell'installazione non viene mostrato un avviso di autorizzazione, ma devi richiedere l'host autorizzazioni prima di poter eseguire qualsiasi azione su un host. Questo è appropriato per utilizzare regole dichiarative per le richieste nette in una che dispone già di autorizzazioni host senza generare altre 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 dovrebbe 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 compare nel file JSON del file manifest poiché si tratta semplicemente di un array. I set di regole statici vengono spiegati più avanti in questo documento.

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

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

Regole e set di regole

Per utilizzare questa API, specificare uno o più set di regole. Una serie di regole contiene un array di regole. Una singola regola esegue una delle seguenti operazioni:

  • Blocca una richiesta di rete.
  • Esegui l'upgrade dello schema (da http a https).
  • Impedisci che una richiesta venga bloccata annullando 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
Si mantengono tra le sessioni del browser e gli upgrade delle estensioni e vengono gestiti tramite JavaScript mentre è in uso un'estensione.
Sessione
Cancellata all'arresto del browser e all'installazione di una nuova versione dell'estensione. Le regole di sessione vengono gestite tramite JavaScript mentre è in uso un'estensione.
Statica
Pacchettizzati, 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.

Set di regole dinamici e con ambito sessione

I set di regole dinamici e relativi alle sessioni vengono gestiti tramite 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 all'arresto del browser e all'installazione di una nuova versione dell'estensione.

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

Set di regole statici

A differenza delle regole dinamiche e di sessione, le regole statiche vengono pacchettizzate, installate e aggiornate quando un'estensione viene installata o aggiornata. 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 sopra, nonché uno o più dizionari Ruleset. Un dizionario Ruleset contiene un percorso al file di regole, un ID per la serie di regole contenuta nel file e indica se la serie di regole è attivata o meno. Gli ultimi due aspetti sono importanti quando si attiva o disattiva 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 non pacchettizzata. 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 pacchetti vengono ignorate.

Revisione rapida

Le modifiche ai set di regole statici possono essere idonee per la revisione rapida. Consulta revisione rapida per le modifiche idonee.

Attivazione e disattivazione di regole e set di regole statici

È possibile abilitare o disabilitare sia le singole regole statiche sia i set di regole statici completi in fase di runtime.

L'insieme di regole e set di regole statici attivati viene mantenuto in tutte le sessioni del browser. Nessuno dei due viene mantenuto negli aggiornamenti delle estensioni, il che significa che solo le regole che hai scelto di lasciare nei file delle regole sono disponibili dopo un aggiornamento.

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

Per attivare o disattivare le regole statiche, chiama updateStaticRules(). Questo metodo prende un oggetto UpdateStaticRulesOptions, che contiene array di ID di regole da attivare o disattivare. Gli ID vengono definiti usando la chiave "id" del dizionario Ruleset. Esiste un limite massimo di 5000 regole statiche disabilitate.

Per attivare o disattivare i set di regole statici, chiama updateEnabledRulesets(). Questo metodo prende un oggetto UpdateRulesetOptions, che contiene array di ID di set di regole da attivare o disattivare. Gli ID vengono definiti usando 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" potrebbero prevedere 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 degli URL

La richiesta netta dichiarativa consente di associare gli URL a un pattern sintassi corrispondente o espressioni regolari.

Sintassi del filtro degli URL

La chiave "condition" di una regola consente a una chiave "urlFilter" di agire sugli URL in un dominio specificato. Puoi creare i 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://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 anche utilizzare espressioni regolari. Consulta le "regexFilter". Per saperne di più i limiti che si applicano a queste condizioni, vedere Regole che utilizzano espressioni regolari.

Scrivi condizioni URL corrette

Scrivi le regole in modo che corrispondano sempre a un intero dominio. In caso contrario, può corrispondere in situazioni impreviste. Ad esempio, quando utilizzi sintassi di corrispondenza dei pattern:

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

Valuta l'uso di:

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

Allo stesso modo, utilizza i caratteri ^ e / per ancorare un'espressione regolare. Per ad esempio, ^https:\/\/www\.google\.com\/ corrisponde a qualsiasi percorso https://www.google.com.

Valutazione delle regole

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

Prima della richiesta

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

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

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

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

Se più estensioni vogliono bloccare o reindirizzare questa richiesta, viene scelta una singola azione da intraprendere. Chrome ordina le regole in questo ordine block > redirect o upgradeScheme > allow o allowAllRequests. Se due regole sono dello stesso tipo, Chrome sceglie la regola dall'estensione installata più di recente.

Prima dell'invio delle intestazioni della richiesta

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

All'interno di una singola estensione, Chrome crea l'elenco di modifiche da eseguire individuando tutte le regole modifyHeaders corrispondenti. Come in precedenza, sono incluse solo le regole che hanno una priorità più alta di qualsiasi regola allow o allowAllRequests corrispondente.

Queste regole vengono applicate da Chrome in un ordine tale che le regole di un'estensione installata più di recente vengano sempre valutate prima delle regole di un'estensione precedente. Inoltre, le regole con una priorità più alta provenienti da un'estensione vengono sempre applicate prima delle regole con una priorità più bassa provenienti dalla stessa estensione. In particolare, anche nelle estensioni:

  • Se una regola viene aggiunta a un'intestazione, le regole con priorità inferiore possono aggiungere 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 aggiungere all'intestazione. Non sono consentite altre modifiche.
  • Se una regola rimuove un'intestazione, le regole con priorità inferiore non potranno modificare ulteriormente l'intestazione.

Dopo aver ricevuto una risposta

Una volta ricevute le intestazioni delle risposte, Chrome valuta le regole con una condizione responseHeaders.

Dopo aver ordinato queste regole per 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 ha raggiunto questa fase, è già stata inviata al server e quest'ultimo ha ricevuto dati come il corpo della richiesta. Una regola di blocco o reindirizzamento con una condizione di intestazioni di risposta continuerà a essere eseguita, ma non può effettivamente bloccare o reindirizzare la richiesta.

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

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

Regole di sicurezza

Le regole sicure sono definite come regole con un'azione di block, allow, allowAllRequests o upgradeScheme. Queste regole sono soggette a un aumento quota delle regole dinamiche.

Limiti delle regole

C'è un overhead in termini di prestazioni per il caricamento e la valutazione delle regole nel browser, pertanto si applicano alcuni limiti quando si usa l'API. I limiti dipendono dal tipo di della 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 set di regole statici come parte della chiave manifest "rule_resources", ma è possibile abilitare solo 50 set di regole alla volta. Quest'ultimo si chiama MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. Collettivamente, questi insiemi di regole sono garantite per almeno 30.000 regole. Questo è chiamato GUARANTEED_MINIMUM_STATIC_RULES.

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

Regole di sessione

Un'estensione può avere fino a 5000 regole per le sessioni. Questo viene esposto MAX_NUMBER_OF_SESSION_RULES

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

Regole dinamiche

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

A partire da Chrome 121, è disponibile un limite più ampio di 30.000 regole per le regole dinamiche sicure. esposto come MAX_NUMBER_OF_DYNAMIC_RULES. Qualsiasi Ai fini di questo limite verranno conteggiate anche le regole non sicure aggiunte entro il limite di 5000.

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

Regole che utilizzano espressioni regolari

Tutti i tipi di regole possono utilizzare espressioni regolari; tuttavia, il numero totale di regole per le espressioni regolari di ciascun tipo non può essere maggiore di 1000. Questo valore è denominato MAX_NUMBER_OF_REGEX_RULES.

Inoltre, una volta compilata, ciascuna regola deve essere inferiore a 2 kB. Ciò è correlato più o meno alla complessità della regola. Se tenti di caricare una regola che supera questo limite, viene 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. Sono incluse le risposte dalla cache HTTP, ma non possono includere risposte che passano attraverso il gestore onfetch di un service worker. declarativeNetRequest non influirà sulle risposte generate dal service worker o recuperate da CacheStorage, ma influirà sulle chiamate a fetch() effettuate in un service worker.

Risorse accessibili dal web

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

Modifica dell'intestazione

L'operazione di aggiunta è supportata solo per le seguenti intestazioni: accept, accept-encoding, accept-language, access-control-request-headers, cache-control, connection, content-language, cookie, forwarded, if-match, if-none-match, keep-alive, range, te, trailer, transfer-encoding, upgrade, user-agent, via, want-digest, x-forwarded-for.

Esempi

Esempi di codice

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

Aggiornamento set di regole statici

L'esempio seguente illustra come attivare e disattivare i set di regole tenendo conto del numero di set di regole statici disponibili e di quello massimo abilitati. Questo accade quando il numero di regole statiche necessarie supera il numero consentito. Affinché questo comando funzioni, alcuni set di regole dovrebbero essere installati con alcuni di essi disabilitati (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

I seguenti esempi illustrano in che modo Chrome assegna la priorità alle regole in un'estensione. Quando le esamini, potresti voler aprire le regole di assegnazione delle priorità in un'altra finestra.

La "priorità" chiave

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

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

Navigazione su https://google.com
Questo URL è gestito da due regole: le regole con ID 1 e 4. La regola con ID 1 si applica perché le azioni "block" hanno una priorità più alta rispetto a quelle in "redirect". Le altre regole non si applicano perché si riferiscono a URL più lunghi.
Navigazione all'indirizzo https://google.com/1234
A causa dell'URL più lungo, la regola con ID 2 ora corrisponde in aggiunta alle regole con ID 1 e 4. La regola con ID 2 si applica perché "allow" ha una priorità più alta di "block" e "redirect".
Navigazione all'indirizzo https://google.com/12345
Tutte e quattro le regole corrispondono a questo URL. La regola con ID 3 si applica 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 di hosting per *://*.example.com/*.

L'esempio seguente mostra come reindirizzare una richiesta da example.com a una pagina all'interno dell'estensione stessa. Il percorso dell'estensione /a.jpg viene risolto in chrome-extension://EXTENSION_ID/a.jpg, dove EXTENSION_ID è l'ID dell'estensione. Affinché 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"]
  }
}

Di seguito viene utilizzata 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 le espressioni regolari per eseguire il reindirizzamento da https://www.abc.xyz.com/path a https://abc.xyz.com/path. Nella chiave "regexFilter", osserva come vengono utilizzati i caratteri di escape dei punti e che il gruppo di acquisizione seleziona "abc" o "def". La chiave "regexSubstitution" specifica la prima corrispondenza restituita dell'espressione regolare utilizzando "\1". In questo caso, "abc" viene acquisito dall'URL reindirizzato e inserito nella sostituzione.

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

Intestazioni

L'esempio seguente rimuove tutti i cookie da un frame principale e da 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 del frame in cui è stata originata. Una richiesta viene considerata proprietaria se ha lo stesso dominio (eTLD+1) del frame da cui ha avuto origine la richiesta.

Enum

"firstParty"
La richiesta di rete è proprietaria del frame da cui è stata originata.

"thirdParty"
La richiesta di rete è di una terza parte del frame da cui è stata originata.

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 è persistente in tutte le 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 elemento statico Ruleset.

GetRulesFilter

Chrome 111 e versioni successive .

Proprietà

  • ruleIds

    numero[] facoltativo

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

HeaderInfo

Chrome 128 e versioni successive .

Proprietà

  • excludedValues

    string[] facoltativo

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

  • intestazione

    stringa

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

  • valori

    string[] facoltativo

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

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

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

    "*" e "?" può essere preceduto da una barra rovesciata, ad esempio '\*' e "\?"

HeaderOperation

Chrome 86 e versioni successive .

Descrive le operazioni possibili per "modifyHeaders" personalizzata.

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 qualsiasi intestazione esistente con lo stesso nome.

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

IsRegexSupportedResult

Chrome 87 e versioni successive .

Proprietà

  • isSupported

    booleano

  • motivo

    FacoltativoUnsupportedRegexReason

    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

    ID del Ruleset a cui appartiene questa regola. Per una regola che ha origine dall'insieme di regole dinamiche, il valore sarà pari a DYNAMIC_RULESET_ID.

MatchedRuleInfo

Proprietà

  • regola

    MatchedRule

  • tabId

    numero

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

  • timeStamp

    numero

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

MatchedRuleInfoDebug

Proprietà

  • richiesta

    RequestDetails

    I dettagli della richiesta a cui è stata rilevata la corrispondenza con la regola.

  • regola

    MatchedRule

MatchedRulesFilter

Proprietà

  • minTimeStamp

    numero facoltativo

    Se specificato, le regole vengono associate solo dopo il timestamp specificato.

  • tabId

    numero facoltativo

    Se specificato, corrisponde solo alle regole per la scheda specificata. Corrisponde alle regole non associate ad alcuna scheda attiva se impostata 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 per l'intestazione. Deve essere specificato per le operazioni append e set.

QueryKeyValue

Proprietà

  • chiave

    stringa

  • replaceOnly

    booleano facoltativo

    Chrome 94 e versioni successive .

    Nel primo caso, la chiave di query viene sostituita solo se è già presente. In caso contrario, la chiave viene aggiunta anche se non è presente. Il valore predefinito è false.

  • valore

    stringa

QueryTransform

Proprietà

  • addOrReplaceParams

    QueryKeyValue[] facoltativo

    L'elenco di coppie chiave-valore di 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 regexFilter. La prima corrispondenza di regexFilter all'interno dell'URL verrà sostituita con questo pattern. All'interno di regexSubstitution, è possibile utilizzare cifre con caratteri di escape rovesciati (da \1 a \9) per inserire i gruppi di acquisizione corrispondenti. \0 si riferisce all'intero testo corrispondente.

  • trasformazione

    URLTransform facoltativo

    Trasformazioni degli 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

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

  • regex

    stringa

    L'espressione regolare da verificare.

  • requireCapturing

    booleano facoltativo

    Indica se è necessario acquisire il valore regex specificato. 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. un valore positivo indica l'ID di un frame secondario in cui viene eseguita 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

    FrameType facoltativo

    Chrome 106 e versioni successive .

    Il tipo di frame, se la richiesta è relativa a un frame.

  • iniziatore

    stringa facoltativo

    L'origine in cui è stata avviata la richiesta. Ciò non avviene con i reindirizzamenti. Se si tratta di un'origine opaca, 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 ne ha uno.

  • 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 avviene la richiesta. Imposta 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

"collega"

"elimina"

"get"

"head"

"opzioni"

"patch"

"post"

"put"

"altro"

ResourceType

Descrive il tipo di risorsa della richiesta di rete.

Enum

"main_frame"

"sub_frame"

"foglio di stile"

"script"

"image"

"font"

"object"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"trasporto web"

"webbundle"

"altro"

Rule

Proprietà

  • azione

    RuleAction

    L'azione da eseguire in caso di corrispondenza a questa regola.

  • condizione

    RuleCondition

    La condizione in cui 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à della regola. Il valore predefinito è 1. Se specificato, deve essere maggiore o uguale a 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 per la richiesta. 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 della regola 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"
Esegui l'upgrade dello schema dell'URL delle richieste 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 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, tutte le richieste vengono accettate.

  • domini

    string[] facoltativo

    Ritirato da Chrome 101

    In alternativa, utilizza initiatorDomains

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

  • excludedDomains

    string[] facoltativo

    Ritirato da Chrome 101

    In alternativa, utilizza 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, nessun dominio viene escluso. Ha la precedenza su initiatorDomains.

    Note:

    • Sottodomini come "a.example.com" sono consentiti.
    • Le voci devono contenere solo caratteri ASCII.
    • Utilizza la codifica punycode per i domini internazionalizzati.
    • Questo corrisponde all'iniziatore 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, nessun dominio viene escluso. Ha la precedenza su requestDomains.

    Note:

    • Sottodomini come "a.example.com" sono consentiti.
    • Le voci devono contenere solo 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 non corrispondenti alla regola. È necessario specificare solo uno tra requestMethods e excludedRequestMethods. Se nessuno dei due metodi viene specificato, viene trovata una corrispondenza con tutti i metodi di richiesta.

  • excludedResourceTypes

    ResourceType[] facoltativo

    Elenco dei tipi di risorse a cui la regola non corrisponderà. È necessario specificare solo uno tra resourceTypes e excludedResourceTypes. Se nessuno dei due è specificato, tutti i tipi di risorse tranne "main_frame" sono bloccati.

  • excludedResponseHeaders

    HeaderInfo[] facoltativo

    Chrome 128 e versioni successive .

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

  • excludedTabIds

    numero[] facoltativo

    Chrome 92 e versioni successive .

    Elenco di tabs.Tab.id che non devono corrispondere alla regola. L'ID tabs.TAB_ID_NONE esclude le richieste che non provengono da una scheda. 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 provenienti da tutti i domini. Non è consentito un elenco vuoto.

    Note:

    • Sottodomini come "a.example.com" sono consentiti.
    • Le voci devono contenere solo caratteri ASCII.
    • Utilizza la codifica punycode per i domini internazionalizzati.
    • Questo corrisponde all'iniziatore della richiesta e non all'URL della richiesta.
    • Vengono corrispondenti anche i sottodomini dei domini elencati.
  • isUrlFilterCaseSensitive

    booleano facoltativo

    Se urlFilter o regexFilter (a seconda di quale sia specificata) è sensibile alle maiuscole. Il valore predefinito è false.

  • regexFilter

    stringa facoltativo

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

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

    Nota: regexFilter deve essere composto solo da caratteri ASCII. Questo viene abbinato a 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 formato utf-8.

  • requestDomains

    string[] facoltativo

    Chrome 101 e versioni successive .

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

    Note:

    • Sottodomini come "a.example.com" sono consentiti.
    • Le voci devono contenere solo caratteri ASCII.
    • Utilizza la codifica punycode per i domini internazionalizzati.
    • Vengono corrispondenti anche i sottodomini dei domini elencati.
  • requestMethods

    RequestMethod[] facoltativo

    Chrome 91 e versioni successive .

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

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

  • resourceTypes

    ResourceType[] facoltativo

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

  • responseHeaders

    HeaderInfo[] facoltativo

    Chrome 128 e versioni successive .

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

  • tabIds

    numero[] facoltativo

    Chrome 92 e versioni successive .

    Elenco di tabs.Tab.id a cui la regola deve corrispondere. L'ID tabs.TAB_ID_NONE corrisponde alle richieste che non provengono da una scheda. Non è consentito un elenco vuoto. Supportata solo per le regole basate sulle sessioni.

  • urlFilter

    stringa facoltativo

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

    '*' : jolly: trova qualsiasi numero di caratteri.

    '|' : ancoraggio a sinistra/destra: se utilizzato a una delle due estremità del pattern, consente di specificare rispettivamente l'inizio e la fine dell'URL.

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

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

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

    Se omesso, viene trovata una corrispondenza per tutti gli URL. Non è consentita una stringa vuota.

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

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

    Nota: urlFilter deve essere composto solo da caratteri ASCII. Questo viene abbinato a 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 formato utf-8. Ad esempio, se l'URL della richiesta è http://abc.рCerchi?q=impostare, il valore urlFilter verrà abbinato all'URL http://abc.xn--p1ai/?q=%D1%84.

Ruleset

Proprietà

  • abilitata

    booleano

    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. 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 diminuiranno 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 soddisfano la richiesta ipotetica.

TestMatchRequestDetails

Chrome 103 e versioni successive .

Proprietà

  • iniziatore

    stringa facoltativo

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

  • method

    RequestMethod facoltativo

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

  • responseHeaders

    oggetto facoltativo

    In attesa

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

  • tabId

    numero facoltativo

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

    numero[] 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 un elemento Ruleset statico che deve essere attivato.

UpdateStaticRulesOptions

Chrome 111 e versioni successive .

Proprietà

  • disableRuleIds

    numero[] facoltativo

    Insieme di ID corrispondenti alle regole in Ruleset da disattivare.

  • enableRuleIds

    numero[] facoltativo

    Insieme di ID corrispondenti alle regole in Ruleset da attivare.

  • rulesetId

    stringa

    L'ID corrispondente a un elemento statico Ruleset.

URLTransform

Proprietà

  • frammento

    stringa facoltativo

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

  • host

    stringa facoltativo

    Il nuovo host per la richiesta.

  • password

    stringa facoltativo

    La nuova password per la richiesta.

  • percorso

    stringa facoltativo

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

  • porta

    stringa facoltativo

    La nuova porta per la richiesta. Se è 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. o dovrebbe iniziare con "?".

  • queryTransform

    QueryTransform facoltativo

    Aggiungi, rimuovi o sostituisci coppie chiave-valore della 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 a MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules, specificato in minuti. Le chiamate aggiuntive non riusciranno 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 a un'estensione nei relativi set di regole statici abilitati. Qualsiasi regola che supera questo limite verrà conteggiata ai fini del limite di regole statico globale.

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 basate su 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 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 elementi "non sicuri" regole dinamiche che un'estensione può aggiungere.

Valore

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120 e versioni successive .

Il numero massimo di elementi "non sicuri" regole con ambito a livello di sessione 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

"_session"

Metodi

getAvailableStaticRuleCount()

Promesso 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 di regole statiche globale.

Parametri

  • callback

    funzione 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 sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

getDisabledRuleIds()

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

Restituisce l'elenco di regole statiche nell'elemento Ruleset specificato che sono attualmente disattivate.

Parametri

  • Specifica il set di regole su cui eseguire le query.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      numero[]

Resi

  • Prometti<numero[]>

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

getDynamicRules()

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

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

Parametri

  • filtro

    GetRulesFilter facoltativo

    Chrome 111 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

Resi

  • Prometti<regola[]>

    Chrome 91 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

getEnabledRulesets()

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

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

Parametri

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (rulesetIds: string[]) => void

    • rulesetIds

      stringa[]

Resi

  • Promise&lt;string[]&gt;

    Chrome 91 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

getMatchedRules()

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

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

Parametri

Resi

  • Promise&lt;RulesMatchedDetails&gt;

    Chrome 91 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

getSessionRules()

Promesso 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. I chiamanti possono facoltativamente 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

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (rules: Rule[]) => void

Resi

  • Prometti<regola[]>

    Chrome 91 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

isRegexSupported()

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

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

Parametri

Resi

  • Promise&lt;IsRegexSupportedResult&gt;

    Chrome 91 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

setExtensionActionOptions()

Promesso 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

  • callback

    funzione facoltativa

    Chrome 89 e versioni successive .

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Chrome 91 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

testMatchOutcome()

Promesso 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 pacchettizzate, in quanto questa è destinata esclusivamente a essere utilizzata durante lo sviluppo delle estensioni.

Parametri

Resi

  • Promise&lt;TestMatchOutcomeResult&gt;

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

updateDynamicRules()

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

Consente di modificare l'insieme corrente di regole dinamiche per l'estensione. Prima vengono rimosse le regole con ID elencati in options.removeRuleIds e poi vengono aggiunte le regole specificate 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 sono persistenti in tutte le 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

  • Chrome 87 e versioni successive .
  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Chrome 91 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

updateEnabledRulesets()

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

Consente di aggiornare l'insieme di set di regole statici abilitati per l'estensione. Le serie di regole con ID elencati nel campo options.disableRulesetIds vengono prima rimosse e poi vengono aggiunte le serie di regole elencate in options.enableRulesetIds. Tieni presente che l'insieme di set di regole statici attivati viene mantenuto tra le sessioni, ma non negli aggiornamenti delle estensioni, poiché la chiave manifest rule_resources determinerà l'insieme di set di regole statici attivati a ogni aggiornamento delle estensioni.

Parametri

  • Chrome 87 e versioni successive .
  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Chrome 91 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

updateSessionRules()

Promesso 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. Prima vengono rimosse le regole con ID elencati in options.removeRuleIds e poi vengono aggiunte le regole specificate 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 rese persistenti tra le sessioni e sono supportate in memoria.
  • MAX_NUMBER_OF_SESSION_RULES è il numero massimo di regole per le sessioni che un'estensione può aggiungere.

Parametri

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Chrome 91 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

updateStaticRules()

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

Disattiva e attiva singole regole statiche in una Ruleset. Le modifiche alle regole appartenenti a un Ruleset disattivato avranno effetto alla successiva attivazione.

Parametri

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

Eventi

onRuleMatchedDebug

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

Attivato quando una regola corrisponde a una richiesta. Disponibile solo per le estensioni non pacchettizzate con autorizzazione "declarativeNetRequestFeedback", in quanto questa è destinata a essere utilizzata esclusivamente a scopo di debug.

Parametri