chrome.declarativeNetRequest

Описание

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

Разрешения

declarativeNetRequest
declarativeNetRequestWithHostAccess

declarativeNetRequestFeedback
host_permissions

Доступность

Chrome 84+

Манифест

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

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

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

Понятия и применение

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

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

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

Динамический
Сохраняются между сессиями браузера и обновлениями расширений и управляются с помощью JavaScript во время использования расширения.
Сессия
Сбрасывается при закрытии браузера и при установке новой версии расширения. Правила сессии управляются с помощью JavaScript во время использования расширения.
Статический
Упаковывается, устанавливается и обновляется при установке или обновлении расширения. Статические правила хранятся в файлах правил в формате JSON и перечисляются в файле манифеста.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Для включения или отключения статических наборов правил вызовите метод ` 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-адреса правило с ID 2 теперь соответствует требованиям в дополнение к правилам с ID 1 и 4. Правило с ID 2 применяется, потому что "allow" имеет более высокий приоритет, чем "block" и "redirect" .
Перейти по ссылке https://google.com/12345
Все четыре правила соответствуют этому URL-адресу. Правило с ID 3 применяется, поскольку его приоритет, определенный разработчиком, является наивысшим в группе. 
[
  {
    "id": 1,
    "priority": 1,
    "action": { "type": "block" },
    "condition": {"urlFilter": "google.com", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 2,
    "priority": 1,
    "action": { "type": "allow" },
    "condition": { "urlFilter": "google.com/123", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 3,
    "priority": 2,
    "action": { "type": "block" },
    "condition": { "urlFilter": "google.com/12345", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 4,
    "priority": 1,
    "action": { "type": "redirect", "redirect": { "url": "https://example.com" } },
    "condition": { "urlFilter": "google.com", "resourceTypes": ["main_frame"] }
  },
]

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

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

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

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

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

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

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

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

Заголовки

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

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

Типы

DomainType

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

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

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

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

ExtensionActionOptions

Chrome 88+

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

  • displayActionCountAsBadgeText

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

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

  • tabUpdate

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

    Chrome 89+

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

GetDisabledRuleIdsOptions

Chrome 111+

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

  • rulesetId

    нить

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

GetRulesFilter

Chrome 111+

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

  • ruleIds

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

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

HeaderInfo

Chrome 128+

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

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

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

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

  • заголовок

    нить

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

  • ценности

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

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

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

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

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

HeaderOperation

Chrome 86+

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

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

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

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

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

IsRegexSupportedResult

Chrome 87+

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

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

    логический

  • причина

    UnsupportedRegexReason optional

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

MatchedRule

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

  • ruleId

    число

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

  • rulesetId

    нить

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

MatchedRuleInfo

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

  • правило

    MatchedRule

  • tabId

    число

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

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

    число

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

MatchedRuleInfoDebug

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

  • запрос

    RequestDetails

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

  • правило

    MatchedRule

MatchedRulesFilter

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

  • minTimeStamp

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

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

  • tabId

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

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

ModifyHeaderInfo

Chrome 86+

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

  • заголовок

    нить

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

  • операция

    HeaderOperation

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

  • ценить

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

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

QueryKeyValue

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

  • ключ

    нить

  • replaceOnly

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

    Chrome 94+

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

  • ценить

    нить

QueryTransform

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

  • addOrReplaceParams

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

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

  • removeParams

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

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

Redirect

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

  • extensionPath

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

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

  • regexSubstitution

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

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

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

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

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

  • url

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

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

RegexOptions

Chrome 87+

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

  • isCaseSensitive

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

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

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

    нить

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

  • requireCapturing

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

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

RequestDetails

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

  • documentId

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

    Chrome 106+

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

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

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

    Chrome 106+

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

  • frameId

    число

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

  • frameType

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

    Chrome 106+

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

  • инициатор

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

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

  • метод

    нить

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

  • parentDocumentId

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

    Chrome 106+

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

  • parentFrameId

    число

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

  • requestId

    нить

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

  • tabId

    число

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

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

  • url

    нить

    URL запроса.

RequestMethod

Chrome 91+

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

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

"соединять"

"удалить"

"получать"

"голова"

"параметры"

"пластырь"

"почта"

"помещать"

"другой"

ResourceType

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

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

"main_frame"

"sub_frame"

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

"сценарий"

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

"шрифт"

"объект"

"xmlhttprequest"

"пинг"

"csp_report"

«медиа»

"вебсокет"

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

"webbundle"

"другой"

Rule

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

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

  • состояние

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

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

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

    число

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

  • приоритет

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

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

RuleAction

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

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

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

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

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

    ModifyHeaderInfo [] optional

    Chrome 86+

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

  • responseHeaders

    ModifyHeaderInfo [] optional

    Chrome 86+

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

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

RuleActionType

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

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

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

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

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

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

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

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

RuleCondition

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

  • domainType

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

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

  • домены

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

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

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

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

  • excludedDomains

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

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

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

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

  • excludedInitiatorDomains

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

    Chrome 101+

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

    Примечания:

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

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

    Chrome 101+

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

    Примечания:

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

    RequestMethod [] optional

    Chrome 91+

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

  • excludedResourceTypes

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

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

  • excludedResponseHeaders

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

    Chrome 128+

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

  • excludedTabIds

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

    Chrome 92+

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

  • excludedTopDomains

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

    В ожидании

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

    Примечания:

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

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

    Chrome 101+

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

    Примечания:

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

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

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

  • regexFilter

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

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

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

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

  • requestDomains

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

    Chrome 101+

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

    Примечания:

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

    RequestMethod [] optional

    Chrome 91+

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

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

  • resourceTypes

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

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

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

  • responseHeaders

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

    Chrome 128+

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

  • tabIds

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

    Chrome 92+

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

  • topDomains

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

    В ожидании

    Правило будет соответствовать сетевым запросам только в том случае, если домен соответствующего фрейма верхнего уровня совпадает с одним из доменов в списке 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

В ожидании

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

"urlFilter"

"regexFilter"

"isUrlFilterCaseSensitive"

"initiatorDomains"

"excludedInitiatorDomains"

"requestDomains"

"excludedRequestDomains"

"topDomains"

"исключенныеТопДомены"

«домены»

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

"resourceTypes"

"excludedResourceTypes"

"requestMethods"

"excludedRequestMethods"

"domainType"

"tabIds"

"excludedTabIds"

"responseHeaders"

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

Ruleset

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

  • включено

    логический

    Указывает, включен ли набор правил по умолчанию.

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

    нить

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

  • путь

    нить

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

RulesMatchedDetails

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

  • rulesMatchedInfo

    MatchedRuleInfo []

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

TabActionCountUpdate

Chrome 89+

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

  • увеличение

    число

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

  • tabId

    число

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

TestMatchOutcomeResult

Chrome 103+

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

  • matchedRules

    MatchedRule []

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

TestMatchRequestDetails

Chrome 103+

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

  • инициатор

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

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

  • метод

    RequestMethod ( необязательный параметр)

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

  • responseHeaders

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

    Chrome 129+

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

  • tabId

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

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

  • topUrl

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

    В ожидании

    Связанный с запросом URL-адрес фрейма верхнего уровня (если таковой имеется).

  • тип

    ResourceType

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

  • url

    нить

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

UnsupportedRegexReason

Chrome 87+

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

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

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

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

UpdateRuleOptions

Chrome 87+

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

  • addRules

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

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

  • removeRuleIds

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

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

UpdateRulesetOptions

Chrome 87+

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

  • disableRulesetIds

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

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

  • enableRulesetIds

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

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

UpdateStaticRulesOptions

Chrome 111+

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

  • disableRuleIds

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

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

  • enableRuleIds

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

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

  • rulesetId

    нить

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

URLTransform

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

  • фрагмент

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

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

  • хозяин

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

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

  • пароль

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

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

  • путь

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

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

  • порт

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

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

  • запрос

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

    Новый запрос для данного запроса. Он должен быть либо пустым, в этом случае существующий запрос удаляется, либо начинаться с '?'.

  • queryTransform

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

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

  • схема

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

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

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

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

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

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

DYNAMIC_RULESET_ID

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

Ценить

"_динамический"

GETMATCHEDRULES_QUOTA_INTERVAL

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

Ценить

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89+

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

Ценить

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

Количество вызовов функции getMatchedRules в течение периода, равного GETMATCHEDRULES_QUOTA_INTERVAL .

Ценить

20

MAX_NUMBER_OF_DYNAMIC_RULES

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

Ценить

30000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94+

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

Ценить

50

MAX_NUMBER_OF_REGEX_RULES

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

Ценить

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120+

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

Ценить

5000

MAX_NUMBER_OF_STATIC_RULESETS

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

Ценить

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120+

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

Ценить

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120+

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

Ценить

5000

SESSION_RULESET_ID

Chrome 90+

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

Ценить

"_session"

Методы

getAvailableStaticRuleCount()

Promise Chrome 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.

Параметры

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

    функция необязательна

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

    (count: number) => void

    • считать

      число

Возвраты

  • Обещание<число>

    Chrome 91+

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

getDisabledRuleIds()

Promise Chrome 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.

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

    функция необязательна

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

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      число[]

Возвраты

  • Promise<number[]>

    Promise that resolves with a list of ids that correspond to the disabled rules in that ruleset.

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

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.

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

    функция необязательна

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

    (rules: Rule[]) => void

    • правила

      Rule []

Возвраты

  • Promise< Rule []>

    Chrome 91+

    Promise that resolves with the set of dynamic rules. The Promise may be rejected in case of transient internal errors.

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

getEnabledRulesets()

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

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

Параметры

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

    функция необязательна

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

    (rulesetIds: string[]) => void

    • rulesetIds

      нить[]

Возвраты

  • Promise<string[]>

    Chrome 91+

    Promise that resolves with a list of ids, where each id corresponds to an enabled static Ruleset .

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

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.

Параметры

  • фильтр

    MatchedRulesFilter optional

    An object to filter the list of matched rules.

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

    функция необязательна

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

    (details: RulesMatchedDetails) => void

Возвраты

  • Chrome 91+

    Promise that resolves once the list of matched rules has been fetched. In case of an error, the Promise will be rejected. This can happen for multiple reasons, such as insufficient permissions, or exceeding the quota.

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

getSessionRules()

Promise Chrome 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.

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

    функция необязательна

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

    (rules: Rule[]) => void

    • правила

      Rule []

Возвраты

  • Promise< Rule []>

    Chrome 91+

    Promise that resolves with the set of session scoped rules.

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

isRegexSupported()

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

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

Параметры

  • regexOptions

    RegexOptions

    The regular expression to check.

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

    функция необязательна

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

    (result: IsRegexSupportedResult) => void

Возвраты

  • Chrome 91+

    Promise that resolves with details consisting of whether the regular expression is supported and the reason if not.

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

setExtensionActionOptions()

Promise Chrome 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

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

    функция необязательна

    Chrome 89+

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

    () => void

Возвраты

  • Обещание<пустота>

    Chrome 91+

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

testMatchOutcome()

Promise Chrome 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.

Параметры

Возвраты

  • Promise that resolves with the details of matched rules.

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

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+
  • перезвонить

    функция необязательна

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

    () => void

Возвраты

  • Обещание<пустота>

    Chrome 91+

    Promise that resolves once the update is complete. In case of an error, the promise will be rejected and no change will be made to the rule set. This can happen for multiple reasons, such as invalid rule format, duplicate rule ID, rule count limit exceeded, internal errors, and others.

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

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+
  • перезвонить

    функция необязательна

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

    () => void

Возвраты

  • Обещание<пустота>

    Chrome 91+

    Promise that resolves once the update is complete. In case of an error, the promise will be rejected and no change will be made to the set of enabled rulesets. This can happen for multiple reasons, such as invalid ruleset IDs, rule count limit exceeded, or internal errors.

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

updateSessionRules()

Promise Chrome 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

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

    функция необязательна

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

    () => void

Возвраты

  • Обещание<пустота>

    Chrome 91+

    Promise that resolves once the update is complete. In case of an error, the promise will be rejected and no change will be made to the rule set. This can happen for multiple reasons, such as invalid rule format, duplicate rule ID, rule count limit exceeded, and others.

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

updateStaticRules()

Promise Chrome 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

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

    функция необязательна

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

    () => void

Возвраты

  • Обещание<пустота>

    Promise that resolves when the update is complete. In case of an error, the promise will be rejected and no change will be made to the enabled static rules.

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

События

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.

Параметры