Эта страница переведена с помощью Cloud Translation API.

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, поскольку это требует меньше вычислительных затрат.

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

конструктор
пустота
Функция constructor выглядит так:
```
(arg: AddRequestCookie)=> {...}
```
- аргумент
  ДобавитьзапросCookie
- возвращает
  ДобавитьзапросCookie
печенье
ЗапросCookie
Файл cookie, который будет добавлен в запрос. Ни одно поле не может быть неопределенным.

AddResponseCookie

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

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

конструктор
пустота
Функция constructor выглядит так:
```
(arg: AddResponseCookie)=> {...}
```
- аргумент
  Аддреспонсекуки
- возвращает
  Аддреспонсекуки
печенье
ОтветCookie
Файл cookie, который будет добавлен в ответ. Необходимо указать имя и значение.

AddResponseHeader

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

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

конструктор
пустота
Функция constructor выглядит так:
```
(arg: AddResponseHeader)=> {...}
```
- аргумент
  Аддответхеадер
- возвращает
  Аддответхеадер
имя
нить
Имя заголовка HTTP-ответа.
ценить
нить
Значение заголовка ответа HTTP.

CancelRequest

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

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

конструктор
пустота
Функция constructor выглядит так:
```
(arg: CancelRequest)=> {...}
```
- аргумент
  Отменить запрос
- возвращает
  Отменить запрос

EditRequestCookie

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

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

конструктор
пустота
Функция constructor выглядит так:
```
(arg: EditRequestCookie)=> {...}
```
- аргумент
  РедактироватьЗапросCookie
- возвращает
  РедактироватьЗапросCookie
фильтр
ЗапросCookie
Отфильтруйте файлы cookie, которые будут изменены. Все пустые записи игнорируются.
модификация
ЗапросCookie
Атрибуты, которые должны быть переопределены в файлах cookie, соответствующих фильтру. Атрибуты, которым присвоена пустая строка, удаляются.

EditResponseCookie

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

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

конструктор
пустота
Функция constructor выглядит так:
```
(arg: EditResponseCookie)=> {...}
```
- аргумент
  EditResponseCookie
- возвращает
  EditResponseCookie
фильтр
ФильтрОтветCookie
Отфильтруйте файлы 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)=> {...}
```
- аргумент
  ПеренаправлениеByRegEx
- возвращает
  ПеренаправлениеByRegEx
от
нить
Шаблон соответствия, который может содержать группы захвата. Группы захвата упоминаются в синтаксисе Perl ($1, $2, ...) вместо синтаксиса RE2 (\1, \2, ...), чтобы быть ближе к регулярным выражениям JavaScript.
к
нить
Шаблон назначения.

RedirectRequest

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

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

конструктор
пустота
Функция constructor выглядит так:
```
(arg: RedirectRequest)=> {...}
```
- аргумент
  Запрос перенаправления
- возвращает
  Запрос перенаправления
URL-адрес перенаправления
нить
Назначение, куда перенаправляется запрос.

RedirectToEmptyDocument

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

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

конструктор
пустота
Функция constructor выглядит так:
```
(arg: RedirectToEmptyDocument)=> {...}
```
- аргумент
  Перенаправление на пустой документ
- возвращает
  Перенаправление на пустой документ

RedirectToTransparentImage

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

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

конструктор
пустота
Функция constructor выглядит так:
```
(arg: RedirectToTransparentImage)=> {...}
```
- аргумент
  ПеренаправлениеToTransparentImage
- возвращает
  ПеренаправлениеToTransparentImage

RemoveRequestCookie

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

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

конструктор
пустота
Функция constructor выглядит так:
```
(arg: RemoveRequestCookie)=> {...}
```
- аргумент
  Удалить запросCookie
- возвращает
  Удалить запросCookie
фильтр
ЗапросCookie
Отфильтруйте файлы cookie, которые будут удалены. Все пустые записи игнорируются.

RemoveRequestHeader

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

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

конструктор
пустота
Функция constructor выглядит так:
```
(arg: RemoveRequestHeader)=> {...}
```
- аргумент
  Удалитьреквестхедер
- возвращает
  Удалитьреквестхедер
имя
нить
Имя заголовка HTTP-запроса (без учета регистра).

RemoveResponseCookie

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

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

конструктор
пустота
Функция constructor выглядит так:
```
(arg: RemoveResponseCookie)=> {...}
```
- аргумент
  УдалитьОтветCookie
- возвращает
  УдалитьОтветCookie
фильтр
ФильтрОтветCookie
Отфильтруйте файлы cookie, которые будут удалены. Все пустые записи игнорируются.

RemoveResponseHeader

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

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

конструктор
пустота
Функция constructor выглядит так:
```
(arg: RemoveResponseHeader)=> {...}
```
- аргумент
  УдалитьОтветхедер
- возвращает
  УдалитьОтветхедер
имя
нить
Имя заголовка HTTP-запроса (без учета регистра).
ценить
строка необязательна
Значение заголовка HTTP-запроса (регистронезависимо).

RequestCookie

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

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

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

RequestMatcher

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

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

конструктор
пустота
Функция constructor выглядит так:
```
(arg: RequestMatcher)=> {...}
```
- аргумент
  RequestMatcher
- возвращает
  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 .

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

конструктор
пустота
Функция constructor выглядит так:
```
(arg: SendMessageToExtension)=> {...}
```
- аргумент
  Отправитьмессажетоэкстенсион
- возвращает
  Отправитьмессажетоэкстенсион
сообщение
нить
Значение, которое будет передано в атрибуте message словаря, передаваемого обработчику событий.

SetRequestHeader

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

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

конструктор
пустота
Функция constructor выглядит так:
```
(arg: SetRequestHeader)=> {...}
```
- аргумент
  SetRequestHeader
- возвращает
  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 указывает идентификатор этого кадра, а не идентификатор внешнего кадра. Идентификаторы кадров уникальны в пределах вкладки.
  - Тип рамки
    тип расширения.FrameType
    Тип фрейма, в котором происходила навигация.
  - сообщение
    нить
    Сообщение, отправленное вызывающим скриптом.
  - метод
    нить
    Стандартный метод HTTP.
  - родительскийDocumentId
    строка необязательна
    UUID родительского документа, владеющего этим фреймом. Это не установлено, если нет родителя.
  - родительскийFrameId
    число
    Идентификатор кадра, который заключает в себе кадр, отправивший запрос. Установите значение -1, если родительский фрейм не существует.
  - идентификатор запроса
    нить
    Идентификатор запроса. Идентификаторы запросов уникальны в рамках сеанса браузера. В результате их можно было использовать для связи разных событий одного и того же запроса.
  - этап
    Этап
    Этап сетевого запроса, на котором произошло событие.
  - идентификатор табуляции
    число
    Идентификатор вкладки, в которой происходит запрос. Установите значение -1, если запрос не связан с вкладкой.
  - метка времени
    число
    Время срабатывания этого сигнала в миллисекундах с начала эпохи.
  - тип
    вебрекуест.ResourceType
    Как будет использоваться запрошенный ресурс.
  - URL
    нить