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

declarativeNetRequestFeedback
host_permissions

Disponibilidade

Chrome 84 ou superior

Manifesto

Além das permissões descritas acima, alguns tipos de conjuntos de regras, ou seja, conjuntos de regras 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/*"
  ],
  ...
}

Conceitos e uso

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.

As próximas seções explicam os tipos de conjuntos de regras em detalhes.

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

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.

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"]
  }
}

urlFilter caracteres correspondentes

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). Veja alguns exemplos abaixo.

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://example.com/
"|https*" https://example.com http://example.com/
http://https.com
"example*^123|" https://example.com/123
http://abc.com/example?123		 https://example.com/1234
https://abc.com/example0123

Priorização de regras

As regras são acionadas por solicitações enviadas de páginas da Web. Se várias regras corresponderem a uma solicitação específica, elas precisarão ser priorizadas. Nesta seção, explicamos como eles são priorizados. A priorização ocorre em duas etapas.

  1. A prioridade é determinada para as regras dentro de uma extensão.
  2. Se mais de uma extensão puder aplicar uma regra a uma solicitação, a prioridade será determinada para todas as extensões que corresponderem a uma solicitação específica.

Pensando nessa correspondência desta forma: qualquer regra que uma extensão específica priorizar será, então, priorizada em relação às regras de outras extensões.

Priorização de regras em uma extensão

Em uma única extensão, a priorização é definida usando o seguinte processo:

  1. A regra com a prioridade mais alta definida pelo desenvolvedor (em outras palavras, o campo "priority") é retornada.

  2. Se houver mais de uma regra com a prioridade mais alta definida pelo desenvolvedor, elas serão priorizadas usando o campo "action", na seguinte ordem:

    1. allow
    2. allowAllRequests
    3. block
    4. upgradeScheme
    5. redirect

  3. Se o tipo de ação não for block ou redirect, todas as regras modifyHeaders correspondentes serão avaliadas. Se houver regras com prioridade definida pelo desenvolvedor menor que a especificada para allow e allowAllRequests, elas serão ignoradas.

  4. Se várias regras modificarem o mesmo cabeçalho, a modificação será determinada pelo campo "priority" definido pelo desenvolvedor e pelas operações especificadas.

    • Se uma regra for anexada a um cabeçalho, as regras de prioridade mais baixa só poderão ser anexadas a esse cabeçalho. As operações definir e remover não são permitidas.
    • Se uma regra definir um cabeçalho, as regras de prioridade mais baixa só poderão ser anexadas a esse cabeçalho. 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.

Priorização de regras entre extensões

Se apenas uma extensão tiver uma regra que corresponda a uma solicitação, essa regra será aplicada. No entanto, se mais de uma extensão corresponder a uma solicitação, o seguinte processo será usado:

  1. As regras são priorizadas usando o campo "action", na seguinte ordem:

    1. block
    2. redirect ou upgradeScheme
    3. allow ou allowAllRequests

  2. Se houver correspondência de mais de uma regra, a extensão instalada mais recentemente terá prioridade.

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é 50 conjuntos de regras estáticos como parte da chave de manifesto "rule_resources", mas apenas 10 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.

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.

Regras dinâmicas e de sessão

Os limites aplicados às regras dinâmicas e de sessão são mais simples do que às regras estáticas. O número total de ambos não pode exceder 5.000. Isso é chamado de MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES.

Regras que usam regex

Todos os tipos de regras podem usar expressões regulares. No entanto, o número total de regras regex 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 abaixo será exibido, e a regra será ignorada.

rules_1.json: Rule with id 1 specified a more complext 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.

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 necessário de regras estáticas exceder 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 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 abaixo 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

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.

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

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

  • 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

    As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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

  • 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[]>

    As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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

Retorna

  • Promessa<Rule[]>

    Chrome 91 ou versões mais recentes

    As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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

    As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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

Retorna

  • Promise&lt;RulesMatchedDetails&gt;

    Chrome 91 ou versões mais recentes

    As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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

Retorna

  • Promessa<Rule[]>

    Chrome 91 ou versões mais recentes

    As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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

Retorna

  • Promise&lt;IsRegexSupportedResult&gt;

    Chrome 91 ou versões mais recentes

    As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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

  • 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

    As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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

Retorna

  • Promise&lt;TestMatchOutcomeResult&gt;

    As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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

  • 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

    As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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

  • 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

    As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 91 ou versões mais recentes

    As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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

Retorna

  • Promessa<void>

    As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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