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 do que a API chrome.webRequest, porque você pode registrar regras que são avaliadas no navegador, e não no mecanismo JavaScript, o que reduz as latências de ida e volta e permite maior eficiência.

Permissões

declarativeWebRequest

É necessário declarar a permissão "declarativeWebRequest" no manifesto da extensão para usar essa API, assim como 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 em que você quer acionar uma 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, ela poderá configurar uma regra para:

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

A API declarativa de solicitação da Web segue os conceitos da API declarativa. Você pode registrar regras no objeto de evento chrome.declarativeWebRequest.onRequest.

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

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

As solicitações para https://www.example.com seriam rejeitadas por RequestMatcher devido ao esquema. Além disso, todas as solicitações de um iframe incorporado seriam rejeitadas devido a 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 para 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 de solicitação da Web declarativa segue o modelo de ciclo de vida para solicitações da Web da API Web 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 também só podem ser executadas em estágios específicos. As tabelas a seguir listam os estágios de solicitação compatíveis com as 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 usado para expressar exceções. O exemplo a seguir bloqueia todas as solicitações para 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 nos estágios da solicitação. Todas as condições de todas as regras são avaliadas em cada etapa de uma solicitação da Web. Se uma ação IgnoreRules for executada, ela se aplicará apenas a outras ações executadas para a mesma solicitação da Web no mesmo estágio.

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 é computacionalmente mais barata.

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 é computacionalmente mais barata.

Propriedades

AddResponseHeader

Adiciona o cabeçalho de resposta à resposta dessa solicitação da Web. Como vários cabeçalhos de resposta podem ter o mesmo nome, é necessário remover e, em seguida, adicionar 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 é computacionalmente mais barata.

Propriedades

  • construtor

    void

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

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

  • Função filter

    RequestCookie

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

  • modificação

    RequestCookie

    Atributos que serão substituídos nos cookies que processaram 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 é computacionalmente mais barata.

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 horário atual). Apenas cookies com data de validade definida como "agora + ageLowerBound" ou posterior atendem a esse critério. Os cookies de sessão não atendem ao critério deste filtro. A vida útil do cookie é calculada com os atributos de cookie "max-age" ou "expires". Se ambos forem especificados, "max-age" será usado 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 horário atual). Somente cookies com data e hora de validade no intervalo [agora, agora + ageUpperBound] atendem a esse critério. Os cookies de sessão e os cookies com data de validade no passado não atendem ao critério deste filtro. A vida útil do cookie é calculada com os atributos de cookie "max-age" ou "expires". Se ambos forem especificados, "max-age" será usado para calcular a vida útil do cookie.

  • domínio

    string opcional

    Valor do atributo de cookie do domínio.

  • vence em

    string opcional

    Valor do atributo do cookie "Expira".

  • httpOnly

    string opcional

    Existência do atributo de cookie HttpOnly.

  • maxAge

    número opcional

    Valor do atributo de cookie "Max-Age"

  • name

    string opcional

    Nome de um cookie.

  • caminho

    string opcional

    Valor do atributo do cookie de caminho.

  • seguro

    string opcional

    Existência do atributo de cookie seguro.

  • sessionCookie

    booleano opcional

    Filtra os cookies de sessão. Os cookies de sessão não têm vida útil especificada nos atributos "max-age" ou "expires".

  • valor

    string opcional

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

HeaderFilter

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

Propriedades

  • nameContains

    string|string[] optional

    Corresponde se o nome do cabeçalho contém todas as strings especificadas.

  • nameEquals

    string opcional

    Corresponde se o nome do cabeçalho é igual à string especificada.

  • namePrefix

    string opcional

    Corresponde 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[] optional

    Corresponde se o valor do cabeçalho contém todas as strings especificadas.

  • valueEquals

    string opcional

    Corresponde se o valor do cabeçalho é igual à string especificada.

  • valuePrefix

    string opcional

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

  • valueSuffix

    string opcional

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

IgnoreRules

Oculta 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 é permanente. Ela afeta apenas as regras e as ações delas no mesmo estágio de solicitação de rede. As regras são executadas em ordem decrescente de prioridades. Essa ação afeta regras de prioridade mais baixa do que a regra atual. As regras com a mesma prioridade podem ou não ser ignoradas.

  • lowerPriorityThan

    número opcional

    Se definido, as regras com prioridade mais baixa do que o valor especificado serão ignoradas. Esse limite não é permanente. Ele afeta apenas as regras e as 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 de na sintaxe RE2 (\1, \2, ...) para que fiquem mais próximos às expressões regulares do 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 de solicitação. É preferível usar a API Cookies porque ela é computacionalmente mais barata.

Propriedades

RemoveRequestHeader

Remove o cabeçalho da solicitação com o 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 é computacionalmente mais barata.

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)=> {...}

  • name

    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

  • name

    string opcional

    Nome de um cookie.

  • valor

    string opcional

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

RequestMatcher

Corresponde 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) está 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 está contido na lista.

  • excludeRequestHeaders

    HeaderFilter[] opcional

    Corresponde se nenhum dos cabeçalhos da solicitação corresponder a nenhum dos HeaderFilters.

  • excludeResponseHeaders

    HeaderFilter[] opcional

    Corresponde se nenhum dos cabeçalhos de resposta corresponder a nenhum dos HeaderFilters.

  • firstPartyForCookiesUrl

    UrlFilter opcional

    Descontinuado

    Ignorado desde a versão 82.

    Corresponde se as condições do UrlFilter são atendidas para o URL "próprio" da solicitação. O URL "próprio" de uma solicitação, quando presente, pode ser diferente do URL de destino da solicitação e descreve o que é considerado "próprio" para verificações de cookies de terceiros.

  • requestHeaders

    HeaderFilter[] opcional

    Corresponde se alguns dos cabeçalhos de solicitação corresponderem a 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

    Corresponde se alguns dos cabeçalhos de resposta corresponderem a um dos HeaderFilters.

  • etapas

    Fase[] 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 completa só é aplicável em estágios compatíveis com todos os atributos.

  • thirdPartyForCookies

    booleano opcional

    Descontinuado

    Ignorado desde a versão 87.

    Se definido como verdadeiro, ele corresponde às solicitações sujeitas a políticas de cookies de terceiros. Se definido como falso, corresponde a todas as outras solicitações.

  • url

    UrlFilter opcional

    Corresponde se as condições do UrlFilter são atendidas para o URL da solicitação.

ResponseCookie

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

Propriedades

  • domínio

    string opcional

    Valor do atributo de cookie do domínio.

  • vence em

    string opcional

    Valor do atributo do cookie "Expira".

  • httpOnly

    string opcional

    Existência do atributo de cookie HttpOnly.

  • maxAge

    número opcional

    Valor do atributo de cookie "Max-Age"

  • name

    string opcional

    Nome de um cookie.

  • caminho

    string opcional

    Valor do atributo do cookie de caminho.

  • seguro

    string opcional

    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 para o valor especificado. Se um cabeçalho com o nome especificado não existir antes, um novo será criado. A comparação de nomes de cabeçalho é 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)=> {...}

  • name

    string

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

  • valor

    string

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

Stage

Tipo enumerado

"onBeforeRequest"

"onBeforeSendHeaders"

"onHeadersReceived"

"onAuthRequired"

Eventos

onMessage

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

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

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 em que o documento está.

      • 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 for main_frame ou sub_frame), frameId indicará o ID desse frame, não o ID do frame externo. Os IDs de frame são exclusivos dentro de uma guia.

      • 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 contém o frame. Isso não será definido se não houver um pai.

      • parentFrameId

        number

        ID do frame que une o frame que enviou a solicitação. Definido como -1 se nenhum frame pai existir.

      • requestId

        string

        O ID da solicitação. Os IDs das solicitações são exclusivos em uma sessão do navegador. Como resultado, eles podem ser usados 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 a solicitação ocorre. 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 declarativa de eventos 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