chrome.declarativeWebRequest

Descrizione

Nota: questa API è deprecata. Controlla invece l'API declarativeNetRequest. Utilizza l'API chrome.declarativeWebRequest per intercettare, bloccare o modificare le richieste in corso. È molto più veloce rispetto all' API chrome.webRequest perché puoi registrare le regole valutate nel browser anziché nel motore JavaScript, riducendo così le latenze di round trip e consentendo una maggiore efficienza.

Autorizzazioni

declarativeWebRequest

Per utilizzare questa API, devi dichiarare l'autorizzazione "declarativeWebRequest" nel manifest dell'estensione per utilizzare questa API, insieme alle autorizzazioni host.

{
  "name": "My extension",
  ...
  "permissions": [
    "declarativeWebRequest",
    "*://*/*"
  ],
  ...
}

Disponibilità

Canale beta ≤ MV2

Manifest

Tieni presente che alcuni tipi di azioni non sensibili non richiedono le autorizzazioni dell'host:

  • CancelRequest
  • IgnoreRules
  • RedirectToEmptyDocument
  • RedirectToTransparentImage

L'azione SendMessageToExtension() richiede le autorizzazioni host per tutti gli host per cui vuoi attivare un messaggio nelle richieste di rete.

Tutte le altre azioni richiedono autorizzazioni host per tutti gli URL.

Ad esempio, se "https://*.google.com/*" è l'unica autorizzazione host di cui dispone un'estensione, questa potrebbe impostare una regola per:

  • Annulla una richiesta a https://www.google.com o https://anything.else.com.
  • Invia un messaggio quando vai a https://www.google.com, ma non a https://something.else.com.

L'estensione non può configurare una regola per reindirizzare https://www.google.com a https://mail.google.com.

Regole

L'API Declarative Web Request segue i concetti dell'API dichiarativa. Puoi registrare le regole nell'oggetto evento chrome.declarativeWebRequest.onRequest.

L'API Declarative Web Request supporta un solo tipo di criteri di corrispondenza, ovvero RequestMatcher. L'elemento RequestMatcher corrisponde alle richieste di rete se e solo se sono soddisfatti tutti i criteri elencati. La seguente RequestMatcher corrisponde a una richiesta di rete quando l'utente inserisce https://www.example.com nella minibox:

var matcher = new chrome.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com', schemes: ['http'] },
  resourceType: ['main_frame']
});

Le richieste inviate a https://www.example.com verranno rifiutate dal RequestMatcher a causa dello schema. Inoltre, tutte le richieste per un iframe incorporato vengono rifiutate a causa del resourceType.

Per annullare tutte le richieste a "example.com", puoi definire una regola nel seguente modo:

var rule = {
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'example.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]
};

Per annullare tutte le richieste a example.com e foobar.com, puoi aggiungere una seconda condizione, poiché ogni condizione è sufficiente per attivare tutte le azioni specificate:

var rule2 = {
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'example.com' } }),
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'foobar.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]
};

Registra le regole nel seguente modo:

chrome.declarativeWebRequest.onRequest.addRules([rule2]);

Valutazione di condizioni e azioni

L'API Declarative Web Request segue il modello di ciclo di vita per le richieste web dell'API WebRequest. Ciò significa che è possibile testare le condizioni solo in fasi specifiche di una richiesta web e, analogamente, le azioni possono essere eseguite solo in fasi specifiche. Le seguenti tabelle elencano le fasi della richiesta compatibili con condizioni e azioni.

Fasi della richiesta durante le quali è possibile elaborare gli attributi della condizione.
Attributo condizione onBeforeRequest onBeforeSendHeaders onHeadersReceived onAuthRequired
url ✓ ✓ ✓ ✓
resourceType ✓ ✓ ✓ ✓
contentType ✓
excludeContentType ✓
responseHeaders ✓
excludeResponseHeaders ✓
requestHeaders ✓
excludeRequestHeaders ✓
thirdPartyForCookies ✓ ✓ ✓ ✓
Fasi di richiesta durante le quali è possibile eseguire le azioni.
Evento onBeforeRequest onBeforeSendHeaders onHeadersReceived onAuthRequired
AddRequestCookie ✓
AddResponseCookie ✓
AddResponseHeader ✓
CancelRequest ✓ ✓ ✓ ✓
EditRequestCookie ✓
EditResponseCookie ✓
IgnoreRules ✓ ✓ ✓ ✓
RedirectByRegEx ✓ ✓
RedirectRequest ✓ ✓
RedirectToEmptyDocument ✓ ✓
RedirectToTransparentImage ✓ ✓
RemoveRequestCookie ✓
RemoveRequestHeader ✓
RemoveResponseCookie ✓
RemoveResponseHeader ✓
SendMessageToExtension ✓ ✓ ✓ ✓
SetRequestHeader ✓

Utilizzare le priorità per eseguire l'override delle regole

Le regole possono essere associate alle priorità come descritto nell'API Eventi. Questo meccanismo può essere usato per esprimere eccezioni. L'esempio seguente blocca tutte le richieste alle immagini denominate evil.jpg, tranne sul server "myserver.com".

var rule1 = {
  priority: 100,
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
        url: { pathEquals: 'evil.jpg' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]
};
var rule2 = {
  priority: 1000,
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: '.myserver.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.IgnoreRules({
      lowerPriorityThan: 1000 })
  ]
};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

È importante riconoscere che l'azione IgnoreRules non è persistente nelle fasi della richiesta. Tutte le condizioni di tutte le regole vengono valutate in ogni fase di una richiesta web. Se viene eseguita un'azione IgnoreRules, si applica solo alle altre azioni eseguite per la stessa richiesta web nella stessa fase.

Tipi

AddRequestCookie

Aggiunge un cookie alla richiesta o ne esegue l'override, nel caso in cui esista già un altro cookie con lo stesso nome. È preferibile utilizzare l'API Cookies perché è meno costoso dal punto di vista del calcolo.

Proprietà

AddResponseCookie

Aggiunge un cookie alla risposta o ne esegue l'override, nel caso in cui esista già un altro cookie con lo stesso nome. È preferibile utilizzare l'API Cookies perché è meno costoso dal punto di vista del calcolo.

Proprietà

AddResponseHeader

Aggiunge l'intestazione della risposta alla risposta di questa richiesta web. Poiché più intestazioni di risposta possono condividere lo stesso nome, devi prima rimuovere e aggiungere una nuova intestazione di risposta per sostituirne una.

Proprietà

  • costruttore

    void

    La funzione constructor ha il seguente aspetto: 

    (arg: AddResponseHeader)=> {...}

  • nome

    stringa

    Nome dell'intestazione della risposta HTTP.

  • valore

    stringa

    Valore dell'intestazione della risposta HTTP.

CancelRequest

Azione dell'evento dichiarativo che annulla una richiesta di rete.

Proprietà

EditRequestCookie

Modifica uno o più cookie della richiesta. È preferibile utilizzare l'API Cookies perché è meno costoso dal punto di vista del calcolo.

Proprietà

  • costruttore

    void

    La funzione constructor ha il seguente aspetto: 

    (arg: EditRequestCookie)=> {...}

  • filter

    RequestCookie

    Filtra in base ai cookie che verranno modificati. Tutte le voci vuote vengono ignorate.

  • modifica

    RequestCookie

    Attributi che devono essere sostituiti nei cookie che hanno eseguito il filtro. Gli attributi impostati su una stringa vuota vengono rimossi.

EditResponseCookie

Modifica uno o più cookie di risposta. È preferibile utilizzare l'API Cookies perché è meno costoso dal punto di vista del calcolo.

Proprietà

FilterResponseCookie

Un filtro di un cookie nelle risposte HTTP.

Proprietà

  • ageLowerBound

    numero facoltativo

    Limite inferiore inclusivo relativo alla durata dei cookie (specificato in secondi dopo l'ora attuale). Solo i cookie con data e ora di scadenza impostata su "ora + ageLowerBound" o successivamente soddisfano questo criterio. I cookie di sessione non soddisfano il criterio di questo filtro. La durata del cookie viene calcolata in base agli attributi dei cookie "max-age" o "expires". Se sono specificati entrambi, viene utilizzato "max-age" per calcolare la durata dei cookie.

  • ageUpperBound

    numero facoltativo

    Limite superiore inclusivo sulla durata dei cookie (specificato in secondi dopo l'ora attuale). Solo i cookie con data e ora di scadenza comprese nell'intervallo [now, now + ageUpperBound] soddisfano questo criterio. I cookie di sessione e i cookie con data e ora di scadenza nel passato non soddisfano il criterio di questo filtro. La durata del cookie viene calcolata in base agli attributi dei cookie "max-age" o "expires". Se sono specificati entrambi, viene utilizzato "max-age" per calcolare la durata dei cookie.

  • dominio

    stringa facoltativo

    Valore dell'attributo dei cookie del dominio.

  • scadenza

    stringa facoltativo

    Valore dell'attributo "Scadenza cookie".

  • httpOnly

    stringa facoltativo

    Esistenza dell'attributo cookie HttpOnly.

  • maxAge

    numero facoltativo

    Valore dell'attributo del cookie di Max-Age

  • nome

    stringa facoltativo

    Nome di un cookie.

  • percorso

    stringa facoltativo

    Valore dell'attributo cookie del percorso.

  • sicuro

    stringa facoltativo

    Esistenza dell'attributo cookie sicuro.

  • sessionCookie

    booleano facoltativo

    Filtra i cookie di sessione. I cookie di sessione non hanno una durata specificata in nessuno degli attributi "max-age" o "expires".

  • valore

    stringa facoltativo

    Il valore di un cookie può essere riempito tra virgolette.

HeaderFilter

Filtrare le intestazioni delle richieste per vari criteri. Più criteri vengono valutati come una congiunzione.

Proprietà

  • nameContains

    string|string[] optional

    Corrisponde se il nome dell'intestazione contiene tutte le stringhe specificate.

  • nameEquals

    stringa facoltativo

    Corrisponde se il nome dell'intestazione è uguale alla stringa specificata.

  • namePrefix

    stringa facoltativo

    Corrisponde se il nome dell'intestazione inizia con la stringa specificata.

  • nameSuffix

    stringa facoltativo

    Corrisponde se il nome dell'intestazione termina con la stringa specificata.

  • valueContains

    string|string[] optional

    Corrisponde se il valore dell'intestazione contiene tutte le stringhe specificate.

  • valueEquals

    stringa facoltativo

    Corrisponde se il valore dell'intestazione è uguale alla stringa specificata.

  • valuePrefix

    stringa facoltativo

    Corrisponde se il valore dell'intestazione inizia con la stringa specificata.

  • valueSuffix

    stringa facoltativo

    Corrisponde se il valore dell'intestazione termina con la stringa specificata.

IgnoreRules

Maschera tutte le regole che corrispondono ai criteri specificati.

Proprietà

  • costruttore

    void

    La funzione constructor ha il seguente aspetto: 

    (arg: IgnoreRules)=> {...}

  • hasTag

    stringa facoltativo

    Se impostate, le regole con il tag specificato vengono ignorate. L'opzione ignorando non è persistente, interessa solo le regole e le relative azioni nella stessa fase di richiesta di rete. Tieni presente che le regole vengono eseguite in ordine decrescente in base alle priorità. Questa azione influisce sulle regole con priorità inferiore rispetto alla regola corrente. Le regole con la stessa priorità possono essere ignorate o meno.

  • lowerPriorityThan

    numero facoltativo

    Se impostate, le regole con una priorità inferiore rispetto al valore specificato vengono ignorate. Questo confine non è persistente, interessa solo le regole e le relative azioni nella stessa fase di richiesta di rete.

RedirectByRegEx

Reindirizza una richiesta applicando un'espressione regolare all'URL. Le espressioni regolari utilizzano la sintassi RE2.

Proprietà

  • costruttore

    void

    La funzione constructor ha il seguente aspetto: 

    (arg: RedirectByRegEx)=> {...}

  • da

    stringa

    Un pattern di corrispondenza che può contenere gruppi di acquisizione. Si fa riferimento ai gruppi di cattura nella sintassi Perl ($1, $2, ...) anziché nella sintassi RE2 (\1, \2, ...) per essere più vicini alle espressioni regolari JavaScript.

  • a una

    stringa

    Pattern di destinazione.

RedirectRequest

Azione dell'evento dichiarativo che reindirizza una richiesta di rete.

Proprietà

RedirectToEmptyDocument

Azione dell'evento dichiarativo che reindirizza una richiesta di rete a un documento vuoto.

Proprietà

RedirectToTransparentImage

Azione dell'evento dichiarativo che reindirizza una richiesta di rete a un'immagine trasparente.

Proprietà

RemoveRequestCookie

Rimuove uno o più cookie della richiesta. È preferibile utilizzare l'API Cookies perché è meno costoso dal punto di vista del calcolo.

Proprietà

RemoveRequestHeader

Rimuove l'intestazione della richiesta per il nome specificato. Non utilizzare SetRequestHeader e removeRequestHeader con lo stesso nome di intestazione nella stessa richiesta. Ogni nome di intestazione della richiesta si verifica una sola volta in ogni richiesta.

Proprietà

RemoveResponseCookie

Rimuove uno o più cookie di risposta. È preferibile utilizzare l'API Cookies perché è meno costoso dal punto di vista del calcolo.

Proprietà

RemoveResponseHeader

Rimuove tutte le intestazioni di risposta dei nomi e dei valori specificati.

Proprietà

  • costruttore

    void

    La funzione constructor ha il seguente aspetto: 

    (arg: RemoveResponseHeader)=> {...}

  • nome

    stringa

    Nome dell'intestazione della richiesta HTTP (senza distinzione tra maiuscole e minuscole).

  • valore

    stringa facoltativo

    Valore dell'intestazione della richiesta HTTP (senza distinzione tra maiuscole e minuscole).

RequestCookie

Un filtro o una specifica di un cookie nelle richieste HTTP.

Proprietà

  • nome

    stringa facoltativo

    Nome di un cookie.

  • valore

    stringa facoltativo

    Il valore di un cookie può essere riempito tra virgolette.

RequestMatcher

Corrisponde agli eventi di rete in base a diversi criteri.

Proprietà

  • costruttore

    void

    La funzione constructor ha il seguente aspetto: 

    (arg: RequestMatcher)=> {...}

  • contentType

    string[] facoltativo

    Corrisponde se il tipo multimediale MIME di una risposta (dall'intestazione Content-Type HTTP) è contenuto nell'elenco.

  • excludeContentType

    string[] facoltativo

    Corrisponde se il tipo multimediale MIME di una risposta (dall'intestazione Content-Type HTTP) non è contenuto nell'elenco.

  • excludeRequestHeaders

    HeaderFilter[] facoltativo

    Corrisponde se nessuna delle intestazioni della richiesta corrisponde a uno dei filtri delle intestazioni.

  • excludeResponseHeaders

    HeaderFilter[] facoltativo

    Corrisponde se nessuna delle intestazioni della risposta corrisponde a uno degli HeaderFiltri.

  • firstPartyForCookiesUrl

    UrlFilter facoltativo

    Deprecato

    Ignorata dalla release 82.

    Corrisponde se le condizioni di UrlFilter sono soddisfatte per l'URL "proprietario" della richiesta. L'URL "proprietario" di una richiesta, se presente, può essere diverso dall'URL di destinazione della richiesta e descrive cosa viene considerato "proprietario" ai fini del controllo dei cookie di terze parti.

  • requestHeaders

    HeaderFilter[] facoltativo

    Corrisponde se ad alcune delle intestazioni della richiesta corrisponde uno degli HeaderFiltri.

  • resourceType

    Facoltativo ResourceType[]

    Corrisponde se il tipo di richiesta di una richiesta è contenuto nell'elenco. Le richieste che non possono corrispondere a nessuno di questi tipi vengono escluse.

  • responseHeaders

    HeaderFilter[] facoltativo

    Corrisponde se alcune delle intestazioni della risposta corrispondono a uno degli HeaderFiltri.

  • fasi

    Fase[] facoltativa

    Contiene un elenco di stringhe che descrivono le fasi. I valori consentiti sono "onBeforeRequest", "onBeforeSendHeaders", "onHeadersReceived", "onAuthRequired". Se questo attributo è presente, limita le fasi applicabili a quelle elencate. Tieni presente che l'intera condizione è applicabile solo in fasi compatibili con tutti gli attributi.

  • thirdPartyForCookies

    booleano facoltativo

    Deprecato

    Ignorata dalla release 87.

    Se viene impostato su true, corrisponde alle richieste soggette alle norme sui cookie di terze parti. Se impostato su false, corrisponde a tutte le altre richieste.

  • url

    UrlFilter facoltativo

    Corrisponde se le condizioni di UrlFilter sono soddisfatte per l'URL della richiesta.

ResponseCookie

Una specifica di un cookie nelle risposte HTTP.

Proprietà

  • dominio

    stringa facoltativo

    Valore dell'attributo dei cookie del dominio.

  • scadenza

    stringa facoltativo

    Valore dell'attributo "Scadenza cookie".

  • httpOnly

    stringa facoltativo

    Esistenza dell'attributo cookie HttpOnly.

  • maxAge

    numero facoltativo

    Valore dell'attributo del cookie di Max-Age

  • nome

    stringa facoltativo

    Nome di un cookie.

  • percorso

    stringa facoltativo

    Valore dell'attributo cookie del percorso.

  • sicuro

    stringa facoltativo

    Esistenza dell'attributo cookie sicuro.

  • valore

    stringa facoltativo

    Il valore di un cookie può essere riempito tra virgolette.

SendMessageToExtension

Attiva l'evento declarativeWebRequest.onMessage.

Proprietà

SetRequestHeader

Imposta l'intestazione della richiesta del nome specificato sul valore specificato. Se in precedenza non esisteva un'intestazione con il nome specificato, ne viene creata una nuova. Il confronto dei nomi delle intestazioni è sempre senza distinzione tra maiuscole e minuscole. Ogni nome di intestazione della richiesta si verifica una sola volta in ogni richiesta.

Proprietà

  • costruttore

    void

    La funzione constructor ha il seguente aspetto: 

    (arg: SetRequestHeader)=> {...}

  • nome

    stringa

    Nome dell'intestazione della richiesta HTTP.

  • valore

    stringa

    Valore dell'intestazione della richiesta HTTP.

Stage

Enum

"onBeforeRequest"

"onBeforeSendHeaders"

"onHeadersReceived"

"onAuthRequired"

Eventi

onMessage

chrome.declarativeWebRequest.onMessage.addListener(
  callback: function,
)

Attivato quando un messaggio viene inviato tramite declarativeWebRequest.SendMessageToExtension da un'azione dell'API richiesta web dichiarativa.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (details: object)=>void

    • dettagli

      oggetto

      • documentId

        stringa facoltativo

        Un UUID del documento che ha effettuato la richiesta.

      • Il ciclo di vita del documento.

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

      • Il tipo di frame in cui si è verificata la navigazione.

      • messaggio

        stringa

        Il messaggio inviato dallo script di chiamata.

      • method

        stringa

        Metodo HTTP standard.

      • parentDocumentId

        stringa facoltativo

        Un UUID del documento principale proprietario di questo frame. Non è impostato se non esiste 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. Di conseguenza, possono essere utilizzati per mettere in correlazione eventi diversi della stessa richiesta.

      • La fase della richiesta di rete durante la quale è stato attivato l'evento.

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

      • timeStamp

        numero

        Il tempo in millisecondi in cui viene attivato questo segnale dall'epoca.

      • Modalità di utilizzo della risorsa richiesta.

      • url

        stringa

onRequest

Fornisce l'API Declarative Event, composta da addRules, removeRules e getRules.

Condizioni

RequestMatcher

Azioni

AddRequestCookie

AddResponseCookie

AddResponseHeader

CancelRequest

EditRequestCookie

EditResponseCookie

RedirectRequest

RedirectToTransparentImage

RedirectToEmptyDocument

RedirectByRegEx

RemoveRequestCookie

RemoveResponseCookie

RemoveRequestHeader

RemoveResponseHeader

SetRequestHeader

SendMessageToExtension

IgnoreRules