Descrição
A API chrome.declarativeNetRequest
é usada para bloquear ou modificar solicitações de rede especificando regras declarativas. Isso permite que as extensões modifiquem as solicitações de rede sem interceptar e visualizar o conteúdo, oferecendo mais privacidade.
Permissões
declarativeNetRequest
declarativeNetRequestWithHostAccess
As permissões "declarativeNetRequest
" e "declarativeNetRequestWithHostAccess
"
oferecem os mesmos recursos. A diferença entre eles é quando as permissões são
solicitadas ou concedidas.
"declarativeNetRequest"
- Aciona um aviso de permissão no momento da instalação, mas fornece acesso implícito às
regras
allow
,allowAllRequests
eblock
. Use isso quando possível para evitar a necessidade de solicitar acesso total aos hosts. "declarativeNetRequestFeedback"
- Ativa recursos de depuração para extensões descompactadas, especificamente
getMatchedRules()
eonRuleMatchedDebug
. "declarativeNetRequestWithHostAccess"
- Um aviso de permissão não é mostrado no momento da instalação, mas é necessário solicitar permissões de host antes de executar qualquer ação em um host. Isso é apropriado quando você quer usar regras de solicitação de rede declarativas em uma extensão que já tem permissões de host sem gerar outros avisos.
Disponibilidade
Manifesto
Além das permissões descritas anteriormente, determinados tipos de conjuntos de regras (especificamente conjuntos estáticos) exigem a declaração da chave de manifesto "declarative_net_request"
, que precisa ser um dicionário com uma única chave chamada "rule_resources"
. Essa chave é uma matriz que contém dicionários do tipo Ruleset
, como mostrado a seguir. Observe que o nome "Conjunto de regras" não aparece no JSON do manifesto, já que ele é apenas uma matriz. Os conjuntos de regras estáticos são explicados posteriormente neste documento.
{
"name": "My extension",
...
"declarative_net_request" : {
"rule_resources" : [{
"id": "ruleset_1",
"enabled": true,
"path": "rules_1.json"
}, {
"id": "ruleset_2",
"enabled": false,
"path": "rules_2.json"
}]
},
"permissions": [
"declarativeNetRequest",
"declarativeNetRequestFeedback",
],
"host_permissions": [
"http://www.blogger.com/*",
"http://*.google.com/*"
],
...
}
Conceitos e uso
Para usar esta API, especifique um ou mais conjuntos de regras. Um conjunto de regras contém uma matriz de regras. Uma única regra realiza uma das seguintes ações:
- Bloquear uma solicitação de rede.
- Faça upgrade do esquema (http para https).
- Para impedir que uma solicitação seja bloqueada, nege todas as regras de bloqueio correspondentes.
- Redirecionar uma solicitação de rede.
- Modifique cabeçalhos de solicitação ou resposta.
Há três tipos de conjuntos de regras, gerenciados de maneiras ligeiramente diferentes.
- Dynamic
- Persistem em sessões do navegador e upgrades de extensões, além de serem gerenciadas usando JavaScript enquanto uma extensão está em uso.
- Sessão
- Limpo quando o navegador é desligado e quando uma nova versão da extensão é instalada. As regras de sessão são gerenciadas usando JavaScript enquanto uma extensão está em uso.
- Estático
- Em pacote, instalada e atualizada quando uma extensão é instalada ou atualizada. As regras estáticas são armazenadas em arquivos de regras formatados em JSON e listadas no arquivo de manifesto.
As próximas seções explicam os tipos de conjuntos de regras em detalhes.
Conjuntos de regras dinâmicas e no escopo da sessão
Os conjuntos de regras dinâmicas e de sessão são gerenciados usando JavaScript enquanto uma extensão está em uso.
- Regras dinâmicas persistem em sessões do navegador e upgrades de extensão.
- As regras de sessão são apagadas quando o navegador é desligado e quando uma nova versão da extensão é instalada.
Há apenas um de cada um desses tipos de conjunto de regras. Uma extensão pode adicionar ou remover regras de forma dinâmica chamando updateDynamicRules()
e updateSessionRules()
, desde que os limites de regras não sejam excedidos. Para informações sobre limites de regras, consulte Limites de regras. Confira um exemplo disso em exemplos de código.
Conjuntos de regras estáticos
Ao contrário das regras dinâmicas e de sessão, as regras estáticas são empacotadas, instaladas e atualizadas quando uma extensão é instalada ou atualizada. Elas são armazenadas em arquivos de regras no formato JSON, que são indicados à extensão usando as chaves "declarative_net_request"
e "rule_resources"
conforme descrito acima, bem como um ou mais dicionários Ruleset
. Um dicionário Ruleset
contém um caminho para o arquivo de regras, um ID para o conjunto de regras contido no arquivo e se o conjunto de regras está ativado ou desativado. As duas últimas são importantes quando você ativa ou desativa um conjunto de regras de maneira programática.
{
...
"declarative_net_request" : {
"rule_resources" : [{
"id": "ruleset_1",
"enabled": true,
"path": "rules_1.json"
},
...
]
}
...
}
Para testar arquivos de regras, carregue sua extensão descompactada. Erros e avisos sobre regras estáticas inválidas são exibidos somente para extensões descompactadas. Regras estáticas inválidas em extensões compactadas são ignoradas.
Ativar e desativar regras estáticas e conjuntos de regras
Tanto as regras estáticas individuais quanto os conjuntos de regras estáticos completos podem ser ativados ou desativados no ambiente de execução.
O conjunto de regras estáticas e de conjuntos de regras ativados é mantido nas sessões do navegador. Nenhuma delas é mantida nas atualizações de extensões, o que significa que apenas as regras que você escolheu deixar nos arquivos de regras estão disponíveis após uma atualização.
Por motivos de desempenho, também há limites para o número de regras e conjuntos de regras que podem ser ativados ao mesmo tempo. Chame getAvailableStaticRuleCount()
para verificar o número de regras adicionais que podem ser ativadas. Para informações sobre limites de regras, consulte Limites de regras.
Para ativar ou desativar regras estáticas, chame updateStaticRules()
. Esse método usa um objeto UpdateStaticRulesOptions
, que contém matrizes de IDs de regras que serão ativadas ou desativadas. Os IDs são definidos usando a chave "id"
do dicionário Ruleset
.
Para ativar ou desativar rulesets estáticos, chame updateEnabledRulesets()
. Esse método usa um objeto UpdateRulesetOptions
, que contém matrizes de IDs de conjuntos de regras que serão ativados ou desativados. Os IDs são definidos usando a chave "id"
do dicionário Ruleset
.
Regras de build
Seja qual for o tipo, uma regra começa com quatro campos, como mostrado a seguir. Embora as chaves "id"
e "priority"
aceitem um número, as chaves "action"
e "condition"
podem oferecer várias condições de bloqueio e redirecionamento. A regra a seguir bloqueia todas as solicitações de script originadas de "foo.com"
para qualquer URL com "abc"
como substring.
{
"id" : 1,
"priority": 1,
"action" : { "type" : "block" },
"condition" : {
"urlFilter" : "abc",
"initiatorDomains" : ["foo.com"],
"resourceTypes" : ["script"]
}
}
urlFilter caracteres correspondentes
A chave "condition"
de uma regra permite que uma chave "urlFilter"
aja em URLs de um domínio especificado. É possível criar padrões usando tokens de correspondência de padrões. Veja alguns exemplos.
urlFilter |
Correspondências | Sem correspondência |
---|---|---|
"abc" |
https://abcd.com https://example.com/abcd |
https://ab.com |
"abc*d" |
https://abcd.com https://example.com/abcxyzd |
https://abc.com |
"||a.example.com" |
https://a.example.com/ https://b.a.example.com/xyz |
https://example.com/ |
"|https*" |
https://example.com | http://example.com/ http://https.com |
"example*^123|" |
https://example.com/123 http://abc.com/example?123 |
https://example.com/1234 https://abc.com/example0123 |
Priorização de regras
As regras são acionadas por solicitações enviadas de páginas da Web. Se várias regras corresponderem a uma solicitação específica, elas precisarão ser priorizadas. Esta seção explica como eles são priorizados. A priorização ocorre em dois estágios.
- A prioridade é determinada para as regras de uma extensão.
- Se mais de uma extensão puder aplicar uma regra a uma solicitação, a prioridade será determinada para todas as extensões que corresponderem a uma solicitação específica.
Pensando dessa maneira: qualquer regra priorizada por uma extensão será priorizada em relação às regras de outras extensões.
Priorização de regras em uma extensão
Dentro de uma única extensão, a priorização é definida usando o seguinte processo:
- A regra com a maior prioridade definida pelo desenvolvedor (em outras palavras, o campo
"priority"
) é retornada. Se houver mais de uma regra com a maior prioridade definida pelo desenvolvedor, elas serão priorizadas usando o campo
"action"
, na seguinte ordem:allow
allowAllRequests
block
upgradeScheme
redirect
Se o tipo de ação não for
block
ouredirect
, todas as regrasmodifyHeaders
correspondentes serão avaliadas. Se houver regras com prioridade definida pelo desenvolvedor menor que a especificada paraallow
eallowAllRequests
, essas regras serão ignoradas.Se várias regras modificarem o mesmo cabeçalho, a modificação será determinada pelo campo
"priority"
definido pelo desenvolvedor e pelas operações especificadas.- Se uma regra for anexada a um cabeçalho, as regras de prioridade mais baixa só poderão ser anexadas a esse cabeçalho. As operações de definição e remoção não são permitidas.
- Se uma regra definir um cabeçalho, as regras de prioridade mais baixa só poderão ser anexadas a esse cabeçalho. Não são permitidas outras modificações.
- Se uma regra remover um cabeçalho, as regras de prioridade mais baixa não poderão modificar esse cabeçalho.
Priorização de regras entre extensões
Se apenas uma extensão tiver uma regra que corresponda a uma solicitação, ela será aplicada. No entanto, se mais de uma extensão corresponder a uma solicitação, o seguinte processo será usado:
As regras são priorizadas usando o campo
"action"
, na seguinte ordem:block
redirect
ouupgradeScheme
allow
ouallowAllRequests
Se mais de uma regra corresponder, a extensão instalada mais recentemente terá prioridade.
Limites das regras
Há uma sobrecarga de desempenho no carregamento e na avaliação de regras no navegador. Por isso, alguns limites se aplicam ao usar a API. Os limites dependem do tipo de regra que você está usando.
Regras estáticas
As regras estáticas são aquelas especificadas em arquivos de regras declaradas no arquivo de manifesto. Uma extensão pode especificar até 100 rulesets estáticos como parte da chave de manifesto "rule_resources"
. No entanto, apenas 50 desses conjuntos de regras podem ser ativados por vez. O segundo tipo é chamado de MAX_NUMBER_OF_ENABLED_STATIC_RULESETS
. Coletivamente, esses conjuntos de regras garantem pelo menos 30 mil regras. Isso é chamado de GUARANTEED_MINIMUM_STATIC_RULES
.
O número de regras disponíveis depois disso depende de quantas regras forem ativadas por todas as extensões instaladas no navegador do usuário. Para encontrar esse número durante a execução, chame getAvailableStaticRuleCount()
. Confira um exemplo disso em exemplos de código.
Regras de sessão
Uma extensão pode ter até 5.000 regras de sessão. Ele é exposto como
MAX_NUMBER_OF_SESSION_RULES
.
Antes do Chrome 120, havia um limite de 5.000 regras dinâmicas e de sessão combinadas.
Regras dinâmicas
Uma extensão pode ter pelo menos 5.000 regras dinâmicas. Ele é exposto como
MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES
.
A partir do Chrome 121, há um limite maior de 30.000 regras disponíveis para regras dinâmicas seguras,
expostas como MAX_NUMBER_OF_DYNAMIC_RULES
. Regras seguras
são definidas como regras com uma ação de block
, allow
, allowAllRequests
ou upgradeScheme
. Todas
as regras não seguras adicionadas dentro do limite de 5.000 também serão contabilizadas nesse limite.
Antes do Chrome 120, havia um limite combinado de 5.000 regras dinâmicas e de sessão.
Regras que usam expressões regulares
Todos os tipos de regras podem usar expressões regulares. No entanto, o número total de regras de expressão regular de cada tipo não pode exceder 1.000. Isso se chama MAX_NUMBER_OF_REGEX_RULES.
Além disso, cada regra precisa ter menos de 2 KB depois de compilada. Isso está relacionado, em termos gerais, à complexidade da regra. Se você tentar carregar uma regra que exceda esse limite, verá um aviso como o seguinte, e a regra será ignorada.
rules_1.json: Rule with id 1 specified a more complex regex than allowed
as part of the "regexFilter" key.
Interações com service workers
Um declarativeNetRequest se aplica apenas a solicitações que alcançam a pilha de rede. Isso inclui respostas do cache HTTP, mas pode não incluir respostas que passam pelo gerenciador onfetch
de um service worker. "declarativeNetRequest" não afetará as respostas geradas pelo service worker ou recuperadas de CacheStorage
, mas afetará chamadas para fetch()
feitas em um service worker.
Recursos acessíveis na Web
Uma regra declarativeNetRequest não pode redirecionar de uma solicitação de recurso público para um recurso que não seja acessível na Web. Isso vai gerar um erro. Isso acontece mesmo que o recurso acessível pela Web especificado pertença à extensão de redirecionamento. Para declarar recursos para declarativeNetRequest, use a matriz "web_accessible_resources"
do manifesto.
Exemplos
Exemplos de código
Atualizar regras dinâmicas
O exemplo abaixo mostra como chamar updateDynamicRules()
. O procedimento para updateSessionRules()
é o mesmo.
// Get arrays containing new and old rules
const newRules = await getNewRules();
const oldRules = await chrome.declarativeNetRequest.getDynamicRules();
const oldRuleIds = oldRules.map(rule => rule.id);
// Use the arrays to update the dynamic rules
await chrome.declarativeNetRequest.updateDynamicRules({
removeRuleIds: oldRuleIds,
addRules: newRules
});
Atualizar conjuntos de regras estáticos
O exemplo a seguir mostra como ativar e desativar conjuntos de regras considerando o número de conjuntos de regras disponíveis e o máximo de conjuntos de regras estáticos ativados. Você pode fazer isso quando o número de regras estáticas precisa exceder o número permitido. Para que isso funcione, alguns dos conjuntos de regras precisam ser instalados com alguns dos conjuntos desativados, definindo "Enabled"
como false
no arquivo de manifesto.
async function updateStaticRules(enableRulesetIds, disableCandidateIds) {
// Create the options structure for the call to updateEnabledRulesets()
let options = { enableRulesetIds: enableRulesetIds }
// Get the number of enabled static rules
const enabledStaticCount = await chrome.declarativeNetRequest.getEnabledRulesets();
// Compare rule counts to determine if anything needs to be disabled so that
// new rules can be enabled
const proposedCount = enableRulesetIds.length;
if (enabledStaticCount + proposedCount > chrome.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS) {
options.disableRulesetIds = disableCandidateIds
}
// Update the enabled static rules
await chrome.declarativeNetRequest.updateEnabledRulesets(options);
}
Exemplos de regras
Os exemplos a seguir ilustram como o Chrome prioriza regras em uma extensão. Ao analisá-los, abra as regras de priorização em outra janela.
A chave "prioridade"
Esses exemplos exigem a permissão de host para *://*.example.com/*
.
Para descobrir a prioridade de um URL específico, analise as chaves "priority"
(definidas pelo desenvolvedor), "action"
e "urlFilter"
. Esses exemplos se referem ao arquivo de regras de exemplo mostrado abaixo deles.
- Navegação para https://google.com
- Duas regras cobrem este URL: as regras com IDs 1 e 4. A regra com ID 1 se aplica porque as ações
"block"
têm uma prioridade maior do que as ações"redirect"
. As demais regras não se aplicam porque são para URLs mais longos. - Acesse https://google.com/1234
- Por causa do URL mais longo, a regra com ID 2 agora corresponde às regras com IDs 1 e 4. A regra com o ID 2 se aplica porque
"allow"
tem uma prioridade maior que"block"
e"redirect"
. - Acesse https://google.com/12345
- Todas as quatro regras correspondem a esse URL. A regra com o ID 3 se aplica porque a prioridade definida pelo desenvolvedor é a mais alta do grupo.
[
{
"id": 1,
"priority": 1,
"action": { "type": "block" },
"condition": {"urlFilter": "google.com", "resourceTypes": ["main_frame"] }
},
{
"id": 2,
"priority": 1,
"action": { "type": "allow" },
"condition": { "urlFilter": "google.com/123", "resourceTypes": ["main_frame"] }
},
{
"id": 3,
"priority": 2,
"action": { "type": "block" },
"condition": { "urlFilter": "google.com/12345", "resourceTypes": ["main_frame"] }
},
{
"id": 4,
"priority": 1,
"action": { "type": "redirect", "redirect": { "url": "https://example.com" } },
"condition": { "urlFilter": "google.com", "resourceTypes": ["main_frame"] }
},
]
Redirecionamentos
O exemplo abaixo requer permissão de host para *://*.example.com/*
.
O exemplo a seguir mostra como redirecionar uma solicitação de example.com para uma página na própria extensão. O caminho da extensão /a.jpg
é resolvido para chrome-extension://EXTENSION_ID/a.jpg
, em que EXTENSION_ID
é o ID da extensão. Para que isso funcione, o manifesto precisa declarar /a.jpg
como um recurso acessível pela Web.
{
"id": 1,
"priority": 1,
"action": { "type": "redirect", "redirect": { "extensionPath": "/a.jpg" } },
"condition": {
"urlFilter": "https://www.example.com",
"resourceTypes": ["main_frame"]
}
}
O código a seguir usa a chave "transform"
para redirecionar a um subdomínio de example.com. Ele usa uma âncora de nome de domínio ("||") para interceptar solicitações com qualquer esquema de example.com. A chave "scheme"
em "transform"
especifica que redirecionamentos para o subdomínio sempre usarão "https".
{
"id": 1,
"priority": 1,
"action": {
"type": "redirect",
"redirect": {
"transform": { "scheme": "https", "host": "new.example.com" }
}
},
"condition": {
"urlFilter": "||example.com",
"resourceTypes": ["main_frame"]
}
}
O exemplo a seguir usa expressões regulares para redirecionar de https://www.abc.xyz.com/path
para https://abc.xyz.com/path
. Na chave "regexFilter"
, observe como os pontos têm escape e que o grupo de captura seleciona "abc" ou "def". A chave "regexSubstitution"
especifica a primeira correspondência retornada da expressão regular usando "\1". Nesse caso, "abc" é capturado do URL redirecionado e colocado na substituição.
{
"id": 1,
"priority": 1,
"action": {
"type": "redirect",
"redirect": {
"regexSubstitution": "https://\\1.xyz.com/"
}
},
"condition": {
"regexFilter": "^https://www\\.(abc|def)\\.xyz\\.com/",
"resourceTypes": [
"main_frame"
]
}
}
Cabeçalhos
O exemplo a seguir remove todos os cookies de um frame principal e de quaisquer subframes.
{
"id": 1,
"priority": 1,
"action": {
"type": "modifyHeaders",
"requestHeaders": [{ "header": "cookie", "operation": "remove" }]
},
"condition": { "resourceTypes": ["main_frame", "sub_frame"] }
}
Tipos
DomainType
Descreve se a solicitação é primária ou de terceiros para o frame de origem. Uma solicitação é considerada primária se tiver o mesmo domínio (eTLD+1) do frame de origem.
Tipo enumerado
"firstParty"
A solicitação de rede é própria para o frame em que foi originada.
"thirdParty"
A solicitação de rede é de terceiros para o frame em que foi originada.
ExtensionActionOptions
Propriedades
-
displayActionCountAsBadgeText
booleano opcional
Indica se a contagem de ações de uma página será exibida automaticamente como o texto do selo da extensão. Essa preferência é mantida em todas as sessões.
-
tabUpdate
TabActionCountUpdate opcional
Chrome 89 ou mais recenteDetalhes sobre como a contagem de ações da guia precisa ser ajustada.
GetDisabledRuleIdsOptions
Propriedades
-
rulesetId
string
O ID correspondente a um
Ruleset
estático.
GetRulesFilter
Propriedades
-
ruleIds
number[] opcional
Se especificado, apenas as regras com IDs correspondentes serão incluídas.
HeaderOperation
Isso descreve as operações possíveis para uma regra "modifyHeaders".
Tipo enumerado
"append"
adiciona uma nova entrada para o cabeçalho especificado. Essa operação não é compatível com cabeçalhos de solicitação.
"set"
Define um novo valor para o cabeçalho especificado, removendo qualquer cabeçalho existente com o mesmo nome.
"remove"
remove todas as entradas do cabeçalho especificado.
IsRegexSupportedResult
Propriedades
-
isSupported
boolean
-
reason
UnsupportedRegexReason opcional
Especifica o motivo da incompatibilidade da expressão regular. Fornecido apenas se
isSupported
for falso.
MatchedRule
Propriedades
-
ruleId
number
O ID de uma regra correspondente.
-
rulesetId
string
ID da
Ruleset
a que esta regra pertence. Para uma regra originada do conjunto de regras dinâmicas, será igual aDYNAMIC_RULESET_ID
.
MatchedRuleInfo
Propriedades
-
regra
-
tabId
number
O tabId da guia de origem da solicitação, se a guia ainda estiver ativa. Caso contrário, -1.
-
timeStamp
number
A hora em que a regra foi correspondida. Os carimbos de data/hora corresponderão à convenção JavaScript de horas, ou seja, o número de milissegundos desde o período.
MatchedRuleInfoDebug
Propriedades
-
request
Detalhes sobre a solicitação para a qual a regra foi correspondida.
-
regra
MatchedRulesFilter
Propriedades
-
minTimeStamp
número opcional
Se especificado, só corresponde às regras após o carimbo de data/hora determinado.
-
tabId
número opcional
Se especificado, só corresponde às regras da guia em questão. Corresponde às regras não associadas a nenhuma guia ativa quando definida como -1.
ModifyHeaderInfo
Propriedades
-
cabeçalho
string
O nome do cabeçalho a ser modificado.
-
operação
A operação a ser realizada em um cabeçalho.
-
valor
string opcional
O novo valor para o cabeçalho. Precisa ser especificado para as operações
append
eset
.
QueryKeyValue
Propriedades
-
chave
string
-
replaceOnly
booleano opcional
Chrome 94 ou mais recenteSe verdadeiro, a chave de consulta será substituída somente se já estiver presente. Caso contrário, a chave também será adicionada se estiver ausente. O padrão é "false".
-
valor
string
QueryTransform
Propriedades
-
addOrReplaceParams
QueryKeyValue[] opcional
A lista de pares de chave-valor de consulta a serem adicionados ou substituídos.
-
removeParams
string[] opcional
A lista de chaves de consulta a serem removidas.
Redirect
Propriedades
-
extensionPath
string opcional
Caminho relativo ao diretório de extensão. Deve começar com "/".
-
regexSubstitution
string opcional
Padrão de substituição para regras que especificam um
regexFilter
. A primeira correspondência deregexFilter
no URL será substituída por esse padrão. NoregexSubstitution
, dígitos de escape de barra invertida (\1 a \9) podem ser usados para inserir os grupos de captura correspondentes. \0 refere-se ao texto correspondente inteiro. -
transformar
URLTransform opcional
Transformações de URL a serem executadas.
-
url
string opcional
O URL de redirecionamento. Redirecionamentos para URLs JavaScript não são permitidos.
RegexOptions
Propriedades
-
isCaseSensitive
booleano opcional
Indica se o
regex
especificado diferencia maiúsculas de minúsculas. O padrão é verdadeiro. -
Regex
string
O Expresson normal a ser verificado.
-
requireCapturing
booleano opcional
Indica se o
regex
especificado requer captura. A captura só é necessária para regras de redirecionamento que especificam uma açãoregexSubstition
. O valor padrão é falso.
RequestDetails
Propriedades
-
documentId
string opcional
Chrome 106 ou mais recenteO identificador exclusivo do documento do frame, se essa solicitação for para um frame.
-
documentLifecycle
DocumentLifecycle opcional
Chrome 106 ou mais recenteO ciclo de vida do documento do frame, se esta solicitação for para um frame.
-
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
FrameType opcional
Chrome 106 ou mais recenteO tipo do frame, se esta solicitação for para um frame.
-
iniciador
string opcional
A origem em que a solicitação foi iniciada. Isso não muda com redirecionamentos. Se a origem for opaca, a string "null" será usada.
-
method
string
Método HTTP padrão.
-
parentDocumentId
string opcional
Chrome 106 ou mais recenteIdentificador exclusivo do documento pai do frame, se essa solicitação for para um frame e tiver 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.
-
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.
-
Tipo
O tipo de recurso da solicitação.
-
url
string
O URL da solicitação.
RequestMethod
Descreve o método de solicitação HTTP de uma solicitação de rede.
Tipo enumerado
"get"
"head"
"patch"
ResourceType
Descreve o tipo de recurso da solicitação de rede.
Tipo enumerado
"main_frame"
.
"sub_frame"
"script"
"xmlhttprequest"
"ping"
"csp_report"
"websocket"
"webtransport"
"webbundle"
Rule
Propriedades
-
ação
A ação a ser realizada se essa regra for correspondida.
-
condição
A condição em que esta regra é acionada.
-
id
number
Um ID que identifica exclusivamente uma regra. Obrigatório e precisa ser maior ou igual a 1.
-
campanha
número opcional
Prioridade da regra. O padrão é 1. Quando especificado, precisa ser >= 1.
RuleAction
Propriedades
-
Redirecionar
Redirecionamento opcional
Descreve como o redirecionamento deve ser realizado. Válida apenas para regras de redirecionamento.
-
requestHeaders
ModifyHeaderInfo[] opcional
Chrome 86 ou mais recenteOs cabeçalhos de solicitação a serem modificados para a solicitação. Válida somente se RuleActionType for "modifyHeaders".
-
responseHeaders
ModifyHeaderInfo[] opcional
Chrome 86 ou mais recenteOs cabeçalhos de resposta a serem modificados para a solicitação. Válida somente se RuleActionType for "modifyHeaders".
-
Tipo
O tipo de ação a ser realizada.
RuleActionType
Descreve o tipo de ação a ser tomada se um determinado RuleCondition for correspondente.
Tipo enumerado
"block"
Bloquear a solicitação de rede.
"redirect"
Redireciona a solicitação de rede.
"allow"
Permitir a solicitação de rede. A solicitação não será interceptada se houver uma regra de permissão correspondente.
"upgradeScheme"
Faça upgrade do esquema do URL de solicitação de rede para https se a solicitação for http ou ftp.
"modifyHeaders"
Modifique os cabeçalhos de solicitação/resposta da solicitação de rede.
"allowAllRequests"
Permite todas as solicitações em uma hierarquia de frames, incluindo a própria solicitação de frame.
RuleCondition
Propriedades
-
domainType
DomainType opcional
Especifica se a solicitação de rede é própria ou de terceiros para o domínio de origem. Se omitido, todas as solicitações são aceitas.
-
domínios
string[] opcional
Descontinuado desde o Chrome 101Use
initiatorDomains
A regra só vai corresponder a solicitações de rede originadas da lista de
domains
. -
excludedDomains
string[] opcional
Descontinuado desde o Chrome 101A regra não corresponderá a solicitações de rede originadas da lista de
excludedDomains
. -
excludedInitiatorDomains
string[] opcional
Chrome 101 e mais recentesA regra não corresponderá a solicitações de rede originadas da lista de
excludedInitiatorDomains
. Se a lista estiver vazia ou omitida, nenhum domínio será excluído. Essa opção tem precedência sobreinitiatorDomains
.Observações:
- Subdomínios como "a.example.com" também são permitidos.
- As entradas precisam ter apenas caracteres ASCII.
- Use a codificação punycode para domínios internacionalizados.
- Isso corresponde ao iniciador da solicitação, não ao URL dela.
- Os subdomínios dos domínios listados também são excluídos.
-
excludedRequestDomains
string[] opcional
Chrome 101 e mais recentesA regra não corresponderá às solicitações de rede quando os domínios corresponderem a um da lista de
excludedRequestDomains
. Se a lista estiver vazia ou omitida, nenhum domínio será excluído. Essa opção tem precedência sobrerequestDomains
.Observações:
- Subdomínios como "a.example.com" também são permitidos.
- As entradas precisam ter apenas caracteres ASCII.
- Use a codificação punycode para domínios internacionalizados.
- Os subdomínios dos domínios listados também são excluídos.
-
excludedRequestMethods
RequestMethod[] opcional
Chrome 91 ou mais recenteLista de métodos de solicitação não correspondentes à regra. Somente
requestMethods
ouexcludedRequestMethods
precisa ser especificado. Se nenhum deles for especificado, todos os métodos de solicitação serão correspondidos. -
excludedResourceTypes
ResourceType[] opcional
Lista de tipos de recursos para os quais a regra não corresponde. Somente
resourceTypes
ouexcludedResourceTypes
precisa ser especificado. Se nenhum deles for especificado, todos os tipos de recurso, exceto "main_frame", serão bloqueados. -
excludedTabIds
number[] opcional
Chrome 92 ou mais recenteLista de
tabs.Tab.id
a que a regra não deve corresponder. Um ID detabs.TAB_ID_NONE
exclui solicitações que não se originam de uma guia. Compatível apenas com regras com escopo de sessão. -
initiatorDomains
string[] opcional
Chrome 101 e mais recentesA regra só vai corresponder a solicitações de rede originadas da lista de
initiatorDomains
. Se a lista for omitida, a regra será aplicada às solicitações de todos os domínios. Uma lista vazia não é permitida.Observações:
- Subdomínios como "a.example.com" também são permitidos.
- As entradas precisam ter apenas caracteres ASCII.
- Use a codificação punycode para domínios internacionalizados.
- Isso corresponde ao iniciador da solicitação, não ao URL dela.
- Os subdomínios dos domínios listados também são correspondentes.
-
isUrlFilterCaseSensitive
booleano opcional
Define se
urlFilter
ouregexFilter
(o que for especificado) diferencia maiúsculas de minúsculas. O padrão é false -
regexFilter
string opcional
Expressão regular para correspondência com o URL de solicitação de rede. Isso segue a sintaxe RE2.
Observação: é possível especificar apenas
urlFilter
ouregexFilter
.Observação: o
regexFilter
precisa ser composto apenas por caracteres ASCII. É feita a correspondência com um URL em que o host é codificado no formato punycode (no caso de domínios internacionalizados) e todos os outros caracteres não ASCII são codificados em utf-8. -
requestDomains
string[] opcional
Chrome 101 e mais recentesA regra só vai corresponder às solicitações de rede quando o domínio corresponder a um da lista de
requestDomains
. Se a lista for omitida, a regra será aplicada às solicitações de todos os domínios. Uma lista vazia não é permitida.Observações:
- Subdomínios como "a.example.com" também são permitidos.
- As entradas precisam ter apenas caracteres ASCII.
- Use a codificação punycode para domínios internacionalizados.
- Os subdomínios dos domínios listados também são correspondentes.
-
requestMethods
RequestMethod[] opcional
Chrome 91 ou mais recenteLista de métodos de solicitação HTTP a que a regra pode corresponder. Uma lista vazia não é permitida.
Observação: a especificação de uma condição de regra
requestMethods
também excluirá solicitações não HTTP(S), mas a especificação deexcludedRequestMethods
não. -
resourceTypes
ResourceType[] opcional
Lista de tipos de recursos aos quais a regra pode corresponder. Uma lista vazia não é permitida.
Observação: isso precisa ser especificado para regras
allowAllRequests
e só pode incluir os tipos de recursosub_frame
emain_frame
. -
tabIds
number[] opcional
Chrome 92 ou mais recenteLista de
tabs.Tab.id
a que a regra deve corresponder. Um ID detabs.TAB_ID_NONE
corresponde a solicitações que não se originam de uma guia. Uma lista vazia não é permitida. Compatível apenas com regras com escopo de sessão. -
urlFilter
string opcional
O padrão que corresponde ao URL da solicitação de rede. Construções compatíveis:
'*' : caractere curinga: corresponde a qualquer número de caracteres.
'|' : âncora esquerda/direita: se usado em qualquer extremidade do padrão, especifica o início/fim do URL, respectivamente.
'||' : âncora de nome de domínio: se usada no início do padrão, especifica o início de um (sub)domínio do URL.
'^' : caractere separador: corresponde a tudo, exceto uma letra, um dígito ou um dos seguintes caracteres:
_
,-
,.
ou%
. Isso também corresponde ao fim do URL.Portanto, o
urlFilter
é composto pelas seguintes partes: (Âncora opcional de nome de domínio/esquerda) + padrão + (Âncora direita opcional).Se omitido, todos os URLs serão correspondentes. Strings em branco não são permitidas.
Um padrão que começa com
||*
não é permitido. Use*
.Observação: é possível especificar apenas
urlFilter
ouregexFilter
.Observação: o
urlFilter
precisa ser composto apenas por caracteres ASCII. É feita a correspondência com um URL em que o host é codificado no formato punycode (no caso de domínios internacionalizados) e todos os outros caracteres não ASCII são codificados em utf-8. Por exemplo, quando o URL da solicitação for http://abc.рgraphics?q=&,urlFilter
será correspondido ao URL http://abc.xn--p1ai/?q=%D1%84.
Ruleset
Propriedades
-
ativado
boolean
Indica se o conjunto de regras está ativado por padrão.
-
id
string
Uma string não vazia que identifica exclusivamente o conjunto de regras. Os IDs que começam com "_" são reservados para uso interno.
-
caminho
string
O caminho do conjunto de regras JSON relativo ao diretório de extensão.
RulesMatchedDetails
Propriedades
-
rulesMatchedInfo
Regras que correspondem ao filtro especificado.
TabActionCountUpdate
Propriedades
-
increment
number
O valor pelo qual incrementar a contagem de ações da guia. Valores negativos diminuirão a contagem.
-
tabId
number
A guia em que a contagem de ações será atualizada.
TestMatchOutcomeResult
Propriedades
-
matchedRules
As regras (se houver) que correspondem à solicitação hipotética.
TestMatchRequestDetails
Propriedades
-
iniciador
string opcional
O URL do iniciador (se houver) da solicitação hipotética.
-
method
RequestMethod opcional
Método HTTP padrão da solicitação hipotética. O padrão é "get" para solicitações HTTP e é ignorado para solicitações que não são HTTP.
-
tabId
número opcional
O ID da guia em que ocorre a solicitação hipotética. Não precisa corresponder a um ID de guia real. O padrão é -1, ou seja, a solicitação não está relacionada a uma guia.
-
Tipo
O tipo de recurso da solicitação hipotética.
-
url
string
O URL da solicitação hipotética.
UnsupportedRegexReason
Descreve o motivo pelo qual uma determinada expressão regular não é compatível.
Tipo enumerado
"syntaxError"
A expressão regular está sintaticamente incorreta ou usa recursos não disponíveis na sintaxe RE2.
"memoryLimitExcluídoed"
A expressão regular excede o limite de memória.
UpdateRuleOptions
Propriedades
-
addRules
Regra[] opcional
Regras a serem adicionadas.
-
removeRuleIds
number[] opcional
IDs das regras a serem removidas. Todos os IDs inválidos serão ignorados.
UpdateRulesetOptions
Propriedades
UpdateStaticRulesOptions
Propriedades
URLTransform
Propriedades
-
fragment
string opcional
O novo fragmento para a solicitação. Precisa estar vazio (nesse caso, o fragmento existente será apagado) ou começar com '#'.
-
anfitrião
string opcional
O novo host da solicitação.
-
senha
string opcional
A nova senha da solicitação.
-
caminho
string opcional
O novo caminho para a solicitação. Se estiver vazio, o caminho atual será apagado.
-
porta
string opcional
A nova porta da solicitação. Se estiver vazia, a porta atual será apagada.
-
consulta
string opcional
A nova consulta para a solicitação. Deve estar vazio (nesse caso, a consulta existente é apagada) ou deve começar com "?".
-
queryTransform
QueryTransform opcional
Adicione, remova ou substitua pares de chave-valor de consulta.
-
planejar
string opcional
O novo esquema para a solicitação. Os valores permitidos são "http", "https", "ftp" e "chrome-extension".
-
nome de usuário
string opcional
O novo nome de usuário para a solicitação.
Propriedades
DYNAMIC_RULESET_ID
ID do conjunto de regras das regras dinâmicas adicionadas pela extensão.
Valor
"_dynamic"
GETMATCHEDRULES_QUOTA_INTERVAL
Intervalo de tempo em que as chamadas MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules
podem ser feitas, especificado em minutos. As chamadas adicionais vão falhar imediatamente e definir runtime.lastError
. Observação: as chamadas getMatchedRules
associadas a um gesto do usuário estão isentas da cota.
Valor
10
GUARANTEED_MINIMUM_STATIC_RULES
O número mínimo de regras estáticas garantidas para uma extensão em todos os conjuntos de regras estáticos ativados. Todas as regras acima desse limite são contabilizadas no limite de regras estáticas globais.
Valor
30.000
MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL
O número de vezes que getMatchedRules
pode ser chamado em um período de GETMATCHEDRULES_QUOTA_INTERVAL
.
Valor
20
MAX_NUMBER_OF_DYNAMIC_RULES
O número máximo de regras dinâmicas que uma extensão pode adicionar.
Valor
30.000
MAX_NUMBER_OF_ENABLED_STATIC_RULESETS
O número máximo de Rulesets
estáticos que uma extensão pode ativar por vez.
Valor
50
MAX_NUMBER_OF_REGEX_RULES
O número máximo de regras de expressão regular que uma extensão pode adicionar. Esse limite é avaliado separadamente para o conjunto de regras dinâmicas e para o especificado no arquivo de recursos da regra.
Valor
1.000
MAX_NUMBER_OF_SESSION_RULES
O número máximo de regras com escopo da sessão que uma extensão pode adicionar.
Valor
5.000
MAX_NUMBER_OF_STATIC_RULESETS
O número máximo de Rulesets
estáticos que uma extensão pode especificar como parte da chave do manifesto de "rule_resources"
.
Valor
100
MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES
O número máximo de regras dinâmicas "não seguras" que uma extensão pode adicionar.
Valor
5.000
MAX_NUMBER_OF_UNSAFE_SESSION_RULES
O número máximo de regras com escopo de sessão "não seguras" que uma extensão pode adicionar.
Valor
5.000
SESSION_RULESET_ID
ID do conjunto de regras para as regras com escopo da sessão adicionadas pela extensão.
Valor
"_session"
Métodos
getAvailableStaticRuleCount()
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
callback?: function,
)
Retorna o número de regras estáticas que uma extensão pode ativar antes que o limite de regra estática global seja atingido.
Parâmetros
-
callback
função optional
O parâmetro
callback
tem esta aparência:(count: number)=>void
-
contagem
number
-
Retorna
-
Prometer<número>
Chrome 91 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
getDisabledRuleIds()
chrome.declarativeNetRequest.getDisabledRuleIds(
options: GetDisabledRuleIdsOptions,
callback?: function,
)
Retorna a lista de regras estáticas no Ruleset
especificado que estão desativadas no momento.
Parâmetros
-
opções
Especifica o conjunto de regras a ser consultado.
-
callback
função optional
O parâmetro
callback
tem esta aparência:(disabledRuleIds: number[])=>void
-
disabledRuleIds
Número[]
-
Retorna
-
Prometer<número[]>
Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
getDynamicRules()
chrome.declarativeNetRequest.getDynamicRules(
filter?: GetRulesFilter,
callback?: function,
)
Retorna o conjunto atual de regras dinâmicas da extensão. Os autores da chamada podem, opcionalmente, filtrar a lista de regras buscadas especificando um filter
.
Parâmetros
-
Função filter
GetRulesFilter opcional
Chrome 111 ou mais recenteUm objeto para filtrar a lista de regras buscadas.
-
callback
função optional
O parâmetro
callback
tem esta aparência:(rules: Rule[])=>void
-
regras
Regra[]
-
Retorna
-
Prometer<Rule[]>
Chrome 91 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
getEnabledRulesets()
chrome.declarativeNetRequest.getEnabledRulesets(
callback?: function,
)
Retorna os IDs do conjunto atual de conjuntos de regras estáticos ativados.
Parâmetros
-
callback
função optional
O parâmetro
callback
tem esta aparência:(rulesetIds: string[])=>void
-
rulesetIds
string[]
-
Retorna
-
Promessa<string[]>
Chrome 91 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
getMatchedRules()
chrome.declarativeNetRequest.getMatchedRules(
filter?: MatchedRulesFilter,
callback?: function,
)
Retorna todas as regras correspondentes à extensão. Os autores da chamada podem, opcionalmente, filtrar a lista de regras correspondentes especificando um filter
. Esse método só está disponível para extensões com a permissão "declarativeNetRequestFeedback"
ou que têm a permissão "activeTab"
concedida para o tabId
especificado em filter
. Observação: as regras não associadas a um documento ativo que tenha correspondência há mais de cinco minutos não serão retornadas.
Parâmetros
-
Função filter
MatchedRulesFilter opcional
Um objeto para filtrar a lista de regras correspondentes.
-
callback
função optional
O parâmetro
callback
tem esta aparência:(details: RulesMatchedDetails)=>void
-
detalhes
-
Retorna
-
Promise<RulesMatchedDetails>
Chrome 91 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
getSessionRules()
chrome.declarativeNetRequest.getSessionRules(
filter?: GetRulesFilter,
callback?: function,
)
Retorna o conjunto atual de regras com escopo de sessão para a extensão. Os autores da chamada podem, opcionalmente, filtrar a lista de regras buscadas especificando um filter
.
Parâmetros
-
Função filter
GetRulesFilter opcional
Chrome 111 ou mais recenteUm objeto para filtrar a lista de regras buscadas.
-
callback
função optional
O parâmetro
callback
tem esta aparência:(rules: Rule[])=>void
-
regras
Regra[]
-
Retorna
-
Prometer<Rule[]>
Chrome 91 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
isRegexSupported()
chrome.declarativeNetRequest.isRegexSupported(
regexOptions: RegexOptions,
callback?: function,
)
Verifica se a expressão regular fornecida terá suporte como uma condição de regra regexFilter
.
Parâmetros
-
regexOptions
A expressão regular a ser verificada.
-
callback
função optional
O parâmetro
callback
tem esta aparência:(result: IsRegexSupportedResult)=>void
-
resultado
-
Retorna
-
Promise<IsRegexSupportedResult>
Chrome 91 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
setExtensionActionOptions()
chrome.declarativeNetRequest.setExtensionActionOptions(
options: ExtensionActionOptions,
callback?: function,
)
Configura se a contagem de ações para guias deve ser exibida como o texto do ícone da ação da extensão e fornece uma maneira de essa contagem de ações ser incrementada.
Parâmetros
-
opções
-
callback
função optional
Chrome 89 ou mais recenteO parâmetro
callback
tem esta aparência:()=>void
Retorna
-
Promise<void>
Chrome 91 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
testMatchOutcome()
chrome.declarativeNetRequest.testMatchOutcome(
request: TestMatchRequestDetails,
callback?: function,
)
Verifica se alguma das regras declarativeNetRequest da extensão corresponderia a uma solicitação hipotética. Observação: disponível somente para extensões descompactadas, já que ele se destina ao uso durante o desenvolvimento de extensões.
Parâmetros
-
request
-
callback
função optional
O parâmetro
callback
tem esta aparência:(result: TestMatchOutcomeResult)=>void
-
resultado
-
Retorna
-
Promise<TestMatchOutcomeResult>
Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
updateDynamicRules()
chrome.declarativeNetRequest.updateDynamicRules(
options: UpdateRuleOptions,
callback?: function,
)
Modifica o conjunto atual de regras dinâmicas da extensão. As regras com IDs listados em options.removeRuleIds
são removidas primeiro e, em seguida, as regras fornecidas em options.addRules
são adicionadas. Observações:
- Essa atualização ocorre como uma única operação atômica: todas as regras especificadas são adicionadas e removidas ou um erro é retornado.
- Essas regras são mantidas em todas as sessões do navegador e em todas as atualizações de extensões.
- As regras estáticas especificadas como parte do pacote de extensão não podem ser removidas usando essa função.
MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES
é o número máximo de regras dinâmicas e de sessão combinadas que uma extensão pode adicionar.
Parâmetros
-
opçõesChrome 87 ou mais recente
-
callback
função optional
O parâmetro
callback
tem esta aparência:()=>void
Retorna
-
Promise<void>
Chrome 91 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
updateEnabledRulesets()
chrome.declarativeNetRequest.updateEnabledRulesets(
options: UpdateRulesetOptions,
callback?: function,
)
Atualiza o conjunto de conjuntos de regras estáticos ativados para a extensão. Os conjuntos de regras com IDs listados em options.disableRulesetIds
são removidos primeiro e, em seguida, os conjuntos de regras listados em options.enableRulesetIds
são adicionados.
O conjunto de conjuntos de regras estáticos ativados é mantido entre as sessões, mas não nas atualizações de extensões. Ou seja, a chave de manifesto rule_resources
vai determinar o conjunto de conjuntos de regras estáticos ativados em cada atualização da extensão.
Parâmetros
-
opçõesChrome 87 ou mais recente
-
callback
função optional
O parâmetro
callback
tem esta aparência:()=>void
Retorna
-
Promise<void>
Chrome 91 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
updateSessionRules()
chrome.declarativeNetRequest.updateSessionRules(
options: UpdateRuleOptions,
callback?: function,
)
Modifica o conjunto atual de regras com escopo de sessão para a extensão. As regras com IDs listados em options.removeRuleIds
são removidas primeiro e, em seguida, as regras fornecidas em options.addRules
são adicionadas. Observações:
- Essa atualização ocorre como uma única operação atômica: todas as regras especificadas são adicionadas e removidas ou um erro é retornado.
- Essas regras não são mantidas entre as sessões e são salvas na memória.
MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES
é o número máximo de regras dinâmicas e de sessão combinadas que uma extensão pode adicionar.
Parâmetros
-
opções
-
callback
função optional
O parâmetro
callback
tem esta aparência:()=>void
Retorna
-
Promise<void>
Chrome 91 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
updateStaticRules()
chrome.declarativeNetRequest.updateStaticRules(
options: UpdateStaticRulesOptions,
callback?: function,
)
Desativa e ativa regras estáticas individuais em um Ruleset
. As mudanças nas regras pertencentes a um Ruleset
desativado vão entrar em vigor na próxima vez que ele for ativado.
Parâmetros
-
opções
-
callback
função optional
O parâmetro
callback
tem esta aparência:()=>void
Retorna
-
Promise<void>
Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
Eventos
onRuleMatchedDebug
chrome.declarativeNetRequest.onRuleMatchedDebug.addListener(
callback: function,
)
Disparado quando uma regra corresponde a uma solicitação. Disponível somente para extensões descompactadas com a permissão "declarativeNetRequestFeedback"
, porque ela é usada apenas para fins de depuração.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:(info: MatchedRuleInfoDebug)=>void
-
informações
-