browser.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 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 e block. Use essa opção sempre que possível para evitar a necessidade de solicitar acesso total aos hosts.

"declarativeNetRequestFeedback"

Ativa 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 você precisa solicitar permissões de host antes de realizar 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

Chrome 84+ browser.* desde o Chrome 148

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. Os conjuntos de regras estáticos são explicados 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. Um conjunto de regras contém uma matriz de regras. Uma única regra faz o seguinte:

• Bloquear uma solicitação de rede.
• Faça upgrade do esquema (http para https).
• Impedir que uma solicitação seja bloqueada ao negar qualquer regra de bloqueio correspondente.
• Redirecionar uma solicitação de rede.
• Modificar cabeçalhos de solicitação ou resposta.

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

Dinâmico

Persistem em sessões do navegador e upgrades de extensão e são gerenciados usando JavaScript enquanto uma extensão está em uso.

Sessão

Limpo 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

Empacotado, 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.

Conjuntos de regras dinâmicos 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.

• As regras dinâmicas persistem entre as sessões do navegador e as atualizações 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 conjunto de regras. Uma extensão pode adicionar ou remover regras dinamicamente chamando updateDynamicRules() e updateSessionRules(), desde que os limites de regras não sejam excedidos. Para mais 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 para a extensão usando as chaves "declarative_net_request" e "rule_resources", conforme descrito acima, além de 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. Os dois últimos são importantes quando você ativa ou desativa um conjunto de regras 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. Os erros e avisos sobre regras estáticas inválidas só são exibidos para extensões descompactadas. As regras estáticas inválidas em extensões compactadas são ignoradas.

Análise acelerada

As mudanças em conjuntos de regras estáticas podem se qualificar para uma revisão acelerada. Consulte revisão acelerada para mudanças qualificadas.

Ativar e desativar regras e conjuntos de regras estáticos

Tanto as regras estáticas individuais quanto os conjuntos de regras estáticas completos podem ser ativados ou desativados no ambiente de execução.

O conjunto de regras e conjuntos de regras estáticos ativados é mantido em todas as sessões do navegador. Nenhum deles é mantido após as atualizações da extensão, o que significa que apenas as regras que você escolheu deixar nos arquivos de regras estarã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 mais 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 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 conjuntos de regras 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 a seguir. 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 Declarative Net Request permite que você faça a correspondência de URLs com uma sintaxe de correspondência de padrões ou expressões regulares.

Sintaxe do filtro de URL

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

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

Ao escrever regras, sempre corresponda a um domínio inteiro. Caso contrário, a 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:

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

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 de uma solicitação ser feita, uma extensão pode bloqueá-la ou redirecioná-la (incluindo o upgrade do esquema de HTTP para HTTPS) com uma regra correspondente.

Para cada extensão, o navegador determina uma lista de regras de correspondência. As regras com uma ação modifyHeaders não estão incluídas aqui, porque serão processadas mais tarde. Além disso, as regras com uma condição responseHeaders serão consideradas posteriormente (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 maior ou igual dessa extensão, a solicitação será "permitida" e a extensão não terá efeito sobre ela.

Se mais de uma extensão quiser bloquear ou redirecionar essa solicitação, uma única ação será escolhida. O Chrome faz isso classificando 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.

Atenção: os fornecedores de navegadores concordaram em não padronizar a ordem em que as regras com a mesma ação e prioridade são executadas. Isso pode mudar entre execuções ou versões do navegador, mesmo quando distribuído entre vários tipos de conjunto de regras (como uma regra estática e uma regra de sessão). Quando a ordem é importante, sempre especifique uma prioridade de forma explícita.

Antes de os cabeçalhos da solicitação serem enviados

Antes de o Chrome enviar cabeçalhos da solicitação ao servidor, os cabeçalhos são atualizados com base nas regras modifyHeaders correspondentes.

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

Essas regras são aplicadas pelo Chrome em uma ordem em que as regras de uma extensão instalada mais recentemente são sempre avaliadas antes das regras de uma extensão mais antiga. Além disso, as regras de prioridade mais alta de uma extensão são sempre aplicadas antes das regras de prioridade mais baixa da mesma extensão. Em especial, mesmo entre extensões:

• Se uma regra adicionar ao final de um cabeçalho, as regras de prioridade mais baixa só poderão adicionar ao final desse cabeçalho. Não é permitido definir e remover operações.
• Se uma regra definir um cabeçalho, somente as 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 mais modificá-lo.

Depois que uma resposta é 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 devido a 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 esse estágio, ela já foi enviada ao servidor, que 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 de bloqueio, e o Chrome encerra a solicitação antecipadamente. 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 aos cabeçalhos de resposta funciona da mesma forma que a descrita em "Antes do envio dos cabeçalhos da solicitação". Aplicar modificações aos cabeçalhos da solicitação não faz nada, já que 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 uma cota maior de regras dinâmicas.

Limites das regras

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

Observação: antes do Chrome 120, as extensões eram limitadas a um total de 50 conjuntos de regras estáticas, e apenas 10 deles podiam ser ativados ao mesmo tempo. Use o campo de manifesto minimum_chrome_version para limitar quais versões do Chrome podem instalar sua extensão.

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

Observação: a partir do Chrome 128, se um usuário desativar uma extensão em chrome://extensions, as regras estáticas dela não vão mais ser contabilizadas no limite global de regras estáticas. Isso pode liberar a cota de regras estáticas para outras extensões, mas também significa que, quando a extensão for reativada, ela poderá ter menos regras estáticas disponíveis do que antes.

Regras de sessão

Uma extensão pode ter até 5.000 regras de sessão. Isso é 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. Isso é 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. As regras não seguras adicionadas dentro do limite de 5.000 também serão contabilizadas.

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 depois de compilada. Isso se correlaciona aproximadamente com a 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 chegam à pilha de rede. Isso inclui respostas do cache HTTP, mas pode não incluir respostas que passam pelo gerenciador onfetch de um service worker. A declarativeNetRequest não afeta as respostas geradas pelo service worker ou recuperadas de CacheStorage, mas afeta as chamadas para fetch() feitas em um service worker.

Recursos acessíveis pela Web

Uma regra declarativeNetRequest não pode redirecionar uma solicitação de recurso público para um recurso que não seja acessível pela Web. Isso aciona um erro. Isso é válido mesmo que o recurso acessível pela 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 anexação só é compatível com os seguintes cabeçalhos de solicitação: 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. Essa lista de permissões diferencia maiúsculas de minúsculas (bug 449152902).

Ao anexar a um cabeçalho de solicitação ou resposta, o navegador vai usar o separador apropriado sempre que possível.

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 browser.declarativeNetRequest.getDynamicRules();
const oldRuleIds = oldRules.map(rule => rule.id);

// Use the arrays to update the dynamic rules
await browser.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 estáticos disponíveis e o número máximo de conjuntos de regras estáticos ativados. Isso é feito quando o número de regras estáticas necessárias excede o número permitido. Para que isso funcione, alguns dos seus 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 browser.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 > browser.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS) {
    options.disableRulesetIds = disableCandidateIds
  }
  // Update the enabled static rules
  await browser.declarativeNetRequest.updateEnabledRulesets(options);
}

Exemplos de regras

Os exemplos a seguir mostram como o Chrome prioriza as regras em uma extensão. Ao analisá-las, talvez seja útil abrir as regras de priorização em uma janela separada.

A chave "priority"

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

Para determinar a prioridade de um URL específico, consulte as chaves "priority" (definida pelo desenvolvedor), "action" e "urlFilter". Esses exemplos se referem ao arquivo de regra de exemplo mostrado abaixo deles.

Navegação para https://google.com

Duas regras cobrem esse URL: as regras com os IDs 1 e 4. A regra com o ID 1 é aplicada porque as ações "block" têm uma 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, além das regras com os IDs 1 e 4. A regra com ID 2 é aplicada porque "allow" tem uma prioridade maior 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 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 dentro da 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 pela 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 uma â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 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 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

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

Enumeração

"firstParty"
A solicitação de rede é própria do frame em que foi originada.

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

ExtensionActionOptions

Chrome 88+ browser.* desde o Chrome 148

Propriedades

• displayActionCountAsBadgeText

  booleano opcional

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

• tabUpdate

  TabActionCountUpdate opcional

  Chrome 89+ browser.* desde o Chrome 148

  Detalhes de como a contagem de ações da guia deve ser ajustada.

GetDisabledRuleIdsOptions

Chrome 111+ browser.* desde o Chrome 148

Propriedades

• rulesetId

  string

  O ID correspondente a um Ruleset estático.

GetRulesFilter

Chrome 111+ browser.* desde o Chrome 148

Propriedades

• ruleIds

  number[] opcional

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

HeaderInfo

Chrome 128+ browser.* desde o Chrome 148

Propriedades

• excludedValues

  string[] opcional

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

• cabeçalho

  string

  O nome do cabeçalho. Essa condição só vai corresponder ao nome se values e excludedValues não forem especificados.

• values

  string[] opcional

  Se especificada, essa condição será atendida se o valor do cabeçalho corresponder a pelo menos um padrão nessa lista. Isso é compatível com a correspondência de valores de cabeçalho que não diferencia maiúsculas de minúsculas, além das seguintes construções:

  '*' : 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+ browser.* desde o Chrome 148

Descreve as operações possíveis para uma regra "modifyHeaders".

Enumeração

"append"
Adiciona uma nova entrada para o cabeçalho especificado. Ao modificar os cabeçalhos de uma solicitação, essa operação só é compatível com cabeçalhos específicos.

"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+ browser.* desde o Chrome 148

Propriedades

• isSupported

  booleano

• reason

  UnsupportedRegexReason opcional

  Especifica o motivo pelo qual a expressão regular não é aceita. Fornecido apenas se isSupported for falso.

MatchedRule

Propriedades

• ruleId

  número

  O ID de uma regra correspondente.

• rulesetId

  string

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

MatchedRuleInfo

Propriedades

• regra

  MatchedRule

• tabId

  número

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

• timeStamp

  número

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

MatchedRuleInfoDebug

Propriedades

• solicitação

  RequestDetails

  Detalhes sobre a solicitação que correspondeu à regra.

• regra

  MatchedRule

MatchedRulesFilter

Propriedades

• minTimeStamp

  número optional

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

• tabId

  número optional

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

ModifyHeaderInfo

Chrome 86+ browser.* desde o Chrome 148

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 as operações append e set.

QueryKeyValue

Propriedades

• chave

  string

• replaceOnly

  booleano opcional

  Chrome 94+ browser.* desde o Chrome 148

  Se for 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 é "falso".

• 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 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 indica o texto correspondente inteiro.

• 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+ browser.* desde o Chrome 148

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 requer captura. A captura só é necessária para regras de redirecionamento que especificam uma ação regexSubstition. O valor padrão é falso.

RequestDetails

Propriedades

• documentId

  string opcional

  Chrome 106+ browser.* desde o Chrome 148

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

• documentLifecycle

  DocumentLifecycle opcional

  Chrome 106+ browser.* desde o Chrome 148

  O ciclo de vida do documento do frame, se essa solicitação for para um frame.

• frameId

  número

  O valor 0 indica que a solicitação ocorre no frame principal. Um valor positivo indica o ID de um subframe em que a solicitação ocorre. Se o documento de um (sub)frame for carregado (type é main_frame ou sub_frame), frameId vai indicar o ID desse frame, não o do frame externo. Os IDs de frame são exclusivos em uma guia.

• frameType

  FrameType opcional

  Chrome 106+ browser.* desde o Chrome 148

  O tipo do 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 os redirecionamentos. Se for uma origem opaca, a string "null" será usada.

• método

  string

  Método HTTP padrão.

• parentDocumentId

  string opcional

  Chrome 106+ browser.* desde o Chrome 148

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

• parentFrameId

  número

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

• requestId

  string

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

• tabId

  número

  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

  ResourceType

  O tipo de recurso da solicitação.

• url

  string

  O URL da solicitação.

RequestMethod

Chrome 91+ browser.* desde o Chrome 148

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

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 houver correspondência com essa regra.

• condição

  RuleCondition

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

• ID

  número

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

• prioridade

  número optional

  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+ browser.* desde o Chrome 148

  Os cabeçalhos da solicitação a serem modificados para a solicitação. Válido apenas se RuleActionType for "modifyHeaders".

• responseHeaders

  ModifyHeaderInfo[] opcional

  Chrome 86+ browser.* desde o Chrome 148

  Os cabeçalhos de resposta a serem modificados para a solicitação. Válido apenas se RuleActionType for "modifyHeaders".

• tipo

  RuleActionType

  O tipo de ação a ser realizada.

RuleActionType

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

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"
Faz upgrade do 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 omitido, todas as solicitações serão aceitas.

• domínios

  string[] opcional

  Descontinuado desde o Chrome 101

  Use initiatorDomains

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

• excludedDomains

  string[] opcional

  Descontinuado desde o 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+ browser.* desde o Chrome 148

  A regra não vai corresponder às solicitações de rede originadas da lista de excludedInitiatorDomains. Se a lista estiver vazia ou for 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 conter 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+ browser.* desde o Chrome 148

  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 for 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 conter 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+ browser.* desde o Chrome 148

  Lista de métodos de solicitação que não correspondem à regra. Somente requestMethods ou excludedRequestMethods deve 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 que não correspondem à regra. Somente resourceTypes ou excludedResourceTypes deve ser especificado. Se nenhum deles for especificado, todos os tipos de recursos, exceto "main_frame", serão bloqueados.

• excludedResponseHeaders

  HeaderInfo[] opcional

  Chrome 128+ browser.* desde o Chrome 148

  A regra não será correspondente 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+ browser.* desde o Chrome 148

  Lista de tabs.Tab.id que não devem corresponder à regra. Um ID de tabs.TAB_ID_NONE exclui solicitações que não se originam de uma guia. Compatível apenas com regras no escopo da sessão.

• excludedTopDomains

  string[] opcional

  Chrome 145+ browser.* desde o Chrome 148

  A regra não vai corresponder às solicitações de rede quando o domínio do frame de nível superior associado corresponder a um da lista de excludedTopDomains. Se a lista estiver vazia ou for omitida, nenhum domínio será excluído. Isso tem precedência sobre topDomains.

  Observações:

  • Subdomínios como "a.example.com" também são permitidos.
  • As entradas precisam conter 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.
  • Para solicitações sem frame de nível superior associado (por exemplo, solicitações iniciadas pelo ServiceWorker), o domínio do iniciador da solicitação é considerado.
• initiatorDomains

  string[] opcional

  Chrome 101+ browser.* desde o Chrome 148

  A regra só vai corresponder às 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. Não é permitido usar uma lista vazia.

  Observações:

  • Subdomínios como "a.example.com" também são permitidos.
  • As entradas precisam conter 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

  Se o urlFilter ou o regexFilter (o que for especificado) 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 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+ browser.* desde o Chrome 148

  A 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 a solicitações de todos os domínios. Não é permitido usar uma lista vazia.

  Observações:

  • Subdomínios como "a.example.com" também são permitidos.
  • As entradas precisam conter 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+ browser.* desde o Chrome 148

  Lista de métodos de solicitação HTTP que podem ser correspondidos pela regra. Não é permitido usar uma lista vazia.

  Observação: especificar uma condição de regra requestMethods também vai excluir solicitações que não sejam HTTP(S), enquanto especificar excludedRequestMethods não vai.

• resourceTypes

  ResourceType[] opcional

  Lista de tipos de recursos que podem ser correspondidos pela regra. Não é permitido usar uma lista vazia.

  Observação: isso precisa ser especificado para regras allowAllRequests e pode incluir apenas os tipos de recurso sub_frame e main_frame.

• responseHeaders

  HeaderInfo[] opcional

  Chrome 128+ browser.* desde o Chrome 148

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

• tabIds

  number[] opcional

  Chrome 92+ browser.* desde o Chrome 148

  Lista de tabs.Tab.id que a regra precisa corresponder. Um ID de tabs.TAB_ID_NONE corresponde a solicitações que não se originam de uma guia. Não é permitido usar uma lista vazia. Compatível apenas com regras no escopo da sessão.

• topDomains

  string[] opcional

  Chrome 145+ browser.* desde o Chrome 148

  A regra só vai corresponder às solicitações de rede quando o domínio do frame de nível superior associado corresponder a um da lista de topDomains. Se a lista for omitida, a regra será aplicada às solicitações associadas a todos os domínios de frame de nível superior. Não é permitido usar uma lista vazia.

  Observações:

  • Subdomínios como "a.example.com" também são permitidos.
  • As entradas precisam conter apenas caracteres ASCII.
  • Use a codificação punycode para domínios internacionalizados.
  • Os subdomínios dos domínios listados também são correspondentes.
  • Para solicitações sem frame de nível superior associado (por exemplo, solicitações iniciadas pelo ServiceWorker), o domínio do iniciador da solicitação é considerado.
• urlFilter

  string opcional

  O padrão que é comparado com o URL da solicitação de rede. Construções compatíveis:

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

  '|': âncora esquerda/direita. Se usado em uma das extremidades do padrão, especifica o início/fim do URL, respectivamente.

  '||': âncora de nome de domínio. Se usado 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 %. Isso 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. Não é permitido usar uma string vazia.

  Não é permitido um padrão que comece com ||*. Use *.

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

  Observação: o urlFilter precisa ser composto apenas por caracteres ASCII. Isso é comparado 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 é http://abc.рф?q=ф, o urlFilter é comparado com o URL http://abc.xn--p1ai/?q=%D1%84.

RuleConditionKeys

Chrome 145+ browser.* desde o Chrome 148

Enumeração

"urlFilter"

"regexFilter"

"isUrlFilterCaseSensitive"

"initiatorDomains"

"excludedInitiatorDomains"

"requestDomains"

"excludedRequestDomains"

"topDomains"

"excludedTopDomains"

"domains"

"excludedDomains"

"resourceTypes"

"excludedResourceTypes"

"requestMethods"

"excludedRequestMethods"

"domainType"

"tabIds"

"excludedTabIds"

"responseHeaders"

"excludedResponseHeaders"

Ruleset

Propriedades

• ativado

  booleano

  Se o conjunto de regras está ativado por padrão.

• ID

  string

  Uma string não vazia que identifica o conjunto de regras de forma exclusiva. Os IDs que começam com "_" são reservados para uso interno.

• caminho

  string

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

RulesMatchedDetails

Propriedades

• rulesMatchedInfo

  MatchedRuleInfo[]

  Regras que correspondem ao filtro fornecido.

TabActionCountUpdate

Chrome 89+ browser.* desde o Chrome 148

Propriedades

• increment

  número

  O valor para incrementar a contagem de ações da guia. Valores negativos diminuem a contagem.

• tabId

  número

  A guia em que a contagem de ações será atualizada.

TestMatchOutcomeResult

Chrome 103+ browser.* desde o Chrome 148

Propriedades

• matchedRules

  MatchedRule[]

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

TestMatchRequestDetails

Chrome 103+ browser.* desde o Chrome 148

Propriedades

• iniciador

  string opcional

  O URL do iniciador (se houver) para a solicitação hipotética.

• método

  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 optional

  Chrome 129+ browser.* desde o Chrome 148

  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 retornará cabeçalhos de resposta vazios, que podem corresponder a regras que correspondem à inexistência de cabeçalhos. Por exemplo, {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}

• tabId

  número optional

  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.

• topUrl

  string opcional

  Chrome 145+ browser.* desde o Chrome 148

  O URL do frame de nível superior associado (se houver) para a solicitação.

• tipo

  ResourceType

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

• url

  string

  O URL da solicitação hipotética.

UnsupportedRegexReason

Chrome 87+ browser.* desde o Chrome 148

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+ browser.* desde o Chrome 148

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+ browser.* desde o Chrome 148

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+ browser.* desde o Chrome 148

Propriedades

• disableRuleIds

  number[] opcional

  Conjunto de IDs correspondentes às regras no Ruleset que serão desativadas.

• enableRuleIds

  number[] opcional

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

• rulesetId

  string

  O ID correspondente a um Ruleset estático.

URLTransform

Propriedades

• fragment

  string opcional

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

• host

  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á limpo.

• porta

  string opcional

  A nova porta para a 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 de 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 dinâmicas adicionadas pela extensão.

Valor

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

Intervalo de tempo em que as chamadas de 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 uma interação inicial estão isentas da cota.

Valor

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89+ browser.* desde o Chrome 148

O número mínimo de regras estáticas garantidas para uma extensão em todos os conjuntos de regras estáticas ativados. 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+ browser.* desde o Chrome 148

O número máximo de Rulesets estáticos que uma extensão pode ativar de uma só 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 as especificadas no arquivo de recursos de regras.

Valor

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120+ browser.* desde o Chrome 148

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

Valor

5000

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+ browser.* desde o Chrome 148

O número máximo de regras dinâmicas "não seguras" que uma extensão pode adicionar.

Valor

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120+ browser.* desde o Chrome 148

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

Valor

5000

SESSION_RULESET_ID

Chrome 90+ browser.* desde o Chrome 148

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

Valor

"_session"

Métodos

getAvailableStaticRuleCount()

Chrome 89+ browser.* desde o Chrome 148

browser.declarativeNetRequest.getAvailableStaticRuleCount(): Promise<number>

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.

Retorna

• Promise<number>

  Chrome 91+ browser.* desde o Chrome 148

getDisabledRuleIds()

Chrome 111+ browser.* desde o Chrome 148

browser.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
): Promise<number[]>

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

Parâmetros

• opções

  GetDisabledRuleIdsOptions

  Especifica o conjunto de regras a ser consultado.

Retorna

• Promise<number[]>

  Promessa que é resolvida com uma lista de IDs que correspondem às regras desativadas nesse conjunto de regras.

getDynamicRules()

browser.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
): Promise<Rule[]>

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

Parâmetros

• filtro

  GetRulesFilter opcional

  Chrome 111+ browser.* desde o Chrome 148

  Um objeto para filtrar a lista de regras buscadas.

Retorna

• Promise<Rule[]>

  Chrome 91+ browser.* desde o Chrome 148

  Promessa que é resolvida com o conjunto de regras dinâmicas. A promessa pode ser rejeitada em caso de erros internos temporários.

getEnabledRulesets()

browser.declarativeNetRequest.getEnabledRulesets(): Promise<string[]>

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

Retorna

• Promise<string[]>

  Chrome 91+ browser.* desde o Chrome 148

  Promessa que é resolvida com uma lista de IDs, em que cada ID corresponde a um Ruleset estático ativado.

getMatchedRules()

browser.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
): Promise<RulesMatchedDetails>

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 com 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

• filtro

  MatchedRulesFilter opcional

  Um objeto para filtrar a lista de regras correspondentes.

Retorna

• Promise<RulesMatchedDetails>

  Chrome 91+ browser.* desde o Chrome 148

  Promessa que é resolvida quando a lista de regras correspondentes é buscada. Em caso de erro, a promessa será rejeitada. Isso pode acontecer por vários motivos, como permissões insuficientes ou exceder a cota.

getSessionRules()

Chrome 90+ browser.* desde o Chrome 148

browser.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
): Promise<Rule[]>

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+ browser.* desde o Chrome 148

  Um objeto para filtrar a lista de regras buscadas.

Retorna

• Promise<Rule[]>

  Chrome 91+ browser.* desde o Chrome 148

  Promessa que é resolvida com o conjunto de regras com escopo de sessão.

isRegexSupported()

Chrome 87+ browser.* desde o Chrome 148

browser.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
): Promise<IsRegexSupportedResult>

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

Parâmetros

• regexOptions

  RegexOptions

  A expressão regular a ser verificada.

Retorna

• Promise<IsRegexSupportedResult>

  Chrome 91+ browser.* desde o Chrome 148

  Promessa que é resolvida com detalhes que consistem em saber se a expressão regular é compatível e o motivo, se não for.

setExtensionActionOptions()

Chrome 88+ browser.* desde o Chrome 148

browser.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
): Promise<void>

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

Parâmetros

• opções

  ExtensionActionOptions

Retorna

• Promessa<void>

  Chrome 91+ browser.* desde o Chrome 148

testMatchOutcome()

Chrome 103+ browser.* desde o Chrome 148

browser.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
): Promise<TestMatchOutcomeResult>

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

Parâmetros

• solicitação

  TestMatchRequestDetails

Retorna

• Promise<TestMatchOutcomeResult>

  Promessa que é resolvida com os detalhes das regras correspondentes.

updateDynamicRules()

browser.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
): Promise<void>

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 acontece como uma única operação atômica: ou todas as regras especificadas são adicionadas e removidas ou um erro é retornado.
• Essas regras são mantidas entre as sessões do navegador e as 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

• opções

  UpdateRuleOptions

  Chrome 87+ browser.* desde o Chrome 148

Retorna

• Promessa<void>

  Chrome 91+ browser.* desde o Chrome 148

  Promessa que é resolvida quando a atualização é concluída. Em caso de erro, a promessa será rejeitada e nenhuma alteração será feita no conjunto de regras. Isso pode acontecer por vários motivos, como formato de regra inválido, ID de regra duplicado, limite de contagem de regras excedido, erros internos, entre outros.

updateEnabledRulesets()

browser.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
): Promise<void>

Atualiza o conjunto de regras estáticas ativadas 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 entre as atualizações da extensão. 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ções

  UpdateRulesetOptions

  Chrome 87+ browser.* desde o Chrome 148

Retorna

• Promessa<void>

  Chrome 91+ browser.* desde o Chrome 148

  Promessa que é resolvida quando a atualização é concluída. Em caso de erro, a promessa será rejeitada, e nenhuma alteração será feita no conjunto de regras ativadas. Isso pode acontecer por vários motivos, como IDs de conjunto de regras inválidos, limite de contagem de regras excedido ou erros internos.

updateSessionRules()

Chrome 90+ browser.* desde o Chrome 148

browser.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
): Promise<void>

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 acontece como uma única operação atômica: ou 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 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

• opções

  UpdateRuleOptions

Retorna

• Promessa<void>

  Chrome 91+ browser.* desde o Chrome 148

  Promessa que é resolvida quando a atualização é concluída. Em caso de erro, a promessa será rejeitada e nenhuma alteração será feita no conjunto de regras. Isso pode acontecer por vários motivos, como formato de regra inválido, ID de regra duplicado, limite de contagem de regras excedido, entre outros.

updateStaticRules()

Chrome 111+ browser.* desde o Chrome 148

browser.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
): Promise<void>

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

Parâmetros

• opções

  UpdateStaticRulesOptions

Retorna

• Promessa<void>

  Promessa que é resolvida quando a atualização é concluída. Em caso de erro, a promessa será rejeitada, e nenhuma mudança será feita nas regras estáticas ativadas.

Eventos

onRuleMatchedDebug

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

Disparado quando uma regra corresponde 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

• callback

  função

  O parâmetro callback é semelhante a:

  (info: MatchedRuleInfoDebug) => void

  • informações

    MatchedRuleInfoDebug