chrome.declarativeWebRequest

Descrizione

Nota: questa API è deprecata. Dai un'occhiata all'API declarativeNetRequest. Utilizza l'API chrome.declarativeWebRequest per intercettare, bloccare o modificare le richieste in corso di pubblicazione. È molto più veloce rispetto all'API chrome.webRequest perché puoi registrare regole valutate nel browser anziché nel motore JavaScript, il che riduce le latenze di round trip e consente un'efficienza maggiore.

Autorizzazioni

declarativeWebRequest

Devi dichiarare la richiesta "declarativeWebRequest" autorizzazione nel manifest dell'estensione per utilizzare 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 le cui richieste di rete su cui vuoi attivare un messaggio.

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

Ad esempio, se "https://*.google.com/*" è l'unica autorizzazione host di cui dispone un'estensione, tale estensione può 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ò impostare 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 registrarti all'oggetto evento chrome.declarativeWebRequest.onRequest.

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

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

Le richieste a https://www.example.com verranno rifiutate da RequestMatcher a causa dello schema. Inoltre, tutte le richieste per un iframe incorporato verranno rifiutate a causa dell'elemento resourceType.

Per annullare tutte le richieste a "example.com", puoi definire una regola come segue:

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 come segue:

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 del Web API di richiesta. Ciò significa che le condizioni possono essere testate solo in fasi specifiche di una richiesta web Allo stesso modo, le azioni possono essere eseguite solo in fasi specifiche. Le seguenti tabelle elencano che siano 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 delle richieste durante le quali possono essere eseguite 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 Events. Questo meccanismo può essere vengono utilizzate per esprimere le eccezioni. L'esempio seguente blocca tutte le richieste alle immagini denominate evil.jpg tranne sul server "mioserver.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 in tutta la richiesta fasi. Tutte le condizioni di tutte le regole vengono valutate in ogni fase di una richiesta web. Se L'azione IgnoreRules viene eseguita, si applica solo ad altre azioni eseguite per la stessa una richiesta web nella stessa fase.

Tipi

AddRequestCookie

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

Proprietà

AddResponseCookie

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

Proprietà

AddResponseHeader

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

Proprietà

  • costruttore

    null

    La funzione constructor ha questo aspetto: 

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

  • nome

    stringa

    Nome dell'intestazione della risposta HTTP.

  • valore

    stringa

    Valore di intestazione della risposta HTTP.

CancelRequest

Azione di evento dichiarativo 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 costoso dal punto di vista del calcolo.

Proprietà

  • costruttore

    null

    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 che devono essere sostituiti dai cookie che hanno eseguito il controllo del 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 costoso dal punto di vista del calcolo.

Proprietà

FilterResponseCookie

Un filtro di un cookie nelle risposte HTTP.

Proprietà

  • ageLowerBound

    numero facoltativo

    Limite inferiore inclusivo per la durata dei cookie (specificato in secondi dopo l'ora attuale). Solo i cookie la cui data e ora di scadenza è impostata su "ora + ageLowerBound" o in un secondo momento, soddisfano questo criterio. I cookie di sessione non soddisfano il criterio di questo filtro. La durata dei cookie viene calcolata da "max-age" o "scade" degli attributi dei cookie. Se sono specificati entrambi, "max-age" per calcolare la durata dei cookie.

  • ageUpperBound

    numero facoltativo

    Limite superiore inclusivo per la durata dei cookie (specificato in secondi dopo l'ora attuale). Solo i cookie la cui data e ora di scadenza è compresa 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 dei cookie viene calcolata da "max-age" o "scade" degli attributi dei cookie. Se sono specificati entrambi, "max-age" per calcolare la durata dei cookie.

  • dominio

    stringa facoltativo

    Valore dell'attributo cookie Dominio.

  • scadenza

    stringa facoltativo

    Valore dell'attributo Scade cookie.

  • httpOnly

    stringa facoltativo

    Esistenza dell'attributo cookie HttpOnly.

  • maxAge

    numero facoltativo

    Valore dell'attributo cookie Max-Age

  • nome

    stringa facoltativo

    Nome di un cookie.

  • percorso

    stringa facoltativo

    Valore dell'attributo dei cookie del percorso.

  • sicuro

    stringa facoltativo

    Esistenza dell'attributo cookie sicuro.

  • sessionCookie

    booleano facoltativo

    Filtra i cookie di sessione. Per i cookie di sessione non è specificata la durata in nessuna di "max-age" o "scade" attributi.

  • valore

    stringa facoltativo

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

HeaderFilter

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

Proprietà

  • nameContains

    string | string[] facoltativo

    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[] facoltativo

    Trova la corrispondenza 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 soddisfano i criteri specificati.

Proprietà

  • costruttore

    null

    La funzione constructor ha questo aspetto: 

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

  • hasTag

    stringa facoltativo

    Se impostato, le regole con il tag specificato vengono ignorate. L'azione da ignorare non è permanente, influisce solo sulle regole e sulle 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 o meno essere ignorate.

  • lowerPriorityThan

    numero facoltativo

    Se impostate, le regole con una priorità inferiore a quella specificata vengono ignorate. Questo confine non è persistente, influisce solo sulle regole e sulle 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

    null

    La funzione constructor ha questo aspetto: 

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

  • da

    stringa

    Un pattern di corrispondenza che può contenere gruppi di acquisizione. Ai gruppi di cattura viene fatto riferimento nella sintassi Perl ($1, $2, ...) anziché nella sintassi RE2 (\1, \2, ...) al fine di essere più vicini alle espressioni regolari JavaScript.

  • a

    stringa

    Pattern destinazione.

RedirectRequest

Azione di evento dichiarativa che reindirizza una richiesta di rete.

Proprietà

RedirectToEmptyDocument

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

Proprietà

RedirectToTransparentImage

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

Proprietà

RemoveRequestCookie

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

Proprietà

RemoveRequestHeader

Rimuove l'intestazione della richiesta del nome specificato. Non utilizzare SetRequestHeader e RimuoviRequestHeader 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. Tieni presente che è preferibile utilizzare l'API Cookies perché è meno costoso dal punto di vista del calcolo.

Proprietà

RemoveResponseHeader

Rimuove tutte le intestazioni delle risposte dei nomi e dei valori specificati.

Proprietà

  • costruttore

    null

    La funzione constructor ha questo aspetto: 

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

  • nome

    stringa

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

  • valore

    stringa facoltativo

    Valore di 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 vari criteri.

Proprietà

  • costruttore

    null

    La funzione constructor ha questo aspetto: 

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

  • contentType

    string[] facoltativo

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

  • excludeContentType

    string[] facoltativo

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

  • excludeRequestHeaders

    HeaderFilter[] facoltativo

    Corrisponde a se nessuna delle intestazioni della richiesta corrisponde a uno degli HeaderFilters.

  • excludeResponseHeaders

    HeaderFilter[] facoltativo

    Trova la corrispondenza se nessuna delle intestazioni della risposta corrisponde a uno degli HeaderFilter.

  • firstPartyForCookiesUrl

    UrlFilter facoltativo

    Obsoleta

    Ignorata dalla release 82.

    Corrisponde a se le condizioni di UrlFilter sono soddisfatte per il "proprietario" URL della richiesta. I dati "proprietari" L'URL di una richiesta, se presente, può essere diverso dall'URL di destinazione della richiesta e descrive ciò che è considerato "proprietario" ai fini dei controlli di terze parti per i cookie.

  • requestHeaders

    HeaderFilter[] facoltativo

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

  • resourceType

    ResourceType[] facoltativo

    Corrisponde se il tipo di richiesta di una richiesta è contenuto nell'elenco. Le richieste che non possono corrispondere a nessun tipo verranno escluse.

  • responseHeaders

    HeaderFilter[] facoltativo

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

  • fasi

    Fase[] facoltativa

    Contiene un elenco di stringhe che descrivono le fasi. I valori consentiti sono "onBeforeRequests", "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

    Obsoleta

    Ignorata dalla release 87.

    Se 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 a se le condizioni di UrlFilter sono soddisfatte per l'URL della richiesta.

ResponseCookie

La specifica di un cookie nelle risposte HTTP.

Proprietà

  • dominio

    stringa facoltativo

    Valore dell'attributo cookie Dominio.

  • scadenza

    stringa facoltativo

    Valore dell'attributo Scade cookie.

  • httpOnly

    stringa facoltativo

    Esistenza dell'attributo cookie HttpOnly.

  • maxAge

    numero facoltativo

    Valore dell'attributo cookie Max-Age

  • nome

    stringa facoltativo

    Nome di un cookie.

  • percorso

    stringa facoltativo

    Valore dell'attributo dei 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 non esisteva prima 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

    null

    La funzione constructor ha questo aspetto: 

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

  • nome

    stringa

    Nome dell'intestazione della richiesta HTTP.

  • valore

    stringa

    Valore di 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 di richiesta web dichiarativa.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (details: object) => void

    • dettagli

      oggetto

      • documentId

        stringa facoltativo

        L'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. 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.

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

        Un UUID del documento padre a cui appartiene questo frame. Questa opzione non è impostata se non è presente alcun 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, potrebbero essere utilizzati per collegare 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 avviene la richiesta. Imposta su -1 se la richiesta non è correlata a una scheda.

      • timeStamp

        numero

        Il tempo in cui viene attivato questo segnale, in millisecondi 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