Эта страница переведена с помощью 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 в адресную строку:

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]);

Примечание: Регистрировать или отменять регистрацию правил всегда следует пакетно, а не по отдельности, поскольку каждая из этих операций создает новые внутренние структуры данных. Это создание требует значительных вычислительных ресурсов, но обеспечивает очень быстрый алгоритм сопоставления URL-адресов для сотен тысяч URL-адресов. Дополнительные рекомендации по повышению производительности приведены в разделе «Производительность » API событий .

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

Декларативный 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`		✓

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

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

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

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

AddResponseCookie

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

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

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

AddResponseHeader

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

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

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

CancelRequest

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

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

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

EditRequestCookie

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

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

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

EditResponseCookie

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

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

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

FilterResponseCookie

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

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

ageLowerBound
число необязательно
Нижняя граница срока действия cookie-файлов (указывается в секундах после текущего времени). Этому критерию соответствуют только cookie-файлы, дата и время истечения срока действия которых установлены на 'now + ageLowerBound' или позже. Сессионные cookie-файлы не соответствуют критерию этого фильтра. Срок действия cookie-файлов рассчитывается на основе атрибутов cookie 'max-age' или 'expires'. Если указаны оба атрибута, для расчета срока действия cookie используется 'max-age'.
ageUpperBound
число необязательно
Верхняя граница срока действия cookie-файлов (указывается в секундах после текущего времени). Этому критерию соответствуют только cookie-файлы, дата и время истечения срока действия которых находятся в интервале [сейчас, сейчас + ageUpperBound]. Сессионные cookie-файлы и cookie-файлы, дата и время истечения срока действия которых находятся в прошлом, не соответствуют критерию этого фильтра. Срок действия cookie-файлов рассчитывается на основе атрибутов cookie 'max-age' или 'expires'. Если указаны оба атрибута, для расчета срока действия cookie используется 'max-age'.
домен
строка необязательный
Значение атрибута cookie "Домен".
истекает
строка необязательный
Значение атрибута cookie Expires.
httpТолько
строка необязательный
Наличие атрибута HttpOnly в cookie.
максВозраст
число необязательно
Значение атрибута Max-Age файла cookie
имя
строка необязательный
Название файла cookie.
путь
строка необязательный
Значение атрибута cookie Path.
безопасный
строка необязательный
Наличие атрибута Secure cookie.
сессионный файл cookie
логический необязательный
Фильтрует сессионные cookie. Срок действия сессионных cookie не указан ни в одном из атрибутов 'max-age' или 'expires'.
ценить
строка необязательный
Значение cookie-файла может быть дополнено двойными кавычками.

HeaderFilter

Фильтры запрашивают заголовки для различных критериев. Несколько критериев оцениваются как конъюнкция.

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

nameContains
строка | строка[] необязательно
Совпадение происходит, если имя заголовка содержит все указанные строки.
имя равно
строка необязательный
Совпадение происходит, если имя заголовка совпадает с указанной строкой.
префикс имени
строка необязательный
Совпадение происходит, если имя заголовка начинается с указанной строки.
суффикс имени
строка необязательный
Совпадение происходит, если имя заголовка заканчивается указанной строкой.
valueСодержит
строка | строка[] необязательно
Соответствует условию, если значение заголовка содержит все указанные строки.
значение равно
строка необязательный
Соответствует, если значение заголовка совпадает с указанной строкой.
valuePrefix
строка необязательный
Совпадение происходит, если значение заголовка начинается с указанной строки.
значениеСуффикс
строка необязательный
Совпадение происходит, если значение заголовка заканчивается указанной строкой.

IgnoreRules

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

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

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

RedirectByRegEx

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

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

конструктор
пустота
Функция- constructor выглядит следующим образом:
```
(arg: RedirectByRegEx) => {...}
```
- арг
  RedirectByRegEx
- возвраты
  RedirectByRegEx
от
нить
Шаблон соответствия, который может содержать группы захвата. Группы захвата используются в синтаксисе Perl ($1, $2, ...) вместо синтаксиса RE2 (\1, \2, ...), чтобы быть ближе к регулярным выражениям JavaScript.
к
нить
Схема назначения.

RedirectRequest

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

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

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

RedirectToEmptyDocument

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

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

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

RedirectToTransparentImage

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

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

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

RemoveRequestCookie

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

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

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

RemoveRequestHeader

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

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

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

RemoveResponseCookie

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

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

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

RemoveResponseHeader

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

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

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

RequestCookie

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

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

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

RequestMatcher

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

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

конструктор
пустота
Функция- constructor выглядит следующим образом:
```
(arg: RequestMatcher) => {...}
```
- арг
  RequestMatcher
- возвраты
  RequestMatcher
contentType
строка[] необязательный
Совпадение происходит, если MIME-тип носителя ответа (из заголовка HTTP Content-Type) содержится в списке.
excludeContentType
строка[] необязательный
Срабатывает, если MIME-тип носителя ответа (из заголовка HTTP Content-Type) отсутствует в списке.
excludeRequestHeaders
HeaderFilter [] optional
Соответствует, если ни один из заголовков запроса не соответствует ни одному из фильтров заголовков.
excludeResponseHeaders
HeaderFilter [] optional
Соответствует, если ни один из заголовков ответа не соответствует ни одному из фильтров заголовков.
firstPartyForCookiesUrl
UrlFilter ( необязательно)
Устаревший
Игнорируется с момента выхода версии 82.
Соответствует условиям UrlFilter, если для URL-адреса запроса, относящегося к «первой стороне», выполняются условия. URL-адрес запроса, относящийся к «первой стороне», если он присутствует, может отличаться от целевого URL-адреса запроса и описывает, что считается «первой стороной» для целей проверки файлов cookie третьими сторонами.
заголовки запроса
HeaderFilter [] optional
Соответствует, если хотя бы один из заголовков запроса совпадает с одним из фильтров заголовков (HeaderFilters).
ресурсТип
ResourceType [] необязательный
Соответствует, если тип запроса содержится в списке. Запросы, которые не соответствуют ни одному из типов, будут отфильтрованы.
responseHeaders
HeaderFilter [] optional
Соответствует, если хотя бы один из заголовков ответа совпадает с одним из фильтров заголовков (HeaderFilters).
этапы
Этап [] необязательный
Содержит список строк, описывающих этапы. Допустимые значения: 'onBeforeRequest', 'onBeforeSendHeaders', 'onHeadersReceived', 'onAuthRequired'. Если этот атрибут присутствует, то он ограничивает применимые этапы перечисленными. Обратите внимание, что всё условие применимо только к этапам, совместимым со всеми атрибутами.
thirdPartyForCookies
логический необязательный
Устаревший
Игнорировалось с момента выхода версии 87.
Если установлено значение true, обрабатываются запросы, на которые распространяются политики использования файлов cookie третьих сторон. Если установлено значение false, обрабатываются все остальные запросы.
url
UrlFilter ( необязательно)
Соответствует условиям UrlFilter, если они выполняются для URL-адреса запроса.

ResponseCookie

Описание cookie-файла в HTTP-ответах.

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

домен
строка необязательный
Значение атрибута cookie "Домен".
истекает
строка необязательный
Значение атрибута cookie Expires.
httpТолько
строка необязательный
Наличие атрибута HttpOnly в cookie.
максВозраст
число необязательно
Значение атрибута Max-Age файла cookie
имя
строка необязательный
Название файла cookie.
путь
строка необязательный
Значение атрибута cookie Path.
безопасный
строка необязательный
Наличие атрибута Secure cookie.
ценить
строка необязательный
Значение cookie-файла может быть дополнено двойными кавычками.

SendMessageToExtension

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

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

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

SetRequestHeader

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

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

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

Stage

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

"onBeforeRequest"

"onBeforeSendHeaders"

"onHeadersReceived"

"onAuthRequired"

События

onMessage

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

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

Параметры

перезвонить
функция
Параметр callback выглядит следующим образом:
```
(details: object) => void
```
- подробности
  объект
  - documentId
    строка необязательный
    UUID документа, отправившего запрос.
  - жизненный цикл документа
    extensionTypes.DocumentLifecycle
    Жизненный цикл документа.
  - frameId
    число
    Значение 0 указывает на то, что запрос выполняется в главном фрейме; положительное значение указывает идентификатор подфрейма, в котором выполняется запрос. Если документ (под)фрейма загружен ( type main_frame или sub_frame ), frameId указывает идентификатор этого фрейма, а не идентификатор внешнего фрейма. Идентификаторы фреймов уникальны в пределах одной вкладки.
  - frameType
    extensionTypes.FrameType
    Тип фрейма, в котором происходила навигация.
  - сообщение
    нить
    Сообщение, отправленное вызывающим скриптом.
  - метод
    нить
    Стандартный HTTP-метод.
  - parentDocumentId
    строка необязательный
    UUID родительского документа, которому принадлежит этот фрейм. Этот параметр не устанавливается, если родительского документа нет.
  - parentFrameId
    число
    Идентификатор кадра, который содержит кадр, отправивший запрос. Установите значение -1, если родительский кадр отсутствует.
  - requestId
    нить
    Идентификатор запроса. Идентификаторы запросов уникальны в рамках одной браузерной сессии. В результате их можно использовать для связи различных событий одного и того же запроса.
  - этап
    Этап
    Этап сетевого запроса, на котором было инициировано событие.
  - tabId
    число
    Идентификатор вкладки, в которой выполняется запрос. Установите значение -1, если запрос не связан с вкладкой.
  - метка времени
    число
    Время срабатывания этого сигнала, в миллисекундах с начала эпохи.
  - тип
    webRequest.ResourceType
    Как будет использоваться запрошенный ресурс.
  - url
    нить