chrome.declarativeNetRequest

Описание

API chrome.declarativeNetRequest используется для блокировки или изменения сетевых запросов путем указания декларативных правил. Это позволяет расширениям изменять сетевые запросы, не перехватывая их и не просматривая их содержимое, тем самым обеспечивая большую конфиденциальность.

Разрешения

declarativeNetRequest
declarativeNetRequestWithHostAccess

Права доступа " declarativeNetRequest " и " declarativeNetRequestWithHostAccess " предоставляют одинаковые возможности. Разница между ними заключается в моменте запроса или предоставления прав доступа.

"declarativeNetRequest"

При установке выдает предупреждение о правах доступа, но предоставляет неявный доступ к правилам allow , allowAllRequests и block . Используйте это по возможности, чтобы избежать необходимости запрашивать полный доступ к хостам.

"declarativeNetRequestFeedback"

Включает функции отладки для распакованных расширений , в частности, getMatchedRules() и onRuleMatchedDebug .

"declarativeNetRequestWithHostAccess"

Предупреждение о правах доступа не отображается во время установки, но перед выполнением каких-либо действий на хосте необходимо запросить права доступа к хосту. Это уместно, если вы хотите использовать декларативные правила сетевых запросов в расширении, которое уже имеет права доступа к хосту, без генерации дополнительных предупреждений.

Доступность

Chrome 84+

Манифест

В дополнение к описанным ранее разрешениям, для некоторых типов наборов правил, в частности статических наборов правил, требуется объявить ключ манифеста "declarative_net_request" , который должен представлять собой словарь с единственным ключом "rule_resources" . Этот ключ представляет собой массив, содержащий словари типа Ruleset , как показано ниже. (Обратите внимание, что имя "Ruleset" не отображается в JSON-файле манифеста, поскольку это всего лишь массив.) Статические наборы правил описаны далее в этом документе.

{
  "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/*"
  ],
  ...
}

Правила и своды правил

Для использования этого API необходимо указать один или несколько наборов правил. Набор правил содержит массив правил. Одно правило выполняет одно из следующих действий:

• Заблокировать сетевой запрос.
• Обновите схему (с HTTP на HTTPS).
• Предотвратите блокировку запроса, отменив действие любых соответствующих правил блокировки.
• Перенаправить сетевой запрос.
• Изменяйте заголовки запроса или ответа.

Существует три типа наборов правил, управление которыми осуществляется несколько по-разному.

Динамический

Сохраняются между сессиями браузера и обновлениями расширений и управляются с помощью JavaScript во время использования расширения.

Сессия

Сбрасывается при закрытии браузера и при установке новой версии расширения. Правила сессии управляются с помощью JavaScript во время использования расширения.

Статический

Упаковывается, устанавливается и обновляется при установке или обновлении расширения. Статические правила хранятся в файлах правил в формате JSON и перечисляются в файле манифеста.

Динамические и ограниченные рамками сессии наборы правил

Управление динамическими и сессионными наборами правил осуществляется с помощью JavaScript во время использования расширения.

• Динамические правила сохраняются между сеансами браузера и обновлениями расширений.
• Правила сессии сбрасываются при закрытии браузера и при установке новой версии расширения.

Существует только один экземпляр каждого из этих типов наборов правил. Расширение может динамически добавлять или удалять правила, вызывая методы updateDynamicRules() и updateSessionRules() , при условии, что не превышены лимиты правил. Информацию о лимитах правил см. в разделе «Лимиты правил» . Пример этого можно увидеть в разделе «Примеры кода» .

Статические наборы правил

В отличие от динамических и сессионных правил, статические правила упаковываются, устанавливаются и обновляются при установке или обновлении расширения. Они хранятся в файлах правил в формате JSON, которые указываются расширению с помощью ключей "declarative_net_request" и "rule_resources" как описано выше , а также в одном или нескольких словарях Ruleset . Словарь Ruleset содержит путь к файлу правил, идентификатор набора правил, содержащегося в файле, и информацию о том, включен или выключен набор правил. Последние два параметра важны при программном включении или отключении набора правил.

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

Для проверки файлов правил загрузите ваше расширение в распакованном виде . Ошибки и предупреждения о недопустимых статических правилах отображаются только для распакованных расширений. Недопустимые статические правила в упакованных расширениях игнорируются.

Ускоренное рассмотрение

Изменения в статических наборах правил могут подлежать ускоренной проверке. См. раздел «Ускоренная проверка» для получения информации о допустимых изменениях .

Включение и отключение статических правил и наборов правил.

Как отдельные статические правила, так и полные наборы статических правил могут быть включены или отключены во время выполнения.

Набор включенных статических правил и наборов правил сохраняется между сеансами браузера. Ни те, ни другие не сохраняются при обновлении расширений, а это значит, что после обновления будут доступны только те правила, которые вы решили оставить в своих файлах правил.

В целях повышения производительности также существуют ограничения на количество правил и наборов правил, которые могут быть включены одновременно. Вызовите функцию getAvailableStaticRuleCount() , чтобы проверить количество дополнительных правил, которые могут быть включены. Информацию об ограничениях на правила см. в разделе «Ограничения на правила» .

Для включения или отключения статических правил вызовите метод updateStaticRules() . Этот метод принимает объект UpdateStaticRulesOptions , содержащий массивы идентификаторов правил, которые нужно включить или отключить. Идентификаторы определяются с помощью ключа "id" словаря Ruleset . Максимальное количество отключенных статических правил — 5000.

Для включения или отключения статических наборов правил вызовите метод ` updateEnabledRulesets() . Этот метод принимает объект UpdateRulesetOptions , содержащий массивы идентификаторов наборов правил, которые нужно включить или отключить. Идентификаторы определяются с помощью ключа "id" словаря Ruleset .

Правила построения

Независимо от типа, правило начинается с четырех полей, как показано ниже. Ключи "id" и "priority" принимают числовое значение, а ключи "action" и "condition" могут содержать несколько условий блокировки и перенаправления. Следующее правило блокирует все запросы скриптов, исходящие с "foo.com" на любой URL-адрес, содержащий "abc" в качестве подстроки.

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

соответствие URL

Declarative Net Request предоставляет возможность сопоставлять URL-адреса либо с помощью синтаксиса сопоставления с шаблоном, либо с помощью регулярных выражений.

синтаксис фильтра URL

Ключ "condition" правила позволяет использовать ключ "urlFilter" для обработки URL-адресов в указанном домене. Шаблоны создаются с помощью токенов сопоставления шаблонов . Вот несколько примеров.

urlFilter	Матчи	Не совпадает
"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://baexample.com/xyz https://a.example.company	https://example.com/
"|https*"	https://example.com	http://example.com/ http://https.com
"example*^123|"	https://example.com/123 http://abc.com/example?123	https://example.com/1234 https://abc.com/example0123

Регулярные выражения

В условиях также можно использовать регулярные выражения. См. ключ "regexFilter" . Чтобы узнать об ограничениях, применяемых к этим условиям, см. Правила, использующие регулярные выражения .

Указывайте правильные условия URL-адреса

При написании правил следует всегда тщательно проверять соответствие всему домену. В противном случае ваше правило может сработать в неожиданных ситуациях. Например, при использовании синтаксиса сопоставления с шаблоном:

• google.com некорректно соответствует https://example.com/?param=google.com
• ||google.com ошибочно соответствует https://google.company
• https://www.google.com ошибочно соответствует https://example.com/?param=https://www.google.com

Рекомендуем использовать:

• ||google.com/ , который соответствует всем путям и всем поддоменам.
• |https://www.google.com/ , который соответствует всем путям и не содержит поддоменов.

Аналогично, используйте символы ^ и / для привязки регулярного выражения. Например, ^https:\/\/www\.google\.com\/ соответствует любому пути на https://www.google.com.

Оценка правил

Правила DNR применяются браузером на различных этапах жизненного цикла сетевого запроса.

Перед запросом

Перед отправкой запроса расширение может заблокировать или перенаправить его (включая обновление схемы с HTTP на HTTPS) с помощью соответствующего правила.

Для каждого расширения браузер определяет список соответствующих правил. Правила с действием modifyHeaders здесь не включены, поскольку они будут обработаны позже. Кроме того, правила с условием responseHeaders будут рассмотрены позже (когда будут доступны заголовки ответа) и не включены.

Затем для каждого расширения Chrome выбирает не более одного кандидата на запрос. Chrome находит соответствующее правило, упорядочивая все совпадающие правила по приоритету. Правила с одинаковым приоритетом упорядочиваются по действию ( allow или allowAllRequests > block > upgradeScheme > redirect ).

Если кандидат относится к правилу allow или allowAllRequests , или если фрейм, в котором отправляется запрос, ранее соответствовал правилу allowAllRequests с более высоким или равным приоритетом из этого расширения, запрос считается «разрешенным», и расширение не окажет на него никакого влияния.

Если несколько расширений хотят заблокировать или перенаправить этот запрос, выбирается одно действие. Chrome делает это, сортируя правила в порядке block > redirect или upgradeScheme > allow или allowAllRequests . Если два правила имеют одинаковый тип, Chrome выбирает правило из наиболее недавно установленного расширения.

Внимание: производители браузеров договорились не стандартизировать порядок выполнения правил с одинаковым действием и приоритетом. Этот порядок может меняться между запусками или версиями браузеров, даже если правила распределены между несколькими типами наборов правил (например, статическое правило и правило сессии). Если порядок важен, всегда следует явно указывать приоритет.

Перед отправкой заголовков запроса

Перед отправкой заголовков запроса на сервер Chrome, заголовки обновляются в соответствии с правилами modifyHeaders .

В рамках одного расширения Chrome формирует список необходимых изменений, находя все соответствующие правила modifyHeaders . Как и прежде, включаются только те правила, которые имеют более высокий приоритет, чем любые соответствующие правила allow или allowAllRequests .

Эти правила применяются Chrome в таком порядке, что правила из недавно установленного расширения всегда оцениваются раньше правил из более старого расширения. Кроме того, правила с более высоким приоритетом из одного расширения всегда применяются раньше правил с более низким приоритетом из того же расширения. Примечательно, что это справедливо даже для разных расширений:

• Если правило добавляет элементы в заголовок, то правила с более низким приоритетом могут добавлять элементы только в этот заголовок. Операции установки и удаления не допускаются.
• Если правило задает заголовок, то к этому заголовку могут добавляться только правила с более низким приоритетом из того же расширения. Другие изменения не допускаются.
• Если правило удаляет заголовок, то правила с более низким приоритетом не могут в дальнейшем изменять этот заголовок.

После получения ответа

После получения заголовков ответа Chrome оценивает правила, содержащие условие responseHeaders .

После сортировки этих правил по action и priority и исключения любых правил, которые стали избыточными из-за совпадения с правилом allow или allowAllRequests (это происходит аналогично шагам в разделе "Перед запросом"), Chrome может заблокировать или перенаправить запрос от имени расширения.

Обратите внимание, что если запрос дошёл до этой стадии, значит, он уже отправлен на сервер, и сервер получил данные, такие как тело запроса. Правило блокировки или перенаправления с условием в заголовках ответа всё равно будет выполнено, но фактически не сможет заблокировать или перенаправить запрос.

В случае правила блокировки, обработка запроса осуществляется путем получения заблокированного ответа страницей, отправившей запрос, и досрочного завершения запроса браузером Chrome. В случае правила перенаправления, Chrome отправляет новый запрос на перенаправленный URL. Убедитесь, что такое поведение соответствует требованиям конфиденциальности вашего расширения.

Если запрос не заблокирован и не перенаправлен, Chrome применяет все правила modifyHeaders . Применение изменений к заголовкам ответа работает так же, как описано в разделе «Перед отправкой заголовков запроса». Применение изменений к заголовкам запроса ничего не меняет, поскольку запрос уже был отправлен.

Правила безопасности

Безопасные правила определяются как правила с действием типа block , allow , allowAllRequests или upgradeScheme . На эти правила распространяется увеличенная квота динамических правил.

Ограничения правил

Загрузка и оценка правил в браузере сопряжены с дополнительными затратами на производительность, поэтому при использовании API действуют определенные ограничения. Ограничения зависят от типа используемого правила.

Статические правила

Статические правила — это правила, указанные в файлах правил, объявленных в файле манифеста. Расширение может указать до 100 наборов статических правил в качестве части ключа манифеста "rule_resources" , но одновременно может быть включено только 50 из этих наборов правил. Последнее называется MAX_NUMBER_OF_ENABLED_STATIC_RULESETS . В совокупности этим наборам правил гарантируется не менее 30 000 правил. Это называется GUARANTEED_MINIMUM_STATIC_RULES .

Примечание: До версии Chrome 120 количество статических наборов правил для расширений было ограничено 50, и одновременно можно было включить только 10 из них. Используйте поле minimum_chrome_version в манифесте, чтобы ограничить версии Chrome, которые могут установить ваше расширение.

Количество доступных правил после этого зависит от того, сколько правил включено всеми расширениями, установленными в браузере пользователя. Это число можно узнать во время выполнения, вызвав метод getAvailableStaticRuleCount() . Пример этого можно увидеть в разделе примеров кода .

Примечание: Начиная с Chrome 128, если пользователь отключает расширение через chrome://extensions, статические правила расширения больше не будут учитываться в глобальном лимите статических правил. Это потенциально освобождает квоту статических правил для других расширений, но также означает, что при повторном включении расширения у него может быть меньше доступных статических правил, чем раньше.

Правила сессии

Расширение может содержать до 5000 правил сессии. Это значение отображается как MAX_NUMBER_OF_SESSION_RULES .

До версии Chrome 120 существовало ограничение в 5000 правил, объединяющих динамические и сессионные правила.

Динамические правила

Расширение может содержать не менее 5000 динамических правил. Это значение отображается как MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES .

Начиная с Chrome 121, существует более высокий лимит в 30 000 правил для безопасных динамических правил, который отображается как MAX_NUMBER_OF_DYNAMIC_RULES . Любые небезопасные правила, добавленные в пределах лимита в 5000, также будут учитываться в этом лимите.

До версии Chrome 120 существовало ограничение в 5000 правил, объединяющих динамические и сессионные правила.

Правила, использующие регулярные выражения

Все типы правил могут использовать регулярные выражения; однако общее количество правил регулярных выражений каждого типа не может превышать 1000. Это называется MAX_NUMBER_OF_REGEX_RULES .

Кроме того, размер каждого правила после компиляции должен быть менее 2 КБ. Это примерно соответствует сложности правила. Если вы попытаетесь загрузить правило, превышающее этот лимит, вы увидите предупреждение, подобное приведенному ниже, и правило будет проигнорировано.

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

Взаимодействие с работниками сферы услуг

Оператор declarativeNetRequest применяется только к запросам, достигающим сетевого стека. Это включает ответы из HTTP-кэша, но может не включать ответы, проходящие через обработчик onfetch сервис-воркера. Оператор declarativeNetRequest не повлияет на ответы, сгенерированные сервис-воркером или полученные из CacheStorage , но повлияет на вызовы fetch() выполняемые в сервис-воркере.

Ресурсы, доступные через Интернет

Правило declarativeNetRequest не может перенаправлять запрос с общедоступного ресурса на ресурс, недоступный через веб-интерфейс. Это вызовет ошибку. Это справедливо даже в том случае, если указанный веб-доступный ресурс принадлежит расширению, осуществляющему перенаправление. Для объявления ресурсов для declarativeNetRequest используйте массив "web_accessible_resources" из манифеста.

Изменение заголовка

Операция добавления поддерживается только для следующих заголовков запроса: accept , accept-encoding , accept-language , access-control-request-headers , cache-control , connection , content-language , cookie , forwarded , if-match , if-none-match , keep-alive , range , te , trailer , transfer-encoding , upgrade , user-agent , via , want-digest , x-forwarded-for . Этот список разрешенных заголовков чувствителен к регистру ( ошибка 449152902 ).

При добавлении в заголовок запроса или ответа браузер будет использовать соответствующий разделитель, где это возможно.

Примеры

Примеры кода

Обновить динамические правила

В следующем примере показано, как вызвать метод updateDynamicRules() . Процедура вызова метода updateSessionRules() аналогична.

// 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
});

Обновить статические наборы правил

В следующем примере показано, как включать и отключать наборы правил, учитывая количество доступных и максимальное количество включенных статических наборов правил. Это необходимо делать, когда количество необходимых статических правил превышает допустимое. Для этого некоторые из ваших наборов правил должны быть установлены, а некоторые — отключены (установив значение параметра "Enabled" в false в файле манифеста).

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);
}

Примеры правил

Приведенные ниже примеры иллюстрируют, как Chrome расставляет приоритеты в правилах расширения. При их просмотре вы можете открыть правила расстановки приоритетов в отдельном окне.

Ключ «приоритета»

Для просмотра этих примеров требуется разрешение хоста на доступ к *://*.example.com/* .

Чтобы определить приоритет конкретного URL-адреса, посмотрите на ключи "priority" (определяемые разработчиком), "action" и "urlFilter" . В приведенных примерах используются примеры файлов правил, показанные ниже.

Перейти по ссылке https://google.com

Для этого URL-адреса действуют два правила: правила с идентификаторами 1 и 4. Правило с идентификатором 1 применяется, поскольку действия "block" имеют более высокий приоритет, чем действия "redirect" . Остальные правила не применяются, поскольку они предназначены для более длинных URL-адресов.

Перейти по ссылке https://google.com/1234

Из-за большей длины URL-адреса правило с ID 2 теперь соответствует требованиям в дополнение к правилам с ID 1 и 4. Правило с ID 2 применяется, потому что "allow" имеет более высокий приоритет, чем "block" и "redirect" .

Перейти по ссылке https://google.com/12345

Все четыре правила соответствуют этому URL-адресу. Правило с ID 3 применяется, поскольку его приоритет, определенный разработчиком, является наивысшим в группе.

[
  {
    "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"] }
  },
]

Перенаправления

Для выполнения приведенного ниже примера требуются права доступа к *://*.example.com/* со стороны хоста.

В следующем примере показано, как перенаправить запрос с example.com на страницу внутри самого расширения. Путь расширения /a.jpg преобразуется в chrome-extension://EXTENSION_ID/a.jpg , где EXTENSION_ID — это идентификатор вашего расширения. Для корректной работы в манифесте необходимо указать /a.jpg как веб-доступный ресурс .

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

В следующем примере используется ключ "transform" для перенаправления на поддомен example.com. Для перехвата запросов с любой схемой от example.com используется якорь доменного имени ("||"). Ключ "scheme" в "transform" указывает, что перенаправления на поддомен всегда будут использовать "https".

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

В следующем примере используются регулярные выражения для перенаправления с https://www.abc.xyz.com/path на https://abc.xyz.com/path . Обратите внимание, что в ключе "regexFilter" точки экранированы, а группа захвата выбирает либо "abc", либо "def". Ключ "regexSubstitution" указывает первое найденное совпадение регулярного выражения с помощью символа "\1". В данном случае "abc" захватывается из перенаправленного URL и помещается в подстановку.

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

Заголовки

В следующем примере удаляются все файлы cookie как из основного фрейма, так и из любых дочерних фреймов.

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

Типы

DomainType

Это описывает, является ли запрос запросом первой или третьей стороной по отношению к фрейму, в котором он был инициирован. Запрос считается запросом первой стороны, если он имеет тот же домен (eTLD+1), что и фрейм, в котором он был инициирован.

Перечисление

"firstParty"
Сетевой запрос является первым участником того кадра, в котором он был инициирован.

"третья сторона"
Сетевой запрос является запросом от третьей стороны по отношению к той системе, в которой он был инициирован.

ExtensionActionOptions

Chrome 88+

Характеристики

• displayActionCountAsBadgeText

  логический необязательный

  Автоматически ли отображать счетчик действий для страницы в качестве текста значка расширения. Эта настройка сохраняется между сессиями.

• tabUpdate

  TabActionCountUpdate (необязательно)

  Chrome 89+

  Подробности о том, как следует корректировать счетчик действий на вкладке.

GetDisabledRuleIdsOptions

Chrome 111+

Характеристики

• rulesetId

  нить

  Идентификатор, соответствующий статическому Ruleset .

GetRulesFilter

Chrome 111+

Характеристики

• ruleIds

  число[] необязательно

  Если указано иное, включаются только правила с совпадающими идентификаторами.

HeaderInfo

Chrome 128+

Характеристики

• исключенные значения

  строка[] необязательный

  Если указано, это условие не выполняется, если заголовок существует, но его значение содержит хотя бы один элемент из этого списка. Используется тот же синтаксис шаблона соответствия, что и values .

• заголовок

  нить

  Название заголовка. Это условие выполняется только в том случае, если не указаны values и excludedValues .

• ценности

  строка[] необязательный

  Если указано, это условие выполняется, если значение заголовка соответствует хотя бы одному шаблону из этого списка. Поддерживается сопоставление значений заголовков без учета регистра, а также следующие конструкции:

  '*' : Соответствует любому количеству символов.

  '?' : Соответствует нулю или одному символу (символам).

  Символы '*' и '?' можно экранировать обратной косой чертой, например, '\*' и '\?'.

HeaderOperation

Chrome 86+

Здесь описаны возможные операции для правила "modifyHeaders".

Перечисление

"добавить"
Добавляет новую запись для указанного заголовка. При изменении заголовков запроса эта операция поддерживается только для определенных заголовков .

"набор"
Устанавливает новое значение для указанного заголовка, удаляя все существующие заголовки с тем же именем.

"удалять"
Удаляет все записи для указанного заголовка.

IsRegexSupportedResult

Chrome 87+

Характеристики

• поддерживается

  логический

• причина

  UnsupportedRegexReason optional

  Указывает причину, по которой регулярное выражение не поддерживается. Предоставляется только в том случае, если isSupported имеет значение false.

MatchedRule

Характеристики

• ruleId

  число

  Идентификатор соответствующего правила.

• rulesetId

  нить

  Идентификатор набора Ruleset к которому принадлежит это правило. Для правила, входящего в набор динамических правил, он будет равен DYNAMIC_RULESET_ID .

MatchedRuleInfo

Характеристики

• правило

  MatchedRule

• tabId

  число

  tabId — идентификатор вкладки, с которой поступил запрос, если вкладка все еще активна. В противном случае — -1.

• метка времени

  число

  Время, когда правило сработало. Временные метки будут соответствовать соглашениям JavaScript для времени, то есть количеству миллисекунд с начала эпохи.

MatchedRuleInfoDebug

Характеристики

• запрос

  RequestDetails

  Подробная информация о запросе, для которого было найдено соответствующее правило.

• правило

  MatchedRule

MatchedRulesFilter

Характеристики

• minTimeStamp

  число необязательно

  Если указано иное, сопоставляется только с правилами, действующими после указанной временной метки.

• tabId

  число необязательно

  Если указано, сопоставляет только правила для данной вкладки. Если установлено значение -1, сопоставляет правила, не связанные ни с одной активной вкладкой.

ModifyHeaderInfo

Chrome 86+

Характеристики

• заголовок

  нить

  Название заголовка, подлежащего изменению.

• операция

  HeaderOperation

  Операция, которая должна быть выполнена над заголовком.

• ценить

  строка необязательный

  Новое значение для заголовка. Необходимо указывать для операций append и set .

QueryKeyValue

Характеристики

• ключ

  нить

• replaceOnly

  логический необязательный

  Chrome 94+

  Если значение равно true, ключ запроса заменяется только в том случае, если он уже присутствует. В противном случае, ключ также добавляется, если он отсутствует. По умолчанию — false.

• ценить

  нить

QueryTransform

Характеристики

• addOrReplaceParams

  QueryKeyValue [] необязательный

  Список пар ключ-значение запроса, которые необходимо добавить или заменить.

• removeParams

  строка[] необязательный

  Список ключей запроса, подлежащих удалению.

Redirect

Характеристики

• extensionPath

  строка необязательный

  Путь относительно каталога расширений. Должен начинаться с '/'.

• regexSubstitution

  строка необязательный

  Шаблон подстановки для правил, определяющих regexFilter . Первое совпадение regexFilter в URL-адресе будет заменено этим шаблоном. Внутри regexSubstitution можно использовать цифры, экранированные обратной косой чертой (\1–\9), для вставки соответствующих групп захвата. \0 обозначает весь совпадающий текст.

• трансформировать

  URLTransform ( необязательно)

  Для выполнения преобразования URL-адресов.

• url

  строка необязательный

  URL-адрес перенаправления. Перенаправления на URL-адреса JavaScript не допускаются.

RegexOptions

Chrome 87+

Характеристики

• isCaseSensitive

  логический необязательный

  Указывает, чувствительно ли указанное regex . По умолчанию — true.

• регулярное выражение

  нить

  Регулярное выражение для проверки.

• requireCapturing

  логический необязательный

  Требуется ли перехват указанного regex . Перехват требуется только для правил перенаправления, которые указывают действие regexSubstition . По умолчанию — false.

RequestDetails

Характеристики

• documentId

  строка необязательный

  Chrome 106+

  Уникальный идентификатор документа фрейма, если данный запрос относится к фрейму.

• жизненный цикл документа

  Жизненный цикл документа ( необязательно)

  Chrome 106+

  Жизненный цикл документа фрейма, если данный запрос относится к фрейму.

• frameId

  число

  Значение 0 указывает на то, что запрос выполняется в главном фрейме; положительное значение указывает идентификатор подфрейма, в котором выполняется запрос. Если документ (под)фрейма загружен ( type main_frame или sub_frame ), frameId указывает идентификатор этого фрейма, а не идентификатор внешнего фрейма. Идентификаторы фреймов уникальны в пределах одной вкладки.

• frameType

  FrameType ( необязательно)

  Chrome 106+

  Укажите тип рамки, если запрос касается именно рамки.

• инициатор

  строка необязательный

  Источник, откуда был инициирован запрос. Он не меняется при перенаправлениях. Если это непрозрачный источник, будет использоваться строка 'null'.

• метод

  нить

  Стандартный HTTP-метод.

• parentDocumentId

  строка необязательный

  Chrome 106+

  Уникальный идентификатор родительского документа фрейма, если данный запрос относится к фрейму и имеет родительский документ.

• parentFrameId

  число

  Идентификатор кадра, который содержит кадр, отправивший запрос. Установите значение -1, если родительский кадр отсутствует.

• requestId

  нить

  Идентификатор запроса. Идентификаторы запросов уникальны в рамках одной браузерной сессии.

• tabId

  число

  Идентификатор вкладки, в которой выполняется запрос. Установите значение -1, если запрос не связан с вкладкой.

• тип

  ResourceType

  Тип ресурса запроса.

• url

  нить

  URL запроса.

RequestMethod

Chrome 91+

В этом описании представлен метод HTTP-запроса к сети.

Перечисление

"соединять"

"удалить"

"получать"

"голова"

"параметры"

"пластырь"

"почта"

"помещать"

"другой"

ResourceType

Здесь описывается тип ресурса, к которому относится сетевой запрос.

Перечисление

"main_frame"

"sub_frame"

"таблица стилей"

"сценарий"

"изображение"

"шрифт"

"объект"

"xmlhttprequest"

"пинг"

"csp_report"

«медиа»

"вебсокет"

"вебтранспорт"

"webbundle"

"другой"

Rule

Характеристики

• действие

  ПравилоДействие

  Действия, которые необходимо предпринять, если это правило совпало.

• состояние

  ПравилоУсловие

  Условие, при котором срабатывает это правило.

• идентификатор

  число

  Идентификатор, однозначно определяющий правило. Обязателен и должен быть >= 1.

• приоритет

  число необязательно

  Приоритет правила. По умолчанию — 1. Если указано, значение должно быть >= 1.

RuleAction

Характеристики

• перенаправление

  Перенаправление ( необязательно)

  Описывает, как должно выполняться перенаправление. Действительно только для правил перенаправления.

• заголовки запроса

  ModifyHeaderInfo [] optional

  Chrome 86+

  Заголовки запроса, которые необходимо изменить. Действительно только в том случае, если RuleActionType имеет значение "modifyHeaders".

• responseHeaders

  ModifyHeaderInfo [] optional

  Chrome 86+

  Заголовки ответа, которые необходимо изменить для запроса. Действительно только в том случае, если RuleActionType имеет значение "modifyHeaders".

• тип

  RuleActionType

  Тип действия, которое необходимо выполнить.

RuleActionType

Описывает тип действий, которые следует предпринять, если заданное условие правила соответствует условию.

Перечисление

"блокировать"
Заблокировать сетевой запрос.

"перенаправление"
Перенаправить сетевой запрос.

"позволять"
Разрешите сетевой запрос. Запрос не будет перехвачен, если существует правило разрешения, соответствующее ему.

«upgradeScheme»
Если запрос выполняется по протоколу HTTP или FTP, измените схему URL-адреса сетевого запроса на HTTPS.

"modifyHeaders"
Изменяйте заголовки запроса/ответа в сетевом запросе.

"allowAllRequests"
Разрешить все запросы в рамках иерархии кадров, включая сам запрос кадра.

RuleCondition

Характеристики

• domainType

  DomainType ( необязательно)

  Указывает, является ли сетевой запрос запросом от первого лица или от третьего лица по отношению к домену, с которого он исходит. Если этот параметр опущен, принимаются все запросы.

• домены

  строка[] необязательный

  Устарело с версии Chrome 101.

  Используйте initiatorDomains вместо этого.

  Это правило будет соответствовать только сетевым запросам, исходящим из списка domains .

• excludedDomains

  строка[] необязательный

  Устарело с версии Chrome 101.

  Используйте excludedInitiatorDomains вместо этого.

  Данное правило не будет соответствовать сетевым запросам, исходящим из списка excludedDomains .

• excludedInitiatorDomains

  строка[] необязательный

  Chrome 101+

  Это правило не будет соответствовать сетевым запросам, исходящим из списка excludedInitiatorDomains . Если список пуст или отсутствует, ни один домен не исключается. Это правило имеет приоритет над initiatorDomains .

  Примечания:

  • Также разрешены поддомены, такие как "a.example.com".
  • Записи должны состоять только из символов ASCII.
  • Для интернационализированных доменов используйте кодировку punycode.
  • Это соответствует инициатору запроса, а не URL-адресу запроса.
  • Исключение составляют также поддомены перечисленных доменов.
• excludedRequestDomains

  строка[] необязательный

  Chrome 101+

  Правило не будет соответствовать сетевым запросам, если домен совпадает с одним из доменов в списке excludedRequestDomains . Если список пуст или отсутствует, ни один домен не исключается. Это правило имеет приоритет над requestDomains .

  Примечания:

  • Также разрешены поддомены, такие как "a.example.com".
  • Записи должны состоять только из символов ASCII.
  • Для интернационализированных доменов используйте кодировку punycode.
  • Исключение составляют также поддомены перечисленных доменов.
• excludedRequestMethods

  RequestMethod [] optional

  Chrome 91+

  Список методов запроса, которым правило не соответствует. Необходимо указать только один из параметров: requestMethods или excludedRequestMethods . Если ни один из них не указан, будут соответствовать все методы запроса.

• excludedResourceTypes

  ResourceType [] необязательный

  Список типов ресурсов, которым правило не будет соответствовать. Необходимо указать только один из resourceTypes или excludedResourceTypes . Если ни один из них не указан, блокируются все типы ресурсов, кроме "main_frame".

• excludedResponseHeaders

  HeaderInfo [] необязательный

  Chrome 128+

  Правило не срабатывает, если запрос соответствует какому-либо условию заголовка ответа из этого списка (если указано). Если указаны и excludedResponseHeaders , и responseHeaders , то свойство excludedResponseHeaders имеет приоритет.

• excludedTabIds

  число[] необязательно

  Chrome 92+

  Список вкладок с идентификатором tabs.Tab.id , которым правило не должно соответствовать. Идентификатор tabs.TAB_ID_NONE исключает запросы, не исходящие из вкладки. Поддерживается только для правил, ограниченных областью действия сессии.

• excludedTopDomains

  строка[] необязательный

  В ожидании

  Правило не будет соответствовать сетевым запросам, если домен соответствующего фрейма верхнего уровня совпадает с одним из доменов в списке excludedTopDomains . Если список пуст или отсутствует, домены не исключаются. Это правило имеет приоритет над topDomains .

  Примечания:

  • Также разрешены поддомены, такие как "a.example.com".
  • Записи должны состоять только из символов ASCII.
  • Для интернационализированных доменов используйте кодировку punycode.
  • Исключение составляют также поддомены перечисленных доменов.
  • Для запросов, не имеющих связанного с ними фрейма верхнего уровня (например, запросы, инициированные ServiceWorker), вместо этого рассматривается домен инициатора запроса.
• initiatorDomains

  строка[] необязательный

  Chrome 101+

  Правило будет соответствовать только сетевым запросам, исходящим из списка initiatorDomains . Если список опущен, правило применяется к запросам со всех доменов. Пустой список не допускается.

  Примечания:

  • Также разрешены поддомены, такие как "a.example.com".
  • Записи должны состоять только из символов ASCII.
  • Для интернационализированных доменов используйте кодировку punycode.
  • Это соответствует инициатору запроса, а не URL-адресу запроса.
  • Также выполняется сопоставление субдоменов перечисленных доменов.
• isUrlFilterCaseSensitive

  логический необязательный

  Определяет, чувствителен ли регистр urlFilter или regexFilter (в зависимости от того, какой указан). По умолчанию — false.

• regexFilter

  строка необязательный

  Регулярное выражение для сопоставления с URL-адресом сетевого запроса. Используется синтаксис RE2 .

  Примечание: Можно указать только один из параметров urlFilter или regexFilter .

  Примечание: regexFilter должно состоять только из символов ASCII. Оно сопоставляется с URL-адресом, в котором хост закодирован в формате punycode (в случае интернационализированных доменов), а любые другие символы, не являющиеся ASCII, закодированы в формате utf-8.

• requestDomains

  строка[] необязательный

  Chrome 101+

  Правило будет соответствовать сетевым запросам только в том случае, если домен совпадает с одним из доменов в списке requestDomains . Если список опущен, правило применяется ко всем доменам. Пустой список не допускается.

  Примечания:

  • Также разрешены поддомены, такие как "a.example.com".
  • Записи должны состоять только из символов ASCII.
  • Для интернационализированных доменов используйте кодировку punycode.
  • Также выполняется сопоставление субдоменов перечисленных доменов.
• requestMethods

  RequestMethod [] optional

  Chrome 91+

  List of HTTP request methods which the rule can match. An empty list is not allowed.

  Note: Specifying a requestMethods rule condition will also exclude non-HTTP(s) requests, whereas specifying excludedRequestMethods will not.

• resourceTypes

  ResourceType [] optional

  List of resource types which the rule can match. An empty list is not allowed.

  Note: this must be specified for allowAllRequests rules and may only include the sub_frame and main_frame resource types.

• responseHeaders

  HeaderInfo [] optional

  Chrome 128+

  Rule matches if the request matches any response header condition in this list (if specified).

• tabIds

  number[] optional

  Chrome 92+

  List of tabs.Tab.id which the rule should match. An ID of tabs.TAB_ID_NONE matches requests which don't originate from a tab. An empty list is not allowed. Only supported for session-scoped rules.

• topDomains

  string[] optional

  В ожидании

  The rule will only match network requests when the associated top-level frame's domain matches one from the list of topDomains . If the list is omitted, the rule is applied to requests associated with all top-level frame domains. An empty list is not allowed.

  Примечания:

  • Sub-domains like "a.example.com" are also allowed.
  • The entries must consist of only ascii characters.
  • Use punycode encoding for internationalized domains.
  • Sub-domains of the listed domains are also matched.
  • For requests with no associated top-level frame (eg ServiceWorker initiated requests, the request initiator's domain is considered instead.
• urlFilter

  string optional

  The pattern which is matched against the network request url. Supported constructs:

  '*' : Wildcard: Matches any number of characters.

  '|' : Left/right anchor: If used at either end of the pattern, specifies the beginning/end of the url respectively.

  '||' : Domain name anchor: If used at the beginning of the pattern, specifies the start of a (sub-)domain of the URL.

  '^' : Separator character: This matches anything except a letter, a digit, or one of the following: _ , - , . , or % . This also match the end of the URL.

  Therefore urlFilter is composed of the following parts: (optional Left/Domain name anchor) + pattern + (optional Right anchor).

  If omitted, all urls are matched. An empty string is not allowed.

  A pattern beginning with ||* is not allowed. Use * instead.

  Note: Only one of urlFilter or regexFilter can be specified.

  Note: The urlFilter must be composed of only ASCII characters. This is matched against a url where the host is encoded in the punycode format (in case of internationalized domains) and any other non-ascii characters are url encoded in utf-8. For example, when the request url is http://abc.рф?q=ф, the urlFilter will be matched against the url http://abc.xn--p1ai/?q=%D1%84.

RuleConditionKeys

В ожидании

Перечисление

"urlFilter"

"regexFilter"

"isUrlFilterCaseSensitive"

"initiatorDomains"

"excludedInitiatorDomains"

"requestDomains"

"excludedRequestDomains"

"topDomains"

"excludedTopDomains"

"domains"

"excludedDomains"

"resourceTypes"

"excludedResourceTypes"

"requestMethods"

"excludedRequestMethods"

"domainType"

"tabIds"

"excludedTabIds"

"responseHeaders"

"excludedResponseHeaders"

Ruleset

Характеристики

• включено

  логический

  Whether the ruleset is enabled by default.

• идентификатор

  нить

  A non-empty string uniquely identifying the ruleset. IDs beginning with '_' are reserved for internal use.

• путь

  нить

  The path of the JSON ruleset relative to the extension directory.

RulesMatchedDetails

Характеристики

• rulesMatchedInfo

  MatchedRuleInfo []

  Rules matching the given filter.

TabActionCountUpdate

Chrome 89+

Характеристики

• увеличение

  число

  The amount to increment the tab's action count by. Negative values will decrement the count.

• tabId

  число

  The tab for which to update the action count.

TestMatchOutcomeResult

Chrome 103+

Характеристики

• matchedRules

  MatchedRule []

  The rules (if any) that match the hypothetical request.

TestMatchRequestDetails

Chrome 103+

Характеристики

• инициатор

  string optional

  The initiator URL (if any) for the hypothetical request.

• метод

  RequestMethod optional

  Standard HTTP method of the hypothetical request. Defaults to "get" for HTTP requests and is ignored for non-HTTP requests.

• responseHeaders

  object optional

  Chrome 129+

  The headers provided by a hypothetical response if the request does not get blocked or redirected before it is sent. Represented as an object which maps a header name to a list of string values. If not specified, the hypothetical response would return empty response headers, which can match rules which match on the non-existence of headers. Eg {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}

• tabId

  number optional

  The ID of the tab in which the hypothetical request takes place. Does not need to correspond to a real tab ID. Default is -1, meaning that the request isn't related to a tab.

• topUrl

  string optional

  В ожидании

  The associated top-level frame URL (if any) for the request.

• тип

  ResourceType

  The resource type of the hypothetical request.

• url

  нить

  The URL of the hypothetical request.

UnsupportedRegexReason

Chrome 87+

Describes the reason why a given regular expression isn't supported.

Перечисление

"syntaxError"
The regular expression is syntactically incorrect, or uses features not available in the RE2 syntax .

"memoryLimitExceeded"
The regular expression exceeds the memory limit.

UpdateRuleOptions

Chrome 87+

Характеристики

• addRules

  Rule [] optional

  Rules to add.

• removeRuleIds

  number[] optional

  IDs of the rules to remove. Any invalid IDs will be ignored.

UpdateRulesetOptions

Chrome 87+

Характеристики

• disableRulesetIds

  string[] optional

  The set of ids corresponding to a static Ruleset that should be disabled.

• enableRulesetIds

  string[] optional

  The set of ids corresponding to a static Ruleset that should be enabled.

UpdateStaticRulesOptions

Chrome 111+

Характеристики

• disableRuleIds

  number[] optional

  Set of ids corresponding to rules in the Ruleset to disable.

• enableRuleIds

  number[] optional

  Set of ids corresponding to rules in the Ruleset to enable.

• rulesetId

  нить

  The id corresponding to a static Ruleset .

URLTransform

Характеристики

• фрагмент

  string optional

  The new fragment for the request. Should be either empty, in which case the existing fragment is cleared; or should begin with '#'.

• хозяин

  string optional

  The new host for the request.

• пароль

  string optional

  The new password for the request.

• путь

  string optional

  The new path for the request. If empty, the existing path is cleared.

• порт

  string optional

  The new port for the request. If empty, the existing port is cleared.

• запрос

  string optional

  The new query for the request. Should be either empty, in which case the existing query is cleared; or should begin with '?'.

• queryTransform

  QueryTransform optional

  Add, remove or replace query key-value pairs.

• схема

  string optional

  The new scheme for the request. Allowed values are "http", "https", "ftp" and "chrome-extension".

• имя пользователя

  string optional

  The new username for the request.

Характеристики

DYNAMIC_RULESET_ID

Ruleset ID for the dynamic rules added by the extension.

Ценить

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

Time interval within which MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules calls can be made, specified in minutes. Additional calls will fail immediately and set runtime.lastError . Note: getMatchedRules calls associated with a user gesture are exempt from the quota.

Ценить

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89+

The minimum number of static rules guaranteed to an extension across its enabled static rulesets. Any rules above this limit will count towards the global static rule limit .

Ценить

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

The number of times getMatchedRules can be called within a period of GETMATCHEDRULES_QUOTA_INTERVAL .

Ценить

20

MAX_NUMBER_OF_DYNAMIC_RULES

The maximum number of dynamic rules that an extension can add.

Ценить

30000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94+

The maximum number of static Rulesets an extension can enable at any one time.

Ценить

50

MAX_NUMBER_OF_REGEX_RULES

The maximum number of regular expression rules that an extension can add. This limit is evaluated separately for the set of dynamic rules and those specified in the rule resources file.

Ценить

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120+

The maximum number of session scoped rules that an extension can add.

Ценить

5000

MAX_NUMBER_OF_STATIC_RULESETS

The maximum number of static Rulesets an extension can specify as part of the "rule_resources" manifest key.

Ценить

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120+

The maximum number of "unsafe" dynamic rules that an extension can add.

Ценить

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120+

The maximum number of "unsafe" session scoped rules that an extension can add.

Ценить

5000

SESSION_RULESET_ID

Chrome 90+

Ruleset ID for the session-scoped rules added by the extension.

Ценить

"_session"

Методы

getAvailableStaticRuleCount()

Chrome 89+

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

Returns the number of static rules an extension can enable before the global static rule limit is reached.

Возвраты

• Promise<number>

  Chrome 91+

getDisabledRuleIds()

Chrome 111+

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

Returns the list of static rules in the given Ruleset that are currently disabled.

Параметры

• параметры

  GetDisabledRuleIdsOptions

  Specifies the ruleset to query.

Возвраты

• Promise<number[]>

getDynamicRules()

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

Returns the current set of dynamic rules for the extension. Callers can optionally filter the list of fetched rules by specifying a filter .

Параметры

• фильтр

  GetRulesFilter optional

  Chrome 111+

  An object to filter the list of fetched rules.

Возвраты

• Promise< Rule []>

  Chrome 91+

getEnabledRulesets()

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

Returns the ids for the current set of enabled static rulesets.

Возвраты

• Promise<string[]>

  Chrome 91+

getMatchedRules()

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

Returns all rules matched for the extension. Callers can optionally filter the list of matched rules by specifying a filter . This method is only available to extensions with the "declarativeNetRequestFeedback" permission or having the "activeTab" permission granted for the tabId specified in filter . Note: Rules not associated with an active document that were matched more than five minutes ago will not be returned.

Параметры

• фильтр

  MatchedRulesFilter optional

  An object to filter the list of matched rules.

Возвраты

• Promise< RulesMatchedDetails >

  Chrome 91+

getSessionRules()

Chrome 90+

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

Returns the current set of session scoped rules for the extension. Callers can optionally filter the list of fetched rules by specifying a filter .

Параметры

• фильтр

  GetRulesFilter optional

  Chrome 111+

  An object to filter the list of fetched rules.

Возвраты

• Promise< Rule []>

  Chrome 91+

isRegexSupported()

Chrome 87+

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

Checks if the given regular expression will be supported as a regexFilter rule condition.

Параметры

• regexOptions

  RegexOptions

  The regular expression to check.

Возвраты

• Promise< IsRegexSupportedResult >

  Chrome 91+

setExtensionActionOptions()

Chrome 88+

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

Configures if the action count for tabs should be displayed as the extension action's badge text and provides a way for that action count to be incremented.

Параметры

• параметры

  ExtensionActionOptions

Возвраты

• Promise<void>

  Chrome 91+

testMatchOutcome()

Chrome 103+

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

Checks if any of the extension's declarativeNetRequest rules would match a hypothetical request. Note: Only available for unpacked extensions as this is only intended to be used during extension development.

Параметры

• запрос

  TestMatchRequestDetails

Возвраты

• Promise< TestMatchOutcomeResult >

updateDynamicRules()

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

Modifies the current set of dynamic rules for the extension. The rules with IDs listed in options.removeRuleIds are first removed, and then the rules given in options.addRules are added. Notes:

• This update happens as a single atomic operation: either all specified rules are added and removed, or an error is returned.
• These rules are persisted across browser sessions and across extension updates.
• Static rules specified as part of the extension package can not be removed using this function.
• MAX_NUMBER_OF_DYNAMIC_RULES is the maximum number of dynamic rules an extension can add. The number of unsafe rules must not exceed MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES .

Параметры

• параметры

  UpdateRuleOptions

  Chrome 87+

Возвраты

• Promise<void>

  Chrome 91+

updateEnabledRulesets()

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

Updates the set of enabled static rulesets for the extension. The rulesets with IDs listed in options.disableRulesetIds are first removed, and then the rulesets listed in options.enableRulesetIds are added. Note that the set of enabled static rulesets is persisted across sessions but not across extension updates, ie the rule_resources manifest key will determine the set of enabled static rulesets on each extension update.

Параметры

• параметры

  UpdateRulesetOptions

  Chrome 87+

Возвраты

• Promise<void>

  Chrome 91+

updateSessionRules()

Chrome 90+

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

Modifies the current set of session scoped rules for the extension. The rules with IDs listed in options.removeRuleIds are first removed, and then the rules given in options.addRules are added. Notes:

• This update happens as a single atomic operation: either all specified rules are added and removed, or an error is returned.
• These rules are not persisted across sessions and are backed in memory.
• MAX_NUMBER_OF_SESSION_RULES is the maximum number of session rules an extension can add.

Параметры

• параметры

  UpdateRuleOptions

Возвраты

• Promise<void>

  Chrome 91+

updateStaticRules()

Chrome 111+

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

Disables and enables individual static rules in a Ruleset . Changes to rules belonging to a disabled Ruleset will take effect the next time that it becomes enabled.

Параметры

• параметры

  UpdateStaticRulesOptions

Возвраты

• Promise<void>

События

onRuleMatchedDebug

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

Fired when a rule is matched with a request. Only available for unpacked extensions with the "declarativeNetRequestFeedback" permission as this is intended to be used for debugging purposes only.

Параметры

• перезвонить

  функция

  The callback parameter looks like:

  (info: MatchedRuleInfoDebug) => void

  • информация

    MatchedRuleInfoDebug