---
title: Веб Запрос
slug: Mozilla/Add-ons/WebExtensions/API/webRequest
translation_of: Mozilla/Add-ons/WebExtensions/API/webRequest
---
<div>{{AddonSidebar}}</div>

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

<p>Каждое событие запущено на определённой стадии запроса. Типичный порядок событий такой:<img alt="" src="https://mdn.mozillademos.org/files/13376/webRequest-flow.png" style="display: block; height: 680px; margin-left: auto; margin-right: auto; width: 624px;"></p>

<p>{{WebExtAPIRef("webRequest.onErrorOccurred", "onErrorOccurred")}} Может быть запущен в любой момент во время запроса. Чреда событий может отличаться от приведённой выше: например, в Firefox, после <a href="/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security">HSTS</a> обновления, событие <code>onBeforeRedirect</code> будет запущено сразу же после <code>onBeforeRequest</code>.</p>

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

<ul>
 <li>сам обработчик</li>
 <li>объект {{WebExtAPIRef("webRequest.RequestFilter", "filter")}} , который позволяет получать оповещения о запросах, сделанных к определённым URL или определённым типам ресурсов.</li>
 <li>необязательный объект <code>extraInfoSpec</code> . Может быть использован для передачи дополнительных специфических для события инструкций.</li>
</ul>

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

<p>Для использования webRequest API для определённого хоста, расширение должно иметь "webRequest" <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#API_permissions">API permission</a> и <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#Host_permissions">host permission </a>для этого хоста. Для использования возможности "блокирования" расширение должно также иметь "webRequestBlocking" API разрешение.</p>

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

<h2 id="Модифицирование_заголовков">Модифицирование заголовков</h2>

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

<ul>
 <li>отменить запрос в:
  <ul>
   <li>{{WebExtAPIRef("webRequest.onBeforeRequest", "onBeforeRequest")}}</li>
   <li>{{WebExtAPIRef("webRequest.onBeforeSendHeaders", "onBeforeSendHeaders")}}</li>
   <li>{{WebExtAPIRef("webRequest.onAuthRequired", "onAuthRequired")}}</li>
  </ul>
 </li>
 <li>перенаправить  запрос в:
  <ul>
   <li>{{WebExtAPIRef("webRequest.onBeforeRequest", "onBeforeRequest")}}</li>
   <li>{{WebExtAPIRef("webRequest.onHeadersReceived", "onHeadersReceived")}}</li>
  </ul>
 </li>
 <li>модифицировать заголовки запроса в:
  <ul>
   <li>{{WebExtAPIRef("webRequest.onBeforeSendHeaders", "onBeforeSendHeaders")}}
    <ul>
    </ul>
   </li>
  </ul>
 </li>
 <li>модифицировать заголовки ответа в:
  <ul>
   <li>{{WebExtAPIRef("webRequest.onHeadersReceived", "onHeadersReceived")}}</li>
  </ul>
 </li>
 <li>предоставить учётные данные аутентификации в:
  <ul>
   <li>{{WebExtAPIRef("webRequest.onAuthRequired", "onAuthRequired")}}</li>
  </ul>
 </li>
</ul>

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

<h2 id="Доступ_к_информации_о_безопасности">Доступ к информации о безопасности</h2>

<p>В обработчике {{WebExtAPIRef("webRequest.onHeadersReceived", "onHeadersReceived")}} вы имеете доступ к <a href="/en-US/docs/Glossary/TLS">TLS</a> свойствам запроса через вызов {{WebExtAPIRef("webRequest.getSecurityInfo()", "getSecurityInfo()")}}. Чтобы сделать это, вы должны также передать "blocking" в  <code>extraInfoSpec</code> аргументе к  <code>addListener()</code> события.</p>

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

<h2 id="Modifying_responses">Modifying responses</h2>

<p>Для того, чтобы модифицировать тело HTTP ответа на запрос, вызовите {{WebExtAPIRef("webRequest.filterResponseData")}}, и передайте ID запроса. Это возвратит объект {{WebExtAPIRef("webRequest.StreamFilter")}} который вы сможете использовать чтобы исследовать и изменять данные когда они получены браузером.</p>

<p>Чтобы сделать это, у вас должно быть "webRequestBlocking" API разрешение, а также "webRequest" <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#API_permissions">API permission</a> и <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#Host_permissions">host permission </a>от соответствующего хоста.</p>

<h2 id="Types">Types</h2>

<dl>
 <dt>{{WebExtAPIRef("webRequest.BlockingResponse")}}</dt>
 <dd>
 <p>An object of this type is returned by event listeners that have set <code>"blocking"</code> in their <code>extraInfoSpec</code> argument. By setting particular properties in <code>BlockingResponse</code>, the listener can modify network requests.</p>
 </dd>
 <dt>{{WebExtAPIRef("webRequest.CertificateInfo")}}</dt>
 <dd>An object describing a single X.509 certificate.</dd>
 <dt>{{WebExtAPIRef("webRequest.HttpHeaders")}}</dt>
 <dd>An array of HTTP headers. Each header is represented as an object with two properties: <code>name</code> and either <code>value</code> or <code>binaryValue</code>.</dd>
 <dt>{{WebExtAPIRef("webRequest.RequestFilter")}}</dt>
 <dd>An object describing filters to apply to webRequest events.</dd>
 <dt>{{WebExtAPIRef("webRequest.ResourceType")}}</dt>
 <dd>Represents a particular kind of resource fetched in a web request.</dd>
 <dt>{{WebExtAPIRef("webRequest.SecurityInfo")}}</dt>
 <dd>An object describing the security properties of a particular web request.</dd>
 <dt>{{WebExtAPIRef("webRequest.StreamFilter")}}</dt>
 <dd>An object that can be used to monitor and modify HTTP responses while they are being received.</dd>
 <dt>{{WebExtAPIRef("webRequest.UploadData")}}</dt>
 <dd>Contains data uploaded in a URL request.</dd>
</dl>

<h2 id="Properties">Properties</h2>

<dl>
 <dt>{{WebExtAPIRef("webRequest.MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES")}}</dt>
 <dd>The maximum number of times that <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/WebRequest/handlerBehaviorChanged" title="Suppose an add-on's job is to block web requests against a pattern, and the following scenario happens:"><code>handlerBehaviorChanged()</code></a></code> can be called in a 10 minute period.</dd>
</dl>

<h2 id="Functions">Functions</h2>

<dl>
 <dt>{{WebExtAPIRef("webRequest.handlerBehaviorChanged()")}}</dt>
 <dd>This function can be used to ensure that event listeners are applied correctly when pages are in the browser's in-memory cache.</dd>
 <dt>{{WebExtAPIRef("webRequest.filterResponseData()")}}</dt>
 <dd>Returns a {{WebExtAPIRef("webRequest.StreamFilter")}} object for a given request.</dd>
 <dt>{{WebExtAPIRef("webRequest.getSecurityInfo()")}}</dt>
 <dd>Gets detailed information about the <a href="/en-US/docs/Glossary/TLS">TLS</a> connection associated with a given request.</dd>
</dl>

<h2 id="Events">Events</h2>

<dl>
 <dt>{{WebExtAPIRef("webRequest.onBeforeRequest")}}</dt>
 <dd>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.</dd>
 <dt>{{WebExtAPIRef("webRequest.onBeforeSendHeaders")}}</dt>
 <dd>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.</dd>
 <dt>{{WebExtAPIRef("webRequest.onSendHeaders")}}</dt>
 <dd>Fired just before sending headers. If your add-on or some other add-on modified headers in <code>{{WebExtAPIRef("webRequest.onBeforeSendHeaders", "onBeforeSendHeaders")}}</code>, you'll see the modified version here.</dd>
 <dt>{{WebExtAPIRef("webRequest.onHeadersReceived")}}</dt>
 <dd>Fired when the HTTP response headers associated with a request have been received. You can use this event to modify HTTP response headers.</dd>
 <dt>{{WebExtAPIRef("webRequest.onAuthRequired")}}</dt>
 <dd>Fired when the server asks the client to provide authentication credentials. The listener can do nothing, cancel the request, or supply authentication credentials.</dd>
 <dt>{{WebExtAPIRef("webRequest.onResponseStarted")}}</dt>
 <dd>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.</dd>
 <dt>{{WebExtAPIRef("webRequest.onBeforeRedirect")}}</dt>
 <dd>Fired when a server-initiated redirect is about to occur.</dd>
 <dt>{{WebExtAPIRef("webRequest.onCompleted")}}</dt>
 <dd>Fired when a request is completed.</dd>
 <dt>{{WebExtAPIRef("webRequest.onErrorOccurred")}}</dt>
 <dd>Fired when an error occurs.</dd>
</dl>

<h2 id="Browser_compatibility">Browser compatibility</h2>

<p>{{Compat("webextensions.api.webRequest")}}</p>

<p><a href="/docs/Mozilla/Add-ons/WebExtensions/Chrome_incompatibilities#webRequest_incompatibilities">Extra notes on Chrome incompatibilities</a>.</p>

<p>{{WebExtExamples("h2")}}</p>

<div class="note"><strong>Acknowledgements</strong>

<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/webRequest"><code>chrome.webRequest</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/web_request.json"><code>web_request.json</code></a> in the Chromium code.</p>

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

<div class="hidden">
<pre>// Copyright 2015 The Chromium Authors. All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
//    * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
//    * Redistributions in binary form must reproduce the above
// copyright notice, this list of conditions and the following disclaimer
// in the documentation and/or other materials provided with the
// distribution.
//    * Neither the name of Google Inc. nor the names of its
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
</pre>
</div>