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 solicitações de rede sem interceptar e visualizar o conteúdo delas, oferecendo mais privacidade.

Permissões

declarativeNetRequest
declarativeNetRequestWithHostAccess

O evento "declarativeNetRequest" e "declarativeNetRequestWithHostAccess" permissões fornecem os mesmos recursos. A diferença entre eles é quando as permissões são solicitado ou concedido.

"declarativeNetRequest"

Aciona um aviso de permissão no momento da instalação, mas fornece acesso implícito a allow, allowAllRequests e block. Use isso quando possível para evitar precisar 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 é exibido no momento da instalação, mas você precisa solicitar ao host antes de executar qualquer ação em um host. Isso é apropriado quando você quer usar regras de solicitação de rede declarativa em uma que já tem permissões de host sem gerar de alertas.

Disponibilidade

Chrome 84 ou superior

Manifesto

Além das permissões descritas anteriormente, alguns tipos de conjuntos de regras, principalmente 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. Observe que o nome 'Ruleset' não aparece no JSON do manifesto, já que ele é meramente uma matriz. Os conjuntos de regras estáticos são explicados posteriormente neste documento.

{
  "name": "My extension",
  ...

  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    }, {
      "id": "ruleset_2",
      "enabled": false,
      "path": "rules_2.json"
    }]
  },
  "permissions": [
    "declarativeNetRequest",
    "declarativeNetRequestFeedback",
  ],
  "host_permissions": [
    "http://www.blogger.com/*",
    "http://*.google.com/*"
  ],
  ...
}

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 realiza uma das seguintes ações:

• Bloquear uma solicitação de rede.
• Faça upgrade do esquema (http para https).
• Negue qualquer regra bloqueada correspondente para impedir que uma solicitação seja bloqueada.
• Redirecione uma solicitação de rede.
• Modifique os cabeçalhos de solicitação ou resposta.

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

Dinâmico

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

Sessão

Apagado quando o navegador é desligado e quando uma nova versão da extensão é instalada. As regras de sessão são gerenciadas com 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 com JavaScript enquanto uma extensão está em uso.

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

Há apenas um para cada um desses tipos de conjuntos de regras. Uma extensão pode adicionar ou remover regras de forma dinâmica chamando updateDynamicRules() e updateSessionRules(), desde que os limites das regras não sejam excedidos. Saiba mais sobre os limites de regras em Limites de regras. Confira um exemplo disso em exemplos de código.

Conjuntos de regras estáticos

Ao contrário das regras dinâmicas e de sessão, as regras estáticas são empacotadas, instaladas e atualizadas quando uma extensão é instalada ou atualizada. Elas são armazenadas em arquivos de regras no formato JSON, que são indicados à extensão usando as chaves "declarative_net_request" e "rule_resources", conforme descrito acima, 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. As duas últimas são importantes quando você ativa ou desativa um conjunto de regras de maneira programática.

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

Para testar arquivos de regras, carregue sua extensão descompactada. Erros e avisos sobre regras estáticas inválidas são exibidos somente para extensões descompactadas. Regras estáticas inválidas em extensões empacotadas são ignoradas.

Revisão rápida

As alterações em conjuntos de regras estáticas podem estar qualificadas para revisão rápida. Consulte análise rápida das mudanças qualificadas.

Ativar e desativar regras estáticas e conjuntos de regras

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 estáticas e conjuntos de regras ativados é mantido nas sessões do navegador. Nenhuma delas é mantida nas atualizações de extensões, o que significa que apenas as regras que você escolheu deixar nos arquivos de regras ficam 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 estar ativadas. Saiba mais sobre os limites de regras em 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 ativação ou desativação. 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 ativação ou desativação. Os IDs são definidos usando a chave "id" do dicionário Ruleset.

Regras de criação

Independentemente do tipo, uma regra começa com quatro campos, conforme mostrado abaixo. Embora as chaves "id" e "priority" aceitem 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 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 com um padrão sintaxes correspondentes ou expressões regulares.

Sintaxe do filtro de URL

A chave "condition" de uma regra permite que uma chave "urlFilter" atue nos URLs de um domínio especificado. É possível criar padrões usando tokens de correspondência de padrão (em inglês). Aqui estão 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 Tecla "regexFilter". Para saber mais sobre limites que se aplicam a essas condições, consulte Regras que usam expressões regulares.

Escrever boas condições de URL

Ao criar regras, tome cuidado para que elas sempre correspondam a um domínio inteiro. Caso contrário, seus regra poderá corresponder em situações inesperadas. Por exemplo, ao usar o método sintaxe de correspondência de padrões:

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

Considere usar:

• ||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. Para Por exemplo, ^https:\/\/www\.google\.com\/ corresponde a qualquer caminho 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 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 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 correspondentes por prioridade. 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 o frame em que a solicitação está sendo feita já corresponde a uma regra allowAllRequests de prioridade maior ou igual para essa extensão, a solicitação é "permitida" A extensão não afetará a solicitação.

Se mais de uma extensão quiser bloquear ou redirecionar esse pedido, apenas uma 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 escolherá a regra da extensão instalada mais recentemente.

Cuidado: os fornecedores de navegador 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 de sessão). Quando a ordem for importante, sempre especifique explicitamente uma prioridade.

Antes do envio dos cabeçalhos da solicitação

Antes que o Chrome envie cabeçalhos de 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. 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 com prioridade mais alta de uma extensão são sempre aplicadas antes das regras com prioridade mais baixa da mesma extensão. É importante notar que, mesmo em extensões diferentes:

• 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 definir e remover não são permitidas.
• 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 o cabeçalho for removido de uma regra, as regras de prioridade mais baixa não poderão modificar esse cabeçalho.

Assim que 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 todas as regras 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 esse estágio, 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 nem redirecionar a solicitação.

No caso de uma regra de bloqueio, isso é gerenciado pela página que fez a solicitação receber uma resposta bloqueada e o Chrome encerrou a solicitação antecipadamente. No caso de uma regra de redirecionamento, o Chrome faz uma nova solicitação ao URL redirecionado. Verifique se esses comportamentos atendem às expectativas de privacidade da sua extensão.

Se a solicitação não for bloqueada ou redirecionada, o Chrome aplicará qualquer regra modifyHeaders. A aplicação de modificações nos cabeçalhos de resposta funciona da mesma maneira descrita em "Antes do envio dos cabeçalhos da solicitação". A aplicação de modificações aos cabeçalhos da solicitação não tem efeito algum, porque a solicitação já foi feita.

Regras de segurança

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 cota de regras dinâmicas.

Limites das regras

O carregamento e a avaliação de regras no navegador causam uma sobrecarga de desempenho, por isso alguns limites se aplicam ao usar a API. Os limites dependem do tipo 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 somente 50 desses conjuntos de regras podem ser ativados por vez. O último método é chamado de MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. Coletivamente, esses conjuntos de regras têm a garantia de pelo menos 30.000 regras. 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áticos, e apenas 10 desses conjuntos. podem ser ativadas ao mesmo tempo. Usar o minimum_chrome_version para limitar as versões do Chrome que podem instalar a extensão.

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

Observação:a partir do Chrome 128, se um usuário desativar uma extensão por chrome://extensions, as regras estáticas da extensão não mais longas são contabilizadas no limite de regras estáticas globais. Isso potencialmente libera dados estáticos de regras de firewall para outras extensões, mas também significa que, quando a extensão reativado, talvez ele tenha 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. Ela é exposta como MAX_NUMBER_OF_SESSION_RULES

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

Regras dinâmicas

Uma extensão pode ter pelo menos 5.000 regras dinâmicas. Ela é exposta 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. exposto como MAX_NUMBER_OF_DYNAMIC_RULES. Qualquer um regras não seguras adicionadas dentro do limite de 5.000 também contarão para esse limite.

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

Regras que usam expressões regulares

Todos os tipos de regras podem usar expressões regulares. No entanto, o número total de regras de expressão regular de cada tipo não pode exceder 1.000. Isso se chama MAX_NUMBER_OF_REGEX_RULES.

Além disso, cada regra precisa ter menos de 2 KB depois de compilada. Isso se correlaciona aproximadamente com a complexidade da regra. Se você tentar carregar uma regra que exceda esse limite, um aviso como o seguinte será exibido, e a regra será ignorada.

rules_1.json: Rule with id 1 specified a more complex regex than allowed
as part of the "regexFilter" key.

Interações com service workers

Um declarativeNetRequest só se aplica a solicitações que alcançam a pilha da rede. Isso inclui respostas do cache HTTP, mas pode não incluir respostas que passem pelo gerenciador onfetch de um service worker. declarativeNetRequest não afetará as respostas geradas pelo service worker ou extraídas de CacheStorage, mas afetará 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 pode ser acessado pela Web. Isso aciona um erro. Isso é válido mesmo se o recurso acessível na Web especificado pertencer à 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: 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 e x-forwarded-for.

Exemplos

Exemplos de código

Atualizar regras dinâmicas

O exemplo abaixo mostra como chamar updateDynamicRules(). O procedimento para updateSessionRules() é o mesmo.

// Get arrays containing new and old rules
const newRules = await getNewRules();
const oldRules = await chrome.declarativeNetRequest.getDynamicRules();
const oldRuleIds = oldRules.map(rule => rule.id);

// Use the arrays to update the dynamic rules
await chrome.declarativeNetRequest.updateDynamicRules({
  removeRuleIds: oldRuleIds,
  addRules: newRules
});

Atualizar conjuntos de regras estáticos

O exemplo a seguir mostra como ativar e desativar os conjuntos de regras considerando o número de conjuntos de regras estáticos disponíveis e o número máximo ativado. Faça isso quando o número de regras estáticas necessário exceder o 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 chrome.declarativeNetRequest.getEnabledRulesets();
  // Compare rule counts to determine if anything needs to be disabled so that
  // new rules can be enabled
  const proposedCount = enableRulesetIds.length;
  if (enabledStaticCount + proposedCount > chrome.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS) {
    options.disableRulesetIds = disableCandidateIds
  }
  // Update the enabled static rules
  await chrome.declarativeNetRequest.updateEnabledRulesets(options);
}

Exemplos de regras

Os exemplos a seguir ilustram como o Chrome prioriza regras em uma extensão. Ao analisá-los, recomendamos abrir as regras de priorização em outra janela.

A "prioridade" chave

Estes 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), as chaves "action" e "urlFilter". Estes exemplos se referem ao arquivo de regras de exemplo mostrado abaixo deles.

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

Duas regras abrangem esse URL: as com IDs 1 e 4. A regra com ID 1 se aplica porque as ações "block" têm uma prioridade maior 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

Por causa do URL mais longo, a regra com ID 2 agora corresponde além das regras com IDs 1 e 4. A regra com ID 2 se aplica porque "allow" tem uma prioridade maior que "block" e "redirect".

Navegue até https://google.com/12345

Todas as quatro regras correspondem a esse URL. A regra com ID 3 é aplicável porque sua 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 de extensão /a.jpg é resolvido para chrome-extension://EXTENSION_ID/a.jpg, em que EXTENSION_ID é o ID da sua 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 comando 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" é capturada do URL redirecionado e colocada na substituição.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": {
      "regexSubstitution": "https://\\1.xyz.com/"
    }
  },
  "condition": {
    "regexFilter": "^https://www\\.(abc|def)\\.xyz\\.com/",
    "resourceTypes": [
      "main_frame"
    ]
  }
}

Cabeçalhos

O exemplo a seguir remove todos os cookies de um frame principal e de quaisquer subframes.

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

Tipos

DomainType

Descreve se a solicitação é primária ou de terceiros no frame em que foi originada. Uma solicitação é considerada primária se tiver o mesmo domínio (eTLD+1) do frame em que foi originada.

Enumeração

"firstParty"
A solicitação de rede é primária para o frame em que foi originada.

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

ExtensionActionOptions

Chrome 88 ou superior

Propriedades

• displayActionCountAsBadgeText

  booleano opcional

  Indica se a contagem de ações para uma página deve ser exibida automaticamente como o texto do selo da extensão. Essa preferência é mantida em todas as sessões.

• tabUpdate

  TabActionCountUpdate opcional

  Chrome 89 ou superior

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

GetDisabledRuleIdsOptions

Chrome 111 ou versões mais recentes

Propriedades

• rulesetId

  string

  O ID correspondente a um Ruleset estático.

GetRulesFilter

Chrome 111 ou versões mais recentes

Propriedades

• ruleIds

  number[] opcional

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

HeaderInfo

Chrome 128 ou versões mais recentes

Propriedades

• excludedValues

  string[] opcional

  Se especificada, essa condição não é correspondida se o cabeçalho existir, mas o valor dele contiver pelo menos um elemento nessa lista. Esse código usa a mesma sintaxe de padrão de correspondência que 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 especificada, esta condição corresponde se o valor do cabeçalho corresponde a pelo menos um padrão nesta lista. Isso oferece suporte à 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 '?' pode ter escape com uma barra invertida, por exemplo, "\*" e '\?'

HeaderOperation

Chrome 86 ou versão mais recente

Isso descreve as possíveis operações de um elemento "modifyHeaders" regra de firewall.

Enumeração

"append"
Adiciona uma nova entrada para o cabeçalho especificado. Esta operação não é compatível com cabeçalhos de solicitação.

"set"
Define um novo valor para o cabeçalho especificado, removendo os cabeçalhos existentes com o mesmo nome.

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

IsRegexSupportedResult

Chrome 87 ou superior

Propriedades

• isSupported

  booleano

• reason

  UnsupportedRegexReason opcional

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

MatchedRule

Propriedades

• ruleId

  number

  O ID de uma regra correspondente.

• rulesetId

  string

  ID do Ruleset a que a regra pertence. No caso de uma regra originada do conjunto de regras dinâmicas, esse valor será igual a DYNAMIC_RULESET_ID.

MatchedRuleInfo

Propriedades

• regra

  MatchedRule

• tabId

  number

  O tabId da guia que originou a solicitação, caso ela ainda esteja ativa. caso contrário, será -1.

• timeStamp

  number

  O horário de correspondência da regra. Os carimbos de data/hora correspondem à convenção JavaScript para horas, ou seja, o número de milissegundos desde o período.

MatchedRuleInfoDebug

Propriedades

• solicitação

  RequestDetails

  Detalhes sobre a solicitação correspondente à regra.

• regra

  MatchedRule

MatchedRulesFilter

Propriedades

• minTimeStamp

  número opcional

  Se especificado, só corresponde às regras depois do carimbo de data/hora determinado.

• tabId

  número opcional

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

ModifyHeaderInfo

Chrome 86 ou versão mais recente

Propriedades

• cabeçalho

  string

  O nome do cabeçalho a ser modificado.

• operação

  HeaderOperation

  A operação a ser executada 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 ou versão mais recente

  Se for verdadeira, a chave de consulta só será substituída 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 serem adicionados ou substituídos.

• removeParams

  string[] opcional

  A lista de chaves de consulta a serem removidas.

Redirect

Propriedades

• extensionPath

  string opcional

  Caminho relativo para o diretório de extensão. Deve começar com "/".

• regexSubstitution

  string opcional

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

• transform

  URLTransform opcional

  Transformações de URL a serem realizadas.

• url

  string opcional

  O URL de redirecionamento. Redirecionamentos para URLs de JavaScript não são permitidos.

RegexOptions

Chrome 87 ou superior

Propriedades

• isCaseSensitive

  booleano opcional

  Indica 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

  Indica 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 ou versões mais recentes

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

• documentLifecycle

  DocumentLifecycle opcional

  Chrome 106 ou versões mais recentes

  O ciclo de vida do documento do frame, se essa 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, e não o ID do frame externo. Os IDs de frames são exclusivos em uma guia.

• frameType

  FrameType opcional

  Chrome 106 ou versões mais recentes

  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 por meio de redirecionamentos. Caso tenha origem opaca, a string "null" será usado.

• method

  string

  Método HTTP padrão.

• parentDocumentId

  string opcional

  Chrome 106 ou versões mais recentes

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

• parentFrameId

  number

  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

  number

  O ID da guia em que ocorre a solicitação. 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 ou versões mais recentes

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

Enumeração

"conectar"

"excluir"

"receber"

"head"

"opções"

"patch"

"postagem"

"put"

"outro"

ResourceType

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

Enumeração

"main_frame"

"sub_frame"

"folha de estilo"

"script"

"imagem"

"fonte"

"objeto"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"webtransport"

"pacote da web"

"outro"

Rule

Propriedades

• ação

  RuleAction

  A ação a ser realizada se houver correspondência com essa regra.

• transição

  RuleCondition

  A condição sob a qual essa regra é acionada.

• id

  number

  Um ID que identifica exclusivamente uma regra. Obrigatório e precisa ser maior ou igual a 1.

• prioridade

  número opcional

  Prioridade da regra. O padrão é 1. Quando especificado, deve ser >= 1.

RuleAction

Propriedades

• Redirecionar

  Redirecionamento opcional

  Descreve como fazer o redirecionamento. Válido apenas para regras de redirecionamento.

• requestHeaders

  ModifyHeaderInfo[] opcional

  Chrome 86 ou versão mais recente

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

• responseHeaders

  ModifyHeaderInfo[] opcional

  Chrome 86 ou versão mais recente

  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 tomada se um determinado RuleCondition corresponder.

Enumeração

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

"redirect"
Redirecione 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 que corresponda a ela.

"upgradeScheme"
Atualize 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 solicitação de frame em si.

RuleCondition

Propriedades

• domainType

  DomainType opcional

  Especifica se a solicitação de rede é primária ou de terceiros no domínio de origem. Se omitido, todas as solicitações serão aceitas.

• domínios

  string[] opcional

  Uso suspenso desde o Chrome 101

  Use initiatorDomains

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

• excludedDomains

  string[] opcional

  Uso suspenso desde o Chrome 101

  Use excludedInitiatorDomains

  A regra não corresponderá a solicitações de rede originadas na lista de excludedDomains.

• excludedInitiatorDomains

  string[] opcional

  Chrome 101 ou versões mais recentes

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

  Observações:

  • Subdomínios como "a.example.com" também são permitidos.
  • As entradas precisam ter apenas caracteres ASCII.
  • Usar a codificação punycode para domínios internacionalizados.
  • Isso corresponde ao iniciador da solicitação e não ao URL da solicitação.
  • Os subdomínios dos domínios listados também são excluídos.
• excludedRequestDomains

  string[] opcional

  Chrome 101 ou versões mais recentes

  A regra não corresponderá às solicitações de rede quando o domínio corresponder a uma da lista de excludedRequestDomains. Se a lista estiver vazia ou omitida, nenhum domínio será excluído. Tem precedência sobre requestDomains.

  Observações:

  • Subdomínios como "a.example.com" também são permitidos.
  • As entradas precisam ter apenas caracteres ASCII.
  • Usar a codificação punycode para domínios internacionalizados.
  • Os subdomínios dos domínios listados também são excluídos.
• excludedRequestMethods

  RequestMethod[] opcional

  Chrome 91 ou versões mais recentes

  Lista de métodos de solicitação aos quais a regra não corresponde. Apenas requestMethods ou excludedRequestMethods precisam ser especificados. Se nenhum deles for especificado, todos os métodos de solicitação serão correspondentes.

• excludedResourceTypes

  ResourceType[] opcional

  Lista de tipos de recursos sem correspondência com a regra. Apenas resourceTypes ou excludedResourceTypes precisam ser especificados. Se nenhum deles for especificado, todos os tipos de recursos, exceto "main_frame" estão bloqueados.

• excludedResponseHeaders

  HeaderInfo[] opcional

  Chrome 128 ou versões mais recentes

  A regra não corresponderá 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 ou versões mais recentes

  Lista de tabs.Tab.id a que a regra não deve corresponder. 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.

• initiatorDomains

  string[] opcional

  Chrome 101 ou versões mais recentes

  A regra só vai corresponder às solicitações de rede originadas na lista de initiatorDomains. Se a lista for omitida, a regra será aplicada às solicitações de todos os domínios. Uma lista vazia não é permitida.

  Observações:

  • Subdomínios como "a.example.com" também são permitidos.
  • As entradas precisam ter apenas caracteres ASCII.
  • Usar a codificação punycode para domínios internacionalizados.
  • Isso corresponde ao iniciador da solicitação e não ao URL da solicitação.
  • Também é feita a correspondência dos subdomínios dos domínios listados.
• isUrlFilterCaseSensitive

  booleano opcional

  Define se urlFilter ou regexFilter (o que for especificado) diferencia maiúsculas de minúsculas. O padrão é false

• regexFilter

  string opcional

  Expressão regular para correspondência com o URL de solicitação de rede. Isso segue a sintaxe RE2.

  Observação: 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 qualquer outro caractere não ASCII é codificado em utf-8.

• requestDomains

  string[] opcional

  Chrome 101 ou versões mais recentes

  A regra só vai corresponder às solicitações de rede quando o domínio corresponder a uma da lista de requestDomains. Se a lista for omitida, a regra será aplicada às solicitações de todos os domínios. Uma lista vazia não é permitida.

  Observações:

  • Subdomínios como "a.example.com" também são permitidos.
  • As entradas precisam ter apenas caracteres ASCII.
  • Usar a codificação punycode para domínios internacionalizados.
  • Também é feita a correspondência dos subdomínios dos domínios listados.
• requestMethods

  RequestMethod[] opcional

  Chrome 91 ou versões mais recentes

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

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

• resourceTypes

  ResourceType[] opcional

  Lista de tipos de recursos aos quais a regra pode corresponder. Uma lista vazia não é permitida.

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

• responseHeaders

  HeaderInfo[] opcional

  Chrome 128 ou versões mais recentes

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

• tabIds

  number[] opcional

  Chrome 92 ou versões mais recentes

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

• urlFilter

  string opcional

  O padrão que corresponde ao URL de solicitação de rede. Construções compatíveis:

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

  "|" : âncora esquerda/direita: se usada em qualquer uma das extremidades do padrão, especifica o início/fim do URL, respectivamente.

  '||' : âncora do 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 letra, dígito ou uma das seguintes opções: _, -, . ou %. Isso também corresponde ao final do URL.

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

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

  Um padrão que comece 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 com 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 utf-8. Por exemplo, quando o URL da solicitação for http://abc.рbf?q=bf, o urlFilter será comparado ao URL http://abc.xn--p1ai/?q=%D1%84.

Ruleset

Propriedades

• ativado

  booleano

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

• id

  string

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

• caminho

  string

  O caminho do conjunto de regras JSON relativo ao diretório de extensão.

RulesMatchedDetails

Propriedades

• rulesMatchedInfo

  MatchedRuleInfo[]

  Regras que correspondem ao filtro especificado.

TabActionCountUpdate

Chrome 89 ou superior

Propriedades

• increment

  number

  O valor para incrementar a contagem de ações da guia. Valores negativos diminuirão a contagem.

• tabId

  number

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

TestMatchOutcomeResult

Chrome 103 ou mais recente

Propriedades

• matchedRules

  MatchedRule[]

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

TestMatchRequestDetails

Chrome 103 ou mais recente

Propriedades

• iniciador

  string opcional

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

• method

  RequestMethod opcional

  Método HTTP padrão da solicitação hipotética. O padrão é "get" para solicitações HTTP e é ignorado para solicitações que não são HTTP.

• responseHeaders

  objeto opcional

  Pendente

  Os cabeçalhos fornecidos por uma resposta hipotética se a solicitação não for bloqueada ou redirecionada antes do envio. Representado como um objeto que mapeia um nome de cabeçalho para uma lista de valores de string. Se não especificada, a resposta hipotética retornaria 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 opcional

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

• tipo

  ResourceType

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

• url

  string

  O URL da solicitação hipotética.

UnsupportedRegexReason

Chrome 87 ou superior

Descreve por que uma determinada expressão regular não é compatível.

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 ou superior

Propriedades

• addRules

  Rule[] opcional

  Regras a serem adicionadas.

• removeRuleIds

  number[] opcional

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

UpdateRulesetOptions

Chrome 87 ou superior

Propriedades

• disableRulesetIds

  string[] opcional

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

• enableRulesetIds

  string[] opcional

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

UpdateStaticRulesOptions

Chrome 111 ou versões mais recentes

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 que serão ativadas.

• rulesetId

  string

  O ID correspondente a um Ruleset estático.

URLTransform

Propriedades

• fragment

  string opcional

  O novo fragmento para a solicitação. Precisa estar vazio. Nesse caso, o fragmento existente será apagado. ou deve 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á apagado.

• porta

  string opcional

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

• consulta

  string opcional

  A nova consulta para a solicitação. Deve estar vazio. Nesse caso, a consulta atual será apagada. ou deve começar com "?".

• queryTransform

  QueryTransform opcional

  Adicione, remova ou substitua pares de chave-valor de consultas.

• planejar

  string opcional

  O novo esquema para a solicitação. Os valores permitidos são "http", "https" e "ftp" e "chrome-extension".

• nome de usuário

  string opcional

  O novo nome de usuário para a solicitação.

Propriedades

DYNAMIC_RULESET_ID

ID do conjunto de regras das regras dinâmicas adicionadas pela extensão.

Valor

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

Intervalo de tempo em que chamadas MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules podem ser feitas, especificado em minutos. As outras chamadas vão falhar imediatamente e definir runtime.lastError. Observação: chamadas getMatchedRules associadas a um gesto do usuário estão isentas da cota.

Valor

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89 ou superior

O número mínimo de regras estáticas garantido para uma extensão em todos os conjuntos de regras estáticas ativadas. As regras acima desse limite são contabilizadas no limite de regras estáticas global.

Valor

30.000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

O número de vezes que getMatchedRules pode ser chamado em um período de GETMATCHEDRULES_QUOTA_INTERVAL.

Valor

20

MAX_NUMBER_OF_DYNAMIC_RULES

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

Valor

30.000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94 ou versão mais recente

É 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 o especificado no arquivo de recursos da regra.

Valor

1.000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120 ou mais recente

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

Valor

5.000

MAX_NUMBER_OF_STATIC_RULESETS

O número máximo de Rulesets estáticos que uma extensão pode especificar como parte da chave de manifesto "rule_resources".

Valor

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120 ou mais recente

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

Valor

5.000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120 ou mais recente

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

Valor

5.000

SESSION_RULESET_ID

Chrome 90 ou superior

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 ou versão mais recente

chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
)

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

Parâmetros

• callback

  função opcional

  O parâmetro callback tem esta aparência:

  (count: number) => void

  • contagem

    number

Retorna

• Promise<number>

  Chrome 91 ou versões mais recentes

  O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

getDisabledRuleIds()

Promessa Chrome 111 ou versões mais recentes

chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
  callback?: function,
)

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

Parâmetros

• opções

  GetDisabledRuleIdsOptions

  Especifica o conjunto de regras a ser consultado.

• callback

  função opcional

  O parâmetro callback tem esta aparência:

  (disabledRuleIds: number[]) => void

  • disabledRuleIds

    número[]

Retorna

• Promessa<number[]>

  O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

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 opcionalmente filtrar a lista de regras buscadas especificando um filter.

Parâmetros

• filtro

  GetRulesFilter opcional

  Chrome 111 ou versões mais recentes

  Um objeto para filtrar a lista de regras buscadas.

• callback

  função opcional

  O parâmetro callback tem esta aparência:

  (rules: Rule[]) => void

  • regras

    Regra[]

Retorna

• Promessa<Rule[]>

  Chrome 91 ou versões mais recentes

  O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

getEnabledRulesets()

Promessa

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

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

Parâmetros

• callback

  função opcional

  O parâmetro callback tem esta aparência:

  (rulesetIds: string[]) => void

  • rulesetIds

    string[]

Retorna

• Promise&lt;string[]&gt;

  Chrome 91 ou versões mais recentes

  O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

getMatchedRules()

Promessa

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

Retorna todas as regras que correspondem à extensão. Os autores da chamada podem opcionalmente 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 tenham sido correspondidos há mais de cinco minutos não serão retornadas.

Parâmetros

• filtro

  MatchedRulesFilter opcional

  Um objeto para filtrar a lista de regras correspondentes.

• callback

  função opcional

  O parâmetro callback tem esta aparência:

  (details: RulesMatchedDetails) => void

  • detalhes

    RulesMatchedDetails

Retorna

• Promise&lt;RulesMatchedDetails&gt;

  Chrome 91 ou versões mais recentes

  O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

getSessionRules()

Promessa Chrome 90 ou versões mais recentes

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

Retorna o conjunto atual de regras no escopo da sessão para a extensão. Os autores da chamada podem opcionalmente filtrar a lista de regras buscadas especificando um filter.

Parâmetros

• filtro

  GetRulesFilter opcional

  Chrome 111 ou versões mais recentes

  Um objeto para filtrar a lista de regras buscadas.

• callback

  função opcional

  O parâmetro callback tem esta aparência:

  (rules: Rule[]) => void

  • regras

    Regra[]

Retorna

• Promessa<Rule[]>

  Chrome 91 ou versões mais recentes

  O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

isRegexSupported()

Promessa Chrome 87 ou versão mais recente

chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
  callback?: function,
)

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

Parâmetros

• regexOptions

  RegexOptions

  A expressão regular a ser verificada.

• callback

  função opcional

  O parâmetro callback tem esta aparência:

  (result: IsRegexSupportedResult) => void

  • resultado

    IsRegexSupportedResult

Retorna

• Promise&lt;IsRegexSupportedResult&gt;

  Chrome 91 ou versões mais recentes

  O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

setExtensionActionOptions()

Promessa Chrome 88 ou versão mais recente

chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
  callback?: function,
)

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

Parâmetros

• opções

  ExtensionActionOptions

• callback

  função opcional

  Chrome 89 ou superior

  O parâmetro callback tem esta aparência:

  () => void

Retorna

• Promessa<void>

  Chrome 91 ou versões mais recentes

  O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

testMatchOutcome()

Promessa Chrome 103 ou mais recente

chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
)

Verifica se alguma das regras declarativeNetRequest da extensão corresponderia a uma solicitação hipotética. Observação: disponível somente para extensões descompactadas, para uso exclusivo durante o desenvolvimento da extensão.

Parâmetros

• solicitação

  TestMatchRequestDetails

• callback

  função opcional

  O parâmetro callback tem esta aparência:

  (result: TestMatchOutcomeResult) => void

  • resultado

    TestMatchOutcomeResult

Retorna

• Promise&lt;TestMatchOutcomeResult&gt;

  O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

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 primeiro removidas 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: todas as regras especificadas são adicionadas e removidas ou um erro é retornado.
• Essas regras são mantidas nas sessões do navegador e nas atualizações de extensões.
• As regras estáticas especificadas como parte do pacote de extensão não podem ser removidas usando esta 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 ou superior
• callback

  função opcional

  O parâmetro callback tem esta aparência:

  () => void

Retorna

• Promessa<void>

  Chrome 91 ou versões mais recentes

  O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

updateEnabledRulesets()

Promessa

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

Atualiza o conjunto de conjuntos de regras estáticos ativados para a extensão. Os conjuntos de regras com IDs listados em options.disableRulesetIds são removidos primeiro e, em seguida, os que estão listados em options.enableRulesetIds são adicionados. O conjunto de conjuntos de regras estáticos ativados é mantido nas sessões, mas não nas atualizações de extensão. Ou seja, a chave de manifesto rule_resources determina o conjunto de conjuntos de regras estáticos ativados em cada atualização.

Parâmetros

• opções

  UpdateRulesetOptions

  Chrome 87 ou superior
• callback

  função opcional

  O parâmetro callback tem esta aparência:

  () => void

Retorna

• Promessa<void>

  Chrome 91 ou versões mais recentes

  O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

updateSessionRules()

Promessa Chrome 90 ou versões mais recentes

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 primeiro removidas 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: 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 em backup 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

• callback

  função opcional

  O parâmetro callback tem esta aparência:

  () => void

Retorna

• Promessa<void>

  Chrome 91 ou versões mais recentes

  O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

updateStaticRules()

Promessa Chrome 111 ou versões mais recentes

chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
  callback?: function,
)

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

Parâmetros

• opções

  UpdateStaticRulesOptions

• callback

  função opcional

  O parâmetro callback tem esta aparência:

  () => void

Retorna

• Promessa<void>

  O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

Eventos

onRuleMatchedDebug

chrome.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", que deve ser usada apenas para fins de depuração.

Parâmetros

• callback

  função

  O parâmetro callback tem esta aparência:

  (info: MatchedRuleInfoDebug) => void

  • informações

    MatchedRuleInfoDebug