Перевод не завершен. Пожалуйста, помогите перевести эту статью с английского.

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

Каждое событие запущено на определённой стадии запроса. Типичный порядок событий такой:

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

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

  • сам обработчик
  • обьект filter , который позволяет получать оповещения о запросах, сделанных к определённым URL или определённым типам ресурсов.
  • необязательный обьект extraInfoSpec . Может быть использован для передачи дополнительных срецифических для события инструкций.

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

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

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

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

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

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

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

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

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

Modifying responses

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

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

Types

webRequest.BlockingResponse

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
An object describing a single X.509 certificate.
webRequest.HttpHeaders
An array of HTTP headers. Each header is represented as an object with two properties: name and either value or binaryValue.
webRequest.RequestFilter
An object describing filters to apply to webRequest events.
webRequest.ResourceType
Represents a particular kind of resource fetched in a web request.
webRequest.SecurityInfo
An object describing the security properties of a particular web request.
webRequest.StreamFilter
An object that can be used to monitor and modify HTTP responses while they are being received.
webRequest.UploadData
Contains data uploaded in a URL request.

Properties

webRequest.MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES
The maximum number of times that handlerBehaviorChanged() can be called in a 10 minute period.

Functions

webRequest.handlerBehaviorChanged()
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()
Returns a webRequest.StreamFilter object for a given request.
webRequest.getSecurityInfo()
Gets detailed information about the TLS connection associated with a given request.

Events

webRequest.onBeforeRequest
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
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
Fired just before sending headers. If your add-on or some other add-on modified headers in onBeforeSendHeaders, you'll see the modified version here.
webRequest.onHeadersReceived
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
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
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
Fired when a server-initiated redirect is about to occur.
webRequest.onCompleted
Fired when a request is completed.
webRequest.onErrorOccurred
Fired when an error occurs.

Browser compatibility

Update compatibility data on GitHub
КомпьютерыМобильные
ChromeEdgeFirefoxOperaFirefox для Android
BlockingResponseChrome Полная поддержка ДаEdge Полная поддержка 14Firefox Полная поддержка 45Opera Полная поддержка ДаFirefox Android Полная поддержка 48
CertificateInfoChrome Нет поддержки НетEdge Нет поддержки НетFirefox Полная поддержка 62Opera Нет поддержки НетFirefox Android Полная поддержка 62
HttpHeadersChrome Полная поддержка ДаEdge Полная поддержка 14Firefox Полная поддержка 45Opera Полная поддержка ДаFirefox Android Полная поддержка 48
MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTESChrome Полная поддержка ДаEdge Полная поддержка 14Firefox Полная поддержка 45Opera Полная поддержка ДаFirefox Android Полная поддержка 48
RequestFilterChrome Полная поддержка ДаEdge Полная поддержка 14Firefox Полная поддержка 45Opera Полная поддержка ДаFirefox Android Полная поддержка 48
ResourceTypeChrome Полная поддержка 44Edge Нет поддержки НетFirefox Полная поддержка 45Opera Полная поддержка 31Firefox Android Полная поддержка 48
SecurityInfoChrome Нет поддержки НетEdge Нет поддержки НетFirefox Полная поддержка 62Opera Нет поддержки НетFirefox Android Полная поддержка 62
StreamFilterChrome Нет поддержки НетEdge Нет поддержки НетFirefox Полная поддержка 57Opera Нет поддержки НетFirefox Android Полная поддержка 57
UploadDataChrome Полная поддержка ДаEdge Полная поддержка 14Firefox Полная поддержка 45Opera Полная поддержка ДаFirefox Android Полная поддержка 48
filterResponseDataChrome Нет поддержки НетEdge Нет поддержки НетFirefox Полная поддержка 57Opera Нет поддержки НетFirefox Android Полная поддержка 57
getSecurityInfoChrome Нет поддержки НетEdge Нет поддержки НетFirefox Полная поддержка 62Opera Нет поддержки НетFirefox Android Полная поддержка 62
handlerBehaviorChangedChrome Полная поддержка ДаEdge Полная поддержка 14Firefox Полная поддержка 45Opera Полная поддержка ДаFirefox Android Полная поддержка 48
onAuthRequiredChrome Полная поддержка ДаEdge Полная поддержка 14Firefox Полная поддержка 54
Замечания
Полная поддержка 54
Замечания
Замечания To handle a request asynchronously, return a Promise from the listener.
Opera Полная поддержка ДаFirefox Android Полная поддержка 54
Замечания
Полная поддержка 54
Замечания
Замечания To handle a request asynchronously, return a Promise from the listener.
onBeforeRedirectChrome Полная поддержка ДаEdge Полная поддержка 14Firefox Полная поддержка 46Opera Полная поддержка ДаFirefox Android Полная поддержка 48
onBeforeRequestChrome Полная поддержка Да
Замечания
Полная поддержка Да
Замечания
Замечания Asynchronous event listeners are not supported.
Edge Полная поддержка 14
Замечания
Полная поддержка 14
Замечания
Замечания Asynchronous event listeners are not supported.
Firefox Полная поддержка 46
Замечания
Полная поддержка 46
Замечания
Замечания Asynchronous event listeners are supported from version 52.
Opera Полная поддержка Да
Замечания
Полная поддержка Да
Замечания
Замечания Asynchronous event listeners are not supported.
Firefox Android Полная поддержка 48
Замечания
Полная поддержка 48
Замечания
Замечания Asynchronous event listeners are supported from version 52.
onBeforeSendHeadersChrome Полная поддержка Да
Замечания
Полная поддержка Да
Замечания
Замечания Asynchronous event listeners are not supported.
Edge Полная поддержка 14
Замечания
Полная поддержка 14
Замечания
Замечания Asynchronous event listeners are not supported.
Firefox Полная поддержка 45
Замечания
Полная поддержка 45
Замечания
Замечания Asynchronous event listeners are supported from version 52.
Opera Полная поддержка Да
Замечания
Полная поддержка Да
Замечания
Замечания Asynchronous event listeners are not supported.
Firefox Android Полная поддержка 48
Замечания
Полная поддержка 48
Замечания
Замечания Asynchronous event listeners are supported from version 52.
onCompletedChrome Полная поддержка ДаEdge Полная поддержка 14Firefox Полная поддержка 45Opera Полная поддержка ДаFirefox Android Полная поддержка 48
onErrorOccurredChrome Полная поддержка ДаEdge Полная поддержка 14Firefox Полная поддержка 45Opera Полная поддержка ДаFirefox Android Полная поддержка 48
onHeadersReceivedChrome Полная поддержка Да
Замечания
Полная поддержка Да
Замечания
Замечания Asynchronous event listeners are not supported.
Edge Полная поддержка 14
Замечания
Полная поддержка 14
Замечания
Замечания Asynchronous event listeners are not supported.
Firefox Полная поддержка 45
Замечания
Полная поддержка 45
Замечания
Замечания Modification of the 'Content-Type' header is supported from version 51.
Замечания Asynchronous event listeners are supported from version 52.
Opera Полная поддержка Да
Замечания
Полная поддержка Да
Замечания
Замечания Asynchronous event listeners are not supported.
Firefox Android Полная поддержка 48
Замечания
Полная поддержка 48
Замечания
Замечания Modification of the 'Content-Type' header is supported from version 51.
Замечания Asynchronous event listeners are supported from version 52.
onResponseStartedChrome Полная поддержка ДаEdge Полная поддержка 14Firefox Полная поддержка 45Opera Полная поддержка ДаFirefox Android Полная поддержка 48
onSendHeadersChrome Полная поддержка ДаEdge Полная поддержка 14Firefox Полная поддержка 45Opera Полная поддержка ДаFirefox Android Полная поддержка 48

Легенда

Полная поддержка  
Полная поддержка
Нет поддержки  
Нет поддержки
Смотрите замечания реализации.
Смотрите замечания реализации.

Chrome incompatibilities

webRequest

  • In Firefox requests can be redirected only if their original URL uses the http: or https: scheme.
  • In Firefox, events are not fired for system requests (for example, extension upgrades or searchbar suggestions). From Firefox 57 onwards, Firefox makes an exception for extensions that need to intercept webRequest.onAuthRequired for proxy authorization. See the documentation for webRequest.onAuthRequired.
  • In Firefox, if an extension wants to redirect a public (e.g. HTTPS) URL to an extension page, the extension's manifest.json file must contain a web_accessible_resources key that lists the URL for the extension page. Note that any website may then link or redirect to that url, and extensions should treat any input (POST data, for examples) as if it came from an untrusted source, just as a normal web page should.
  • In Firefox, starting from Firefox 52, some of the browser.webRequest.* APIs allow returning Promises that resolves webRequest.BlockingResponse asynchronously. In Chrome, only webRequest.onAuthRequired supports asynchronous webRequest.BlockingResponse via supplying 'asyncBlocking'.

Example extensions

Acknowledgements

This API is based on Chromium's chrome.webRequest API. This documentation is derived from web_request.json in the Chromium code.

Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.

Метки документа и участники

Внесли вклад в эту страницу: corecode1
Обновлялась последний раз: corecode1,