chrome.declarativeNetRequest

Описание

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

Разрешения

declarativeNetRequest
declarativeNetRequestWithHostAccess

declarativeNetRequestFeedback
host_permissions

Доступность

Хром 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 .

Чтобы включить или отключить статические наборы правил , вызовите метод 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"]
  }
}

urlFilter совпадающие символы

Ключ "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://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

Приоритизация правил

Правила активируются запросами, отправленными с веб-страниц. Если одному запросу соответствует несколько правил, им необходимо назначить приоритет. В этом разделе объясняется, как они назначаются. Приоритезация происходит в два этапа.

  1. Приоритет определяется для правил внутри расширения.
  2. Если более одного расширения могут применить правило к запросу, приоритет определяется для всех расширений, соответствующих конкретному запросу.

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

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

В рамках одного расширения приоритеты определяются с помощью следующего процесса:

  1. Возвращается правило с наивысшим приоритетом, определенным разработчиком (другими словами, поле "priority" ).

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

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

  3. Если тип действия не block или redirect , проверяются все соответствующие правила modifyHeaders . Имейте в виду, что если есть правила с приоритетом, заданным разработчиком, ниже приоритета, указанного для allow и allowAllRequests , такие правила игнорируются.

  4. Если несколько правил изменяют один и тот же заголовок, изменение определяется заданным разработчиком полем "priority" и указанными операциями.

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

Приоритет правил между расширениями

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

  1. Правила ранжируются по приоритету с помощью поля "action" в следующем порядке:

    1. block
    2. redirect или upgradeScheme
    3. allow или allowAllRequests

  2. Если соответствует более одного правила, приоритет имеет последнее установленное расширение.

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

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

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

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

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

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

Ограничения, применяемые к динамическим и сеансовым правилам, проще, чем к статическим. Общее количество правил не может превышать 5000. Это называется MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES .

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

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

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

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

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

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

Доступные в Интернете ресурсы

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

Примеры

Примеры кода

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

В следующем примере показано, как вызвать 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-адреса теперь применяется правило с идентификатором 2 в дополнение к правилам с идентификаторами 1 и 4. Правило с идентификатором 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". В этом случае "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

Хром 88+

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

  • displayActionCountAsBadgeText

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

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

  • вкладкаОбновление

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

    Хром 89+

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

GetDisabledRuleIdsOptions

Хром 111+

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

  • rulesetId

    нить

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

GetRulesFilter

Хром 111+

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

  • идентификаторы правил

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

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

HeaderInfo

Хром 128+

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

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

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

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

  • заголовок

    нить

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

  • ценности

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

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

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

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

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

HeaderOperation

Хром 86+

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

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

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

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

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

IsRegexSupportedResult

Хром 87+

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

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

    булев

  • причина

    Необязательный параметр UnsupportedRegexReason

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

MatchedRule

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

  • ruleId

    число

    Идентификатор правила сопоставления.

  • rulesetId

    нить

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

MatchedRuleInfo

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

  • правило

    MatchedRule

  • tabId

    число

    TabId вкладки, с которой был отправлен запрос, если вкладка всё ещё активна. В противном случае -1.

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

    число

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

MatchedRuleInfoDebug

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

MatchedRulesFilter

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

  • minTimeStamp

    номер необязательно

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

  • tabId

    номер необязательно

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

ModifyHeaderInfo

Хром 86+

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

  • заголовок

    нить

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

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

  • ценить

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

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

QueryKeyValue

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

  • ключ

    нить

  • replaceOnly

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

    Хром 94+

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

  • ценить

    нить

QueryTransform

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

  • addOrReplaceParams

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

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

  • removeParams

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

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

Redirect

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

  • extensionPath

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

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

  • regexПодстановка

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

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

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

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

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

  • URL-адрес

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

    URL-адрес перенаправления. Перенаправления на URL-адреса JavaScript запрещены.

RegexOptions

Хром 87+

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

  • isCaseSensitive

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

    Учитывает ли указанное regex ? Значение по умолчанию — true.

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

    нить

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

  • требуетсяЗахват

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

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

RequestDetails

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

  • documentId

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

    Хром 106+

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

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

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

    Хром 106+

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

  • frameId

    число

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

  • frameType

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

    Хром 106+

    Тип фрейма, если это запрос фрейма.

  • инициатор

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

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

  • метод

    нить

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

  • parentDocumentId

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

    Хром 106+

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

  • parentFrameId

    число

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

  • requestId

    нить

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

  • tabId

    число

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

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

  • URL-адрес

    нить

    URL-адрес запроса.

RequestMethod

Хром 91+

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

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

"соединять"

"удалить"

"получать"

"голова"

"параметры"

"пластырь"

"почта"

"помещать"

"другой"

ResourceType

Здесь описывается тип ресурса сетевого запроса.

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

"main_frame"

"sub_frame"

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

"сценарий"

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

"шрифт"

"объект"

"xmlhttprequest"

"пинг"

"csp_report"

"СМИ"

"вебсокет"

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

"webbundle"

"другой"

Rule

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

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

  • состояние

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

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

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

    число

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

  • приоритет

    номер необязательно

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

RuleAction

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

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

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

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

  • requestHeaders

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

    Хром 86+

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

  • responseHeaders

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

    Хром 86+

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

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

RuleActionType

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

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

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

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

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

"upgradeScheme"
Обновите схему URL сетевого запроса до https, если запрос — http или ftp.

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

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

RuleCondition

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

  • Тип_домена

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

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

  • домены

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

    Не рекомендуется с версии Chrome 101

    Вместо этого используйте initiatorDomains

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

  • исключенныедомены

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

    Не рекомендуется с версии Chrome 101

    Вместо этого используйте excludedInitiatorDomains

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

  • исключенныеInitiatorDomains

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

    Хром 101+

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

    Примечания:

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

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

    Хром 101+

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

    Примечания:

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

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

    Хром 91+

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

  • исключенныеResourceTypes

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

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

  • исключенные заголовки ответов

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

    Хром 128+

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

  • исключенныеTabIds

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

    Хром 92+

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

  • initiatorDomains

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

    Хром 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

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

    Хром 101+

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

    Примечания:

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

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

    Хром 91+

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

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

  • Типы ресурсов

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

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

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

  • responseHeaders

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

    Хром 128+

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

  • tabIds

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

    Хром 92+

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

  • URL-фильтр

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

    Шаблон, сопоставляемый с 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.

Ruleset

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

  • включено

    булев

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

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

    нить

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

  • путь

    нить

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

RulesMatchedDetails

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

  • rulesMatchedInfo

    MatchedRuleInfo []

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

TabActionCountUpdate

Хром 89+

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

  • приращение

    число

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

  • tabId

    число

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

TestMatchOutcomeResult

Хром 103+

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

  • matchedRules

    MatchedRule []

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

TestMatchRequestDetails

Хром 103+

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

  • инициатор

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

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

  • метод

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

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

  • responseHeaders

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

    Хром 129+

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

  • tabId

    номер необязательно

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

  • тип

    ResourceType

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

  • URL-адрес

    нить

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

UnsupportedRegexReason

Хром 87+

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

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

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

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

UpdateRuleOptions

Хром 87+

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

  • addRules

    Правило [] необязательно

    Правила для добавления.

  • removeRuleIds

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

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

UpdateRulesetOptions

Хром 87+

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

  • disableRulesetIds

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

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

  • enableRulesetIds

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

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

UpdateStaticRulesOptions

Хром 111+

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

  • disableRuleIds

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

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

  • enableRuleIds

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

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

  • rulesetId

    нить

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

URLTransform

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

  • фрагмент

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

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

  • хозяин

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

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

  • пароль

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

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

  • путь

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

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

  • порт

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

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

  • запрос

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

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

  • queryTransform

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

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

  • схема

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

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

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

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

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

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

DYNAMIC_RULESET_ID

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

Ценить

"_динамичный"

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

Хром 90+

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

Ценить

"_session"

Методы

getAvailableStaticRuleCount()

PromiseChrome 89+
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
): Promise<number>

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

Параметры

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

    function optional

    The callback parameter looks like: 

    (count: number) => void

    • считать

      число

Возврат

  • Promise<number>

    Chrome 91+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

getDisabledRuleIds()

PromiseChrome 111+
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
  callback?: function,
): Promise<number[]>

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

Параметры

  • параметры

    GetDisabledRuleIdsOptions

    Specifies the ruleset to query.

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

    function optional

    The callback parameter looks like: 

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      число[]

Возврат

  • Promise<number[]>

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

getDynamicRules()

Обещать
chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
  callback?: function,
): 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.

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

    function optional

    The callback parameter looks like: 

    (rules: Rule[]) => void

    • правила

      Rule []

Возврат

  • Promise< Rule []>

    Chrome 91+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

getEnabledRulesets()

Обещать
chrome.declarativeNetRequest.getEnabledRulesets(
  callback?: function,
): Promise<string[]>

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

Параметры

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

    function optional

    The callback parameter looks like: 

    (rulesetIds: string[]) => void

    • rulesetIds

      нить[]

Возврат

  • Promise<string[]>

    Chrome 91+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

getMatchedRules()

Обещать
chrome.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
  callback?: function,
): 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.

Параметры

Возврат

  • Chrome 91+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

getSessionRules()

PromiseChrome 90+
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
  callback?: function,
): 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.

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

    function optional

    The callback parameter looks like: 

    (rules: Rule[]) => void

    • правила

      Rule []

Возврат

  • Promise< Rule []>

    Chrome 91+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

isRegexSupported()

PromiseChrome 87+
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
  callback?: function,
): Promise<IsRegexSupportedResult>

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

Параметры

Возврат

  • Chrome 91+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

setExtensionActionOptions()

PromiseChrome 88+
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
  callback?: function,
): 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

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

    function optional

    Chrome 89+

    The callback parameter looks like: 

    () => void

Возврат

  • Promise<void>

    Chrome 91+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

testMatchOutcome()

PromiseChrome 103+
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
): 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.

Параметры

Возврат

  • Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

updateDynamicRules()

Обещать
chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
  callback?: function,
): 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+
  • перезвонить

    function optional

    The callback parameter looks like: 

    () => void

Возврат

  • Promise<void>

    Chrome 91+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

updateEnabledRulesets()

Обещать
chrome.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
  callback?: function,
): 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+
  • перезвонить

    function optional

    The callback parameter looks like: 

    () => void

Возврат

  • Promise<void>

    Chrome 91+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

updateSessionRules()

PromiseChrome 90+
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
  callback?: function,
): 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

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

    function optional

    The callback parameter looks like: 

    () => void

Возврат

  • Promise<void>

    Chrome 91+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

updateStaticRules()

PromiseChrome 111+
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
  callback?: function,
): 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

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

    function optional

    The callback parameter looks like: 

    () => void

Возврат

  • Promise<void>

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

События

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.

Параметры