declarativeNetRequest

Для использования этого API расширение должно запросить разрешения "declarativeNetRequest" или "declarativeNetRequestWithHostAccess" в файле разрешений своего manifest.json файла.

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

Разрешение "declarativeNetRequestFeedback" необходимо для использования getMatchedRules и onRuleMatchedDebug, так как они возвращают информацию о сопоставленных декларативных правилах. Дополнительная информация приведена в разделе Тестирование.

Декларативные правила определяются четырьмя полями:

• id – Идентификатор, уникально определяющий правило в наборе правил. Обязателен и должен быть >= 1.
• priority – Приоритет правила. Если указан, должен быть >= 1. По умолчанию равен 1. Подробности о влиянии приоритета на применение правил см. в разделе Порядок применения правил.
• condition – condition условия, при которых срабатывает это правило.
• action – action действия, которые необходимо выполнить при совпадении правила. Правила могут выполнять следующие действия:
  • блокировать сетевой запрос.
  • перенаправить сетевой запрос.
  • изменять заголовки сетевого запроса.
  • препятствовать применению другого соответствующего правила.

Вот пример правила, которое блокирует все запросы скриптов, исходящие от "foo.com", к любому URL, содержащему "abc" в качестве подстроки:

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

Поле urlFilter условия правила используется для указания шаблона, который сопоставляется с URL запроса. Подробности см. в разделе RuleCondition. Вот несколько примеров фильтров URL:

Правила организованы в наборы правил:

• статические наборы правил: коллекции правил, определенные с помощью ключа "declarative_net_request" манифеста и хранящиеся в расширении. Расширение может включать и отключать статические наборы правил с помощью updateEnabledRulesets. Набор включенных статических наборов правил сохраняется между сеансами, но не между обновлениями расширения. Статические наборы правил, включенные при установке и обновлении расширения, определяются содержимым ключа манифеста "declarative_net_request".
• динамический набор правил: правила, добавляемые или удаляемые с помощью updateDynamicRules. Эти правила сохраняются между сеансами и обновлениями расширения.
• набор правил сеанса: правила, добавляемые или удаляемые с помощью updateSessionRules. Эти правила не сохраняются между сеансами браузера.

Расширение может:

• указать статические наборы правил в качестве части ключа манифеста "declarative_net_request" до значения MAX_NUMBER_OF_STATIC_RULESETS.
• включить статические наборы правил не менее чем до значения GUARANTEED_MINIMUM_STATIC_RULES, и количество включенных наборов статических правил не должно превышать значения [MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. Кроме того, общее количество правил во включенных наборах статических правил для всех расширений не должно превышать глобального лимита. Расширения не должны зависеть от конкретного значения глобального лимита, а вместо этого должны использовать getAvailableStaticRuleCount, чтобы определить количество дополнительных правил, которые они могут включить.

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

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

1. приоритет правила, где 1 — наименьший приоритет (и правила по умолчанию имеют приоритет 1, если приоритет не задан). Если это не приводит к выбору одного правила:
2. действие правила в следующем порядке приоритета:
   1. "разрешить", что означает, что любые другие оставшиеся правила игнорируются.
   2. "разрешить все запросы" (только для типов ресурсов main_frame и sub_frame) имеет тот же эффект, что и "разрешить", но также применяется к будущим загрузкам дочерних ресурсов в документе (включая дочерние фреймы), сгенерированные из запроса.
   3. "заблокировать" отменяет запрос.
   4. "upgradeScheme" изменяет схему запроса.
   5. "перенаправить" перенаправляет запрос.
   6. "изменить заголовки" переписывает заголовки запроса и ответа. Если это не приводит к выбору одного правила:
3. набор правил, к которому принадлежит правило, в следующем порядке приоритета:
   1. сеанс
   2. динамический
   3. статический. Если это не приводит к выбору одного правила:
4. порядок правила в наборе правил, определяемый как правило с наименьшим значением ID.

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

1. "заблокировать"
2. "перенаправить" и "upgradeScheme"
3. "разрешить" и "разрешить все запросы"

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

testMatchOutcome, getmatchedrules и onRuleMatchedDebug доступны для помощи в тестировании правил и наборов правил. Для этих API требуется разрешение "declarativeNetRequestFeedback" разрешений. Кроме того:

• в Chrome эти API доступны только для распакованных расширений.
• в Firefox эти API доступны только после установки значения предпочтения extensions.dnr.feedback в true. Измените это предпочтение с помощью about:config или --pref флага web-ext инструмента командной строки.

• API declarativeNetRequest оценивает сетевые запросы непосредственно в браузере. Это делает его более производительным, чем API webRequest, где каждый сетевой запрос оценивается в JavaScript в процессе расширения.
• Поскольку запросы не перехватываются процессом расширения, declarativeNetRequest устраняет необходимость в странице фона для расширений.
• В отличие от API webRequest, блокировка или улучшение запросов с помощью API declarativeNetRequest не требует разрешений на хостинг при использовании разрешения declarativeNetRequest.
• API declarativeNetRequest обеспечивает большую конфиденциальность для пользователей, поскольку расширения не читают сетевые запросы, выполняемые от имени пользователя.
• (Только Chrome:) В отличие от API webRequest, любые изображения или фреймы iframes, заблокированные с помощью API declarativeNetRequest, автоматически сворачиваются в DOM.
• При решении вопроса о блокировке или перенаправлении запроса API declarativeNetRequest имеет приоритет над API webRequest, поскольку он позволяет синхронный перехват. Аналогично, любые заголовки, удаленные через API declarativeNetRequest, не отображаются для расширений web request.
• API webRequest более гибкий, чем API declarativeNetRequest, поскольку он позволяет расширениям программно оценивать запрос.

declarativeNetRequest.MatchedRule

Подробности сопоставленного правила.

declarativeNetRequest.ModifyHeaderInfo

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

declarativeNetRequest.Redirect

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

declarativeNetRequest.ResourceType

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

declarativeNetRequest.Rule

Объект, содержащий подробности правила.

declarativeNetRequest.RuleAction

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

declarativeNetRequest.RuleCondition

Объект, определяющий условие, при котором запускается правило.

declarativeNetRequest.URLTransform

Объект, содержащий подробности преобразования URL для действия переадресации.

declarativeNetRequest.DYNAMIC_RULESET_ID

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

declarativeNetRequest.GETMATCHEDRULES_QUOTA_INTERVAL

Интервал времени, в течение которого можно выполнить вызовы declarativeNetRequest.MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL declarativeNetRequest.getMatchedRules.

declarativeNetRequest.GUARANTEED_MINIMUM_STATIC_RULES

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

declarativeNetRequest.MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

Количество вызовов declarativeNetRequest.getMatchedRules, которые можно выполнить в течение периода declarativeNetRequest.GETMATCHEDRULES_QUOTA_INTERVAL.

declarativeNetRequest.MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES

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

declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

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

declarativeNetRequest.MAX_NUMBER_OF_REGEX_RULES

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

declarativeNetRequest.MAX_NUMBER_OF_STATIC_RULESETS

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

declarativeNetRequest.SESSION_RULESET_ID

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

declarativeNetRequest.getAvailableStaticRuleCount()

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

declarativeNetRequest.getDynamicRules()

Возвращает набор динамических правил для расширения.

declarativeNetRequest.getEnabledRulesets()

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

declarativeNetRequest.getMatchedRules()

Возвращает все сопоставленные правила для расширения.

declarativeNetRequest.getSessionRules()

Возвращает набор сеансовых правил для расширения.

declarativeNetRequest.isRegexSupported()

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

declarativeNetRequest.setExtensionActionOptions()

Настраивает обработку счётчика действий для вкладок.

declarativeNetRequest.testMatchOutcome()

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

declarativeNetRequest.updateDynamicRules()

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

declarativeNetRequest.updateEnabledRulesets()

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

declarativeNetRequest.updateSessionRules()

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

declarativeNetRequest.onRuleMatchedDebug

Вызывается, когда правило сопоставляется с запросом во время отладки расширения с разрешением "declarativeNetRequestFeedback".