chrome.declarativeNetRequest

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 interceptá-las e acessar o conteúdo delas, proporcionando mais privacidade.

Permissões

declarativeNetRequest
declarativeNetRequestWithHostAccess

As permissões "declarativeNetRequest" e "declarativeNetRequestWithHostAccess" oferecem os mesmos recursos. A diferença entre elas é quando as permissões são solicitadas ou concedidas.

"declarativeNetRequest"
Aciona um aviso de permissão no momento da instalação, mas oferece acesso implícito às regras allow, allowAllRequests e block. Use essa opção sempre que possível para evitar a necessidade de solicitar acesso total aos hosts.
"declarativeNetRequestFeedback"
Ativa os recursos de depuração para extensões descompactadas, especificamente getMatchedRules() e onRuleMatchedDebug.
"declarativeNetRequestWithHostAccess"
Um aviso de permissão não é mostrado no momento da instalação, mas é necessário solicitar permissões do host antes de realizar qualquer ação em um host. Isso é adequado quando você quer usar regras declarativas de solicitação de rede em uma extensão que já tem permissões de host sem gerar avisos adicionais.

Disponibilidade

Chrome 84 e versões mais recentes

Manifesto

Além das permissões descritas anteriormente, alguns tipos de conjuntos de regras, especificamente os 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, conforme mostrado abaixo. O nome "Ruleset" não aparece no JSON do manifesto, porque é apenas uma matriz. As regras de políticas estáticas são explicadas mais adiante 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/*"
  ],
  ...
}

Regras e conjuntos de regras

Para usar essa API, especifique um ou mais conjuntos de regras. Uma regra de conjunto contém uma matriz de regras. Uma única regra faz uma das seguintes ações:

  • Bloquear uma solicitação de rede.
  • Faça upgrade do esquema (http para https).
  • Impedir que uma solicitação seja bloqueada, negando as regras bloqueadas correspondentes.
  • Redirecionar uma solicitação de rede.
  • Modifique os cabeçalhos de solicitação ou resposta.

Há três tipos de conjuntos de regras, gerenciados de maneiras um pouco diferentes.

Dinâmico
Permanecer em todas as sessões do navegador e upgrades de extensão e são gerenciados usando JavaScript enquanto uma extensão está em uso.
Sessão
É limpa quando o navegador é fechado 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
Embalado, instalado e atualizado 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.

Regras dinâmicas e no escopo da sessão

Os conjuntos de regras de sessão e dinâmicos são gerenciados usando JavaScript enquanto uma extensão está em uso.

  • As regras dinâmicas persistem nas sessões do navegador e nos upgrades de extensão.
  • As regras de sessão são apagadas quando o navegador é fechado e quando uma nova versão da extensão é instalada.

Há apenas um de cada tipo de regra. Uma extensão pode adicionar ou remover regras dinamicamente chamando updateDynamicRules() e updateSessionRules(), desde que os limites de regras não sejam excedidos. Para informações sobre os limites de regras, consulte Limites de regras. Confira um exemplo em exemplos de código.

Conjuntos de regras estáticas

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 a regra contida no arquivo e se a regra está ativada ou desativada. Os dois últimos são importantes quando você ativa ou desativa uma regra de forma programática.

{
  ...
  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    },
    ...
    ]
  }
  ...
}

Para testar arquivos de regras, carregue a extensão descompactada. Erros e avisos sobre regras estáticas inválidas são exibidos apenas para extensões descompactadas. As regras estáticas inválidas em extensões compactadas são ignoradas.

Análise rápida

As mudanças nas regras estáticas podem se qualificar para uma análise rápida. Consulte a revisão acelerada para mudanças qualificadas.

Ativar e desativar regras estáticas e conjuntos de regras

As regras estáticas individuais e os conjuntos de regras estáticas completos podem ser ativados ou desativados no momento da execução.

O conjunto de regras estáticas e conjuntos de regras ativado é mantido em todas as sessões do navegador. Nenhuma delas é mantida nas atualizações de extensão. Ou seja, somente as regras que você deixou nos arquivos de regras estão disponíveis após uma atualização.

Por motivos de desempenho, há também 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 os 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 para ativar ou desativar. Os IDs são definidos usando a chave "id" do dicionário Ruleset. Há um limite máximo de 5.000 regras estáticas desativadas.

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 para ativar ou desativar. Os IDs são definidos usando a chave "id" do dicionário Ruleset.

Regras de build

Independentemente do tipo, uma regra começa com quatro campos, conforme mostrado abaixo. Enquanto as chaves "id" e "priority" usam um número, as chaves "action" e "condition" podem fornecer 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 uma substring.

{
  "id" : 1,
  "priority": 1,
  "action" : { "type" : "block" },
  "condition" : {
    "urlFilter" : "abc",
    "initiatorDomains" : ["foo.com"],
    "resourceTypes" : ["script"]
  }
}

Correspondência de URL

A solicitação de rede declarativa permite corresponder URLs a uma sintaxe de correspondência de padrão ou a expressões regulares.

Sintaxe do filtro de URL

A chave "condition" de uma regra permite que uma chave "urlFilter" aja em URLs de um domínio especificado. Você cria padrões usando tokens de correspondência de padrões. Confira alguns exemplos.

urlFilter Correspondências Não corresponde
"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://a.example.company		 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

Expressões regulares

As condições também podem usar expressões regulares. Consulte a chave "regexFilter". Para saber mais sobre os limites que se aplicam a essas condições, consulte Regras que usam expressões regulares.

Escrever boas condições de URL

Tenha cuidado ao escrever regras para que elas sempre correspondam a um domínio inteiro. Caso contrário, sua regra pode corresponder a situações inesperadas. Por exemplo, ao usar a sintaxe de correspondência de padrões:

  • google.com corresponde incorretamente a https://example.com/?param=google.com
  • ||google.com corresponde incorretamente a https://google.company
  • https://www.google.com corresponde incorretamente a https://example.com/?param=https://www.google.com

Considere usar:

  • ||google.com/, que corresponde a todos os caminhos e subdomínios.
  • |https://www.google.com/, que corresponde a todos os caminhos e não a subdomínios.

Da mesma forma, use os caracteres ^ e / para ancorar uma expressão regular. Por exemplo, ^https:\/\/www\.google\.com\/ corresponde a qualquer caminho em https://www.google.com.

Avaliação de regras

As regras de DNR são aplicadas pelo navegador em vários estágios do ciclo de vida da solicitação de rede.

Antes da solicitação

Antes que uma solicitação seja feita, uma extensão pode bloquear ou redirecionar (incluindo o upgrade do esquema de HTTP para HTTPS) com uma regra correspondente.

Para cada extensão, o navegador determina uma lista de regras correspondentes. As regras com uma ação modifyHeaders não são incluídas aqui, porque serão processadas mais tarde. Além disso, as regras com uma condição responseHeaders serão consideradas mais tarde (quando os cabeçalhos de resposta estiverem disponíveis) e não serão incluídas.

Em seguida, para cada extensão, o Chrome escolhe no máximo um candidato por solicitação. O Chrome encontra uma regra correspondente, ordenando todas as regras correspondentes por prioridade. As regras com a mesma prioridade são ordenadas por ação (allow ou allowAllRequests > block > upgradeScheme > redirect).

Se o candidato for uma regra allow ou allowAllRequests, ou se o frame em que a solicitação está sendo feita tiver correspondido anteriormente a uma regra allowAllRequests de prioridade mais alta ou igual a essa extensão, a solicitação será "permitida" e a extensão não terá nenhum efeito sobre ela.

Se mais de uma extensão quiser bloquear ou redirecionar essa solicitação, uma única ação será escolhida. Para isso, o Chrome classifica as regras na ordem block > redirect ou upgradeScheme > allow ou allowAllRequests. Se duas regras forem do mesmo tipo, o Chrome vai escolher a regra da extensão instalada mais recentemente.

Antes de enviar os cabeçalhos da solicitação

Antes que o Chrome envie cabeçalhos de solicitação para o servidor, eles são atualizados com base nas regras de correspondência modifyHeaders.

Em uma única extensão, o Chrome cria a lista de modificações a serem realizadas encontrando todas as regras modifyHeaders correspondentes. Assim como antes, apenas as regras com prioridade mais alta do que qualquer regra allow ou allowAllRequests correspondente são incluídas.

Essas regras são aplicadas pelo Chrome em uma ordem, de modo que as regras de uma extensão instalada mais recentemente sejam sempre avaliadas antes das regras de uma extensão mais antiga. Além disso, as regras de uma extensão com prioridade mais alta são sempre aplicadas antes das regras de prioridade mais baixa da mesma extensão. Isso vale para todas as extensões:

  • 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 definir e remover não são permitidas.
  • Se uma regra definir um cabeçalho, apenas regras de prioridade mais baixa da mesma extensão poderão ser anexadas a esse cabeçalho. Nenhuma outra modificação é permitida.
  • Se uma regra remover um cabeçalho, as regras de prioridade mais baixa não poderão modificar o cabeçalho.

Quando uma resposta for recebida

Depois que os cabeçalhos de resposta são recebidos, o Chrome avalia as regras com uma condição responseHeaders.

Depois de classificar essas regras por action e priority e excluir as regras que se tornaram redundantes por uma regra allow ou allowAllRequests correspondente (isso acontece de forma idêntica às etapas em "Antes da solicitação"), o Chrome pode bloquear ou redirecionar a solicitação em nome de uma extensão.

Se uma solicitação chegou a essa etapa, ela já foi enviada ao servidor e o servidor recebeu dados, como o corpo da solicitação. Uma regra de bloqueio ou redirecionamento com uma condição de cabeçalhos de resposta ainda será executada, mas não poderá bloquear ou redirecionar a solicitação.

No caso de uma regra de bloqueio, isso é processado pela página que fez a solicitação, que recebe uma resposta bloqueada, e o Chrome encerra a solicitação mais cedo. No caso de uma regra de redirecionamento, o Chrome faz uma nova solicitação para o URL redirecionado. Considere se esses comportamentos atendem às expectativas de privacidade da sua extensão.

Se a solicitação não for bloqueada ou redirecionada, o Chrome vai aplicar as regras modifyHeaders. A aplicação de modificações nos cabeçalhos de resposta funciona da mesma forma que a descrita em "Antes do envio dos cabeçalhos de solicitação". Aplicar modificações aos cabeçalhos de solicitação não faz nada, porque a solicitação já foi feita.

Regras seguras

As regras seguras são definidas como regras com uma ação de block, allow, allowAllRequests ou upgradeScheme. Essas regras estão sujeitas a um aumento da cota de regras dinâmicas.

Limites das regras

Há uma sobrecarga de desempenho ao carregar e avaliar regras no navegador. Portanto, 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 especificadas em arquivos de regras declarados no arquivo de manifesto. Uma extensão pode especificar até 100 regras estáticas como parte da chave de manifesto "rule_resources", mas apenas 50 dessas regras podem ser ativadas por vez. O último é chamado de MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. Coletivamente, esses conjuntos de regras têm garantia de pelo menos 30.000 regras. Isso é chamado de GUARANTEED_MINIMUM_STATIC_RULES.

O número de regras disponíveis depois disso depende de quantas regras são ativadas por todas as extensões instaladas no navegador de um usuário. Para encontrar esse número no momento da execução, chame getAvailableStaticRuleCount(). Confira um exemplo em exemplos de código.

Regras de sessão

Uma extensão pode ter até 5.000 regras de sessão. Ele é exposto como o 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 o 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 safe, exibidas como MAX_NUMBER_OF_DYNAMIC_RULES. Todas as regras não seguras adicionadas dentro do limite de 5.000 também contam para esse limite.

Antes do Chrome 120, havia um limite de 5.000 regras dinâmicas e de sessão combinadas.

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 é chamado de MAX_NUMBER_OF_REGEX_RULES.

Além disso, cada regra precisa ter menos de 2 KB após a compilação. Isso está relacionado à complexidade da regra. Se você tentar carregar uma regra que exceda esse limite, vai aparecer 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

Uma declarativeNetRequest só se aplica a solicitações que alcançam a pilha de rede. Isso inclui respostas do cache HTTP, mas não respostas que passam pelo gerenciador onfetch de um worker de serviço. A declarativeNetRequest não afeta as respostas geradas pelo worker de serviço ou recuperadas de CacheStorage, mas afeta as chamadas para fetch() feitas em um worker de serviço.

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 é acessível pela Web. Isso aciona um erro. Isso é válido mesmo que o recurso acessível da Web especificado seja de propriedade da extensão de redirecionamento. Para declarar recursos para declarativeNetRequest, use a matriz "web_accessible_resources" do manifesto.

Modificação de cabeçalho

A operação de adição tem suporte apenas para os seguintes cabeçalhos: accept, accept-encoding, accept-language, access-control-request-headers, cache-control, connection, content-language, cookie, forwarded, if-match, if-none-match, keep-alive, range, te, trailer, transfer-encoding, upgrade, user-agent, via, want-digest, x-forwarded-for.

Exemplos

Exemplos de código

Atualizar regras dinâmicas

O exemplo a seguir 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áticas

O exemplo a seguir mostra como ativar e desativar conjuntos de regras considerando o número disponível e o número máximo de conjuntos de regras estáticos ativados. Você faria isso quando o número de regras estáticas necessárias exceder o número permitido. Para que isso funcione, alguns conjuntos de regras precisam ser instalados com alguns deles 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á-las, abra as regras de priorização em uma janela separada.

A chave "priority"

Esses exemplos exigem a permissão do host para *://*.example.com/*.

Para calcular a prioridade de um URL específico, observe a chave "priority" (definida pelo desenvolvedor), a chave "action" e a chave "urlFilter". Esses exemplos se referem ao arquivo de regra de exemplo mostrado abaixo.

Navegação para https://google.com
Duas regras abrangem este URL: as regras com os IDs 1 e 4. A regra com o ID 1 é aplicada porque as ações "block" têm prioridade maior do que as ações "redirect". As regras restantes não se aplicam porque são para URLs mais longos.
Navegação para https://google.com/1234
Devido ao URL mais longo, a regra com o ID 2 agora corresponde às regras com os IDs 1 e 4. A regra com o ID 2 é aplicada porque "allow" tem prioridade mais alta que "block" e "redirect".
Navegação para https://google.com/12345
As quatro regras correspondem a esse URL. A regra com o ID 3 é aplicada 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 exige a permissão do 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 como 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 na Web.

{
  "id": 1,
  "priority": 1,
  "action": { "type": "redirect", "redirect": { "extensionPath": "/a.jpg" } },
  "condition": {
    "urlFilter": "||https://www.example.com/",
    "resourceTypes": ["main_frame"]
  }
}

O exemplo a seguir usa a chave "transform" para redirecionar para um subdomínio de example.com. Ele usa um âncora de nome de domínio ("||") para interceptar solicitações com qualquer esquema de example.com. A chave "scheme" em "transform" especifica que os redirecionamentos para o subdomínio sempre vão usar "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 períodos são escapados 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 todos os subframes.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "modifyHeaders",
    "requestHeaders": [{ "header": "cookie", "operation": "remove" }]
  },
  "condition": { "resourceTypes": ["main_frame", "sub_frame"] }
}

Tipos

DomainType

Isso descreve se a solicitação é própria ou de terceiros para o frame em que ela foi gerada. Uma solicitação é considerada própria se tiver o mesmo domínio (eTLD+1) do frame em que foi originada.

Enumeração

"firstParty"
A solicitação de rede é de primeira parte para o frame em que ela foi originada.

"thirdParty"
A solicitação de rede é de terceiros em relação ao frame em que foi originada.

ExtensionActionOptions

Chrome 88 e versões mais recentes

Propriedades

  • displayActionCountAsBadgeText

    booleano opcional

    Define se a contagem de ações de uma página vai ser mostrada automaticamente como o texto do selo da extensão. Essa preferência é mantida entre as sessões.

  • tabUpdate

    TabActionCountUpdate opcional

    Chrome 89 e versões mais recentes

    Detalhes de como ajustar a contagem de ações da guia.

GetDisabledRuleIdsOptions

Chrome 111 e versões mais recentes

Propriedades

  • rulesetId

    string

    O ID correspondente a um Ruleset estático.

GetRulesFilter

Chrome 111 e versões mais recentes

Propriedades

  • ruleIds

    number[] opcional

    Se especificado, apenas as regras com IDs correspondentes serão incluídas.

HeaderInfo

Chrome 128+

Propriedades

  • excludedValues

    string[] opcional

    Se especificado, essa condição não será atendida se o cabeçalho existir, mas o valor dele tiver pelo menos um elemento nessa lista. Ele usa a mesma sintaxe de padrão de correspondência de values.

  • cabeçalho

    string

    O nome do cabeçalho. Essa condição corresponde ao nome somente se values e excludedValues não forem especificados.

  • values

    string[] opcional

    Se especificado, essa condição corresponde se o valor do cabeçalho corresponder a pelo menos um padrão nesta lista. Ele oferece suporte à correspondência de valor de cabeçalho sem distinção entre maiúsculas e minúsculas, além dos seguintes elementos:

    '*' : corresponde a qualquer número de caracteres.

    '?' : corresponde a zero ou um caractere.

    "*" e "?" podem ser escapados com uma barra invertida, por exemplo, "\*" e "\\?"

HeaderOperation

Chrome 86 e versões mais recentes

Esta seção descreve as operações possíveis para uma regra "modifyHeaders".

Enumeração

"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 todos os cabeçalhos com o mesmo nome.

"remove"
Remove todas as entradas do cabeçalho especificado.

IsRegexSupportedResult

Chrome 87 e versões mais recentes

Propriedades

  • isSupported

    booleano

  • reason

    UnsupportedRegexReason opcional

    Especifica o motivo pelo qual a expressão regular não é compatível. Só é fornecido se isSupported for falso.

MatchedRule

Propriedades

  • ruleId

    number

    O ID de uma regra correspondente.

  • rulesetId

    string

    É o ID do Ruleset a que esta regra pertence. Para uma regra originada do conjunto de regras dinâmicas, ela será igual a DYNAMIC_RULESET_ID.

MatchedRuleInfo

Propriedades

  • regra

    MatchedRule

  • tabId

    number

    O tabId da guia de origem da solicitação, se ela ainda estiver ativa. Caso contrário, -1.

  • timeStamp

    number

    O horário em que a regra foi atendida. Os carimbos de data/hora correspondem à convenção do JavaScript para horários, ou seja, o número de milissegundos desde a época.

MatchedRuleInfoDebug

Propriedades

MatchedRulesFilter

Propriedades

  • minTimeStamp

    número opcional

    Se especificado, corresponde apenas às regras após o carimbo de data/hora fornecido.

  • tabId

    número opcional

    Se especificado, corresponde apenas às regras da guia especificada. Corresponde a regras não associadas a nenhuma guia ativa se definido como -1.

ModifyHeaderInfo

Chrome 86 e versões mais recentes

Propriedades

  • cabeçalho

    string

    O nome do cabeçalho a ser modificado.

  • operação

    HeaderOperation

    A operação a ser realizada em um cabeçalho.

  • valor

    string opcional

    O novo valor do cabeçalho. Precisa ser especificado para operações append e set.

QueryKeyValue

Propriedades

  • chave

    string

  • replaceOnly

    booleano opcional

    Chrome 94 e versões mais recentes

    Se verdadeiro, a chave de consulta será substituída apenas 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 da consulta a ser adicionada ou substituída.

  • removeParams

    string[] opcional

    A lista de chaves de consulta a serem removidas.

Redirect

Propriedades

  • extensionPath

    string opcional

    Caminho relativo ao diretório da extensão. Precisa começar com "/".

  • regexSubstitution

    string opcional

    Padrão de substituição para regras que especificam um regexFilter. A primeira correspondência de regexFilter no URL será substituída por esse padrão. Em regexSubstitution, dígitos de escape com barra invertida (\1 a \9) podem ser usados para inserir os grupos de captura correspondentes. \0 se refere a todo o texto correspondente.

  • transform

    URLTransform opcional

    Transformações de URL a serem realizadas.

  • url

    string opcional

    O URL de redirecionamento. Não são permitidos redirecionamentos para URLs de JavaScript.

RegexOptions

Chrome 87 e versões mais recentes

Propriedades

  • isCaseSensitive

    booleano opcional

    Se o regex especificado diferencia maiúsculas de minúsculas. O padrão é verdadeiro.

  • Regex

    string

    A expressão regular a ser verificada.

  • requireCapturing

    booleano opcional

    Se o regex especificado precisa ser capturado. A captura é necessária apenas para regras de redirecionamento que especificam uma ação regexSubstition. O valor padrão é falso.

RequestDetails

Propriedades

  • documentId

    string opcional

    Chrome 106 e versões mais recentes

    O identificador exclusivo do documento do frame, se a solicitação for para um frame.

  • documentLifecycle

    DocumentLifecycle opcional

    Chrome 106 e versões mais recentes

    O ciclo de vida do documento do frame, se a 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 é main_frame ou sub_frame), frameId vai indicar o ID desse frame, não o ID do frame externo. Os IDs de frame são exclusivos em uma guia.

  • frameType

    FrameType opcional

    Chrome 106 e versões mais recentes

    O tipo de frame, se a 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 for uma origem opaca, a string "null" será usada.

  • method

    string

    Método HTTP padrão.

  • parentDocumentId

    string opcional

    Chrome 106 e versões mais recentes

    O identificador exclusivo do documento pai do frame, se esta solicitação for para um frame e tiver um pai.

  • parentFrameId

    number

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

  • requestId

    string

    O ID da solicitação. Os IDs de solicitação são exclusivos em uma sessão do navegador.

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

  • O tipo de recurso da solicitação.

  • url

    string

    O URL da solicitação.

RequestMethod

Chrome 91 e versões mais recentes

Isso descreve o método de solicitação HTTP de uma solicitação de rede.

Enumeração

"connect"

"delete"

"get"

"head"

"options"

"patch"

"post"

"put"

"other"

ResourceType

Ele descreve o tipo de recurso da solicitação de rede.

Enumeração

"main_frame"

"sub_frame"

"stylesheet"

"script"

"image"

"font"

"object"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"webtransport"

"webbundle"

"other"

Rule

Propriedades

  • ação

    RuleAction

    A ação a ser realizada se essa regra for atendida.

  • transição

    RuleCondition

    A condição em que essa regra é acionada.

  • id

    number

    Um ID que identifica exclusivamente uma regra. Obrigatório e precisa ser >= 1.

  • prioridade

    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álido apenas para regras de redirecionamento.

  • requestHeaders

    ModifyHeaderInfo[] opcional

    Chrome 86 e versões mais recentes

    Os cabeçalhos da solicitação que serão modificados. Válido apenas se RuleActionType for "modifyHeaders".

  • responseHeaders

    ModifyHeaderInfo[] opcional

    Chrome 86 e versões mais recentes

    Os cabeçalhos de resposta a serem modificados para a solicitação. Só é válido se RuleActionType for "modifyHeaders".

  • O tipo de ação a ser realizada.

RuleActionType

Descreve o tipo de ação a ser realizada se uma determinada RuleCondition corresponder.

Enumeração

"block"
Bloqueia a solicitação de rede.

"redirect"
Redireciona a solicitação de rede.

"allow"
Permite a solicitação de rede. A solicitação não será interceptada se houver uma regra de permissão correspondente.

"upgradeScheme"
Atualiza o esquema do URL da solicitação de rede para https se a solicitação for http ou ftp.

"modifyHeaders"
Modifica 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 ele for omitido, todas as solicitações serão aceitas.

  • domínios

    string[] opcional

    Descontinuado no Chrome 101

    Use initiatorDomains.

    A regra só vai corresponder a solicitações de rede originadas da lista de domains.

  • excludedDomains

    string[] opcional

    Descontinuado no Chrome 101

    Use excludedInitiatorDomains.

    A regra não vai corresponder às solicitações de rede originadas da lista de excludedDomains.

  • excludedInitiatorDomains

    string[] opcional

    Chrome 101+

    A regra não vai corresponder às solicitações de rede originadas da lista de excludedInitiatorDomains. Se a lista estiver vazia ou omitida, nenhum domínio será excluído. Isso tem precedência sobre initiatorDomains.

    Observações:

    • Subdomínios como "a.example.com" também são permitidos.
    • As entradas precisam consistir apenas de caracteres ASCII.
    • Use a codificação punycode para domínios internacionalizados.
    • Essa correspondência é feita com o iniciador da solicitação, e não com o URL da solicitação.
    • Os subdomínios dos domínios listados também são excluídos.
  • excludedRequestDomains

    string[] opcional

    Chrome 101+

    A regra não vai 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. Isso tem precedência sobre requestDomains.

    Observações:

    • Subdomínios como "a.example.com" também são permitidos.
    • As entradas precisam consistir apenas de 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 e versões mais recentes

    Lista de métodos de solicitação que não correspondem à regra. Somente um entre requestMethods e excludedRequestMethods deve ser especificado. Se nenhum deles for especificado, todos os métodos de solicitação serão correspondentes.

  • excludedResourceTypes

    ResourceType[] opcional

    Lista de tipos de recursos com os quais a regra não vai corresponder. Somente um entre resourceTypes e excludedResourceTypes deve ser especificado. Se nenhum deles for especificado, todos os tipos de recurso, exceto "main_frame", serão bloqueados.

  • excludedResponseHeaders

    HeaderInfo[] opcional

    Chrome 128+

    A regra não corresponde se a solicitação corresponder a qualquer condição de cabeçalho de resposta nesta lista (se especificada). Se excludedResponseHeaders e responseHeaders forem especificados, a propriedade excludedResponseHeaders terá precedência.

  • excludedTabIds

    number[] opcional

    Chrome 92 e versões mais recentes

    Lista de tabs.Tab.id que a regra não pode corresponder. Um ID de tabs.TAB_ID_NONE exclui solicitações que não são originadas de uma guia. Somente compatível com regras no escopo da sessão.

  • initiatorDomains

    string[] opcional

    Chrome 101+

    A regra só vai corresponder a solicitações de rede originadas da lista de initiatorDomains. Se a lista for omitida, a regra será aplicada a 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 consistir apenas de caracteres ASCII.
    • Use a codificação punycode para domínios internacionalizados.
    • Essa correspondência é feita com o iniciador da solicitação, e não com o URL da solicitação.
    • Os subdomínios dos domínios listados também são correspondentes.
  • isUrlFilterCaseSensitive

    booleano opcional

    Se urlFilter ou regexFilter (qualquer um dos dois) diferencia maiúsculas de minúsculas. O padrão é false

  • regexFilter

    string opcional

    Expressão regular para corresponder ao URL da solicitação de rede. Isso segue a sintaxe RE2.

    Observação: só é possível especificar urlFilter ou regexFilter.

    Observação: o regexFilter precisa ser composto apenas por caracteres ASCII. Isso é comparado a um URL em que o host é codificado no formato punycode (no caso de domínios internacionalizados) e qualquer outro caractere não ASCII é codificado em URL em UTF-8.

  • requestDomains

    string[] opcional

    Chrome 101+

    A regra só vai corresponder a solicitações de rede quando o domínio corresponder a um da lista de requestDomains. Se a lista for omitida, a regra será aplicada a 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 consistir apenas de caracteres ASCII.
    • Use a codificação punycode para domínios internacionalizados.
    • Os subdomínios dos domínios listados também são correspondidos.
  • requestMethods

    RequestMethod[] opcional

    Chrome 91 e versões mais recentes

    Lista de métodos de solicitação HTTP que a regra pode corresponder. Uma lista vazia não é permitida.

    Observação: especificar uma condição de regra requestMethods também exclui solicitações que não são HTTP, enquanto especificar excludedRequestMethods não exclui.

  • resourceTypes

    ResourceType[] opcional

    Lista de tipos de recursos que 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 recurso sub_frame e main_frame.

  • responseHeaders

    HeaderInfo[] opcional

    Chrome 128+

    A regra corresponde se a solicitação corresponder a qualquer condição de cabeçalho de resposta nesta lista (se especificada).

  • tabIds

    number[] opcional

    Chrome 92 e versões mais recentes

    Lista de tabs.Tab.id que a regra precisa corresponder. Um ID de tabs.TAB_ID_NONE corresponde a solicitações que não são originadas de uma guia. Uma lista vazia não é permitida. Somente compatível com regras no escopo da sessão.

  • urlFilter

    string opcional

    O padrão que é comparado 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 qualquer coisa, exceto uma letra, um dígito ou um dos seguintes: _, -, . ou %. Ele também corresponde ao final do URL.

    Portanto, urlFilter é composto pelas seguintes partes: (âncora opcional à esquerda/nome de domínio) + padrão + (âncora opcional à direita).

    Se omitido, todos os URLs serão correspondidos. Uma string vazia não é permitida.

    Um padrão que começa com ||* não é permitido. Use *.

    Observação: só é possível especificar urlFilter ou regexFilter.

    Observação: o urlFilter precisa ser composto apenas por caracteres ASCII. Isso é comparado a um URL em que o host é codificado no formato punycode (no caso de domínios internacionalizados) e qualquer outro caractere não ASCII é codificado em URL em UTF-8. Por exemplo, quando o URL da solicitação for http://abc.рф?q=ф, o urlFilter será comparado com o URL http://abc.xn--p1ai/?q=%D1%84.

Ruleset

Propriedades

  • ativado

    booleano

    Indica se a regra está ativada por padrão.

  • id

    string

    Uma string não vazia que identifica exclusivamente a regra. Os IDs que começam com "_" são reservados para uso interno.

  • caminho

    string

    O caminho da regra JSON em relação ao diretório de extensão.

RulesMatchedDetails

Propriedades

  • rulesMatchedInfo

    MatchedRuleInfo[]

    Regras que correspondem ao filtro fornecido.

TabActionCountUpdate

Chrome 89 e versões mais recentes

Propriedades

  • increment

    number

    O valor pelo qual a contagem de ações da guia vai ser incrementada. Valores negativos diminuem a contagem.

  • tabId

    number

    A guia para atualizar a contagem de ações.

TestMatchOutcomeResult

Chrome 103 e versões mais recentes

Propriedades

  • matchedRules

    MatchedRule[]

    As regras (se houver) que correspondem à solicitação hipotética.

TestMatchRequestDetails

Chrome 103 e versões mais recentes

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 não HTTP.

  • responseHeaders

    objeto opcional

    Chrome 129 e versões mais recentes

    Os cabeçalhos fornecidos por uma resposta hipotética se a solicitação não for bloqueada ou redirecionada antes de ser enviada. Representado como um objeto que mapeia um nome de cabeçalho para uma lista de valores de string. Se não for especificado, a resposta hipotética vai retornar cabeçalhos de resposta vazios, que podem corresponder a regras que correspondem à não existência de cabeçalhos. Por exemplo, {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}

  • tabId

    número opcional

    O ID da guia em que a solicitação hipotética ocorre. Não precisa corresponder a um ID de guia real. O padrão é -1, o que significa que a solicitação não está relacionada a uma guia.

  • O tipo de recurso da solicitação hipotética.

  • url

    string

    O URL da solicitação hipotética.

UnsupportedRegexReason

Chrome 87 e versões mais recentes

Descreve o motivo pelo qual uma determinada expressão regular não é aceita.

Enumeração

"syntaxError"
A expressão regular está sintaticamente incorreta ou usa recursos não disponíveis na sintaxe RE2.

"memoryLimitExceeded"
A expressão regular excede o limite de memória.

UpdateRuleOptions

Chrome 87 e versões mais recentes

Propriedades

  • addRules

    Regra[] opcional

    Regras a serem adicionadas.

  • removeRuleIds

    number[] opcional

    IDs das regras a serem removidas. Os IDs inválidos serão ignorados.

UpdateRulesetOptions

Chrome 87 e versões mais recentes

Propriedades

  • disableRulesetIds

    string[] opcional

    O conjunto de IDs correspondentes a um Ruleset estático que precisa ser desativado.

  • enableRulesetIds

    string[] opcional

    O conjunto de IDs correspondentes a um Ruleset estático que precisa ser ativado.

UpdateStaticRulesOptions

Chrome 111 e versões mais recentes

Propriedades

  • disableRuleIds

    number[] opcional

    Conjunto de IDs correspondentes às regras no Ruleset a serem desativadas.

  • enableRuleIds

    number[] opcional

    Conjunto de IDs correspondentes às regras no Ruleset para ativar.

  • rulesetId

    string

    O ID correspondente a um Ruleset estático.

URLTransform

Propriedades

  • fragment

    string opcional

    O novo fragmento da solicitação. Precisa estar vazio, caso em que o fragmento atual é limpo, ou precisa começar com '#'.

  • host

    string opcional

    O novo host da solicitação.

  • senha

    string opcional

    A nova senha para a solicitação.

  • caminho

    string opcional

    O novo caminho da solicitação. Se estiver vazio, o caminho atual será apagado.

  • porta

    string opcional

    A nova porta da solicitação. Se estiver vazio, a porta atual será limpa.

  • consulta

    string opcional

    A nova consulta para a solicitação. Precisa estar vazio, caso em que a consulta atual é apagada, ou começar com "?".

  • queryTransform

    QueryTransform opcional

    Adicione, remova ou substitua pares de chave-valor da consulta.

  • planejar

    string opcional

    O novo esquema da 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 da solicitação.

Propriedades

DYNAMIC_RULESET_ID

ID do conjunto de regras para as 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 falharão imediatamente e definirão 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

Chrome 89 e versões mais recentes

O número mínimo de regras estáticas garantidas a uma extensão em todas as regras estáticas ativadas. Todas as regras acima desse limite serão contabilizadas no limite global de regras estáticas.

Valor

30000

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

30000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94 e versões mais recentes

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 as especificadas no arquivo de recursos de regras.

Valor

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120+

O número máximo de regras com escopo de 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 de manifesto "rule_resources".

Valor

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120+

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

Chrome 120+

O número máximo de regras de escopo de sessão "não seguras" que uma extensão pode adicionar.

Valor

5.000

SESSION_RULESET_ID

Chrome 90 e versões mais recentes

ID do conjunto de regras para as regras no escopo da sessão adicionadas pela extensão.

Valor

"_session"

Métodos

getAvailableStaticRuleCount()

Promessa Chrome 89+ 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
)

Retorna o número de regras estáticas que uma extensão pode ativar antes que o limite global de regras estáticas seja atingido.

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (count: number) => void

    • contagem

      number

Retorna

  • Promise<number>

    Chrome 91 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

getDisabledRuleIds()

Promessa Chrome 111+ 
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
  callback?: function,
)

Retorna a lista de regras estáticas no Ruleset fornecido que estão desativadas no momento.

Parâmetros

  • Especifica o conjunto de regras a ser consultado.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      number[]

Retorna

  • Promise<number[]>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

getDynamicRules()

Promessa 
chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
  callback?: function,
)

Retorna o conjunto atual de regras dinâmicas para a extensão. Os autores da chamada podem filtrar a lista de regras buscadas especificando um filter.

Parâmetros

  • filtro

    GetRulesFilter opcional

    Chrome 111 e versões mais recentes

    Um objeto para filtrar a lista de regras buscadas.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (rules: Rule[]) => void

Retorna

  • Promise<Rule[]>

    Chrome 91 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

getEnabledRulesets()

Promessa 
chrome.declarativeNetRequest.getEnabledRulesets(
  callback?: function,
)

Retorna os IDs do conjunto atual de conjuntos de regras estáticas ativados.

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (rulesetIds: string[]) => void

    • rulesetIds

      string[]

Retorna

  • Promise<string[]>

    Chrome 91 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

getMatchedRules()

Promessa 
chrome.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
  callback?: function,
)

Retorna todas as regras correspondentes à extensão. Os autores da chamada podem filtrar a lista de regras correspondentes especificando um filter. Esse método está disponível apenas para extensões com a permissão "declarativeNetRequestFeedback" ou que tenham a permissão "activeTab" concedida para o tabId especificado em filter. Observação: as regras não associadas a um documento ativo que foram correspondidas há mais de cinco minutos não serão retornadas.

Parâmetros

Retorna

  • Chrome 91 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

getSessionRules()

Promessa Chrome 90+ 
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 filtrar a lista de regras buscadas especificando um filter.

Parâmetros

  • filtro

    GetRulesFilter opcional

    Chrome 111 e versões mais recentes

    Um objeto para filtrar a lista de regras buscadas.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (rules: Rule[]) => void

Retorna

  • Promise<Rule[]>

    Chrome 91 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

isRegexSupported()

Promessa Chrome 87+ 
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
  callback?: function,
)

Verifica se a expressão regular especificada será aceita como uma condição de regra regexFilter.

Parâmetros

Retorna

  • Chrome 91 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

setExtensionActionOptions()

Promessa Chrome 88+ 
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
  callback?: function,
)

Configura se a contagem de ações para guias deve ser mostrada como o texto do selo da ação da extensão e oferece uma maneira de incrementar essa contagem.

Parâmetros

  • callback

    função opcional

    Chrome 89 e versões mais recentes

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    Chrome 91 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

testMatchOutcome()

Promessa Chrome 103+ 
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
)

Verifica se alguma das regras declarativeNetRequest da extensão corresponde a uma solicitação hipotética. Observação: disponível apenas para extensões descompactadas, já que é destinado apenas ao desenvolvimento de extensões.

Parâmetros

Retorna

  • As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

updateDynamicRules()

Promessa 
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 depois as regras fornecidas em options.addRules são adicionadas. Observações:

  • Essa atualização acontece 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 atualizações da extensão.
  • 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_RULES é o número máximo de regras dinâmicas que uma extensão pode adicionar. O número de regras não seguras não pode exceder MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES.

Parâmetros

  • Chrome 87 e versões mais recentes
  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    Chrome 91 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

updateEnabledRulesets()

Promessa 
chrome.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
  callback?: function,
)

Atualiza o conjunto de conjuntos de regras estáticas ativados para a extensão. As regras com IDs listados em options.disableRulesetIds são removidas primeiro, e depois as regras listadas em options.enableRulesetIds são adicionadas. O conjunto de conjuntos de regras estáticas ativadas é mantido em todas as sessões, mas não nas atualizações de extensão. Ou seja, a chave de manifesto rule_resources vai determinar o conjunto de regras estáticas ativadas em cada atualização de extensão.

Parâmetros

  • Chrome 87 e versões mais recentes
  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    Chrome 91 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

updateSessionRules()

Promessa Chrome 90+ 
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 depois as regras fornecidas em options.addRules são adicionadas. Observações:

  • Essa atualização acontece 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 em todas as sessões e são armazenadas na memória.
  • MAX_NUMBER_OF_SESSION_RULES é o número máximo de regras de sessão que uma extensão pode adicionar.

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    Chrome 91 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

updateStaticRules()

Promessa Chrome 111+ 
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
  callback?: function,
)

Desativa e ativa regras estáticas individuais em um Ruleset. As mudanças nas regras de uma Ruleset desativada vão entrar em vigor na próxima vez que ela for ativada.

Parâmetros

Retorna

  • Promise<void>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

Eventos

onRuleMatchedDebug

chrome.declarativeNetRequest.onRuleMatchedDebug.addListener(
  callback: function,
)

É acionado quando uma regra é correspondida a uma solicitação. Disponível apenas para extensões descompactadas com a permissão "declarativeNetRequestFeedback", já que ela é destinada apenas para fins de depuração.

Parâmetros