1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
|
---
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 class="notranslate">// 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>
|
