chrome.declarativeWebRequest

Descrição

Observação:essa API foi descontinuada. Confira a API declarativeNetRequest. Use a API chrome.declarativeWebRequest para interceptar, bloquear ou modificar solicitações em andamento. Ela é significativamente mais rápida que a API chrome.webRequest porque é possível registrar regras que são avaliadas no navegador em vez do mecanismo JavaScript, o que reduz latências de ida e volta e permite maior eficiência.

Permissões

declarativeWebRequest

É necessário declarar o objeto "declarativeWebRequest" no manifesto da extensão para usar essa com as permissões de host.

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

Disponibilidade

Canal Beta ≤ MV2

Manifesto

Alguns tipos de ações não confidenciais não exigem permissões de host:

  • CancelRequest
  • IgnoreRules
  • RedirectToEmptyDocument
  • RedirectToTransparentImage

A ação SendMessageToExtension() requer permissões de host para todos os hosts com solicitações de rede. você quer acionar a mensagem.

Todas as outras ações exigem permissões de host para todos os URLs.

Por exemplo, se "https://*.google.com/*" for a única permissão de host que uma extensão tem, essa pode configurar uma regra para:

  • Cancele uma solicitação para https://www.google.com ou https://anything.else.com.
  • Enviar uma mensagem ao navegar para https://www.google.com, mas não para https://something.else.com.

A extensão não pode configurar uma regra para redirecionar https://www.google.com para https://mail.google.com.

Regras

Ela segue os conceitos da API declarativa. Você pode se registrar ao objeto de evento chrome.declarativeWebRequest.onRequest.

A API Declarative Web Request oferece suporte a um único tipo de critério de correspondência, o RequestMatcher. A RequestMatcher corresponderá a solicitações de rede somente se todos os critérios listados forem atendidos. O seguinte RequestMatcher corresponderia a uma solicitação de rede quando o usuário inserir https://www.example.com no ominibox:

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

As solicitações para https://www.example.com vão ser rejeitadas pelo RequestMatcher devido ao esquema. Além disso, todas as solicitações de um iframe incorporado seriam rejeitadas devido ao resourceType.

Para cancelar todas as solicitações para "example.com", defina uma regra da seguinte maneira:

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

Para cancelar todas as solicitações de example.com e foobar.com, adicione uma segunda condição, já que cada condição é suficiente para acionar todas as ações especificadas:

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

Registre as regras da seguinte maneira:

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

Avaliação de condições e ações

A API Declarative Web Request segue o modelo de ciclo de vida para solicitações da Web da API Web API Request. Isso significa que as condições só podem ser testadas em estágios específicos de uma solicitação da Web Da mesma forma, as ações só podem ser executadas em estágios específicos. As tabelas a seguir listam de solicitação compatíveis com condições e ações.

Estágios de solicitação em que os atributos de condição podem ser processados.
Atributo de condição onBeforeRequest onBeforeSendHeaders onHeadersReceived onAuthRequired
url ✓ ✓ ✓ ✓
resourceType ✓ ✓ ✓ ✓
contentType ✓
excludeContentType ✓
responseHeaders ✓
excludeResponseHeaders ✓
requestHeaders ✓
excludeRequestHeaders ✓
thirdPartyForCookies ✓ ✓ ✓ ✓
Estágios de solicitação em que as ações podem ser executadas.
Evento onBeforeRequest onBeforeSendHeaders onHeadersReceived onAuthRequired
AddRequestCookie ✓
AddResponseCookie ✓
AddResponseHeader ✓
CancelRequest ✓ ✓ ✓ ✓
EditRequestCookie ✓
EditResponseCookie ✓
IgnoreRules ✓ ✓ ✓ ✓
RedirectByRegEx ✓ ✓
RedirectRequest ✓ ✓
RedirectToEmptyDocument ✓ ✓
RedirectToTransparentImage ✓ ✓
RemoveRequestCookie ✓
RemoveRequestHeader ✓
RemoveResponseCookie ✓
RemoveResponseHeader ✓
SendMessageToExtension ✓ ✓ ✓ ✓
SetRequestHeader ✓

Usar prioridades para substituir regras

As regras podem ser associadas a prioridades conforme descrito na API Events. Esse mecanismo pode ser usados para expressar exceções. O exemplo a seguir bloqueia todas as solicitações de imagens chamadas evil.jpg exceto no servidor "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 reconhecer que a ação IgnoreRules não é mantida na solicitação . em fases. Todas as condições de todas as regras são avaliadas em cada estágio de uma solicitação da Web. Se um IgnoreRules for executada, ela se aplica somente a outras ações executadas para o mesmo solicitação da Web na mesma etapa.

Tipos

AddRequestCookie

Adiciona um cookie à solicitação ou substitui um cookie, caso já exista outro com o mesmo nome. É preferível usar a API Cookies porque ela é mais econômica em termos computacionais.

Propriedades

AddResponseCookie

Adiciona um cookie à resposta ou substitui um cookie, caso já exista outro com o mesmo nome. É preferível usar a API Cookies porque ela é mais econômica em termos computacionais.

Propriedades

AddResponseHeader

Adiciona o cabeçalho de resposta à resposta dessa solicitação da Web. Como vários cabeçalhos de resposta podem compartilhar o mesmo nome, primeiro remova e adicione um novo cabeçalho de resposta para substituir um.

Propriedades

CancelRequest

Ação de evento declarativa que cancela uma solicitação de rede.

Propriedades

EditRequestCookie

Edita um ou mais cookies da solicitação. É preferível usar a API Cookies porque ela é mais econômica em termos computacionais.

Propriedades

  • construtor

    void

    A função constructor tem esta aparência: 

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

  • filtro

    RequestCookie

    Filtre os cookies que serão modificados. Todas as entradas vazias são ignoradas.

  • modificação

    RequestCookie

    Atributos que devem ser substituídos nos cookies que atingiram o filtro. Os atributos definidos como uma string vazia são removidos.

EditResponseCookie

Edita um ou mais cookies de resposta. É preferível usar a API Cookies porque ela é mais econômica em termos computacionais.

Propriedades

FilterResponseCookie

Um filtro de um cookie em respostas HTTP.

Propriedades

  • ageLowerBound

    número opcional

    Limite inferior inclusivo no ciclo de vida do cookie (especificado em segundos após o tempo atual). Somente cookies com data de validade definida como "now + ageLowerBound" ou mais tarde atenderão a esse critério. Os cookies de sessão não atendem ao critério desse filtro. A vida útil do cookie é calculada a partir de "max-age" ou 'expira' do cookie. Se ambos forem especificados, 'max-age' é usada para calcular a vida útil do cookie.

  • ageUpperBound

    número opcional

    Limite superior inclusivo no ciclo de vida do cookie (especificado em segundos após o tempo atual). Somente os cookies com data de validade no intervalo [now, now + ageUpperBound] atendem a esse critério. Os cookies de sessão e os cookies com data de expiração no passado não atendem ao critério desse filtro. A vida útil do cookie é calculada a partir de "max-age" ou 'expira' do cookie. Se ambos forem especificados, 'max-age' é usada para calcular a vida útil do cookie.

  • domínio

    string opcional

    Valor do atributo do cookie do domínio.

  • vence em

    string opcional

    Valor do atributo de cookie "Expira em".

  • httpOnly

    string opcional

    A existência do atributo do cookie HttpOnly.

  • maxAge

    número opcional

    Valor do atributo de cookie Max-Age

  • nome

    string opcional

    Nome de um cookie.

  • caminho

    string opcional

    Valor do atributo do cookie de caminho.

  • seguro

    string opcional

    A existência do atributo de cookie seguro.

  • sessionCookie

    booleano opcional

    Filtra os cookies de sessão. Cookies de sessão não têm ciclo de vida especificado em "max-age" ou 'expira' atributos.

  • valor

    string opcional

    Valor de um cookie, pode ser preenchido entre aspas duplas.

HeaderFilter

Filtra cabeçalhos de solicitação para vários critérios. Vários critérios são avaliados como uma conjunção.

Propriedades

  • nameContains

    string | string[] opcional

    Faz uma correspondência se o nome do cabeçalho contiver todas as strings especificadas.

  • nameEquals

    string opcional

    Faz correspondência se o nome do cabeçalho é igual à string especificada.

  • namePrefix

    string opcional

    Faz correspondência se o nome do cabeçalho começa com a string especificada.

  • nameSuffix

    string opcional

    Corresponde se o nome do cabeçalho termina com a string especificada.

  • valueContains

    string | string[] opcional

    Faz uma correspondência se o valor do cabeçalho contiver todas as strings especificadas.

  • valueEquals

    string opcional

    Faz correspondência se o valor do cabeçalho é igual à string especificada.

  • valuePrefix

    string opcional

    Faz a correspondência se o valor do cabeçalho começar com a string especificada.

  • valueSuffix

    string opcional

    Corresponde se o valor do cabeçalho terminar com a string especificada.

IgnoreRules

Mascara todas as regras que correspondem aos critérios especificados.

Propriedades

  • construtor

    void

    A função constructor tem esta aparência: 

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

  • hasTag

    string opcional

    Se definido, as regras com a tag especificada serão ignoradas. Essa ação de ignorar não é mantida, afeta apenas as regras e as ações delas no mesmo estágio de solicitação de rede. Observe que as regras são executadas em ordem decrescente de prioridade. Essa ação afeta regras com menor prioridade que a regra atual. Regras com a mesma prioridade podem ou não ser ignoradas.

  • lowerPriorityThan

    número opcional

    Se definida, as regras com prioridade mais baixa do que o valor especificado serão ignoradas. Esse limite não é persistido, afeta apenas regras e suas ações do mesmo estágio de solicitação de rede.

RedirectByRegEx

Redireciona uma solicitação aplicando uma expressão regular no URL. As expressões regulares usam a sintaxe RE2.

Propriedades

  • construtor

    void

    A função constructor tem esta aparência: 

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

  • de

    string

    Um padrão de correspondência que pode conter grupos de captura. Os grupos de captura são referenciados na sintaxe Perl ($1, $2, ...), em vez da sintaxe RE2 (\1, \2, ...) para se aproximarem das expressões regulares JavaScript.

  • a

    string

    Padrão de destino.

RedirectRequest

Ação de evento declarativa que redireciona uma solicitação de rede.

Propriedades

RedirectToEmptyDocument

Ação de evento declarativa que redireciona uma solicitação de rede para um documento vazio.

Propriedades

RedirectToTransparentImage

Ação de evento declarativa que redireciona uma solicitação de rede para uma imagem transparente.

Propriedades

RemoveRequestCookie

Remove um ou mais cookies da solicitação. É preferível usar a API Cookies porque ela é mais econômica em termos computacionais.

Propriedades

RemoveRequestHeader

Remove o cabeçalho de solicitação do nome especificado. Não use SetRequestHeader e RemoveRequestHeader com o mesmo nome de cabeçalho na mesma solicitação. Cada nome de cabeçalho de solicitação ocorre apenas uma vez em cada solicitação.

Propriedades

RemoveResponseCookie

Remove um ou mais cookies de resposta. É preferível usar a API Cookies porque ela é mais econômica em termos computacionais.

Propriedades

RemoveResponseHeader

Remove todos os cabeçalhos de resposta dos nomes e valores especificados.

Propriedades

  • construtor

    void

    A função constructor tem esta aparência: 

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

  • nome

    string

    Nome do cabeçalho da solicitação HTTP (não diferencia maiúsculas de minúsculas).

  • valor

    string opcional

    Valor do cabeçalho da solicitação HTTP (não diferencia maiúsculas de minúsculas).

RequestCookie

Um filtro ou especificação de um cookie em solicitações HTTP.

Propriedades

  • nome

    string opcional

    Nome de um cookie.

  • valor

    string opcional

    Valor de um cookie, pode ser preenchido entre aspas duplas.

RequestMatcher

Corresponde a eventos de rede por vários critérios.

Propriedades

  • construtor

    void

    A função constructor tem esta aparência: 

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

  • contentType

    string[] opcional

    Corresponde se o tipo de mídia MIME de uma resposta (do cabeçalho HTTP Content-Type) estiver contido na lista.

  • excludeContentType

    string[] opcional

    Corresponde se o tipo de mídia MIME de uma resposta (do cabeçalho HTTP Content-Type) não estiver contido na lista.

  • excludeRequestHeaders

    HeaderFilter[] opcional

    Faz correspondência se nenhum dos cabeçalhos de solicitação corresponde a qualquer um dos HeaderFilters.

  • excludeResponseHeaders

    HeaderFilter[] opcional

    Faz correspondência se nenhum dos cabeçalhos de resposta corresponde a qualquer um dos HeaderFilters.

  • firstPartyForCookiesUrl

    UrlFilter opcional

    Descontinuado

    Ignorado desde a versão 82.

    Corresponde se as condições do UrlFilter forem atendidas para o "próprio" URL da solicitação. O "primário" O URL de uma solicitação, quando presente, pode ser diferente do URL de destino da solicitação e descreve o que é considerado "próprio" em nome das verificações de cookies feitas por terceiros.

  • requestHeaders

    HeaderFilter[] opcional

    Corresponde se alguns dos cabeçalhos da solicitação são correspondidos por um dos HeaderFilters.

  • resourceType

    ResourceType[] opcional

    Corresponde se o tipo de uma solicitação está contido na lista. As solicitações que não corresponderem a nenhum dos tipos serão filtradas.

  • responseHeaders

    HeaderFilter[] opcional

    Faz correspondência se alguns dos cabeçalhos de resposta são correspondidos por um dos HeaderFilters.

  • etapas

    Estágio[] opcional

    Contém uma lista de strings que descrevem os estágios. Os valores permitidos são "onBeforeRequest", "onBeforeSendHeaders", "onHeadersReceived" e "onAuthRequired". Se esse atributo estiver presente, ele limitará os estágios aplicáveis àqueles listados. A condição inteira só é aplicável em fases compatíveis com todos os atributos.

  • thirdPartyForCookies

    booleano opcional

    Descontinuado

    Ignorado desde a versão 87.

    Se definida como verdadeira, corresponderá a solicitações sujeitas a políticas de cookies de terceiros. Se definido como falso, corresponde a todas as outras solicitações.

  • url

    UrlFilter opcional

    Faz correspondência se as condições do UrlFilter são atendidas para o URL da solicitação.

ResponseCookie

Uma especificação de um cookie em respostas HTTP.

Propriedades

  • domínio

    string opcional

    Valor do atributo do cookie do domínio.

  • vence em

    string opcional

    Valor do atributo de cookie "Expira em".

  • httpOnly

    string opcional

    A existência do atributo do cookie HttpOnly.

  • maxAge

    número opcional

    Valor do atributo de cookie Max-Age

  • nome

    string opcional

    Nome de um cookie.

  • caminho

    string opcional

    Valor do atributo do cookie de caminho.

  • seguro

    string opcional

    A existência do atributo de cookie seguro.

  • valor

    string opcional

    Valor de um cookie, pode ser preenchido entre aspas duplas.

SendMessageToExtension

Aciona o evento declarativeWebRequest.onMessage.

Propriedades

SetRequestHeader

Define o cabeçalho da solicitação do nome especificado como o valor especificado. Se não houver um cabeçalho com o nome especificado antes, um novo será criado. A comparação de nomes de cabeçalhos é sempre indiferente a maiúsculas. Cada nome de cabeçalho de solicitação ocorre apenas uma vez em cada solicitação.

Propriedades

  • construtor

    void

    A função constructor tem esta aparência: 

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

  • nome

    string

    Nome do cabeçalho da solicitação HTTP.

  • valor

    string

    Valor do cabeçalho da solicitação HTTP.

Stage

Enumeração

"onBeforeRequest"

"onBeforeSendHeaders"

"onHeadersReceived"

"onAuthRequired"

Eventos

onMessage

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

Disparado quando uma mensagem é enviada pelo declarativeWebRequest.SendMessageToExtension de uma ação da API de solicitação da Web declarativa.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (details: object) => void

    • detalhes

      objeto

      • documentId

        string opcional

        Um UUID do documento que fez a solicitação.

      • O ciclo de vida do documento.

      • frameId

        number

        O valor 0 indica que a solicitação acontece no frame principal. um valor positivo indica o ID de um subframe em que a solicitação acontece. Se o documento de um (sub)frame for carregado (type é main_frame ou sub_frame), frameId vai indicar o ID desse frame, e não o ID do frame externo. Os IDs de frames são exclusivos em uma guia.

      • O tipo de frame em que a navegação ocorreu.

      • mensagem

        string

        A mensagem enviada pelo script de chamada.

      • method

        string

        Método HTTP padrão.

      • parentDocumentId

        string opcional

        Um UUID do documento pai que possui este frame. Isso não será definido se não houver pai.

      • parentFrameId

        number

        ID do frame que envolve o frame que enviou a solicitação. Defina como -1 se não houver um frame pai.

      • requestId

        string

        O ID da solicitação. Os IDs de solicitação são exclusivos em uma sessão do navegador. Como resultado, elas podem ser usadas para relacionar diferentes eventos da mesma solicitação.

      • etapa

        Fase

        O estágio da solicitação de rede em que o evento foi acionado.

      • tabId

        number

        O ID da guia em que ocorre a solicitação. Defina como -1 se a solicitação não estiver relacionada a uma guia.

      • timeStamp

        number

        É a hora em que esse sinal é acionado, em milissegundos, desde o período.

      • Como o recurso solicitado será usado.

      • url

        string

onRequest

Fornece a API Declarative Event, que consiste em addRules, removeRules e getRules.

Condições

RequestMatcher

Ações

AddRequestCookie

AddResponseCookie

AddResponseHeader

CancelRequest

EditRequestCookie

EditResponseCookie

RedirectRequest

RedirectToTransparentImage

RedirectToEmptyDocument

RedirectByRegEx

RemoveRequestCookie

RemoveResponseCookie

RemoveRequestHeader

RemoveResponseHeader

SetRequestHeader

SendMessageToExtension

IgnoreRules