chrome.declarativeWebRequest

Descrizione

Nota:questa API è obsoleta. Dai un'occhiata all'API declarativeNetRequest. Utilizza l'API chrome.declarativeWebRequest per intercettare, bloccare o modificare le richieste in transito. È molto più veloce dell'API chrome.webRequest perché puoi registrare regole che vengono valutate nel browser anziché nel motore JavaScript, il che riduce le latenze di andata e ritorno e consente una maggiore efficienza.

Autorizzazioni

declarativeWebRequest

Per utilizzare questa API, devi dichiarare l'autorizzazione "declarativeWebRequest" nel manifest dell'estensione, 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'organizzatore:

  • CancelRequest
  • IgnoreRules
  • RedirectToEmptyDocument
  • RedirectToTransparentImage

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

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

Ad esempio, se "https://*.google.com/*" è l'unica autorizzazione host di un'estensione, questa può configurare una regola per:

  • Annullare una richiesta a https://www.google.com o https://anything.else.com.
  • Invia un messaggio quando navighi verso https://www.google.com, ma non verso 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 regole per l'oggetto evento chrome.declarativeWebRequest.onRequest.

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

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

Le richieste di https://www.example.com verrebbero rifiutate da RequestMatcher a causa del programma. Inoltre, tutte le richieste di un iframe incorporato verranno rifiutate a causa di 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 modo seguente:

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

Valutazione di condizioni e azioni

L'API Declarative Web Request segue il modello del ciclo di vita per le richieste web dell'API Web Request. Ciò significa che le condizioni possono essere testate solo in fasi specifiche di una richiesta web e, allo stesso modo, le azioni possono essere eseguite solo in fasi specifiche. Le tabelle seguenti 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 della richiesta durante le quali è possibile eseguire 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 ignorare le regole

Le regole possono essere associate alle priorità come descritto nell'API Events. Questo meccanismo può essere utilizzato 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 viene mantenuta 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, questa si applica solo alle altre azioni eseguite per la stessa richiesta web nella stessa fase.

Tipi

AddRequestCookie

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

Proprietà

AddResponseCookie

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

Proprietà

AddResponseHeader

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

Proprietà

  • costruttore

    void

    La funzione constructor ha questo aspetto: 

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

  • nome

    stringa

    Nome dell'intestazione della risposta HTTP.

  • valore

    stringa

    Valore dell'intestazione della risposta HTTP.

CancelRequest

Azione evento dichiarativa che annulla una richiesta di rete.

Proprietà

EditRequestCookie

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

Proprietà

  • costruttore

    void

    La funzione constructor ha questo aspetto: 

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

  • filtro

    RequestCookie

    Filtra i cookie che verranno modificati. Tutte le voci vuote vengono ignorate.

  • modifica

    RequestCookie

    Attributi da sostituire nei cookie che corrispondono al filtro. Gli attributi impostati su una stringa vuota vengono rimossi.

EditResponseCookie

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

Proprietà

FilterResponseCookie

Un filtro di un cookie nelle risposte HTTP.

Proprietà

  • ageLowerBound

    number optional

    Limite inferiore inclusivo della durata del cookie (specificato in secondi dopo l'ora corrente). Solo i cookie la cui data e ora di scadenza è impostata su "ora + ageLowerBound" o successiva soddisfano questo criterio. I cookie di sessione non soddisfano i criteri di questo filtro. La durata del cookie viene calcolata in base agli attributi del cookie "max-age" o "expires". Se vengono specificati entrambi, viene utilizzato "max-age" per calcolare la durata del cookie.

  • ageUpperBound

    number optional

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

  • dominio

    stringa facoltativa

    Valore dell'attributo cookie di dominio.

  • scadenza

    stringa facoltativa

    Valore dell'attributo del cookie Expires.

  • httpOnly

    stringa facoltativa

    Esistenza dell'attributo del cookie HttpOnly.

  • maxAge

    number optional

    Valore dell'attributo cookie Max-Age

  • nome

    stringa facoltativa

    Nome di un cookie.

  • percorso

    stringa facoltativa

    Valore dell'attributo cookie Path.

  • sicuro

    stringa facoltativa

    Esistenza dell'attributo cookie Secure.

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

    Valore di un cookie, può essere racchiuso tra virgolette doppie.

HeaderFilter

Filtra le intestazioni delle richieste in base a vari criteri. Più criteri vengono valutati come una congiunzione.

Proprietà

  • nameContains

    stringa | stringa[] facoltativo

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

  • nameEquals

    stringa facoltativa

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

  • namePrefix

    stringa facoltativa

    Trova una corrispondenza se il nome dell'intestazione inizia con la stringa specificata.

  • nameSuffix

    stringa facoltativa

    Trova una corrispondenza se il nome dell'intestazione termina con la stringa specificata.

  • valueContains

    stringa | stringa[] facoltativo

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

  • valueEquals

    stringa facoltativa

    Trova la corrispondenza se il valore dell'intestazione è uguale alla stringa specificata.

  • valuePrefix

    stringa facoltativa

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

  • valueSuffix

    stringa facoltativa

    Trova la corrispondenza 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 questo aspetto: 

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

  • hasTag

    stringa facoltativa

    Se impostate, le regole con il tag specificato vengono ignorate. Questo ignoramento non è persistente e influisce solo sulle regole e sulle relative azioni della stessa fase della richiesta di rete. Tieni presente che le regole vengono eseguite in ordine decrescente di priorità. Questa azione influisce sulle regole con priorità inferiore rispetto alla regola corrente. Le regole con la stessa priorità potrebbero essere ignorate o meno.

  • lowerPriorityThan

    number optional

    Se impostate, le regole con una priorità inferiore al valore specificato vengono ignorate. Questo limite non viene mantenuto e influisce solo sulle regole e sulle relative azioni della stessa fase della 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 questo aspetto: 

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

  • da

    stringa

    Un pattern di corrispondenza che può contenere gruppi di acquisizione. I gruppi di acquisizione vengono indicati nella sintassi Perl ($1, $2, …) anziché nella sintassi RE2 (\1, \2, …) per avvicinarsi alle espressioni regolari JavaScript.

  • a

    stringa

    Pattern di destinazione.

RedirectRequest

Azione evento dichiarativa che reindirizza una richiesta di rete.

Proprietà

RedirectToEmptyDocument

Azione evento dichiarativa che reindirizza una richiesta di rete a un documento vuoto.

Proprietà

RedirectToTransparentImage

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

Proprietà

RemoveRequestCookie

Rimuove uno o più cookie di richiesta. Tieni presente che è preferibile utilizzare l'API Cookies perché è meno costosa dal punto di vista del calcolo.

Proprietà

RemoveRequestHeader

Rimuove l'intestazione della richiesta del nome specificato. Non utilizzare SetRequestHeader e RemoveRequestHeader con lo stesso nome di intestazione nella stessa richiesta. Ogni nome di intestazione della richiesta viene visualizzato una sola volta in ogni richiesta.

Proprietà

RemoveResponseCookie

Rimuove uno o più cookie della risposta. Tieni presente che è preferibile utilizzare l'API Cookies perché è meno costosa 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 questo aspetto: 

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

  • nome

    stringa

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

  • valore

    stringa facoltativa

    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 facoltativa

    Nome di un cookie.

  • valore

    stringa facoltativa

    Valore di un cookie, può essere racchiuso tra virgolette doppie.

RequestMatcher

Corrisponde agli eventi di rete in base a vari criteri.

Proprietà

  • costruttore

    void

    La funzione constructor ha questo aspetto: 

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

  • contentType

    string[] facoltativo

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

  • excludeContentType

    string[] facoltativo

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

  • excludeRequestHeaders

    HeaderFilter[] facoltativo

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

  • excludeResponseHeaders

    HeaderFilter[] facoltativo

    Corrisponde se nessuna delle intestazioni di risposta corrisponde a uno qualsiasi dei HeaderFilter.

  • firstPartyForCookiesUrl

    UrlFilter facoltativo

    Obsoleto

    Ignorata a partire dalla release 82.

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

  • requestHeaders

    HeaderFilter[] facoltativo

    Corrisponde se alcune delle intestazioni della richiesta corrispondono a uno dei HeaderFilter.

  • resourceType

    ResourceType[] facoltativo

    Corrisponde se il tipo di richiesta di una richiesta è contenuto nell'elenco. Le richieste che non corrispondono a nessuno dei tipi verranno filtrate.

  • responseHeaders

    HeaderFilter[] facoltativo

    Corrisponde se alcune delle intestazioni di risposta corrispondono a uno dei HeaderFilter.

  • fasi

    Stage[] facoltativo

    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 nelle fasi compatibili con tutti gli attributi.

  • thirdPartyForCookies

    booleano facoltativo

    Obsoleto

    Ignorato a partire dalla release 87.

    Se impostato su true, le richieste corrispondenti sono 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 vengono soddisfatte per l'URL della richiesta.

ResponseCookie

Una specifica di un cookie nelle risposte HTTP.

Proprietà

  • dominio

    stringa facoltativa

    Valore dell'attributo cookie di dominio.

  • scadenza

    stringa facoltativa

    Valore dell'attributo del cookie Expires.

  • httpOnly

    stringa facoltativa

    Esistenza dell'attributo del cookie HttpOnly.

  • maxAge

    number optional

    Valore dell'attributo cookie Max-Age

  • nome

    stringa facoltativa

    Nome di un cookie.

  • percorso

    stringa facoltativa

    Valore dell'attributo cookie Path.

  • sicuro

    stringa facoltativa

    Esistenza dell'attributo cookie Secure.

  • valore

    stringa facoltativa

    Valore di un cookie, può essere racchiuso tra virgolette doppie.

SendMessageToExtension

Attiva l'evento declarativeWebRequest.onMessage.

Proprietà

SetRequestHeader

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

Proprietà

  • costruttore

    void

    La funzione constructor ha questo 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 declarativeWebRequest.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (details: object) => void

    • dettagli

      oggetto

      • documentId

        stringa facoltativa

        Un UUID del documento che ha effettuato la richiesta.

      • Il ciclo di vita in cui si trova il documento.

      • frameId

        numero

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

      • Il tipo di frame in cui è avvenuta la navigazione.

      • messaggio

        stringa

        Il messaggio inviato dallo script di chiamata.

      • method

        stringa

        Metodo HTTP standard.

      • parentDocumentId

        stringa facoltativa

        Un UUID del documento principale proprietario di questo frame. Questo valore non viene impostato se non è presente un genitore.

      • parentFrameId

        numero

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

      • requestId

        stringa

        L'ID della richiesta. Gli ID richiesta sono univoci all'interno di una sessione del browser. Di conseguenza, potrebbero essere utilizzati per mettere in relazione diversi eventi della stessa richiesta.

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

      • tabId

        numero

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

      • timeStamp

        numero

        L'ora in cui viene attivato questo segnale, in millisecondi dall'epoca.

      • Come verrà utilizzata la 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