chrome.declarativeWebRequest

Описание

Примечание. Этот API устарел. Вместо этого ознакомьтесь с API declarativeNetRequest . Используйте API chrome.declarativeWebRequest для перехвата, блокировки или изменения запросов в реальном времени. Это значительно быстрее, чем API chrome.webRequest , поскольку вы можете регистрировать правила, которые оцениваются в браузере, а не в движке JavaScript, что снижает задержки в обоих направлениях и обеспечивает более высокую эффективность.

Разрешения

declarativeWebRequest

Чтобы использовать этот API, вы должны объявить разрешение «declarativeWebRequest» в манифесте расширения вместе с разрешениями хоста .

{
  "name": "My extension",
  ...
  "permissions": [
    "declarativeWebRequest",
    "*://*/*"
  ],
  ...
}

Доступность

Бета-канал ≤ MV2

Манифест

Обратите внимание, что некоторые типы неконфиденциальных действий не требуют разрешений хоста:

  • CancelRequest
  • IgnoreRules
  • RedirectToEmptyDocument
  • RedirectToTransparentImage

Действие SendMessageToExtension() требует разрешений хоста для всех хостов, чьи сетевые запросы вы хотите инициировать сообщение.

Для всех остальных действий требуются разрешения хоста для всех URL-адресов.

Например, если "https://*.google.com/*" — единственное разрешение хоста, которое имеет расширение, то такое расширение может установить правило для:

  • Отмените запрос на https://www.google.com или https://anything.else.com .
  • Отправьте сообщение при переходе на https://www.google.com но не на https://something.else.com .

Расширение не может настроить правило для перенаправления https://www.google.com на https://mail.google.com .

Правила

Декларативный API веб-запросов следует концепциям Декларативного API . Вы можете зарегистрировать правила в объекте события chrome.declarativeWebRequest.onRequest .

API декларативных веб-запросов поддерживает один тип критериев соответствия — RequestMatcher . RequestMatcher сопоставляет сетевые запросы тогда и только тогда, когда все перечисленные критерии выполняются. Следующий RequestMatcher будет соответствовать сетевому запросу, когда пользователь вводит https://www.example.com в ominibox:

var matcher = new chrome.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com', schemes: ['http'] },
  resourceType: ['main_frame']
});

Запросы к https://www.example.com будут отклонены RequestMatcher из-за этой схемы. Кроме того, все запросы на встроенный iframe будут отклонены из-за resourceType .

Чтобы отменить все запросы к «example.com», вы можете определить правило следующим образом:

var rule = {
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'example.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]
};

Чтобы отменить все запросы к example.com и foobar.com , вы можете добавить второе условие, поскольку каждого условия достаточно для запуска всех указанных действий:

var rule2 = {
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'example.com' } }),
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'foobar.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]
};

Правила регистрации следующие:

chrome.declarativeWebRequest.onRequest.addRules([rule2]);

Оценка условий и действий

Декларативный API веб-запросов соответствует модели жизненного цикла веб-запросов API веб-запросов . Это означает, что условия можно тестировать только на определенных этапах веб-запроса, а действия также могут выполняться только на определенных этапах. В следующих таблицах перечислены этапы запроса, совместимые с условиями и действиями.

Этапы запроса, на которых могут обрабатываться атрибуты условий.
Атрибут условия onBeforeRequest onBeforeSendHeaders onHeadersReceived onAuthRequired
url ✓ ✓ ✓ ✓
resourceType ✓ ✓ ✓ ✓
contentType ✓
excludeContentType ✓
responseHeaders ✓
excludeResponseHeaders ✓
requestHeaders ✓
excludeRequestHeaders ✓
thirdPartyForCookies ✓ ✓ ✓ ✓
Этапы запроса, на которых могут выполняться действия.
Событие onBeforeRequest onBeforeSendHeaders onHeadersReceived onAuthRequired
AddRequestCookie ✓
AddResponseCookie ✓
AddResponseHeader ✓
CancelRequest ✓ ✓ ✓ ✓
EditRequestCookie ✓
EditResponseCookie ✓
IgnoreRules ✓ ✓ ✓ ✓
RedirectByRegEx ✓ ✓
RedirectRequest ✓ ✓
RedirectToEmptyDocument ✓ ✓
RedirectToTransparentImage ✓ ✓
RemoveRequestCookie ✓
RemoveRequestHeader ✓
RemoveResponseCookie ✓
RemoveResponseHeader ✓
SendMessageToExtension ✓ ✓ ✓ ✓
SetRequestHeader ✓

Используйте приоритеты для отмены правил

Правила можно связать с приоритетами, как описано в Events API . Этот механизм можно использовать для выражения исключений. В следующем примере блокируются все запросы к изображениям с именем evil.jpg , кроме сервера «myserver.com».

var rule1 = {
  priority: 100,
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
        url: { pathEquals: 'evil.jpg' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]
};
var rule2 = {
  priority: 1000,
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: '.myserver.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.IgnoreRules({
      lowerPriorityThan: 1000 })
  ]
};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

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

Типы

AddRequestCookie

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

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

AddResponseCookie

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

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

AddResponseHeader

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

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

CancelRequest

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

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

EditRequestCookie

Редактирует один или несколько файлов cookie запроса. Обратите внимание, что предпочтительнее использовать API файлов cookie, поскольку это требует меньше вычислительных затрат.

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

  • конструктор

    пустота

    Функция constructor выглядит так: 

    (arg: EditRequestCookie) => {...}

  • фильтр

    ЗапросCookie

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

  • модификация

    ЗапросCookie

    Атрибуты, которые должны быть переопределены в файлах cookie, соответствующих фильтру. Атрибуты, которым присвоена пустая строка, удаляются.

EditResponseCookie

Редактирует один или несколько файлов cookie ответа. Обратите внимание, что предпочтительнее использовать API файлов cookie, поскольку это требует меньше вычислительных затрат.

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

  • конструктор

    пустота

    Функция constructor выглядит так: 

    (arg: EditResponseCookie) => {...}

  • Отфильтруйте файлы cookie, которые будут изменены. Все пустые записи игнорируются.

  • модификация

    ОтветCookie

    Атрибуты, которые должны быть переопределены в файлах cookie, соответствующих фильтру. Атрибуты, которым присвоена пустая строка, удаляются.

FilterResponseCookie

Фильтр файлов cookie в ответах HTTP.

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

  • возрастLowerBound

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

    Включающая нижняя граница срока действия файлов cookie (указанная в секундах после текущего времени). Этому критерию соответствуют только файлы cookie, дата и время истечения срока действия которых установлены на «сейчас + ageLowerBound» или позже. Сеансовые файлы cookie не соответствуют критериям этого фильтра. Срок действия файлов cookie рассчитывается на основе атрибутов файлов cookie «max-age» или «expires». Если указаны оба параметра, для расчета срока службы файлов cookie используется «max-age».

  • возрастUpperBound

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

    Включающая верхняя граница срока действия файлов cookie (указывается в секундах после текущего времени). Этому критерию соответствуют только файлы cookie, дата и время окончания срока действия которых находится в интервале [сейчас, сейчас + ageUpperBound]. Сеансовые файлы cookie и файлы cookie, срок действия которых истекает в прошлом, не соответствуют критерию этого фильтра. Срок действия cookie рассчитывается на основе атрибутов cookie «max-age» или «expires». Если указаны оба параметра, для расчета срока службы файлов cookie используется «max-age».

  • домен

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

    Значение атрибута cookie домена.

  • истекает

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

    Значение атрибута cookie Expires.

  • httpOnly

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

    Наличие атрибута cookie HttpOnly.

  • МаксВозраст

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

    Значение атрибута cookie Max-Age

  • имя

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

    Имя файла cookie.

  • путь

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

    Значение атрибута cookie Path.

  • безопасный

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

    Наличие атрибута Secure cookie.

  • сеансCookie

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

    Фильтрует файлы cookie сеанса. Сеансовые файлы cookie не имеют срока действия, указанного в атрибутах «max-age» или «expire».

  • ценить

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

    Значение файла cookie может быть заключено в двойные кавычки.

HeaderFilter

Фильтрует заголовки запросов по различным критериям. Несколько критериев оцениваются как совокупность.

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

  • имяСодержит

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

    Соответствует, если имя заголовка содержит все указанные строки.

  • имяРавно

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

    Соответствует, если имя заголовка равно указанной строке.

  • имяПрефикс

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

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

  • имяСуффикс

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

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

  • значениеСодержит

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

    Соответствует, если значение заголовка содержит все указанные строки.

  • значениеРавно

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

    Соответствует, если значение заголовка равно указанной строке.

  • значениеПрефикс

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

    Соответствует, если значение заголовка начинается с указанной строки.

  • значениеСуффикс

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

    Соответствует, если значение заголовка заканчивается указанной строкой.

IgnoreRules

Маскирует все правила, соответствующие указанным критериям.

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

  • конструктор

    пустота

    Функция constructor выглядит так: 

    (arg: IgnoreRules) => {...}

  • имеет тег

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

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

  • более низкий приоритет, чем

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

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

RedirectByRegEx

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

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

  • конструктор

    пустота

    Функция constructor выглядит так: 

    (arg: RedirectByRegEx) => {...}

  • от

    нить

    Шаблон соответствия, который может содержать группы захвата. Группы захвата упоминаются в синтаксисе Perl ($1, $2, ...) вместо синтаксиса RE2 (\1, \2, ...), чтобы быть ближе к регулярным выражениям JavaScript.

  • к

    нить

    Шаблон назначения.

RedirectRequest

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

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

RedirectToEmptyDocument

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

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

RedirectToTransparentImage

Декларативное событие, которое перенаправляет сетевой запрос на прозрачное изображение.

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

RemoveRequestCookie

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

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

RemoveRequestHeader

Удаляет заголовок запроса указанного имени. Не используйте SetRequestHeader и RemoveRequestHeader с одинаковым именем заголовка в одном и том же запросе. Каждое имя заголовка запроса встречается только один раз в каждом запросе.

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

RemoveResponseCookie

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

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

RemoveResponseHeader

Удаляет все заголовки ответов с указанными именами и значениями.

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

  • конструктор

    пустота

    Функция constructor выглядит так: 

    (arg: RemoveResponseHeader) => {...}

  • имя

    нить

    Имя заголовка HTTP-запроса (без учета регистра).

  • ценить

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

    Значение заголовка HTTP-запроса (регистронезависимо).

RequestCookie

Фильтр или спецификация файла cookie в HTTP-запросах.

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

  • имя

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

    Имя файла cookie.

  • ценить

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

    Значение файла cookie может быть заключено в двойные кавычки.

RequestMatcher

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

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

  • конструктор

    пустота

    Функция constructor выглядит так: 

    (arg: RequestMatcher) => {...}

  • тип контента

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

    Соответствует, если в списке содержится тип носителя MIME ответа (из заголовка HTTP Content-Type).

  • исключатьконтенттипе

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

    Соответствует, если тип носителя MIME ответа (из заголовка HTTP Content-Type) не содержится в списке.

  • исключить заголовки запроса

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

    Соответствует, если ни один из заголовков запроса не соответствует ни одному из HeaderFilters.

  • исключитьResponseHeaders

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

    Соответствует, если ни один из заголовков ответа не соответствует ни одному из HeaderFilters.

  • firstPartyForCookiesUrl

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

    Устарело

    Игнорируется с версии 82.

    Соответствует, если условия UrlFilter выполнены для «основного» URL-адреса запроса. «Основной» URL-адрес запроса, если он присутствует, может отличаться от целевого URL-адреса запроса и описывает то, что считается «основным» для сторонних проверок на наличие файлов cookie.

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

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

    Соответствует, если некоторые заголовки запроса совпадают с одним из HeaderFilters.

  • тип ресурса

    ТипРесурса [] необязательно

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

  • Заголовки ответа

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

    Соответствует, если некоторые заголовки ответов совпадают с одним из HeaderFilters.

  • этапы

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

    Содержит список строк, описывающих этапы. Допустимые значения: «onBeforeRequest», «onBeforeSendHeaders», «onHeadersReceived», «onAuthRequired». Если этот атрибут присутствует, он ограничивает применимые этапы перечисленными. Обратите внимание, что все условие применимо только на этапах, совместимых со всеми атрибутами.

  • третьяпартияфоркукиес

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

    Устарело

    Игнорируется с версии 87.

    Если установлено значение true, сопоставляет запросы, на которые распространяются политики сторонних файлов cookie. Если установлено значение false, соответствует всем остальным запросам.

  • URL

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

    Соответствует, если для URL-адреса запроса выполняются условия UrlFilter.

ResponseCookie

Спецификация файла cookie в ответах HTTP.

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

  • домен

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

    Значение атрибута cookie домена.

  • истекает

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

    Значение атрибута cookie Expires.

  • httpOnly

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

    Наличие атрибута cookie HttpOnly.

  • МаксВозраст

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

    Значение атрибута cookie Max-Age

  • имя

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

    Имя файла cookie.

  • путь

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

    Значение атрибута cookie Path.

  • безопасный

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

    Наличие атрибута Secure cookie.

  • ценить

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

    Значение файла cookie может быть заключено в двойные кавычки.

SendMessageToExtension

Запускает событие declarativeWebRequest.onMessage .

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

SetRequestHeader

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

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

  • конструктор

    пустота

    Функция constructor выглядит так: 

    (arg: SetRequestHeader) => {...}

  • имя

    нить

    Имя заголовка HTTP-запроса.

  • ценить

    нить

    Значение заголовка HTTP-запроса.

Stage

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

"onBeforeRequest"

"онбефоресендхедерс"

"onHeadersReceived"

"onAuthRequired"

События

onMessage

chrome.declarativeWebRequest.onMessage.addListener(
  callback: function,
)

Запускается, когда сообщение отправляется через declarativeWebRequest.SendMessageToExtension из действия API декларативного веб-запроса.

Параметры

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

    функция

    Параметр callback выглядит так: 

    (details: object) => void

    • подробности

      объект

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

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

        UUID документа, отправившего запрос.

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

        ExtensionTypes.DocumentLifecycle

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

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

        число

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

      • Тип фрейма, в котором происходила навигация.

      • сообщение

        нить

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

      • метод

        нить

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

      • родительскийDocumentId

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

        UUID родительского документа, владеющего этим фреймом. Это не установлено, если нет родителя.

      • родительскийFrameId

        число

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

      • идентификатор запроса

        нить

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

      • этап

        Этап

        Этап сетевого запроса, на котором произошло событие.

      • идентификатор табуляции

        число

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

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

        число

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

      • Как будет использоваться запрошенный ресурс.

      • URL

        нить

onRequest

Предоставляет API декларативных событий , состоящий из addRules , removeRules и getRules .

Условия

RequestMatcher

Действия

ДобавитьзапросCookie

Аддреспонсекуки

Аддответхеадер

ОтменаЗапрос

РедактироватьЗапросCookie

EditResponseCookie

Запрос перенаправления

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

Перенаправление на пустой документ

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

Удалить запросCookie

УдалитьОтветCookie

Удалитьреквестхедер

УдалитьОтветхедер

SetRequestHeader

Отправитьмессажетоэкстенсион

Игнорировать правила