chrome.declarativeWebRequest

refresh date: 2026-09-25 robots: noindex

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 trânsito. Ela é muito mais rápida do que a API chrome.webRequest porque você pode registrar regras que são avaliadas no navegador em vez do mecanismo JavaScript, o que reduz as latências de ida e volta e permite maior eficiência.

Permissões

declarativeWebRequest

Você precisa declarar a permissão "declarativeWebRequest" no manifesto da extensão para usar essa API, além das permissões de host.

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

Disponibilidade

Canal Beta ≤ MV2

Manifesto

Alguns tipos de ações não sensíveis não exigem permissões de host:

  • CancelRequest
  • IgnoreRules
  • RedirectToEmptyDocument
  • RedirectToTransparentImage

A ação SendMessageToExtension() exige permissões de host para qualquer host em que você queira acionar uma mensagem com solicitações de rede.

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:

  • Cancele um pedido para https://www.google.com ou https://anything.else.com.
  • Enviar uma mensagem ao navegar até https://www.google.com, mas não até 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 Declarative Web Request segue os conceitos da API Declarative. É possível registrar regras no objeto de evento chrome.declarativeWebRequest.onRequest.

A API Declarative Web Request aceita um único tipo de critério de correspondência, o RequestMatcher. O RequestMatcher corresponde às 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 digitasse https://www.example.com na omnibox:

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 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 de "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 uma é 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 Request. Isso significa que as condições só podem ser testadas em etapas específicas de uma solicitação da Web e, da mesma forma, as ações só podem ser executadas em etapas específicas. As tabelas a seguir listam os estágios de solicitação compatíveis com condições e ações.

Estágios da 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 da 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 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 em todas as etapas de 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 de IgnoreRules for executada, ela será aplicada apenas a outras ações executadas para a mesma solicitação da Web no mesmo estágio.

Tipos

AddRequestCookie

Adiciona ou substitui um cookie na solicitação, caso já exista outro com o mesmo nome. É preferível usar a API Cookies porque ela é menos dispendiosa em termos de computação.

Propriedades

AddResponseCookie

Adiciona ou substitui um cookie na resposta, caso já exista outro com o mesmo nome. É preferível usar a API Cookies porque ela é menos dispendiosa em termos de computação.

Propriedades

AddResponseHeader

Adiciona o cabeçalho de resposta à resposta desta 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 é menos dispendiosa em termos de computação.

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 serão substituídos em cookies que corresponderam ao filtro. Os atributos definidos como uma string vazia são removidos.

EditResponseCookie

Edita um ou mais cookies da resposta. É preferível usar a API Cookies porque ela é menos dispendiosa em termos de computação.

Propriedades

FilterResponseCookie

Um filtro de um cookie em respostas HTTP.

Propriedades

  • ageLowerBound

    número optional

    Limite inferior inclusivo na vida útil do cookie (especificado em segundos após o horário atual). Somente os cookies cujo prazo de validade está definido como "agora + ageLowerBound" ou posterior atendem a esse critério. Os cookies de sessão não atendem ao critério desse filtro. O ciclo de vida do cookie é calculado com base nos atributos "max-age" ou "expires" do cookie. Se ambos forem especificados, "max-age" será usado para calcular o ciclo de vida do cookie.

  • ageUpperBound

    número optional

    Limite superior inclusivo na vida útil do cookie (especificado em segundos após o horário atual). Apenas os cookies cuja data e hora de validade estão no intervalo [agora, agora + ageUpperBound] atendem a esse critério. Cookies de sessão e cookies cuja data e hora de validade estão no passado não atendem ao critério desse filtro. O ciclo de vida do cookie é calculado com base nos atributos "max-age" ou "expires" do cookie. Se ambos forem especificados, "max-age" será usado para calcular o ciclo de vida do cookie.

  • domínio

    string opcional

    Valor do atributo "Domain" do cookie.

  • vence em

    string opcional

    Valor do atributo de cookie "Expires".

  • httpOnly

    string opcional

    Existência do atributo de cookie HttpOnly.

  • maxAge

    número optional

    Valor do atributo de cookie "Max-Age".

  • nome

    string opcional

    Nome de um cookie.

  • caminho

    string opcional

    Valor do atributo de cookie "Path".

  • seguro

    string opcional

    Existência do atributo de cookie "Secure".

  • sessionCookie

    booleano opcional

    Filtra cookies de sessão. Os cookies de sessão não têm um ciclo de vida especificado em nenhum dos atributos "max-age" ou "expires".

  • valor

    string opcional

    Valor de um cookie, que pode ser colocado 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

    A correspondência será feita se o nome do cabeçalho contiver todas as strings especificadas.

  • nameEquals

    string opcional

    Corresponde se o nome do cabeçalho for 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[] opcional

    Corresponde se o valor do cabeçalho contiver todas as strings especificadas.

  • valueEquals

    string opcional

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

  • valuePrefix

    string opcional

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

  • valueSuffix

    string opcional

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

IgnoreRules

Mascaram 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 não é permanente, afetando apenas regras e ações da mesma etapa de solicitação de rede. As regras são executadas em ordem decrescente de prioridade. Essa ação afeta regras de prioridade menor que a atual. Regras com a mesma prioridade podem ou não ser ignoradas.

  • lowerPriorityThan

    número optional

    Se definido, as regras com uma prioridade menor que o valor especificado serão ignoradas. Esse limite não é persistente, afetando apenas regras e ações da mesma etapa de solicitação de rede.

RedirectByRegEx

Redireciona uma solicitação aplicando uma expressão regular ao 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 ficar mais perto das 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 da solicitação. É preferível usar a API Cookies porque ela é menos dispendiosa em termos de computação.

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 da solicitação aparece apenas uma vez em cada solicitação.

Propriedades

RemoveResponseCookie

Remove um ou mais cookies da resposta. É preferível usar a API Cookies porque ela é menos dispendiosa em termos de computação.

Propriedades

RemoveResponseHeader

Remove todos os cabeçalhos de resposta com os 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 (sem diferenciação de maiúsculas e minúsculas).

  • valor

    string opcional

    Valor do cabeçalho da solicitação HTTP (sem diferenciação de maiúsculas e 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, que pode ser colocado 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 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

    Corresponde se nenhum dos cabeçalhos de solicitação corresponder a um HeaderFilter.

  • excludeResponseHeaders

    HeaderFilter[] opcional

    Corresponde se nenhum dos cabeçalhos de resposta for correspondido por um HeaderFilter.

  • firstPartyForCookiesUrl

    UrlFilter opcional

    Descontinuado

    Ignorado desde a versão 82.

    Corresponde se as condições do UrlFilter forem 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 fins de verificações de terceiros para cookies.

  • 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 estiver 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 forem correspondidos por um dos HeaderFilters.

  • etapas

    Etapa[] opcional

    Contém uma lista de strings que descrevem as etapas. Os valores permitidos são "onBeforeRequest", "onBeforeSendHeaders", "onHeadersReceived", "onAuthRequired". Se esse atributo estiver presente, ele vai limitar as etapas aplicáveis às listadas. A condição completa só é aplicável em etapas compatíveis com todos os atributos.

  • thirdPartyForCookies

    booleano opcional

    Descontinuado

    Ignorado desde a versão 87.

    Se definido como "true", corresponde a solicitações sujeitas a políticas de cookies de terceiros. Se definido como "false", corresponde a todas as outras solicitações.

  • url

    UrlFilter opcional

    Corresponde se as condições do UrlFilter forem 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 "Domain" do cookie.

  • vence em

    string opcional

    Valor do atributo de cookie "Expires".

  • httpOnly

    string opcional

    Existência do atributo de cookie HttpOnly.

  • maxAge

    número optional

    Valor do atributo de cookie "Max-Age".

  • nome

    string opcional

    Nome de um cookie.

  • caminho

    string opcional

    Valor do atributo de cookie "Path".

  • seguro

    string opcional

    Existência do atributo de cookie "Secure".

  • valor

    string opcional

    Valor de um cookie, que pode ser colocado entre aspas duplas.

SendMessageToExtension

Aciona o evento declarativeWebRequest.onMessage.

Propriedades

SetRequestHeader

Define o cabeçalho da solicitação do nome especificado com o valor especificado. Se um cabeçalho com o nome especificado não existia antes, um novo será criado. A comparação de nomes de cabeçalho não diferencia maiúsculas de minúsculas. Cada nome de cabeçalho da solicitação aparece 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,
)

Acionado quando uma mensagem é enviada via declarativeWebRequest.SendMessageToExtension de uma ação da API declarative web request.

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

        número

        O valor 0 indica que a solicitação ocorre no frame principal. Um valor positivo indica o ID de um subframe em que a solicitação ocorre. Se o documento de um (sub)frame for carregado (type é main_frame ou sub_frame), frameId vai indicar o ID desse frame, não do frame externo. Os IDs de frame 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.

      • método

        string

        Método HTTP padrão.

      • parentDocumentId

        string opcional

        Um UUID do documento principal proprietário deste frame. Não será definido se não houver um elemento pai.

      • parentFrameId

        número

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

      • requestId

        string

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

      • etapa

        Etapa

        A etapa da solicitação de rede durante a qual o evento foi acionado.

      • tabId

        número

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

      • timeStamp

        número

        O momento em que esse indicador é 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