browser.declarativeNetRequest

Описание

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

Разрешения

declarativeNetRequest
declarativeNetRequestWithHostAccess

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

"declarativeNetRequest"

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

"declarativeNetRequestFeedback"

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

"declarativeNetRequestWithHostAccess"

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

Доступность

Chrome 84+ browser.* начиная с Chrome 148

Манифест

Помимо разрешений, описанных выше, для некоторых типов наборов правил, в частности статических, требуется объявить ключ манифеста "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://b.a.example.com/xyz https://a.example.company	https://example.com/
"|https*"	https://example.com	http://example.com/ http://https.com
"example*^123|"	https://example.com/123 http://abc.com/example?123	https://example.com/1234 https://abc.com/example0123

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

В условиях также можно использовать регулярные выражения. См. ключ "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 выбирает правило из расширения, установленного последним.

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

До отправки заголовков запроса

Перед отправкой заголовков запроса на сервер они обновляются в соответствии с правилами 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 browser.declarativeNetRequest.getDynamicRules();
const oldRuleIds = oldRules.map(rule => rule.id);

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

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

В примере ниже показано, как включать и отключать наборы правил с учетом количества доступных и максимального количества включенных статических наборов правил. Это может потребоваться, если вам нужно больше статических правил, чем разрешено. Чтобы это работало, некоторые наборы правил должны быть установлены с отключенными наборами правил (для этого в файле манифеста нужно задать для "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 browser.declarativeNetRequest.getEnabledRulesets();
  // Compare rule counts to determine if anything needs to be disabled so that
  // new rules can be enabled
  const proposedCount = enableRulesetIds.length;
  if (enabledStaticCount + proposedCount > browser.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS) {
    options.disableRulesetIds = disableCandidateIds
  }
  // Update the enabled static rules
  await browser.declarativeNetRequest.updateEnabledRulesets(options);
}

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

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

Ключ priority

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

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

Переход на страницу https://google.com

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

Переход на страницу https://google.com/1234

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

Переход на страницу https://google.com/12345

Этому URL соответствуют все четыре правила. Применяется правило с идентификатором 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". В этом случае из URL переадресации извлекается значение 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"
Сетевой запрос является собственным для фрейма, в котором он был создан.

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

ExtensionActionOptions

Chrome 88+ browser.* начиная с Chrome 148

Свойства

• displayActionCountAsBadgeText

  Логическое значение (необязательно)

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

• tabUpdate

  TabActionCountUpdate необязательный

  Chrome 89+ browser.* начиная с Chrome 148

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

GetDisabledRuleIdsOptions

Chrome 111+ browser.* начиная с Chrome 148

Свойства

• rulesetId

  string

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

GetRulesFilter

Chrome 111+ browser.* начиная с Chrome 148

Свойства

• ruleIds

  number[] optional

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

HeaderInfo

Chrome 128+ browser.* начиная с Chrome 148

Свойства

• excludedValues

  string[] необязательно

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

• заголовок

  string

  Название заголовка. Это условие соответствует названию, только если не указаны оба параметра: values и excludedValues.

• values

  string[] необязательно

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

  * – соответствует любому количеству символов.

  ? – соответствует нулю или одному символу.

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

HeaderOperation

Chrome 86+ browser.* начиная с Chrome 148

Описывает возможные операции для правила modifyHeaders.

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

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

set
Задает новое значение для указанного заголовка, удаляя все существующие заголовки с тем же названием.

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

IsRegexSupportedResult

Chrome 87 и более поздних версий browser.* начиная с Chrome 148

Свойства

• isSupported

  Логическое значение

• reason

  UnsupportedRegexReason необязательный

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

MatchedRule

Свойства

• ruleId

  число

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

• rulesetId

  string

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

MatchedRuleInfo

Свойства

• правило

  MatchedRule

• tabId

  число

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

• timeStamp

  число

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

MatchedRuleInfoDebug

Свойства

• запрос

  RequestDetails

  Сведения о запросе, для которого было подобрано правило.

• правило

  MatchedRule

MatchedRulesFilter

Свойства

• minTimeStamp

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

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

• tabId

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

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

ModifyHeaderInfo

Chrome 86+ browser.* начиная с Chrome 148

Свойства

• заголовок

  string

  Название заголовка, который нужно изменить.

• операция

  HeaderOperation

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

• value

  Строка (необязательно)

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

QueryKeyValue

Свойства

• клавиша

  string

• replaceOnly

  Логическое значение (необязательно)

  Chrome 94+ browser.* начиная с Chrome 148

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

• value

  string

QueryTransform

Свойства

• addOrReplaceParams

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

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

• removeParams

  string[] необязательно

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

Redirect

Свойства

• extensionPath

  Строка (необязательно)

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

• regexSubstitution

  Строка (необязательно)

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

• преобразование

  URLTransform необязательный

  Преобразования URL, которые нужно выполнить.

• url

  Строка (необязательно)

  URL переадресации. Переадресация на URL JavaScript запрещена.

RegexOptions

Chrome 87 и более поздних версий browser.* начиная с Chrome 148

Свойства

• isCaseSensitive

  Логическое значение (необязательно)

  Учитывается ли регистр в указанном значении regex. Значение по умолчанию – true.

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

  string

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

• requireCapturing

  Логическое значение (необязательно)

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

RequestDetails

Свойства

• documentId

  Строка (необязательно)

  Chrome 106 и более поздних версий browser.* начиная с Chrome 148

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

• documentLifecycle

  DocumentLifecycle необязательно

  Chrome 106 и более поздних версий browser.* начиная с Chrome 148

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

• frameId

  число

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

• frameType

  FrameType необязательный

  Chrome 106 и более поздних версий browser.* начиная с Chrome 148

  Тип фрейма, если запрос предназначен для фрейма.

• инициатор

  Строка (необязательно)

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

• method

  string

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

• parentDocumentId

  Строка (необязательно)

  Chrome 106 и более поздних версий browser.* начиная с Chrome 148

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

• parentFrameId

  число

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

• requestId

  string

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

• tabId

  число

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

• тип

  ResourceType

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

• url

  string

  URL запроса.

RequestMethod

Chrome 91+ browser.* начиная с Chrome 148

Описывает метод HTTP-запроса для сетевого запроса.

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

"connect"

"delete"

"get"

"head"

"options"

"patch"

"post"

"put"

"other"

ResourceType

Описывает тип ресурса сетевого запроса.

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

"main_frame"

"sub_frame"

"stylesheet"

"script"

"image"

"font"

"object"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"webtransport"

"webbundle"

"other"

Rule

Свойства

• действие

  RuleAction

  Действие, которое нужно выполнить, если правило сработало.

• условие

  RuleCondition

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

• id

  число

  Идентификатор, который однозначно определяет правило. Обязательный параметр. Значение должно быть больше или равно 1.

• приоритет

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

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

RuleAction

Свойства

• Переадресация

  Переадресация необязательно

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

• requestHeaders

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

  Chrome 86+ browser.* начиная с Chrome 148

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

• responseHeaders

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

  Chrome 86+ browser.* начиная с Chrome 148

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

• тип

  RuleActionType

  Тип действия, которое нужно выполнить.

RuleActionType

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

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

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

"redirect"
Перенаправляет сетевой запрос.

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

"upgradeScheme"
Заменить схему URL сетевого запроса на https, если в запросе используется http или ftp.

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

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

RuleCondition

Свойства

• domainType

  DomainType необязательный

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

• domains

  string[] необязательно

  Устарело в Chrome 101

  Используйте initiatorDomains

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

• excludedDomains

  string[] необязательно

  Устарело в Chrome 101

  Используйте excludedInitiatorDomains

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

• excludedInitiatorDomains

  string[] необязательно

  Chrome 101+ browser.* начиная с Chrome 148

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

  Примечания

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

  string[] необязательно

  Chrome 101+ browser.* начиная с Chrome 148

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

  Примечания

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

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

  Chrome 91+ browser.* начиная с Chrome 148

  Список методов запроса, которые не соответствуют правилу. Можно указать только одно значение: requestMethods или excludedRequestMethods. Если не указан ни один из них, сопоставляются все методы запроса.

• excludedResourceTypes

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

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

• excludedResponseHeaders

  HeaderInfo[] optional

  Chrome 128+ browser.* начиная с Chrome 148

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

• excludedTabIds

  number[] optional

  Chrome 92 и более поздние версии browser.* начиная с Chrome 148

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

• excludedTopDomains

  string[] необязательно

  Chrome 145 и более поздние версии browser.* начиная с Chrome 148

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

  Примечания

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

  string[] необязательно

  Chrome 101+ browser.* начиная с Chrome 148

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

  Примечания

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

  Логическое значение (необязательно)

  Учитывается ли регистр в urlFilter или regexFilter (в зависимости от того, что указано). Значение по умолчанию – false.

• regexFilter

  Строка (необязательно)

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

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

  Примечание. regexFilter должен состоять только из символов ASCII. Сопоставление выполняется с URL, в котором хост закодирован в формате Punycode (для интернационализованных доменов), а все остальные символы, не входящие в набор ASCII, закодированы в UTF-8.

• requestDomains

  string[] необязательно

  Chrome 101+ browser.* начиная с Chrome 148

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

  Примечания

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

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

  Chrome 91+ browser.* начиная с Chrome 148

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

  Примечание. Если вы укажете условие правила requestMethods, то запросы, не относящиеся к HTTP(S), также будут исключены. Если же вы укажете условие excludedRequestMethods, то этого не произойдет.

• resourceTypes

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

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

  Примечание. Это значение необходимо указать для правил allowAllRequests. Оно может включать только типы ресурсов sub_frame и main_frame.

• responseHeaders

  HeaderInfo[] optional

  Chrome 128+ browser.* начиная с Chrome 148

  Правило применяется, если запрос соответствует любому условию заголовка ответа в этом списке (если указано).

• tabIds

  number[] optional

  Chrome 92 и более поздние версии browser.* начиная с Chrome 148

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

• topDomains

  string[] необязательно

  Chrome 145 и более поздние версии browser.* начиная с Chrome 148

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

  Примечания

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

  Строка (необязательно)

  Шаблон, который сопоставляется с URL сетевого запроса. Поддерживаемые конструкции:

  * – подстановочный знак, соответствующий любому количеству символов.

  | – левый/правый якорь. Если этот символ используется в начале или конце шаблона, он указывает на начало или конец URL соответственно.

  || – якорь доменного имени. Если он используется в начале шаблона, то указывает на начало домена или субдомена в URL.

  ^ – разделитель. Соответствует любому символу, кроме букв, цифр и следующих знаков: _, -, . и %. Это также соответствует концу URL.

  Таким образом, urlFilter состоит из следующих частей: (необязательный левый якорь или якорь доменного имени) + шаблон + (необязательный правый якорь).

  Если он не указан, сопоставляются все URL. Пустая строка не допускается.

  Шаблон не может начинаться с ||*. Вместо нее следует использовать *.

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

  Примечание. urlFilter должен состоять только из символов ASCII. Сопоставление выполняется с URL, в котором хост закодирован в формате Punycode (для интернационализованных доменов), а все остальные символы, не входящие в набор ASCII, закодированы в UTF-8. Например, если URL запроса – http://abc.рф?q=ф, то urlFilter будет сопоставляться с URL http://abc.xn--p1ai/?q=%D1%84.

RuleConditionKeys

Chrome 145 и более поздние версии browser.* начиная с Chrome 148

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

"urlFilter"

"regexFilter"

"isUrlFilterCaseSensitive"

"initiatorDomains"

"excludedInitiatorDomains"

"requestDomains"

"excludedRequestDomains"

"topDomains"

"excludedTopDomains"

"domains"

"excludedDomains"

"resourceTypes"

"excludedResourceTypes"

"requestMethods"

"excludedRequestMethods"

"domainType"

"tabIds"

"excludedTabIds"

"responseHeaders"

"excludedResponseHeaders"

Ruleset

Свойства

• включено

  Логическое значение

  Включен ли набор правил по умолчанию.

• id

  string

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

• путь

  string

  Путь к набору правил JSON относительно каталога расширения.

RulesMatchedDetails

Свойства

• rulesMatchedInfo

  MatchedRuleInfo[]

  Правила, соответствующие заданному фильтру.

TabActionCountUpdate

Chrome 89+ browser.* начиная с Chrome 148

Свойства

• больше

  число

  Значение, на которое увеличивается количество действий на вкладке. Отрицательные значения уменьшают количество.

• tabId

  число

  Вкладка, для которой нужно обновить количество действий.

TestMatchOutcomeResult

Chrome 103 и более поздних версий browser.* начиная с Chrome 148

Свойства

• matchedRules

  MatchedRule[]

  Правила (если есть), которые соответствуют гипотетическому запросу.

TestMatchRequestDetails

Chrome 103 и более поздних версий browser.* начиная с Chrome 148

Свойства

• инициатор

  Строка (необязательно)

  URL инициатора (если есть) для гипотетического запроса.

• method

  RequestMethod необязательный

  Стандартный метод HTTP гипотетического запроса. По умолчанию для HTTP-запросов используется значение "get". Для запросов, не относящихся к HTTP, этот параметр игнорируется.

• responseHeaders

  Объект (необязательно)

  Chrome 129 и более поздние версии browser.* начиная с Chrome 148

  Заголовки, которые будут предоставлены гипотетическим ответом, если запрос не будет заблокирован или перенаправлен до отправки. Представлен в виде объекта, который сопоставляет название заголовка со списком строковых значений. Если не указать этот параметр, гипотетический ответ будет возвращать пустые заголовки, которые могут соответствовать правилам, проверяющим отсутствие заголовков. Пример: {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}

• tabId

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

  Идентификатор вкладки, в которой выполняется гипотетический запрос. Не обязательно должен соответствовать идентификатору реальной вкладки. Значение по умолчанию – -1, что означает, что запрос не связан с вкладкой.

• topUrl

  Строка (необязательно)

  Chrome 145 и более поздние версии browser.* начиная с Chrome 148

  URL фрейма верхнего уровня, связанного с запросом (если есть).

• тип

  ResourceType

  Тип ресурса гипотетического запроса.

• url

  string

  URL гипотетического запроса.

UnsupportedRegexReason

Chrome 87 и более поздних версий browser.* начиная с Chrome 148

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

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

"syntaxError"
Регулярное выражение содержит синтаксическую ошибку или использует функции, недоступные в синтаксисе RE2.

"memoryLimitExceeded"
Регулярное выражение превышает лимит памяти.

UpdateRuleOptions

Chrome 87 и более поздних версий browser.* начиная с Chrome 148

Свойства

• addRules

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

  Правила, которые нужно добавить.

• removeRuleIds

  number[] optional

  Идентификаторы правил, которые нужно удалить. Недействительные идентификаторы будут игнорироваться.

UpdateRulesetOptions

Chrome 87 и более поздних версий browser.* начиная с Chrome 148

Свойства

• disableRulesetIds

  string[] необязательно

  Набор идентификаторов, соответствующих статическому Ruleset, который нужно отключить.

• enableRulesetIds

  string[] необязательно

  Набор идентификаторов, соответствующих статическому Ruleset, который нужно включить.

UpdateStaticRulesOptions

Chrome 111+ browser.* начиная с Chrome 148

Свойства

• disableRuleIds

  number[] optional

  Набор идентификаторов, соответствующих правилам в Ruleset, которые нужно отключить.

• enableRuleIds

  number[] optional

  Набор идентификаторов, соответствующих правилам в Ruleset, которые нужно включить.

• rulesetId

  string

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

URLTransform

Свойства

• fragment

  Строка (необязательно)

  Новый фрагмент для запроса. Должен быть пустым (в этом случае существующий фрагмент удаляется) или начинаться с символа "#".

• хост

  Строка (необязательно)

  Новый хост для запроса.

• пароль

  Строка (необязательно)

  Новый пароль для запроса.

• путь

  Строка (необязательно)

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

• порт

  Строка (необязательно)

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

• запрос

  Строка (необязательно)

  Новый запрос. Должен быть пустым (в этом случае существующий запрос удаляется) или начинаться с символа "?".

• queryTransform

  QueryTransform необязательный

  Добавление, удаление или замена пар "ключ-значение" в запросе.

• схема

  Строка (необязательно)

  Новая схема для запроса. Допустимые значения: http, https, ftp и chrome-extension.

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

  Строка (необязательно)

  Новое имя пользователя для запроса.

Свойства

DYNAMIC_RULESET_ID

Идентификатор набора правил для динамических правил, добавленных расширением.

Значение

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

Интервал времени в минутах, в течение которого можно совершать звонки в MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules. Дополнительные вызовы будут сразу же отклоняться с ошибкой runtime.lastError. Примечание. Вызовы getMatchedRules, связанные с жестом пользователя, не учитываются в квоте.

Значение

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89+ browser.* начиная с Chrome 148

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

Значение

30 000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

Количество вызовов getMatchedRules за период GETMATCHEDRULES_QUOTA_INTERVAL.

Значение

20

MAX_NUMBER_OF_DYNAMIC_RULES

Максимальное количество динамических правил, которые может добавить расширение.

Значение

30 000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94+ browser.* начиная с Chrome 148

Максимальное количество статических Rulesets, которые расширение может включить одновременно.

Значение

50

MAX_NUMBER_OF_REGEX_RULES

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

Значение

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120+ browser.* начиная с Chrome 148

Максимальное количество правил в области действия сеанса, которые может добавить расширение.

Значение

5000

MAX_NUMBER_OF_STATIC_RULESETS

Максимальное количество статических Rulesets, которое расширение может указать в ключе манифеста "rule_resources".

Значение

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120+ browser.* начиная с Chrome 148

Максимальное количество "небезопасных" динамических правил, которые может добавить расширение.

Значение

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120+ browser.* начиная с Chrome 148

Максимальное количество "небезопасных" правил на уровне сеанса, которые может добавить расширение.

Значение

5000

SESSION_RULESET_ID

Chrome 90 и более поздних версий browser.* начиная с Chrome 148

Идентификатор набора правил для правил на уровне сеанса, добавленных расширением.

Значение

"_session"

Методы

getAvailableStaticRuleCount()

Chrome 89+ browser.* начиная с Chrome 148

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

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

Возвраты

• Promise<number>

  Chrome 91+ browser.* начиная с Chrome 148

getDisabledRuleIds()

Chrome 111+ browser.* начиная с Chrome 148

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

Возвращает список статических правил в заданном Ruleset, которые в настоящее время отключены.

Параметры

• Параметры

  GetDisabledRuleIdsOptions

  Указывает набор правил для запроса.

Возвраты

• Promise<number[]>

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

getDynamicRules()

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

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

Параметры

• фильтр

  GetRulesFilter необязательный

  Chrome 111+ browser.* начиная с Chrome 148

  Объект для фильтрации списка полученных правил.

Возвраты

• Promise<Rule[]>

  Chrome 91+ browser.* начиная с Chrome 148

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

getEnabledRulesets()

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

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

Возвраты

• Promise<string[]>

  Chrome 91+ browser.* начиная с Chrome 148

  Объект Promise, который распознается как список идентификаторов, где каждый идентификатор соответствует включенному статическому Ruleset.

getMatchedRules()

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

Возвращает все правила, соответствующие расширению. Вызывающие абоненты могут отфильтровать список сопоставленных правил, указав filter. Этот метод доступен только для расширений с разрешением "declarativeNetRequestFeedback" или с разрешением "activeTab", предоставленным для tabId, указанного в filter. Примечание. Правила, не связанные с активным документом, которые были сопоставлены более пяти минут назад, не будут возвращены.

Параметры

• фильтр

  MatchedRulesFilter необязательно

  Объект для фильтрации списка сопоставленных правил.

Возвраты

• Promise<RulesMatchedDetails>

  Chrome 91+ browser.* начиная с Chrome 148

  Объект Promise, который разрешается после получения списка сопоставленных правил. В случае ошибки объект Promise будет отклонен. Это может произойти по разным причинам, например из-за недостаточных разрешений или превышения квоты.

getSessionRules()

Chrome 90 и более поздних версий browser.* начиная с Chrome 148

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

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

Параметры

• фильтр

  GetRulesFilter необязательный

  Chrome 111+ browser.* начиная с Chrome 148

  Объект для фильтрации списка полученных правил.

Возвраты

• Promise<Rule[]>

  Chrome 91+ browser.* начиная с Chrome 148

  Promise, который разрешается с набором правил на уровне сеанса.

isRegexSupported()

Chrome 87 и более поздних версий browser.* начиная с Chrome 148

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

Проверяет, будет ли заданное регулярное выражение поддерживаться в качестве условия правила regexFilter.

Параметры

• regexOptions

  RegexOptions

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

Возвраты

• Promise<IsRegexSupportedResult>

  Chrome 91+ browser.* начиная с Chrome 148

  Объект Promise, который возвращает сведения о том, поддерживается ли регулярное выражение, и причину, если оно не поддерживается.

setExtensionActionOptions()

Chrome 88+ browser.* начиная с Chrome 148

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

Определяет, должно ли количество действий для вкладок отображаться в виде текста на значке действия расширения, и позволяет увеличивать это количество.

Параметры

• Параметры

  ExtensionActionOptions

Возвраты

• Promise<void>

  Chrome 91+ browser.* начиная с Chrome 148

testMatchOutcome()

Chrome 103 и более поздних версий browser.* начиная с Chrome 148

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

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

Параметры

• запрос

  TestMatchRequestDetails

Возвраты

• Promise<TestMatchOutcomeResult>

  Promise, который разрешается с подробными сведениями о сопоставленных правилах.

updateDynamicRules()

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

Изменяет текущий набор динамических правил для расширения. Сначала удаляются правила с идентификаторами, указанными в options.removeRuleIds, а затем добавляются правила, указанные в options.addRules. Примечания

• Это обновление выполняется как единая атомарная операция: либо все указанные правила добавляются и удаляются, либо возвращается ошибка.
• Эти правила сохраняются между сеансами браузера и обновлениями расширений.
• Статические правила, указанные в пакете расширения, нельзя удалить с помощью этой функции.
• MAX_NUMBER_OF_DYNAMIC_RULES – максимальное количество динамических правил, которые может добавить расширение. Количество небезопасных правил не должно превышать MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES.

Параметры

• Параметры

  UpdateRuleOptions

  Chrome 87 и более поздних версий browser.* начиная с Chrome 148

Возвраты

• Promise<void>

  Chrome 91+ browser.* начиная с Chrome 148

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

updateEnabledRulesets()

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

Обновляет набор включенных статических наборов правил для расширения. Сначала удаляются наборы правил с идентификаторами, указанными в options.disableRulesetIds, а затем добавляются наборы правил, указанные в options.enableRulesetIds. Обратите внимание, что набор включенных статических наборов правил сохраняется между сеансами, но не между обновлениями расширений. Это значит, что ключ манифеста rule_resources будет определять набор включенных статических наборов правил при каждом обновлении расширения.

Параметры

• Параметры

  UpdateRulesetOptions

  Chrome 87 и более поздних версий browser.* начиная с Chrome 148

Возвраты

• Promise<void>

  Chrome 91+ browser.* начиная с Chrome 148

  Обещание, которое выполняется после завершения обновления. В случае ошибки обещание будет отклонено, а набор включенных наборов правил останется без изменений. Это может произойти по разным причинам, например из-за недействительных идентификаторов наборов правил, превышения лимита на количество правил или внутренних ошибок.

updateSessionRules()

Chrome 90 и более поздних версий browser.* начиная с Chrome 148

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

Изменяет текущий набор правил для расширения в рамках сеанса. Сначала удаляются правила с идентификаторами, указанными в options.removeRuleIds, а затем добавляются правила, указанные в options.addRules. Примечания

• Это обновление выполняется как единая атомарная операция: либо все указанные правила добавляются и удаляются, либо возвращается ошибка.
• Эти правила не сохраняются между сеансами и хранятся в памяти.
• MAX_NUMBER_OF_SESSION_RULES – максимальное количество правил сеанса, которое может добавить расширение.

Параметры

• Параметры

  UpdateRuleOptions

Возвраты

• Promise<void>

  Chrome 91+ browser.* начиная с Chrome 148

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

updateStaticRules()

Chrome 111+ browser.* начиная с Chrome 148

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

Отключает и включает отдельные статические правила в Ruleset. Изменения в правилах, относящихся к отключенному Ruleset, вступят в силу при следующем включении.

Параметры

• Параметры

  UpdateStaticRulesOptions

Возвраты

• Promise<void>

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

События

onRuleMatchedDebug

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

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

Параметры

• обратный вызов

  function

  Параметр callback выглядит следующим образом:

  (info: MatchedRuleInfoDebug) => void

  • информация

    MatchedRuleInfoDebug