Веб Запрос
==========

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

Каждое событие запущено на определённой стадии запроса. Типичный порядок событий такой:
 ![](/ru/docs/Mozilla/Add-ons/WebExtensions/API/webRequest/webrequest-flow.png)

`onErrorOccurred` (en-US) Может быть запущен в любой момент во время запроса. Чреда событий может отличаться от приведённой выше: например, в Firefox, после HSTS обновления, событие `onBeforeRedirect` будет запущено сразу же после `onBeforeRequest`.

Все события, кроме `onErrorOccurred`, могут принимать три аргумента в `addListener()`:

* сам обработчик
* объект `filter` (en-US) , который позволяет получать оповещения о запросах, сделанных к определённым URL или определённым типам ресурсов.
* необязательный объект `extraInfoSpec` . Может быть использован для передачи дополнительных специфических для события инструкций.

Функции - обработчику передаётся объект `details` который содержит информацию о запросе. Она содержит ID запроса, который обеспечен для включения надстройки, которая позволяет соотносить события, ассоциируемые с одним запросом. Это уникально в пределах сессии и контекста надстройки. Информация остаётся одинаковой везде на протяжении запроса, даже при перенаправлениях и обменах аутентификации.

Для использования webRequest API для определённого хоста, расширение должно иметь "webRequest" API permission и host permission для этого хоста. Для использования возможности "блокирования" расширение должно также иметь "webRequestBlocking" API разрешение.

Для перехвата ресурсов, загруженных страницей (таких как картинки, скрипты или таблицы стилей), расширение должно иметь разрешение хоста для ресурса также как и для главной страницы, запрашивающей ресурс. К примеру, если страница на `https://developer.mozilla.org` загружает картинку из `https://mdn.mozillademos.org`, тогда расширение должно иметь разрешения обоих хостов чтобы перехватить запрос картинки.

Модифицирование заголовков
--------------------------

Используя некоторые из этих событий, вы можете модифицировать запрос. Конкретно, вы можете:

* отменить запрос в:
    + `onBeforeRequest` (en-US)
    + `onBeforeSendHeaders` (en-US)
    + `onAuthRequired` (en-US)
* перенаправить запрос в:
    + `onBeforeRequest` (en-US)
    + `onHeadersReceived` (en-US)
* модифицировать заголовки запроса в:
    + `onBeforeSendHeaders` (en-US)
* модифицировать заголовки ответа в:
    + `onHeadersReceived` (en-US)
* предоставить учётные данные аутентификации в:
    + `onAuthRequired` (en-US)

Чтобы сделать это, вам необходимо передать опцию со значением "blocking" в аргументе `extraInfoSpec` к `addListener()`. Это делает обработчик синхронным. В обработчике, вы можете тогда возвратить объект `BlockingResponse` (en-US) который индикует модификацию, какую вам нужно сделать: например, модифицированный заголовок запроса который вы хотите отправить.

Доступ к информации о безопасности
----------------------------------

В обработчике `onHeadersReceived` (en-US) вы имеете доступ к TLS свойствам запроса через вызов `getSecurityInfo()` (en-US). Чтобы сделать это, вы должны также передать "blocking" в `extraInfoSpec` аргументе к `addListener()` события.

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

Modifying responses
-------------------

Для того, чтобы модифицировать тело HTTP ответа на запрос, вызовите `webRequest.filterResponseData` (en-US), и передайте ID запроса. Это возвратит объект `webRequest.StreamFilter` (en-US) который вы сможете использовать чтобы исследовать и изменять данные когда они получены браузером.

Чтобы сделать это, у вас должно быть "webRequestBlocking" API разрешение, а также "webRequest" API permission и host permission от соответствующего хоста.

Types
-----

`webRequest.BlockingResponse` (en-US)

An object of this type is returned by event listeners that have set `"blocking"` in their `extraInfoSpec` argument. By setting particular properties in `BlockingResponse`, the listener can modify network requests.

`webRequest.CertificateInfo` (en-US)

An object describing a single X.509 certificate.

`webRequest.HttpHeaders` (en-US)

An array of HTTP headers. Each header is represented as an object with two properties: `name` and either `value` or `binaryValue`.

`webRequest.RequestFilter` (en-US)

An object describing filters to apply to webRequest events.

`webRequest.ResourceType` (en-US)

Represents a particular kind of resource fetched in a web request.

`webRequest.SecurityInfo` (en-US)

An object describing the security properties of a particular web request.

`webRequest.StreamFilter` (en-US)

An object that can be used to monitor and modify HTTP responses while they are being received.

`webRequest.UploadData` (en-US)

Contains data uploaded in a URL request.

Properties
----------

`webRequest.MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES` (en-US)

The maximum number of times that `handlerBehaviorChanged()` (en-US) can be called in a 10 minute period.

Functions
---------

`webRequest.handlerBehaviorChanged()` (en-US)

This function can be used to ensure that event listeners are applied correctly when pages are in the browser's in-memory cache.

`webRequest.filterResponseData()` (en-US)

Returns a `webRequest.StreamFilter` (en-US) object for a given request.

`webRequest.getSecurityInfo()` (en-US)

Gets detailed information about the TLS connection associated with a given request.

Events
------

`webRequest.onBeforeRequest` (en-US)

Fired when a request is about to be made, and before headers are available. This is a good place to listen if you want to cancel or redirect the request.

`webRequest.onBeforeSendHeaders` (en-US)

Fired before sending any HTTP data, but after HTTP headers are available. This is a good place to listen if you want to modify HTTP request headers.

`webRequest.onSendHeaders` (en-US)

Fired just before sending headers. If your add-on or some other add-on modified headers in ``onBeforeSendHeaders` (en-US)`, you'll see the modified version here.

`webRequest.onHeadersReceived` (en-US)

Fired when the HTTP response headers associated with a request have been received. You can use this event to modify HTTP response headers.

`webRequest.onAuthRequired` (en-US)

Fired when the server asks the client to provide authentication credentials. The listener can do nothing, cancel the request, or supply authentication credentials.

`webRequest.onResponseStarted` (en-US)

Fired when the first byte of the response body is received. For HTTP requests, this means that the status line and response headers are available.

`webRequest.onBeforeRedirect` (en-US)

Fired when a server-initiated redirect is about to occur.

`webRequest.onCompleted` (en-US)

Fired when a request is completed.

`webRequest.onErrorOccurred` (en-US)

Fired when an error occurs.

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Extra notes on Chrome incompatibilities.

Example extensions
------------------

* http-response
* root-cert-stats
* stored-credentials
* user-agent-rewriter

**Примечание:** Это API основано на API Chromium `chrome.webRequest`. Эта документация основана на `web_request.json` из кода Chromium.