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. Isso reduz as latências de ida e volta e aumenta a 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
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
ouhttps://anything.else.com
. - Enviar uma mensagem ao navegar para
https://www.google.com
, mas não parahttps://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
-
construtor
void
A função
constructor
tem esta aparência:(arg: AddRequestCookie) => {...}
-
arg
-
retorna
-
-
biscoito
Cookie a ser adicionado à solicitação. Nenhum campo pode ser indefinido.
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
-
construtor
void
A função
constructor
tem esta aparência:(arg: AddResponseCookie) => {...}
-
retorna
-
-
biscoito
Cookie a ser adicionado à resposta. O nome e o valor precisam ser especificados.
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
-
construtor
void
A função
constructor
tem esta aparência:(arg: AddResponseHeader) => {...}
-
retorna
-
-
nome
string
Nome do cabeçalho de resposta HTTP.
-
valor
string
Valor do cabeçalho de resposta HTTP.
CancelRequest
Ação de evento declarativa que cancela uma solicitação de rede.
Propriedades
-
construtor
void
A função
constructor
tem esta aparência:(arg: CancelRequest) => {...}
-
arg
-
retorna
-
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) => {...}
-
retorna
-
-
filtro
Filtre por cookies que serão modificados. Todas as entradas vazias são ignoradas.
-
modificação
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
-
construtor
void
A função
constructor
tem esta aparência:(arg: EditResponseCookie) => {...}
-
retorna
-
-
filtro
Filtre por cookies que serão modificados. Todas as entradas vazias são ignoradas.
-
modificação
Atributos que serão substituídos nos cookies que processaram o filtro. Os atributos definidos como uma string vazia são removidos.
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"
-
nome
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[] opcional
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[] opcional
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) => {...}
-
arg
-
retorna
-
-
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) => {...}
-
arg
-
retorna
-
-
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
-
construtor
void
A função
constructor
tem esta aparência:(arg: RedirectRequest) => {...}
-
arg
-
retorna
-
-
redirectUrl
string
Destino para onde a solicitação é redirecionada.
RedirectToEmptyDocument
Ação de evento declarativa que redireciona uma solicitação de rede para um documento vazio.
Propriedades
-
construtor
void
A função
constructor
tem esta aparência:(arg: RedirectToEmptyDocument) => {...}
-
retorna
-
RedirectToTransparentImage
Ação de evento declarativa que redireciona uma solicitação de rede para uma imagem transparente.
Propriedades
-
construtor
void
A função
constructor
tem esta aparência:(arg: RedirectToTransparentImage) => {...}
-
retorna
-
RemoveRequestCookie
Remove um ou mais cookies de 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: RemoveRequestCookie) => {...}
-
retorna
-
-
filtro
Filtre por cookies que serão removidos. Todas as entradas vazias são ignoradas.
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
-
construtor
void
A função
constructor
tem esta aparência:(arg: RemoveRequestHeader) => {...}
-
retorna
-
-
nome
string
Nome do cabeçalho da solicitação HTTP (não diferencia maiúsculas de minúsculas).
RemoveResponseCookie
Remove um ou mais cookies de resposta. É preferível usar a API Cookies porque ela é computacionalmente mais barata.
Propriedades
-
construtor
void
A função
constructor
tem esta aparência:(arg: RemoveResponseCookie) => {...}
-
retorna
-
-
filtro
Filtre por cookies que serão removidos. Todas as entradas vazias são ignoradas.
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) => {...}
-
retorna
-
-
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 eventos de rede por vários critérios.
Propriedades
-
construtor
void
A função
constructor
tem esta aparência:(arg: RequestMatcher) => {...}
-
arg
-
retorna
-
-
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
DescontinuadoIgnorado 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
DescontinuadoIgnorado 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"
-
nome
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
-
construtor
void
A função
constructor
tem esta aparência:(arg: SendMessageToExtension) => {...}
-
retorna
-
-
mensagem
string
O valor que será transmitido no atributo
message
do dicionário para o manipulador de eventos.
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) => {...}
-
arg
-
retorna
-
-
nome
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.
-
documentLifecycle
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
formain_frame
ousub_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. -
frameType
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
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
Ações