chrome.declarativeWebRequest

chrome.declarativeWebRequest

1. 清单文件
2. 规则
3. 条件与操作的求值
4. 使用优先级覆盖规则
5. 类型
   1. HeaderFilter
   2. RequestMatcher
   3. CancelRequest
   4. RedirectRequest
   5. RedirectToTransparentImage
   6. RedirectToEmptyDocument
   7. RedirectByRegEx
   8. SetRequestHeader
   9. RemoveRequestHeader
   10. AddResponseHeader
   11. RemoveResponseHeader
   12. IgnoreRules
   13. SendMessageToExtension
   14. RequestCookie
   15. ResponseCookie
   16. FilterResponseCookie
   17. AddRequestCookie
   18. AddResponseCookie
   19. EditRequestCookie
   20. EditResponseCookie
   21. RemoveRequestCookie
   22. RemoveResponseCookie
6. 事件
   1. onRequest
   2. onMessage

描述：	使用 chrome.declarativeWebRequest API 实时地拦截、阻止或者修改请求，它比 chrome.webRequest API 要快得多，因为您注册的规则在浏览器而不是 JavaScript 引擎中求值，这样就减少了来回延迟并且可以获得极高的效率。
可用版本：	仅用于 Beta 和 dev 分支。
权限：	"declarativeWebRequest"  主机权限

清单文件

您必须在扩展程序的清单文件中声明 "declarativeWebRequest" 权限和主机权限才能使用这一 API。

manifest.json

{
  "name": "我的扩展程序",
  ...
  "permissions": [
    "declarativeWebRequest",
    "*://*/*"
  ],
  ...
}

注意，某些类型的不敏感操作不需要主机权限：

• CancelRequest
• IgnoreRules
• RedirectToEmptyDocument
• RedirectToTransparentImage

对于您希望触发消息的网络请求，SendMessageToExtension 操作要求对应主机的主机权限。

所有其他操作要求访问所有 URL 的主机权限。

例如，如果扩展程序唯一拥有的主机权限是 "*://*.google.com/*"，这样的扩展程序可以设置如下规则：

• 取消发送自“http://www.google.com”或“http://anything.else.com”的请求
• 导航至“http://www.google.com”时发送消息，但是导航至“http://something.else.com”时不能发送消息。

扩展程序不能设置规则，将“http://www.google.com”重定向至“http://mail.google.com”。

规则

声明式网络请求 API 遵循声明式 API 的概念，您可以向 chrome.declarativeWebRequest.onRequest 事件对象注册规则。

声明式网络请求API支持一种匹配条件的类型，即 RequestMatcher，当且仅当列出的所有条件都满足时 RequestMatcher 才会匹配网络请求。当用户在 URL 栏中输入“http://www.example.com”时如下的 RequestMatcher 将匹配这一网络请求：

var matcher = new chrome.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com', schemes: ['http'] },
  resourceType: ['main_frame']
  });

向“https://www.example.com”发出的请求因为协议的原因不会被 RequestMatcher 匹配，并且由于 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]);

注意：您始终应该一次性批量注册或取消注册规则，而不是单独进行，因为每一次这样的操作都需要重新创建内部的数据结构，这一重新创建的过程需要大量的计算，但是可以利用一种极快的 URL 匹配算法，用于几十万个 URL。事件 API 的性能部分提供了进一步的性能提示。

条件与操作的求值

声明式网络请求 API 遵循网络请求 API 的生命周期模型，这意味着条件只能在网络请求的特定阶段测试，同样地，操作也只能在特定阶段执行。下表列出了与条件和操作兼容的请求阶段。

能够处理条件属性的请求阶段：
条件属性	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		✓

注意：适用的阶段可以使用 "stages" 属性进一步地约束。

例子：可以将 new chrome.declarativeWebRequest.RequestMatcher({contentType: ["image/jpeg"])) 条件与 new chrome.declarativeWebRequest.CancelRequest() 操作组合，因为它们都可以在 onHeadersReceived 阶段求值，然而不能将该请求匹配器与 new chrome.declarativeWebRequest.RedirectToTransparentImage() 组合，因为内容类型确定后就不能再进行重定向了。

使用优先级覆盖规则

规则中可以包含优先级，如事件 API 中所述，这种机制可以用来表达例外。如下例子将阻止除了来自服务器 "myserver.com" 以外所有名称为 "evil.jpg" 的图片请求，。

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 操作，它仅应用于同一网络请求在同一阶段执行的其他操作。

chrome.declarativeWebRequest 参考

类型

HeaderFilter

通过各种条件过滤请求头信息，多个条件将同时求值。

HeaderFilter 的属性

namePrefix ( optional string )

如果头信息的名称以指定字符串开头则匹配。

nameSuffix ( optional string )

如果头信息的名称以指定字符串结尾则匹配。

nameContains ( optional array of string or string )

如果头信息的名称包含所有指定的字符串则匹配。

nameEquals ( optional string )

如果头信息的名称与指定字符串相同则匹配。

valuePrefix ( optional string )

如果头信息的值以指定字符串开头则匹配。

valueSuffix ( optional string )

如果头信息的值以指定字符串结尾则匹配。

valueContains ( optional array of string or string )

如果头信息的值包含所有指定的字符串则匹配。

valueEquals ( optional string )

如果头信息的值与指定字符串相同则匹配。

RequestMatcher

通过各种条件匹配网络事件。

RequestMatcher 的属性

url ( optional events.UrlFilter )

如果请求所对应的 URL 满足 UrlFilter 的条件则匹配。

firstPartyForCookiesUrl ( optional events.UrlFilter )

如果请求的“第一方”URL 满足 UrlFilter 的条件则匹配，请求的“第一方”URL（如果存在的话）可能与请求的目标 URL 不同，描述的是相对于第三方 Cookie 检查的“第一方”。

resourceType ( optional array of enum of "main_frame", "sub_frame", "stylesheet", "script", "image", "object", "xmlhttprequest", or "other" )

如果请求的类型包含在列表中则匹配，不匹配指定的任何类型的请求将被过滤出去。

contentType ( optional array of string )

如果响应的 MIME 媒体类型（来自 HTTP Content-Type 头信息）包含在列表中则匹配。

excludeContentType ( optional array of string )

如果响应的 MIME 媒体类型（来自 HTTP Content-Type 头信息）没有包含在列表中则匹配。

requestHeaders ( optional array of HeaderFilter )

如果某些请求头信息匹配 HeaderFilter 中的某一个则匹配该请求。

excludeRequestHeaders ( optional array of HeaderFilter )

如果请求头信息都不匹配任何一个 HeaderFilter 则匹配该请求。

responseHeaders ( optional array of HeaderFilter )

如果某些响应头信息匹配 HeaderFilter 中的某一个则匹配该请求。

excludeResponseHeaders ( optional array of HeaderFilter )

如果响应头信息都不匹配任何一个 HeaderFilter 则匹配该请求。

thirdPartyForCookies ( optional boolean )

如果设为 true，则匹配受第三方 Cookie 策略约束的请求；如果设为 false，则匹配所有其他请求。

stages ( optional array of enum of "onBeforeRequest", "onBeforeSendHeaders", "onHeadersReceived", or "onAuthRequired" )

包含描述阶段的字符串列表，允许的值包括 'onBeforeRequest'、'onBeforeSendHeaders'、'onHeadersReceived'、'onAuthRequired'。如果该属性存在的话，它会将适用的阶段限制在这一列表中。注意整个条件只能在与所有属性兼容的阶段中适用。

CancelRequest

声明式事件操作，取消网络请求。

RedirectRequest

声明式事件操作，重定向网络请求。

RedirectRequest 的属性

redirectUrl ( string )

请求重定向的目标。

RedirectToTransparentImage

声明式事件操作，将网络请求重定向至透明图片。

RedirectToEmptyDocument

声明式事件操作，将网络请求重定向至空文档。

RedirectByRegEx

对 URL 应用正则表达式，重定向请求。正则表达式采用 RE2 语法。

RedirectByRegEx 的属性

from ( string )

匹配表达式，可以包含捕获性分组。为了更接近 JavaScript 正则表达式，捕获性分组以 Perl 语法（$1、$2……），而不是 RE2 语法（\1、\2……）引用。

to ( string )

目标表达式。

SetRequestHeader

将指定名称的请求头信息设置为指定值。如果指定名称的头信息原来不存在，则会创建新的。头信息名称的比较不区分大小写，且每个请求中每个请求头信息名称只会出现一次。

SetRequestHeader 的属性

name ( string )

HTTP 请求头信息的名称。

value ( string )

HTTP 请求头信息的值。

RemoveRequestHeader

移除指定名称的请求头信息。不要在同一请求的同一头信息名称上同时使用 SetRequestHeader 和 RemoveRequestHeader。每个请求中每个请求头信息名称只会出现一次。

RemoveRequestHeader 的属性

name ( string )

HTTP 请求头信息的名称（不区分大小写）。

AddResponseHeader

向当前网络请求的响应中添加响应头信息。由于多个响应头信息可能会使用相同的名称，您需要首先删除然后再添加新的响应头信息才能完成替换。

AddResponseHeader 的属性

name ( string )

HTTP 响应头信息的名称。

value ( string )

HTTP 响应头信息的值。

RemoveResponseHeader

删除指定名称和值的所有响应头信息。

RemoveResponseHeader 的属性

name ( string )

HTTP 请求头信息的名称（不区分大小写）。

value ( optional string )

HTTP 响应头信息的值（不区分大小写）。

IgnoreRules

排除所有匹配指定条件的规则。

IgnoreRules 的属性

lowerPriorityThan ( optional integer )

如果设置的话，将忽略优先级低于指定值的规则。这一界限不是持久的，它只会影响同一网络请求阶段的规则与它们对应的操作。

hasTag ( optional string )

如果设置的话，包含指定标签的规则将被忽略。这一忽略不是持久的，它只影响同一网络请求阶段的规则及其操作。注意，规则按照优先级递减的顺序执行，该操作只会影响优先级低于当前规则的规则，具有相同优先级的规则可能会也可能不会被忽略。

SendMessageToExtension

触发 onMessage 事件。

SendMessageToExtension 的属性

message ( string )

传递给事件处理函数的词典中 message 属性的值。

RequestCookie

用于过滤或指定 HTTP 请求中的 Cookie。

RequestCookie 的属性

name ( optional string )

Cookie 的名称。

value ( optional string )

Cookie 的值，可以填充在双引号中。

ResponseCookie

用于指定 HTTP 响应中的 Cookie。

ResponseCookie 的属性

name ( optional string )

Cookie 的名称。

value ( optional string )

Cookie 的值，可以填充在双引号中。

expires ( optional string )

Cookie 的 Expires 属性值。

maxAge ( optional double )

Cookie 的 Max-Age 属性值。

domain ( optional string )

Cookie 的 Domain 属性值。

path ( optional string )

Cookie 的 Path 属性值。

secure ( optional string )

Cookie 的 Secure 属性是否存在。

httpOnly ( optional string )

Cookie 的 HttpOnly 属性是否存在。

FilterResponseCookie

用于 HTTP 响应 Cookie 的过滤器。

FilterResponseCookie 的属性

name ( optional string )

Cookie 的名称。

value ( optional string )

Cookie 的值，可以用双引号填充。

expires ( optional string )

Cookie 的 Expires 属性值。

maxAge ( optional double )

Cookie 的 Max-Age 属性值。

domain ( optional string )

Cookie 的 Domain 属性值。

path ( optional string )

Cookie 的 Path 属性值。

secure ( optional string )

Cookie 的 Secure 属性是否存在。

httpOnly ( optional string )

Cookie 的 HttpOnly 属性是否存在。

ageUpperBound ( optional integer )

Cookie 生命周期的上界（包含）（以当前时间之后多少秒的形式指定），只有过期日期时间在区间 [现在, 现在 + ageUpperBound] 内的 Cookie 满足这一条件，会话 Cookie 以及过期时间在过去的 Cookie 不满足该过滤器的条件。Cookie 的生命周期通过 Cookie 的 'max-age' 或 'expires' 属性来计算，如果两者都指定则使用 'max-age' 来计算 Cookie 的生命周期。

ageLowerBound ( optional integer )

Cookie 生命周期的下界（包含）（以当前时间之后多少秒的形式指定），只有过期日期时间在区间 [现在 + ageLowerBound, 现在] 内的 Cookie 满足这一条件，会话 Cookie 以及过期时间在过去的 Cookie 不满足该过滤器的条件。Cookie 的生命周期通过 Cookie 的 'max-age' 或 'expires' 属性来计算，如果两者都指定则使用 'max-age' 来计算 Cookie 的生命周期。

sessionCookie ( optional boolean )

过滤会话 Cookie，会话 Cookie 没有 'max-age' 或 'expires' 属性指定的生命周期。

AddRequestCookie

向请求中添加或者覆盖（如果相同名称的 Cookie 已经存在）Cookie。注意，您应该首选 Cookie API，因为它在计算上开销更少。

AddRequestCookie 的属性

cookie ( RequestCookie )

要添加至请求的 Cookie，所有字段都不能为 undefined。

AddResponseCookie

向响应中添加或者覆盖（如果相同名称的 Cookie 已经存在）Cookie。注意，您应该首选 Cookie API，因为它在计算上开销更少。

AddResponseCookie 的属性

cookie ( ResponseCookie )

要添加至响应的 Cookie，name 与 value 必须指定。

EditRequestCookie

编辑请求中的一个或多个 Cookie。注意，您应该首选 Cookie API，因为它在计算上开销更少。

EditRequestCookie 的属性

filter ( RequestCookie )

过滤要修改的 Cookie，所有空项都会忽略。

modification ( RequestCookie )

在匹配过滤器的 Cookie 中应该覆盖的属性，设置为空字符串的属性将移除。

EditResponseCookie

编辑响应中的一个或多个 Cookie。注意，您应该首选 Cookie API，因为它在计算上开销更少。

EditResponseCookie 的属性

filter ( FilterResponseCookie )

过滤要修改的 Cookie，所有空项都会忽略。

modification ( ResponseCookie )

在匹配过滤器的 Cookie 中应该覆盖的属性，设置为空字符串的属性将移除。

RemoveRequestCookie

移除请求中的一个或多个 Cookie。注意，您应该首选 Cookie API，因为它在计算上开销更少。

RemoveRequestCookie 的属性

filter ( RequestCookie )

过滤要移除的 Cookie，所有空项都会忽略。

RemoveResponseCookie

移除响应中的一个或多个 Cookie。注意，您应该首选 Cookie API，因为它在计算上开销更少。

RemoveResponseCookie 的属性

filter ( FilterResponseCookie )

过滤要移除的 Cookie，所有空项都会忽略。

事件

onRequest

提供声明式事件 API，包括 $ref:[events.Event.addRules addRules]、$ref:[events.Event.removeRules removeRules] 和 $ref:[events.Event.getRules getRules]。

chrome.declarativeWebRequest.onRequest.addRules(array of Rule rules, function callback)

chrome.declarativeWebRequest.onRequest.removeRules(array of string ruleIdentifiers, function callback)

chrome.declarativeWebRequest.onRequest.getRules(array of string ruleIdentifiers, function callback)

支持的条件

• RequestMatcher

支持的操作

• AddRequestCookie

• AddResponseCookie

• AddResponseHeader

• CancelRequest

• EditRequestCookie

• EditResponseCookie

• RedirectRequest

• RedirectToTransparentImage

• RedirectToEmptyDocument

• RedirectByRegEx

• RemoveRequestCookie

• RemoveResponseCookie

• RemoveRequestHeader

• RemoveResponseHeader

• SetRequestHeader

• SendMessageToExtension

• IgnoreRules

onMessage

当消息通过声明式网络请求 API 的 SendMessageToExtension 操作发送时产生。

addListener

chrome.declarativeWebRequest.onMessage.addListener(function callback)

参数

callback ( function )

callback 参数应该指定一个如下形式的函数：

function(object details) {...};

details ( object )

属性

message ( string )

调用脚本发送的消息。

stage ( enum of "onBeforeRequest", "onBeforeSendHeaders", "onHeadersReceived", or "onAuthRequired" )

事件发生时网络请求所处的阶段。

requestId ( string )

请求标识符。请求标识符在浏览器会话中保证唯一，所以，它们可以用来联系同一请求的不同事件。

url ( string )

method ( string )

标准 HTTP 方法。

frameId ( integer )

0 表示请求发生在主框架中，正数表示发出请求的子框架标识符。如果加载了（子）框架的文档（type 为 "main_frame" 或 "sub_frame"），frameId 指定该框架的标识符，而不是外层框架的标识符。框架标识符在标签页中保证唯一。

parentFrameId ( integer )

包含发送请求框架的框架（即父框架）标识符，如果不存在父框架则为 -1。

tabId ( integer )

产生请求的标签页标识符。如果请求与标签页无关则为 -1。

type ( enum of "main_frame", "sub_frame", "stylesheet", "script", "image", "object", "xmlhttprequest", or "other" )

请求的资源将如何使用。

timeStamp ( double )

该信号触发的时间，以 1970 年 1 月 1 日午夜开始所经过的毫秒数表示。