說明
注意:此 API 已淘汰。請改為參閱 declarativeNetRequest
API。使用 chrome.declarativeWebRequest
API 攔截、封鎖或修改傳輸中的要求。比 chrome.webRequest
API 更快許多,因為您可以註冊在瀏覽器中評估的規則 (而非 JavaScript 引擎),以減少往返延遲時間,並提高效率。
權限
declarativeWebRequest
您必須在擴充功能資訊清單中宣告「larativeWebRequest」權限,以及主機權限,才能使用這個 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 Request 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
發出的要求。此外,由於 resourceType
,系統會拒絕針對內嵌 iframe 提出的所有要求。
如要取消所有傳送至「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 Request API 遵循 WebRequest 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 |
✓ |
使用優先順序覆寫規則
您可以按照 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
動作,則只會套用至在同一階段中針對相同網路要求執行的其他動作。
類型
AddRequestCookie
在請求中加入 Cookie 或覆寫 Cookie,以免其他 Cookie 已存在。請注意,建議使用 Cookie API,因為這麼做的費用較低。
屬性
-
建構函式
void
constructor
函式如下所示:(arg: AddRequestCookie) => {...}
-
arg
-
returns
-
-
在請求中加入的 Cookie。沒有未定義的欄位。
AddResponseCookie
在回應中加入 Cookie 或覆寫 Cookie,以免其他 Cookie 已經有同名的情況。請注意,建議使用 Cookie API,因為這麼做的費用較低。
屬性
-
建構函式
void
constructor
函式如下所示:(arg: AddResponseCookie) => {...}
-
returns
-
-
要新增至回應的 Cookie。您必須指定名稱和值。
AddResponseHeader
將回應標頭新增至這個網路要求的回應。多個回應標頭可能會共用相同的名稱,因此如要更換標頭,請先移除標頭再新增回應標頭。
屬性
-
建構函式
void
constructor
函式如下所示:(arg: AddResponseHeader) => {...}
-
returns
-
-
名稱
字串
HTTP 回應標頭名稱。
-
值
字串
HTTP 回應標頭值。
CancelRequest
取消網路要求的宣告式事件動作。
屬性
-
建構函式
void
constructor
函式如下所示:(arg: CancelRequest) => {...}
-
arg
-
returns
-
EditRequestCookie
編輯一或多個要求的 Cookie。請注意,建議使用 Cookie API,因為這麼做的費用較低。
屬性
-
建構函式
void
constructor
函式如下所示:(arg: EditRequestCookie) => {...}
-
returns
-
-
篩選器
篩選出要修改的 Cookie。系統會忽略所有空白項目。
-
應在破壞篩選器的 Cookie 中覆寫的屬性。系統會移除設為空白字串的屬性。
EditResponseCookie
編輯一或多個回應 Cookie。請注意,建議使用 Cookie API,因為這麼做的費用較低。
屬性
-
建構函式
void
constructor
函式如下所示:(arg: EditResponseCookie) => {...}
-
returns
-
-
篩選出要修改的 Cookie。系統會忽略所有空白項目。
-
應在破壞篩選器的 Cookie 中覆寫的屬性。系統會移除設為空白字串的屬性。
FilterResponseCookie
HTTP 回應中的 Cookie 篩選器。
屬性
-
ageLowerBound
數字 選填
Cookie 生命週期的下限 (以目前時間後秒數指定)。只有到期日時間設為「now + 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 屬性的值。
-
有效期限
字串 選用
Expiration Cookie 屬性的值。
-
httpOnly
字串 選用
存在 HttpOnly Cookie 屬性。
-
maxAge
數字 選填
Max-Age Cookie 屬性的值
-
名稱
字串 選用
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) => {...}
-
arg
-
returns
-
-
hasTag
字串 選用
設定後,系統就會忽略含有指定標記的規則。此忽略不會保留,只會影響在相同網路要求階段的規則及動作。請注意,規則是依優先順序遞減執行。這項操作會影響低於目前規則的規則。系統不一定會忽略優先順序相同的規則。
-
lowerPriorityThan
數字 選填
設定後,系統會忽略優先順序低於指定值的規則。此界線不會保留,只會影響在相同的網路要求階段中的規則及動作。
RedirectByRegEx
在網址上套用規則運算式,將要求重新導向。規則運算式使用 RE2 語法。
屬性
-
建構函式
void
constructor
函式如下所示:(arg: RedirectByRegEx) => {...}
-
arg
-
returns
-
-
來源
字串
可能含有擷取群組的比對模式。系統使用 Perl 語法 ($1、$2, ...) 參照擷取群組,而不是 RE2 語法 (\1、\2, ...),以便更接近 JavaScript 規則運算式。
-
到
字串
目的地模式。
RedirectRequest
重新導向網路要求的宣告式事件動作。
屬性
-
建構函式
void
constructor
函式如下所示:(arg: RedirectRequest) => {...}
-
arg
-
returns
-
-
redirectUrl
字串
要求重新導向的目的地。
RedirectToEmptyDocument
宣告式事件動作,會將網路要求重新導向至空白文件。
屬性
-
建構函式
void
constructor
函式如下所示:(arg: RedirectToEmptyDocument) => {...}
-
returns
-
RedirectToTransparentImage
宣告式事件動作,會將網路要求重新導向至透明圖片。
屬性
-
建構函式
void
constructor
函式如下所示:(arg: RedirectToTransparentImage) => {...}
-
returns
-
RemoveRequestCookie
移除一或多個要求的 Cookie。請注意,建議使用 Cookie API,因為這麼做的費用較低。
屬性
-
建構函式
void
constructor
函式如下所示:(arg: RemoveRequestCookie) => {...}
-
returns
-
-
篩選器
篩選出要移除的 Cookie。系統會忽略所有空白項目。
RemoveRequestHeader
移除指定名稱的要求標頭。請勿在相同要求中使用具有相同標頭名稱的 SetRequestHeader 和 RemoveRequestHeader。每項要求中的各個要求標頭名稱都只會產生一次。
屬性
-
建構函式
void
constructor
函式如下所示:(arg: RemoveRequestHeader) => {...}
-
returns
-
-
名稱
字串
HTTP 要求標頭名稱 (不區分大小寫)。
RemoveResponseCookie
移除一或多個回應 Cookie。請注意,建議使用 Cookie API,因為這麼做的費用較低。
屬性
-
建構函式
void
constructor
函式如下所示:(arg: RemoveResponseCookie) => {...}
-
returns
-
-
篩選出要移除的 Cookie。系統會忽略所有空白項目。
RemoveResponseHeader
移除指定名稱和值的所有回應標頭。
屬性
-
建構函式
void
constructor
函式如下所示:(arg: RemoveResponseHeader) => {...}
-
returns
-
-
名稱
字串
HTTP 要求標頭名稱 (不區分大小寫)。
-
值
字串 選用
HTTP 要求標頭值 (不區分大小寫)。
RequestCookie
HTTP 要求中的 Cookie 篩選器或規格。
屬性
-
名稱
字串 選用
Cookie 的名稱。
-
值
字串 選用
Cookie 的值可以用雙引號括住。
RequestMatcher
依據多種條件比對網路事件。
屬性
-
建構函式
void
constructor
函式如下所示:(arg: RequestMatcher) => {...}
-
arg
-
returns
-
-
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 屬性的值。
-
有效期限
字串 選用
Expiration Cookie 屬性的值。
-
httpOnly
字串 選用
存在 HttpOnly Cookie 屬性。
-
maxAge
數字 選填
Max-Age Cookie 屬性的值
-
名稱
字串 選用
Cookie 的名稱。
-
path
字串 選用
路徑 Cookie 屬性的值。
-
安全
字串 選用
內容是否存在安全 Cookie 屬性。
-
值
字串 選用
Cookie 的值可以用雙引號括住。
SendMessageToExtension
屬性
-
建構函式
void
constructor
函式如下所示:(arg: SendMessageToExtension) => {...}
-
returns
-
-
訊息
字串
系統會將字典的
message
屬性傳遞到事件處理常式。
SetRequestHeader
將指定名稱的要求標頭設為指定值。如果指定名稱的標頭不存在,系統會建立新標頭。標頭名稱比較一律不區分大小寫。每項要求中的各個要求標頭名稱都只會產生一次。
屬性
-
建構函式
void
constructor
函式如下所示:(arg: SetRequestHeader) => {...}
-
arg
-
returns
-
-
名稱
字串
HTTP 要求標頭名稱。
-
值
字串
HTTP 要求標頭值。
Stage
列舉
"onBeforeRequest"
"onBeforeSendHeaders"
"onHeadersReceived"
"onAuthRequired"
活動
onMessage
chrome.declarativeWebRequest.onMessage.addListener(
callback: function,
)
透過宣告式網路要求 API 的動作透過 declarativeWebRequest.SendMessageToExtension
傳送訊息時觸發。
參數
-
回呼
功能
callback
參數如下所示:(details: object) => void
-
詳細資料
物件
-
documentId
字串 選用
提出要求的文件 UUID。
-
documentLifecycle
文件的生命週期。
-
frameId
號碼
值 0 表示要求會在主頁框中執行;正值代表要求發生時子頁框的 ID。如果載入 (子) 畫面的文件 (
type
為main_frame
或sub_frame
),frameId
會指出這個頁框的 ID,而不是外框的 ID。分頁中的影格 ID 不得重複。 -
frameType
導覽所在的頁框類型。
-
訊息
字串
呼叫指令碼所傳送的訊息。
-
method
字串
標準 HTTP 方法。
-
parentDocumentId
字串 選用
擁有這個頁框的上層文件 UUID。如果沒有父項,就無法設定這個屬性。
-
parentFrameId
號碼
包裝傳送要求的影格 ID。如果沒有上層頁框,請設為 -1。
-
requestId
字串
要求的 ID。瀏覽器工作階段中的要求 ID 不得重複。因此,這些事件可以用來連結同一個要求的不同事件。
-
在此流程的各個階段
事件觸發時的網路要求階段。
-
tabId
號碼
發出要求的分頁 ID。如果要求與分頁無關,請設為 -1。
-
timeStamp
號碼
這個信號的觸發時間 (自 Epoch 紀元時間起算,以毫秒為單位)。
-
要求資源的使用情況。
-
網址
字串
-
-
onRequest
提供由 addRules
、removeRules
和 getRules
組成的宣告式事件 API。
動作