chrome.declarativeNetRequest

Descrição

A API chrome.declarativeNetRequest é usada para bloquear ou modificar solicitações de rede especificando regras declarativas. Isso permite que as extensões modifiquem as solicitações de rede sem interceptar e visualizar o conteúdo, oferecendo mais privacidade.

Permissões

declarativeNetRequest
declarativeNetRequestWithHostAccess

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

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

Disponibilidade

Chrome 84 ou mais recente

Manifesto

Além das permissões descritas anteriormente, determinados tipos de conjuntos de regras (especificamente conjuntos estáticos) exigem a declaração da chave de manifesto "declarative_net_request", que precisa ser um dicionário com uma única chave chamada "rule_resources". Essa chave é uma matriz que contém dicionários do tipo Ruleset, como mostrado a seguir. Observe que o nome "Conjunto de regras" não aparece no JSON do manifesto, já que ele é apenas uma matriz. Os conjuntos de regras estáticos são explicados posteriormente neste documento.

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

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

Conceitos e uso

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

  • Bloquear uma solicitação de rede.
  • Faça upgrade do esquema (http para https).
  • Para impedir que uma solicitação seja bloqueada, nege todas as regras de bloqueio correspondentes.
  • Redirecionar uma solicitação de rede.
  • Modifique cabeçalhos de solicitação ou resposta.

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

Dynamic
Persistem em sessões do navegador e upgrades de extensões, além de serem gerenciadas usando JavaScript enquanto uma extensão está em uso.
Sessão
Limpo quando o navegador é desligado e quando uma nova versão da extensão é instalada. As regras de sessão são gerenciadas usando JavaScript enquanto uma extensão está em uso.
Estático
Em pacote, instalada e atualizada quando uma extensão é instalada ou atualizada. As regras estáticas são armazenadas em arquivos de regras formatados em JSON e listadas no arquivo de manifesto.

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

Conjuntos de regras dinâmicas e no escopo da sessão

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

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

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

Conjuntos de regras estáticos

Ao contrário das regras dinâmicas e de sessão, as regras estáticas são empacotadas, instaladas e atualizadas quando uma extensão é instalada ou atualizada. Elas são armazenadas em arquivos de regras no formato JSON, que são indicados à extensão usando as chaves "declarative_net_request" e "rule_resources" conforme descrito acima, bem como um ou mais dicionários Ruleset. Um dicionário Ruleset contém um caminho para o arquivo de regras, um ID para o conjunto de regras contido no arquivo e se o conjunto de regras está ativado ou desativado. As duas últimas são importantes quando você ativa ou desativa um conjunto de regras de maneira programática.

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

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

Ativar e desativar regras estáticas e conjuntos de regras

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

O conjunto de regras estáticas e de conjuntos de regras ativados é mantido nas sessões do navegador. Nenhuma delas é mantida nas atualizações de extensões, o que significa que apenas as regras que você escolheu deixar nos arquivos de regras estão disponíveis após uma atualização.

Por motivos de desempenho, também há limites para o número de regras e conjuntos de regras que podem ser ativados ao mesmo tempo. Chame getAvailableStaticRuleCount() para verificar o número de regras adicionais que podem ser ativadas. Para informações sobre limites de regras, consulte Limites de regras.

Para ativar ou desativar regras estáticas, chame updateStaticRules(). Esse método usa um objeto UpdateStaticRulesOptions, que contém matrizes de IDs de regras que serão ativadas ou desativadas. Os IDs são definidos usando a chave "id" do dicionário Ruleset.

Para ativar ou desativar rulesets estáticos, chame updateEnabledRulesets(). Esse método usa um objeto UpdateRulesetOptions, que contém matrizes de IDs de conjuntos de regras que serão ativados ou desativados. Os IDs são definidos usando a chave "id" do dicionário Ruleset.

Regras de build

Seja qual for o tipo, uma regra começa com quatro campos, como mostrado a seguir. Embora as chaves "id" e "priority" aceitem um número, as chaves "action" e "condition" podem oferecer várias condições de bloqueio e redirecionamento. A regra a seguir bloqueia todas as solicitações de script originadas de "foo.com" para qualquer URL com "abc" como substring.

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

urlFilter caracteres correspondentes

A chave "condition" de uma regra permite que uma chave "urlFilter" aja em URLs de um domínio especificado. É possível criar padrões usando tokens de correspondência de padrões. Veja alguns exemplos.

urlFilter Correspondências Sem correspondência
"abc" https://abcd.com
https://example.com/abcd		 https://ab.com
"abc*d" https://abcd.com
https://example.com/abcxyzd		 https://abc.com
"||a.example.com" https://a.example.com/
https://b.a.example.com/xyz		 https://example.com/
"|https*" https://example.com http://example.com/
http://https.com
"example*^123|" https://example.com/123
http://abc.com/example?123		 https://example.com/1234
https://abc.com/example0123

Priorização de regras

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

  1. A prioridade é determinada para as regras 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 dessa maneira: qualquer regra priorizada por uma extensão será priorizada em relação às regras de outras extensões.

Priorização de regras em uma extensão

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

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

  2. Se houver mais de uma regra com a maior prioridade 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, essas regras 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 de definição e remoção não são permitidas.
    • Se uma regra definir um cabeçalho, as regras de prioridade mais baixa só poderão ser anexadas a esse cabeçalho. Não são permitidas outras modificações.
    • Se uma regra remover um cabeçalho, as regras de prioridade mais baixa não poderão modificar esse cabeçalho.

Priorização de regras entre extensões

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

  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 mais de uma regra corresponder, a extensão instalada mais recentemente terá prioridade.

Limites das regras

Há uma sobrecarga de desempenho no carregamento e na avaliação de regras no navegador. Por isso, alguns limites se aplicam ao usar a API. Os limites dependem do tipo de regra que você está usando.

Regras estáticas

As regras estáticas são aquelas especificadas em arquivos de regras declaradas no arquivo de manifesto. Uma extensão pode especificar até 100 rulesets estáticos como parte da chave de manifesto "rule_resources". No entanto, apenas 50 desses conjuntos de regras podem ser ativados por vez. O segundo tipo é chamado de MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. Coletivamente, esses conjuntos de regras garantem pelo menos 30 mil regras. Isso é chamado de GUARANTEED_MINIMUM_STATIC_RULES.

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

Regras de sessão

Uma extensão pode ter até 5.000 regras de sessão. Ele é exposto como MAX_NUMBER_OF_SESSION_RULES.

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

Regras dinâmicas

Uma extensão pode ter pelo menos 5.000 regras dinâmicas. Ele é exposto como MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES.

A partir do Chrome 121, há um limite maior de 30.000 regras disponíveis para regras dinâmicas seguras, expostas como MAX_NUMBER_OF_DYNAMIC_RULES. Regras seguras são definidas como regras com uma ação de block, allow, allowAllRequests ou upgradeScheme. Todas as regras não seguras adicionadas dentro do limite de 5.000 também serão contabilizadas nesse limite.

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

Regras que usam expressões regulares

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

Além disso, cada regra precisa ter menos de 2 KB depois de compilada. Isso está relacionado, em termos gerais, à complexidade da regra. Se você tentar carregar uma regra que exceda esse limite, verá um aviso como o seguinte, e a regra será ignorada.

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

Interações com service workers

Um declarativeNetRequest se aplica apenas a solicitações que alcançam a pilha de rede. Isso inclui respostas do cache HTTP, mas pode não incluir respostas que passam pelo gerenciador onfetch de um service worker. "declarativeNetRequest" não afetará as respostas geradas pelo service worker ou recuperadas de CacheStorage, mas afetará chamadas para fetch() feitas em um service worker.

Recursos acessíveis na Web

Uma regra declarativeNetRequest não pode redirecionar de uma solicitação de recurso público para um recurso que não seja acessível na Web. Isso vai gerar um erro. Isso acontece mesmo que o recurso acessível pela Web especificado pertença à extensão de redirecionamento. Para declarar recursos para declarativeNetRequest, use a matriz "web_accessible_resources" do manifesto.

Exemplos

Exemplos de código

Atualizar regras dinâmicas

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

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

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

Atualizar conjuntos de regras estáticos

O exemplo a seguir mostra como ativar e desativar conjuntos de regras considerando o número de conjuntos de regras disponíveis e o máximo de conjuntos de regras estáticos ativados. Você pode fazer isso quando o número de regras estáticas precisa exceder o número permitido. Para que isso funcione, alguns dos conjuntos de regras precisam ser instalados com alguns dos conjuntos desativados, definindo "Enabled" como false no arquivo de manifesto.

async function updateStaticRules(enableRulesetIds, disableCandidateIds) {
  // Create the options structure for the call to updateEnabledRulesets()
  let options = { enableRulesetIds: enableRulesetIds }
  // Get the number of enabled static rules
  const enabledStaticCount = await chrome.declarativeNetRequest.getEnabledRulesets();
  // Compare rule counts to determine if anything needs to be disabled so that
  // new rules can be enabled
  const proposedCount = enableRulesetIds.length;
  if (enabledStaticCount + proposedCount > chrome.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS) {
    options.disableRulesetIds = disableCandidateIds
  }
  // Update the enabled static rules
  await chrome.declarativeNetRequest.updateEnabledRulesets(options);
}

Exemplos de regras

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

A chave "prioridade"

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

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

Navegação para https://google.com
Duas regras cobrem este URL: as regras com IDs 1 e 4. A regra com ID 1 se aplica porque as ações "block" têm uma prioridade maior do que as ações "redirect". As demais regras não se aplicam porque são para URLs mais longos.
Acesse https://google.com/1234
Por causa do URL mais longo, a regra com ID 2 agora corresponde às regras com IDs 1 e 4. A regra com o ID 2 se aplica porque "allow" tem uma prioridade maior que "block" e "redirect".
Acesse https://google.com/12345
Todas as quatro regras correspondem a esse URL. A regra com o ID 3 se aplica porque a prioridade definida pelo desenvolvedor é a mais alta do grupo.
[
  {
    "id": 1,
    "priority": 1,
    "action": { "type": "block" },
    "condition": {"urlFilter": "google.com", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 2,
    "priority": 1,
    "action": { "type": "allow" },
    "condition": { "urlFilter": "google.com/123", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 3,
    "priority": 2,
    "action": { "type": "block" },
    "condition": { "urlFilter": "google.com/12345", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 4,
    "priority": 1,
    "action": { "type": "redirect", "redirect": { "url": "https://example.com" } },
    "condition": { "urlFilter": "google.com", "resourceTypes": ["main_frame"] }
  },
]

Redirecionamentos

O exemplo abaixo requer permissão de host para *://*.example.com/*.

O exemplo a seguir mostra como redirecionar uma solicitação de example.com para uma página na própria extensão. O caminho da extensão /a.jpg é resolvido para chrome-extension://EXTENSION_ID/a.jpg, em que EXTENSION_ID é o ID da extensão. Para que isso funcione, o manifesto precisa declarar /a.jpg como um recurso acessível pela Web.

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

O código a seguir usa a chave "transform" para redirecionar a um subdomínio de example.com. Ele usa uma âncora de nome de domínio ("||") para interceptar solicitações com qualquer esquema de example.com. A chave "scheme" em "transform" especifica que redirecionamentos para o subdomínio sempre usarão "https".

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": {
      "transform": { "scheme": "https", "host": "new.example.com" }
    }
  },
  "condition": {
    "urlFilter": "||example.com",
    "resourceTypes": ["main_frame"]
  }
}

O exemplo a seguir usa expressões regulares para redirecionar de https://www.abc.xyz.com/path para https://abc.xyz.com/path. Na chave "regexFilter", observe como os pontos têm escape e que o grupo de captura seleciona "abc" ou "def". A chave "regexSubstitution" especifica a primeira correspondência retornada da expressão regular usando "\1". Nesse caso, "abc" é capturado do URL redirecionado e colocado na substituição.

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

Cabeçalhos

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

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

Tipos

DomainType

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

Tipo enumerado

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

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

ExtensionActionOptions

Chrome 88 ou mais recente

Propriedades

  • displayActionCountAsBadgeText

    booleano opcional

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

  • tabUpdate

    TabActionCountUpdate opcional

    Chrome 89 ou mais recente

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

GetDisabledRuleIdsOptions

Chrome 111 ou mais recente

Propriedades

  • rulesetId

    string

    O ID correspondente a um Ruleset estático.

GetRulesFilter

Chrome 111 ou mais recente

Propriedades

  • ruleIds

    number[] opcional

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

HeaderOperation

Chrome 86 ou mais recente

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

Tipo enumerado

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

"set"
Define um novo valor para o cabeçalho especificado, removendo qualquer cabeçalho existente com o mesmo nome.

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

IsRegexSupportedResult

Chrome 87 ou mais recente

Propriedades

  • isSupported

    boolean

  • reason

    UnsupportedRegexReason opcional

    Especifica o motivo da incompatibilidade da expressão regular. Fornecido apenas se isSupported for falso.

MatchedRule

Propriedades

  • ruleId

    number

    O ID de uma regra correspondente.

  • rulesetId

    string

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

MatchedRuleInfo

Propriedades

  • regra

    MatchedRule

  • tabId

    number

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

  • timeStamp

    number

    A hora em que a regra foi correspondida. Os carimbos de data/hora corresponderão à convenção JavaScript de horas, ou seja, o número de milissegundos desde o período.

MatchedRuleInfoDebug

Propriedades

MatchedRulesFilter

Propriedades

  • minTimeStamp

    número opcional

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

  • tabId

    número opcional

    Se especificado, só corresponde às regras da guia em questão. Corresponde às regras não associadas a nenhuma guia ativa quando definida como -1.

ModifyHeaderInfo

Chrome 86 ou mais recente

Propriedades

  • cabeçalho

    string

    O nome do cabeçalho a ser modificado.

  • operação

    HeaderOperation

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

  • valor

    string opcional

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

QueryKeyValue

Propriedades

  • chave

    string

  • replaceOnly

    booleano opcional

    Chrome 94 ou mais recente

    Se verdadeiro, a chave de consulta será substituída somente se já estiver presente. Caso contrário, a chave também será adicionada se estiver ausente. O padrão é "false".

  • valor

    string

QueryTransform

Propriedades

  • addOrReplaceParams

    QueryKeyValue[] opcional

    A lista de pares de chave-valor de consulta a serem adicionados ou substituídos.

  • removeParams

    string[] opcional

    A lista de chaves de consulta a serem removidas.

Redirect

Propriedades

  • extensionPath

    string opcional

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

  • regexSubstitution

    string opcional

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

  • transformar

    URLTransform opcional

    Transformações de URL a serem executadas.

  • url

    string opcional

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

RegexOptions

Chrome 87 ou mais recente

Propriedades

  • isCaseSensitive

    booleano opcional

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

  • Regex

    string

    O Expresson normal a ser verificado.

  • requireCapturing

    booleano opcional

    Indica se o regex especificado requer captura. A captura só é necessária para regras de redirecionamento que especificam uma ação regexSubstition. O valor padrão é falso.

RequestDetails

Propriedades

  • documentId

    string opcional

    Chrome 106 ou mais recente

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

  • documentLifecycle

    DocumentLifecycle opcional

    Chrome 106 ou mais recente

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

  • frameId

    number

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

  • frameType

    FrameType opcional

    Chrome 106 ou mais recente

    O tipo do frame, se esta solicitação for para um frame.

  • iniciador

    string opcional

    A origem em que a solicitação foi iniciada. Isso não muda com redirecionamentos. Se a origem for opaca, a string "null" será usada.

  • method

    string

    Método HTTP padrão.

  • parentDocumentId

    string opcional

    Chrome 106 ou mais recente

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

  • parentFrameId

    number

    ID do frame que une o frame que enviou a solicitação. Definido como -1 se nenhum frame pai existir.

  • requestId

    string

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

  • tabId

    number

    O ID da guia em que a solicitação ocorre. Defina como -1 se a solicitação não estiver relacionada a uma guia.

  • O tipo de recurso da solicitação.

  • url

    string

    O URL da solicitação.

RequestMethod

Chrome 91 ou mais recente

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

Tipo enumerado

"get"

"head"

"patch"

ResourceType

Descreve o tipo de recurso da solicitação de rede.

Tipo enumerado

"main_frame"
.

"sub_frame"

"script"

"xmlhttprequest"

"ping"

"csp_report"

"websocket"

"webtransport"

"webbundle"

Rule

Propriedades

  • ação

    RuleAction

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

  • condição

    RuleCondition

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

  • id

    number

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

  • campanha

    número opcional

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

RuleAction

Propriedades

  • Redirecionar

    Redirecionamento opcional

    Descreve como o redirecionamento deve ser realizado. Válida apenas para regras de redirecionamento.

  • requestHeaders

    ModifyHeaderInfo[] opcional

    Chrome 86 ou mais recente

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

  • responseHeaders

    ModifyHeaderInfo[] opcional

    Chrome 86 ou mais recente

    Os cabeçalhos de resposta a serem modificados para a solicitação. Válida somente 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 for correspondente.

Tipo enumerado

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

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

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

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

"modifyHeaders"
Modifique os cabeçalhos de solicitação/resposta da solicitação de rede.

"allowAllRequests"
Permite todas as solicitações em uma hierarquia de frames, incluindo a própria solicitação de frame.

RuleCondition

Propriedades

  • domainType

    DomainType opcional

    Especifica se a solicitação de rede é própria ou de terceiros para o domínio de origem. Se omitido, todas as solicitações são aceitas.

  • domínios

    string[] opcional

    Descontinuado desde o Chrome 101

    Use initiatorDomains

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

  • excludedDomains

    string[] opcional

    Descontinuado desde o Chrome 101

    Use excludedInitiatorDomains

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

  • excludedInitiatorDomains

    string[] opcional

    Chrome 101 e mais recentes

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

    Observações:

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

    string[] opcional

    Chrome 101 e mais recentes

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

    Observações:

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

    RequestMethod[] opcional

    Chrome 91 ou mais recente

    Lista de métodos de solicitação não correspondentes à regra. Somente requestMethods ou excludedRequestMethods precisa ser especificado. Se nenhum deles for especificado, todos os métodos de solicitação serão correspondidos.

  • excludedResourceTypes

    ResourceType[] opcional

    Lista de tipos de recursos para os quais a regra não corresponde. Somente resourceTypes ou excludedResourceTypes precisa ser especificado. Se nenhum deles for especificado, todos os tipos de recurso, exceto "main_frame", serão bloqueados.

  • excludedTabIds

    number[] opcional

    Chrome 92 ou mais recente

    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 com escopo de sessão.

  • initiatorDomains

    string[] opcional

    Chrome 101 e mais recentes

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

    Observações:

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

    booleano opcional

    Define se urlFilter 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: é possível especificar apenas urlFilter ou regexFilter.

    Observação: o regexFilter precisa ser composto apenas por caracteres ASCII. É feita a correspondência com um URL em que o host é codificado no formato punycode (no caso de domínios internacionalizados) e todos os outros caracteres não ASCII são codificados em utf-8.

  • requestDomains

    string[] opcional

    Chrome 101 e mais recentes

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

    Observações:

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

    RequestMethod[] opcional

    Chrome 91 ou mais recente

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

    Observação: a especificação de uma condição de regra requestMethods também excluirá solicitações não HTTP(S), mas a especificação de 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 recurso sub_frame e main_frame.

  • tabIds

    number[] opcional

    Chrome 92 ou mais recente

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

  • urlFilter

    string opcional

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

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

    '|' : âncora esquerda/direita: se usado em qualquer extremidade do padrão, especifica o início/fim do URL, respectivamente.

    '||' : âncora de nome de domínio: se usada no início do padrão, especifica o início de um (sub)domínio do URL.

    '^' : caractere separador: corresponde a tudo, exceto uma letra, um dígito ou um dos seguintes caracteres: _, -, . ou %. Isso também corresponde ao fim do URL.

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

    Se omitido, todos os URLs serão correspondentes. Strings em branco não são permitidas.

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

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

    Observação: o urlFilter precisa ser composto apenas por caracteres ASCII. É feita a correspondência com um URL em que o host é codificado no formato punycode (no caso de domínios internacionalizados) e todos os outros caracteres não ASCII são codificados em utf-8. Por exemplo, quando o URL da solicitação for http://abc.рgraphics?q=&, urlFilter será correspondido ao URL http://abc.xn--p1ai/?q=%D1%84.

Ruleset

Propriedades

  • ativado

    boolean

    Indica se o conjunto de regras está ativado por padrão.

  • id

    string

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

  • caminho

    string

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

RulesMatchedDetails

Propriedades

  • rulesMatchedInfo

    MatchedRuleInfo[]

    Regras que correspondem ao filtro especificado.

TabActionCountUpdate

Chrome 89 ou mais recente

Propriedades

  • increment

    number

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

  • tabId

    number

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

TestMatchOutcomeResult

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.

  • tabId

    número opcional

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

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

  • url

    string

    O URL da solicitação hipotética.

UnsupportedRegexReason

Chrome 87 ou mais recente

Descreve o motivo pelo qual uma determinada expressão regular não é compatível.

Tipo enumerado

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

"memoryLimitExcluídoed"
A expressão regular excede o limite de memória.

UpdateRuleOptions

Chrome 87 ou mais recente

Propriedades

  • addRules

    Regra[] opcional

    Regras a serem adicionadas.

  • removeRuleIds

    number[] opcional

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

UpdateRulesetOptions

Chrome 87 ou mais recente

Propriedades

  • disableRulesetIds

    string[] opcional

    O conjunto de IDs correspondente a uma Ruleset estática que precisa ser desativada.

  • enableRulesetIds

    string[] opcional

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

UpdateStaticRulesOptions

Chrome 111 ou mais recente

Propriedades

  • disableRuleIds

    number[] opcional

    Conjunto de IDs correspondentes às regras no Ruleset a ser desativado.

  • enableRuleIds

    number[] opcional

    Conjunto de IDs correspondentes às regras no Ruleset a ser ativado.

  • 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 começar com '#'.

  • anfitrião

    string opcional

    O novo host da solicitação.

  • senha

    string opcional

    A nova senha da solicitação.

  • caminho

    string opcional

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

  • porta

    string opcional

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

  • consulta

    string opcional

    A nova consulta para a solicitação. Deve estar vazio (nesse caso, a consulta existente é apagada) ou deve começar com "?".

  • queryTransform

    QueryTransform opcional

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

  • planejar

    string opcional

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

  • nome de usuário

    string opcional

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

Propriedades

DYNAMIC_RULESET_ID

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

Valor

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

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

Valor

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89 ou mais recente

O número mínimo de regras estáticas garantidas para uma extensão em todos os conjuntos de regras estáticos ativados. Todas as regras acima desse limite são contabilizadas no limite de regras estáticas globais.

Valor

30.000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

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

Valor

20

MAX_NUMBER_OF_DYNAMIC_RULES

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

Valor

30.000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94 ou 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 para 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 com escopo da sessão que uma extensão pode adicionar.

Valor

5.000

MAX_NUMBER_OF_STATIC_RULESETS

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

Valor

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120 ou mais recente

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

Valor

5.000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120 ou mais recente

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

Valor

5.000

SESSION_RULESET_ID

Chrome 90 ou mais recente

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

Valor

"_session"

Métodos

getAvailableStaticRuleCount()

Promessa Chrome 89 ou 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 regra estática global seja atingido.

Parâmetros

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (count: number)=>void

    • contagem

      number

Retorna

  • Prometer<número>

    Chrome 91 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

getDisabledRuleIds()

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

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

Parâmetros

  • Especifica o conjunto de regras a ser consultado.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (disabledRuleIds: number[])=>void

    • disabledRuleIds

      Número[]

Retorna

  • Prometer<número[]>

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

getDynamicRules()

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

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

Parâmetros

  • Função filter

    GetRulesFilter opcional

    Chrome 111 ou mais recente

    Um objeto para filtrar a lista de regras buscadas.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (rules: Rule[])=>void

Retorna

  • Prometer<Rule[]>

    Chrome 91 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

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 optional

    O parâmetro callback tem esta aparência: 

    (rulesetIds: string[])=>void

    • rulesetIds

      string[]

Retorna

  • Promessa<string[]>

    Chrome 91 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

getMatchedRules()

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

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

Parâmetros

Retorna

  • Chrome 91 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

getSessionRules()

Promessa Chrome 90 e versões mais recentes 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
  callback?: function,
)

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

Parâmetros

  • Função filter

    GetRulesFilter opcional

    Chrome 111 ou mais recente

    Um objeto para filtrar a lista de regras buscadas.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (rules: Rule[])=>void

Retorna

  • Prometer<Rule[]>

    Chrome 91 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

isRegexSupported()

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

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

Parâmetros

Retorna

  • Chrome 91 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

setExtensionActionOptions()

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

Configura se a contagem de ações para guias deve ser exibida como o texto do ícone da ação da extensão e fornece uma maneira de essa contagem de ações ser incrementada.

Parâmetros

  • callback

    função optional

    Chrome 89 ou mais recente

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 91 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

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, já que ele se destina ao uso durante o desenvolvimento de extensões.

Parâmetros

Retorna

  • Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

updateDynamicRules()

Promessa 
chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
  callback?: function,
)

Modifica o conjunto atual de regras dinâmicas da extensão. As regras com IDs listados em options.removeRuleIds são removidas primeiro e, em seguida, as regras fornecidas em options.addRules são adicionadas. Observações:

  • Essa atualização ocorre como uma única operação atômica: todas as regras especificadas são adicionadas e removidas ou um erro é retornado.
  • Essas regras são mantidas em todas as sessões do navegador e em todas as atualizações de extensões.
  • As regras estáticas especificadas como parte do pacote de extensão não podem ser removidas usando essa função.
  • MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES é o número máximo de regras dinâmicas e de sessão combinadas que uma extensão pode adicionar.

Parâmetros

  • Chrome 87 ou mais recente
  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 91 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

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 conjuntos de regras listados em options.enableRulesetIds são adicionados. O conjunto de conjuntos de regras estáticos ativados é mantido entre as sessões, mas não nas atualizações de extensões. Ou seja, a chave de manifesto rule_resources vai determinar o conjunto de conjuntos de regras estáticos ativados em cada atualização da extensão.

Parâmetros

  • Chrome 87 ou mais recente
  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 91 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

updateSessionRules()

Promessa Chrome 90 e 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 removidas primeiro e, em seguida, as regras fornecidas em options.addRules são adicionadas. Observações:

  • Essa atualização ocorre como uma única operação atômica: todas as regras especificadas são adicionadas e removidas ou um erro é retornado.
  • Essas regras não são mantidas entre as sessões e são salvas na memória.
  • MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES é o número máximo de regras dinâmicas e de sessão combinadas que uma extensão pode adicionar.

Parâmetros

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 91 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

updateStaticRules()

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

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

Parâmetros

Retorna

  • Promise<void>

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

Eventos

onRuleMatchedDebug

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

Disparado quando uma regra corresponde a uma solicitação. Disponível somente para extensões descompactadas com a permissão "declarativeNetRequestFeedback", porque ela é usada apenas para fins de depuração.

Parâmetros