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
|
---
title: webRequest
slug: Mozilla/Add-ons/WebExtensions/API/webRequest
tags:
- API
- Add-ons
- Extensions
- Interface
- NeedsTranslation
- Non-standard
- Reference
- TopicStub
- WebExtensions
- webRequest
translation_of: Mozilla/Add-ons/WebExtensions/API/webRequest
---
<div>{{AddonSidebar}}</div>
<div>为发出的HTTP请求在不同阶段添加事件监听器。事件监听器可以接收到请求的详细信息，也可以修改或取消请求。</div>
<h2 id="概况">概况</h2>
<p>每个事件都会在请求的特定阶段触发。事件的顺序大概是这样的：</p>
<p>在请求过程中的任意时间，{{WebExtAPIRef("webRequest.onErrorOccurred", "onErrorOccurred")}} 可以被触发。虽然有时候触发的事件顺序不同，举个例子，在火狐浏览器中的HSTS过程，在onBeforeRequest事件执行后，onBeforeRedirect 事件会被立即触发。</p>
<p>所有的事件，接受<code>onErrorOccurred事件</code>, <code>addListener()</code>有三个参数 :</p>
<ul>
<li>监听本身</li>
<li>一个{{WebExtAPIRef("webRequest.RequestFilter", "filter")}} 对象, 所以你仅可以被特定请求或特定的资源类型提醒</li>
<li>一个可选的<code>extraInfoSpec</code>对象. 你可以使用这个对象添加特定的事件命令</li>
</ul>
<p>这个监听函数接收一个<code>details</code>对象，这个对象包含这个请求的信息。他包含一个请求ID, 在插件中这个ID可以关联唯一个请求事件. 这个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>. 为了使用 "blocking" 特性，你必须有 "webRequestBlocking" API 权限。</p>
<p>这个webRequest API不能让你进入一些安全敏感的请求，比如<a href="https://bugzilla.mozilla.org/show_bug.cgi?id=1279371">update checks and OCSP checks</a>.</p>
<h3 id="Modifying_requests">Modifying requests</h3>
<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")}}</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>为了完成这些操作，你需要在<code>extraInfoSpec</code>参数中添加"blocking"的值到事件的<code>addListener()</code>。这将使得监听器变成同步执行。在监听器中，你可以返回一个表明需要作修改的{{WebExtAPIRef("webRequest.BlockingResponse", "BlockingResponse")}}对象：比如说，你想要发送的修改后的请求头。</p>
<p>从Firefox 52开始，监听器会返回一个<code>resolve(BlockingResponse)</code> 的 <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>，而不是直接返回一个<code>BlockingResponse</code>。这使得监听器可以异步地处理请求。</p>
<h2 id="Types">Types</h2>
<dl>
<dt>{{WebExtAPIRef("webRequest.ResourceType")}}</dt>
<dd>Represents a particular kind of resource fetched in a web request.</dd>
<dt>{{WebExtAPIRef("webRequest.RequestFilter")}}</dt>
<dd>An object describing filters to apply to webRequest events.</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.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.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>
</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>
<div class="hidden note">
<p>The "Chrome incompatibilities" section is included from <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities"> https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a> using the <a href="/en-US/docs/Template:WebExtChromeCompat">WebExtChromeCompat</a> macro.</p>
<p>If you need to update this content, edit <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities">https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a>, then shift-refresh this page to see your changes.</p>
</div>
<h3 id="Edge_incompatibilities">Edge incompatibilities</h3>
<p>Promises are not supported in Edge. Use callbacks instead.</p>
<p>{{Compat("webextensions.api.webRequest")}} {{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>
|
