说明
注意:此 API 已废弃。请改为查看 declarativeNetRequest
API。使用 chrome.declarativeWebRequest
API 拦截、屏蔽或修改运行中的请求。其速度明显快于 chrome.webRequest
API,因为您可以注册在浏览器中(而非 JavaScript 引擎)中评估的规则,从而减少往返延迟时间并提高效率。
权限
declarativeWebRequest
您必须在扩展程序清单中声明“declarativeWebRequest”权限以及主机权限,才能使用此 API。
{
"name": "My extension",
...
"permissions": [
"declarativeWebRequest",
"*://*/*"
],
...
}
可用性
清单
请注意,某些类型的非敏感操作不需要主机权限:
CancelRequest
IgnoreRules
RedirectToEmptyDocument
RedirectToTransparentImage
对于您要在其上触发消息的网络请求,SendMessageToExtension()
操作需要任何主机的主机权限。
所有其他操作都需要所有网址的主机权限。
例如,如果 "https://*.google.com/*"
是扩展程序的唯一主机权限,则此类扩展程序可能会设置如下规则:
- 取消对
https://www.google.com
或https://anything.else.com
的请求。 - 在导航到
https://www.google.com
时发送消息,但不在https://something.else.com
时发送消息。
此扩展程序无法设置将 https://www.google.com
重定向至 https://mail.google.com
的规则。
规则
声明式 Web Request API 遵循声明式 API 的概念。您可以将规则注册到 chrome.declarativeWebRequest.onRequest
事件对象。
声明式 Web 请求 API 支持一种匹配类型,即 RequestMatcher
。当且仅当满足列出的所有条件时,RequestMatcher
才会匹配网络请求。当用户在 Ominibox 中输入 https://www.example.com
时,以下 RequestMatcher
将与网络请求匹配:
var matcher = new chrome.declarativeWebRequest.RequestMatcher({
url: { hostSuffix: 'example.com', schemes: ['http'] },
resourceType: ['main_frame']
});
根据架构,RequestMatcher
会拒绝对 https://www.example.com
的请求。此外,针对嵌入式 iframe 的所有请求都会因 resourceType
而被拒绝。
要取消对“example.com”的所有请求,您可以按如下方式定义规则:
var rule = {
conditions: [
new chrome.declarativeWebRequest.RequestMatcher({
url: { hostSuffix: 'example.com' } })
],
actions: [
new chrome.declarativeWebRequest.CancelRequest()
]
};
如需取消对 example.com
和 foobar.com
的所有请求,您可以添加第二个条件,因为每个条件都足以触发所有指定的操作:
var rule2 = {
conditions: [
new chrome.declarativeWebRequest.RequestMatcher({
url: { hostSuffix: 'example.com' } }),
new chrome.declarativeWebRequest.RequestMatcher({
url: { hostSuffix: 'foobar.com' } })
],
actions: [
new chrome.declarativeWebRequest.CancelRequest()
]
};
按如下方式注册规则:
chrome.declarativeWebRequest.onRequest.addRules([rule2]);
条件和操作评估
声明式 Web 请求 API 遵循 Web 请求 API 的网络请求的生命周期模型。这意味着只能在 Web 请求的特定阶段测试条件,同样,操作也只能在特定阶段执行。下表列出了与条件和操作兼容的请求阶段。
可以处理条件属性的请求阶段。 | ||||
---|---|---|---|---|
使用情况属性 | onBeforeRequest | onBeforeSendHeaders | onHeadersReceived | onAuthRequired |
url |
✓ | ✓ | ✓ | ✓ |
resourceType |
✓ | ✓ | ✓ | ✓ |
contentType |
✓ | |||
excludeContentType |
✓ | |||
responseHeaders |
✓ | |||
excludeResponseHeaders |
✓ | |||
requestHeaders |
✓ | |||
excludeRequestHeaders |
✓ | |||
thirdPartyForCookies |
✓ | ✓ | ✓ | ✓ |
可以执行操作的请求阶段。 | ||||
事件 | onBeforeRequest | onBeforeSendHeaders | onHeadersReceived | onAuthRequired |
AddRequestCookie |
✓ | |||
AddResponseCookie |
✓ | |||
AddResponseHeader |
✓ | |||
CancelRequest |
✓ | ✓ | ✓ | ✓ |
EditRequestCookie |
✓ | |||
EditResponseCookie |
✓ | |||
IgnoreRules |
✓ | ✓ | ✓ | ✓ |
RedirectByRegEx |
✓ | ✓ | ||
RedirectRequest |
✓ | ✓ | ||
RedirectToEmptyDocument |
✓ | ✓ | ||
RedirectToTransparentImage |
✓ | ✓ | ||
RemoveRequestCookie |
✓ | |||
RemoveRequestHeader |
✓ | |||
RemoveResponseCookie |
✓ | |||
RemoveResponseHeader |
✓ | |||
SendMessageToExtension |
✓ | ✓ | ✓ | ✓ |
SetRequestHeader |
✓ |
使用优先级来覆盖规则
规则可以与优先级相关联,如 Events API 中所述。此机制可用于表达异常。以下示例将屏蔽对名为 evil.jpg
的映像的所有请求(服务器“myserver.com”除外)。
var rule1 = {
priority: 100,
conditions: [
new chrome.declarativeWebRequest.RequestMatcher({
url: { pathEquals: 'evil.jpg' } })
],
actions: [
new chrome.declarativeWebRequest.CancelRequest()
]
};
var rule2 = {
priority: 1000,
conditions: [
new chrome.declarativeWebRequest.RequestMatcher({
url: { hostSuffix: '.myserver.com' } })
],
actions: [
new chrome.declarativeWebRequest.IgnoreRules({
lowerPriorityThan: 1000 })
]
};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
请务必注意,IgnoreRules
操作不会跨请求阶段持久保存。系统会在网络请求的每个阶段评估所有规则的所有条件。如果执行了 IgnoreRules
操作,该操作仅会应用于同一阶段针对同一 Web 请求执行的其他操作。
类型
AddRequestCookie
在请求中添加 Cookie 或覆盖 Cookie(在已存在其他同名 Cookie 的情况下)。请注意,最好使用 Cookies API,因为其计算成本较低。
属性
-
构造函数
void
constructor
函数如下所示:(arg: AddRequestCookie) => {...}
-
要添加到请求的 Cookie。没有可以未定义的字段。
AddResponseCookie
在响应中添加一个 Cookie 或覆盖某个 Cookie(如果已存在其他同名 Cookie)。请注意,最好使用 Cookies API,因为其计算成本较低。
属性
-
构造函数
void
constructor
函数如下所示:(arg: AddResponseCookie) => {...}
-
要添加到响应的 Cookie。需要指定名称和值。
AddResponseHeader
将响应标头添加到此网络请求的响应中。由于多个响应标头可能共用相同的名称,您需要先移除标头,然后再添加新的响应标头,以便替换标头。
属性
-
构造函数
void
constructor
函数如下所示:(arg: AddResponseHeader) => {...}
-
name
string
HTTP 响应标头名称。
-
值
string
HTTP 响应标头值。
CancelRequest
用于取消网络请求的声明性事件操作。
属性
-
构造函数
void
constructor
函数如下所示:(arg: CancelRequest) => {...}
EditRequestCookie
修改请求的一个或多个 Cookie。请注意,最好使用 Cookies API,因为其计算成本较低。
属性
-
构造函数
void
constructor
函数如下所示:(arg: EditRequestCookie) => {...}
-
filter
过滤出将要修改的 Cookie。系统会忽略所有空条目。
-
在管理过滤器的 Cookie 中,应被覆盖的属性。设置为空字符串的属性会被移除。
EditResponseCookie
修改一个或多个响应 Cookie。请注意,最好使用 Cookies API,因为其计算成本较低。
属性
-
构造函数
void
constructor
函数如下所示:(arg: EditResponseCookie) => {...}
-
filter
过滤出将要修改的 Cookie。系统会忽略所有空条目。
-
在管理过滤器的 Cookie 中,应被覆盖的属性。设置为空字符串的属性会被移除。
FilterResponseCookie
HTTP 响应中的 Cookie 过滤器。
属性
-
ageLowerBound
数字可选
Cookie 生命周期的包含下限(指定在当前时间之后的秒数)。只有失效日期设置为“现在 + ageLowerBound”或更晚的 Cookie 才满足此条件。会话 Cookie 不符合此过滤器的条件。Cookie 生命周期通过“max-age”或“expires”Cookie 属性计算得出。如果两个都指定,则使用“max-age”来计算 Cookie 生命周期。
-
ageUpperBound
数字可选
Cookie 生命周期的包含上限(以当前时间过后的秒数指定)。只有失效日期在 [现在,现在 + ageUpperBound] 间隔范围内的 Cookie 才满足此条件。会话 Cookie 和失效日期为过去时间的 Cookie 不符合此过滤条件的条件。Cookie 生命周期通过“max-age”或“expires”Cookie 属性计算得出。如果两个都指定,则使用“max-age”来计算 Cookie 生命周期。
-
网域
字符串(可选)
网域 Cookie 属性的值。
-
到期时间
字符串(可选)
到期 Cookie 属性的值。
-
httpOnly
字符串(可选)
HttpOnly Cookie 属性是否存在。
-
maxAge
数字可选
“Max-Age”Cookie 属性的值
-
name
字符串(可选)
Cookie 的名称。
-
path
字符串(可选)
路径 Cookie 属性的值。
-
安全
字符串(可选)
安全 Cookie 属性是否存在。
-
sessionCookie
布尔值 选填
过滤会话 Cookie。会话 Cookie 的任何“max-age”或“expires”属性中都未指定有效期。
-
值
字符串(可选)
Cookie 的值,可以用双引号括起来。
HeaderFilter
针对各种条件过滤请求标头。系统会同时对多个条件进行评估。
属性
-
nameContains
string | string[] 可选
如果标头名称包含所有指定字符串,则匹配。
-
nameEquals
字符串(可选)
如果标头名称等于指定字符串,则匹配。
-
namePrefix
字符串(可选)
如果标头名称以指定字符串开头,则匹配。
-
nameSuffix
字符串(可选)
如果标头名称以指定字符串结尾,则匹配。
-
valueContains
string | string[] 可选
如果标头值包含所有指定字符串,则匹配。
-
valueEquals
字符串(可选)
如果标头值等于指定字符串,则匹配。
-
valuePrefix
字符串(可选)
如果标头值以指定字符串开头,则匹配。
-
valueSuffix
字符串(可选)
如果标头值以指定字符串结尾,则匹配。
IgnoreRules
遮盖符合指定条件的所有规则。
属性
-
构造函数
void
constructor
函数如下所示:(arg: IgnoreRules) => {...}
-
参数
-
-
hasTag
字符串(可选)
如果设置了此字段,则具有指定标记的规则会被忽略。忽略的操作不会持续存在,只会影响同一网络请求阶段的规则及其操作。请注意,规则按其优先级的降序执行。此操作会影响优先级低于当前规则的规则。系统可能不会忽略具有相同优先级的规则。
-
lowerPriorityThan
数字可选
如果设置了此字段,系统会忽略优先级低于指定值的规则。此边界不会持久保留,而只会影响同一网络请求阶段的规则及其操作。
RedirectByRegEx
通过对网址应用正则表达式来重定向请求。正则表达式使用 RE2 语法。
属性
-
构造函数
void
constructor
函数如下所示:(arg: RedirectByRegEx) => {...}
-
来自
string
可能包含捕获组的匹配模式。为了更接近 JavaScript 正则表达式,引用捕获组时使用的是 Perl 语法($1、$2...),而非 RE2 语法(\1、\2...)。
-
至
string
目标模式。
RedirectRequest
用于重定向网络请求的声明性事件操作。
属性
-
构造函数
void
constructor
函数如下所示:(arg: RedirectRequest) => {...}
-
redirectUrl
string
请求重定向到的目标位置。
RedirectToEmptyDocument
将网络请求重定向到空文档的声明性事件操作。
属性
-
构造函数
void
constructor
函数如下所示:(arg: RedirectToEmptyDocument) => {...}
RedirectToTransparentImage
将网络请求重定向到透明图片的声明性事件操作。
属性
-
构造函数
void
constructor
函数如下所示:(arg: RedirectToTransparentImage) => {...}
RemoveRequestCookie
移除一个或多个请求的 Cookie。请注意,最好使用 Cookies API,因为其计算成本较低。
属性
-
构造函数
void
constructor
函数如下所示:(arg: RemoveRequestCookie) => {...}
-
filter
过滤出将被移除的 Cookie。系统会忽略所有空条目。
RemoveRequestHeader
移除指定名称的请求标头。请勿在同一请求中使用具有相同标头名称的 SetRequestHeader 和 RemoveRequestHeader。每个请求标头名称在每个请求中仅出现一次。
属性
-
构造函数
void
constructor
函数如下所示:(arg: RemoveRequestHeader) => {...}
-
name
string
HTTP 请求标头名称(不区分大小写)。
RemoveResponseCookie
删除一个或多个响应 Cookie。请注意,最好使用 Cookies API,因为其计算成本较低。
属性
-
构造函数
void
constructor
函数如下所示:(arg: RemoveResponseCookie) => {...}
-
filter
过滤出将被移除的 Cookie。系统会忽略所有空条目。
RemoveResponseHeader
移除指定名称和值的所有响应标头。
属性
-
构造函数
void
constructor
函数如下所示:(arg: RemoveResponseHeader) => {...}
-
name
string
HTTP 请求标头名称(不区分大小写)。
-
值
字符串(可选)
HTTP 请求标头值(不区分大小写)。
RequestCookie
HTTP 请求中 Cookie 的过滤器或规范。
属性
-
name
字符串(可选)
Cookie 的名称。
-
值
字符串(可选)
Cookie 的值,可以用双引号括起来。
RequestMatcher
根据各种条件匹配网络事件。
属性
-
构造函数
void
constructor
函数如下所示:(arg: RequestMatcher) => {...}
-
contentType
string[] 可选
如果列表中包含响应的 MIME 媒体类型(来自 HTTP Content-Type 标头),则匹配。
-
excludeContentType
string[] 可选
如果列表中不包含响应的 MIME 媒体类型(来自 HTTP Content-Type 标头),则匹配。
-
excludeRequestHeaders
HeaderFilter[] 可选
如果没有任何 HeaderFilters 与请求标头匹配,则匹配。
-
excludeResponseHeaders
HeaderFilter[] 可选
如果任何响应标头与任何 HeaderFilters 都不匹配,则匹配。
-
firstPartyForCookiesUrl
UrlFilter 可选
已废弃从版本 82 开始忽略。
如果针对请求的“第一方”网址满足 UrlFilter 的条件,则匹配。请求的“第一方”网址(如果存在)可以与请求的目标网址不同,用于描述为了进行第三方 Cookie 检查而被视为“第一方”的网址。
-
requestHeaders
HeaderFilter[] 可选
如果某些请求标头与其中一个 HeaderFilters 匹配,则匹配。
-
resourceType
ResourceType[] 可选
如果列表中包含请求的请求类型,则匹配。与任何类型都不匹配的请求将被滤除。
-
responseHeaders
HeaderFilter[] 可选
如果某些响应标头与其中一个 HeaderFilters 匹配,则匹配。
-
阶段
阶段[] 选填
包含描述阶段的字符串列表。允许的值为“onBeforeRequest”“onBeforeSendHeaders”“onHeadersReceived”“onAuthRequired”。如果该属性存在,则适用阶段仅限于列出的阶段。请注意,整个条件仅适用于与所有属性都兼容的阶段。
-
thirdPartyForCookies
布尔值 选填
已废弃从版本 87 开始被忽略。
如果此政策设为 true,系统会匹配受第三方 Cookie 政策约束的请求。如果设置为 false,则匹配所有其他请求。
-
网址
UrlFilter 可选
如果针对请求的网址满足 UrlFilter 的条件,则匹配。
ResponseCookie
HTTP 响应中的 Cookie 规范。
属性
-
网域
字符串(可选)
网域 Cookie 属性的值。
-
到期时间
字符串(可选)
到期 Cookie 属性的值。
-
httpOnly
字符串(可选)
HttpOnly Cookie 属性是否存在。
-
maxAge
数字可选
“Max-Age”Cookie 属性的值
-
name
字符串(可选)
Cookie 的名称。
-
path
字符串(可选)
路径 Cookie 属性的值。
-
安全
字符串(可选)
安全 Cookie 属性是否存在。
-
值
字符串(可选)
Cookie 的值,可以用双引号括起来。
SendMessageToExtension
属性
-
构造函数
void
constructor
函数如下所示:(arg: SendMessageToExtension) => {...}
-
消息
string
将在传递给事件处理脚本的字典的
message
属性中传递的值。
SetRequestHeader
将指定名称的请求标头设置为指定值。如果之前不存在具有指定名称的标头,系统会创建一个新标头。标头名称比较始终不区分大小写。每个请求标头名称在每个请求中仅出现一次。
属性
-
构造函数
void
constructor
函数如下所示:(arg: SetRequestHeader) => {...}
-
name
string
HTTP 请求标头名称。
-
值
string
HTTP 请求标头值。
Stage
枚举
"onBeforeRequest"
"onBeforeSendHeaders"
"onHeadersReceived"
"onAuthRequired"
活动
onMessage
chrome.declarativeWebRequest.onMessage.addListener(
callback: function,
)
在声明式 Web 请求 API 的某个操作通过 declarativeWebRequest.SendMessageToExtension
发送消息时触发。
参数
-
callback
功能
callback
参数如下所示:(details: object) => void
-
详细信息
对象
-
documentId
字符串(可选)
发出请求的文档的 UUID。
-
documentLifecycle
文档所在的生命周期。
-
frameId
number
值 0 表示请求发生在主帧中;正值表示请求发生时所在的子帧的 ID。如果(子)帧的文档已加载(
type
为main_frame
或sub_frame
),则frameId
表示此帧的 ID,而不是外框架的 ID。帧 ID 在标签页中是唯一的。 -
frameType
发生导航的帧类型。
-
消息
string
调用脚本发送的消息。
-
method
string
标准 HTTP 方法。
-
parentDocumentId
字符串(可选)
拥有此帧的父文档的 UUID。如果没有父级,则不设置此项。
-
parentFrameId
number
用于封装发送请求的帧的帧的 ID。如果不存在父框架,则设置为 -1。
-
requestId
string
请求的 ID。在浏览器会话中,请求 ID 是唯一的。因此,可用于关联同一请求的不同事件。
-
流程中的
触发事件的网络请求的阶段。
-
tabId
number
发出请求的标签页的 ID。如果请求与标签页无关,则设为 -1。
-
timeStamp
number
此信号触发的时间(以毫秒为单位,从 Epoch 起算)。
-
将如何使用请求的资源。
-
网址
string
-
-
onRequest
提供由 addRules
、removeRules
和 getRules
组成的声明式事件 API。
Action