chrome.declarativeWebRequest

說明

注意：這個 API 已淘汰，請改用 declarativeNetRequest API。使用 chrome.declarativeWebRequest API 攔截、封鎖或修改傳輸中的要求。速度比 chrome.webRequest API 快許多；由於您可以註冊要在瀏覽器中評估的規則 (而非 JavaScript 引擎)，藉此減少往返延遲時間，並提高處理效率。

權限

declarativeWebRequest

您必須宣告「declarativeWebRequest」擴充功能資訊清單中的權限，才能使用擴充功能 API，以及主機權限。

{
  "name": "My extension",
  ...
  "permissions": [
    "declarativeWebRequest",
    "*://*/*"
  ],
  ...
}

可用性

Beta 版 ≤MV2

資訊清單

請注意，特定類型的非敏感動作不需要主機權限：

  • 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 事件物件的規則。

Declarative Web Request API 支援單一類型的比對條件，也就是 RequestMatcher。 只有在符合所有列出的條件的情況下，「RequestMatcher」才會比對網路要求。下列 當使用者在RequestMatcherhttps://www.example.com ominibox：

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

由於配置的關係，向 https://www.example.com 發出的要求會遭到 RequestMatcher 拒絕。 此外，內嵌 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 Request API 遵循網路要求的生命週期模型 Request 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，因為計算費用通常較低。

屬性

AddResponseCookie

將 Cookie 加入回應，或覆寫 Cookie，以免已有其他同名的 Cookie。請注意，建議您使用 Cookie API，因為計算費用通常較低。

屬性

AddResponseHeader

將回應標頭新增至這個網路要求的回應。多個回應標頭可能共用相同名稱，因此你必須先移除回應標頭，再新增回應標頭，才能取代標頭。

屬性

CancelRequest

取消網路要求的宣告式事件動作。

屬性

EditRequestCookie

編輯一或多個要求的 Cookie。請注意，建議您使用 Cookie API，因為計算費用通常較低。

屬性

EditResponseCookie

編輯一或多個回應的 Cookie。請注意，建議您使用 Cookie API，因為計算費用通常較低。

屬性

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 效期

  • 網域

    string optional

    網域 Cookie 屬性的值。

  • 有效期限

    string optional

    Expiration Cookie 屬性的值。

  • httpOnly

    string optional

    有 HttpOnly Cookie 屬性。

  • maxAge

    編號 選填

    Max-Age Cookie 屬性的值

  • 名稱

    string optional

    Cookie 的名稱。

  • 路徑

    string optional

    路徑 Cookie 屬性的值。

  • 安全

    string optional

    有安全 Cookie 屬性。

  • 工作階段 Cookie

    布林值 選填

    篩選工作階段 Cookie。工作階段 Cookie 未在任何「max-age」中指定生命週期或「expires」屬性。

  • 值

    string optional

    Cookie 的值，可用雙引號括住。

HeaderFilter

針對各種條件篩選要求標頭。多項條件會視為相互連接。

屬性

  • nameContains

    string |string[] 選填

    比對標頭名稱是否包含所有指定字串。

  • nameEquals

    string optional

    比對標頭名稱是否等於指定字串。

  • namePrefix

    string optional

    比對標頭名稱開頭為指定字串。

  • nameSuffix

    string optional

    比對標頭名稱結尾是否為指定字串。

  • valueContains

    string |string[] 選填

    比對標頭值是否包含所有指定字串。

  • valueEquals

    string optional

    比對標頭值是否等於指定字串。

  • valuePrefix

    string optional

    比對標頭值是否以指定字串開頭。

  • valueSuffix

    string optional

    比對標頭值結尾是否為指定字串。

IgnoreRules

遮蓋符合指定條件的所有規則。

屬性

  • 建構函式

    void

    constructor 函式如下所示： 

    (arg: IgnoreRules) => {...}

  • hasTag

    string optional

    如果設定這個項目，系統會忽略含有指定標記的規則。忽略訊息不會保留，只會影響相同網路要求階段的規則及其動作。請注意，規則會按照優先順序執行，以遞減順序執行。這項操作會影響優先順序低於目前規則的規則。系統可能不會忽略優先順序相同的規則。

  • lowerPriorityThan

    編號 選填

    如果設定這個項目，系統會忽略優先順序低於指定值的規則。這個邊界不會保留，只會影響相同網路要求階段的規則及其動作。

RedirectByRegEx

對網址套用規則運算式，藉此重新導向要求。規則運算式使用 RE2 語法。

屬性

  • 建構函式

    void

    constructor 函式如下所示： 

    (arg: RedirectByRegEx) => {...}

  • 來自

    字串

    可能包含擷取群組的比對模式。系統是採用 Perl 語法 ($1、$2、...) 來參照擷取群組，而不是 RE2 語法 (\1、\2、...)，以更接近 JavaScript 規則運算式。

  • 到

    字串

    目的地模式。

RedirectRequest

重新導向網路要求的宣告式事件動作。

屬性

RedirectToEmptyDocument

將網路要求重新導向至空白文件的宣告事件動作。

屬性

RedirectToTransparentImage

將網路要求重新導向至透明圖片的宣告式事件動作。

屬性

RemoveRequestCookie

移除一或多個 Cookie 請求。請注意，建議您使用 Cookie API，因為計算費用通常較低。

屬性

RemoveRequestHeader

移除指定名稱的要求標頭。請勿在相同要求中使用具有相同標頭名稱的 SetRequestHeader 和 RemoveRequestHeader。每個要求標頭名稱都只會出現一次。

屬性

RemoveResponseCookie

移除一或多個回應 Cookie。請注意，建議您使用 Cookie API，因為計算費用通常較低。

屬性

RemoveResponseHeader

移除指定名稱和值的所有回應標頭。

屬性

RequestCookie

HTTP 要求中的 Cookie 篩選器或規格。

屬性

  • 名稱

    string optional

    Cookie 的名稱。

  • 值

    string optional

    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 相符。

  • 階段

    Stage[] 選用

    包含用於說明階段的字串清單。允許的值為「onBeforeRequest」、「onBeforeSendHeaders」、「onHeadersReceived」、「onAuthRequired」。如果有這個屬性，則只會列出適用的階段。請注意，整個條件僅適用於與所有屬性相容的階段。

  • thirdPartyForCookies

    布林值 選填

    已淘汰

    自版本 87 起將略過。

    如果設為 true，系統就會比對適用於第三方 Cookie 政策的請求。如果設為 false，則會比對其他所有要求。

  • 網址

    UrlFilter 選用

    比對要求的網址是否符合 UrlFilter 條件。

ResponseCookie

HTTP 回應中的 Cookie 規格。

屬性

  • 網域

    string optional

    網域 Cookie 屬性的值。

  • 有效期限

    string optional

    Expiration Cookie 屬性的值。

  • httpOnly

    string optional

    有 HttpOnly Cookie 屬性。

  • maxAge

    編號 選填

    Max-Age Cookie 屬性的值

  • 名稱

    string optional

    Cookie 的名稱。

  • 路徑

    string optional

    路徑 Cookie 屬性的值。

  • 安全

    string optional

    有安全 Cookie 屬性。

  • 值

    string optional

    Cookie 的值，可用雙引號括住。

SendMessageToExtension

觸發 declarativeWebRequest.onMessage 事件。

屬性

SetRequestHeader

將指定名稱的要求標頭設為指定值。如果含有指定名稱的標頭之前不存在，系統會建立新的標頭。標頭名稱比較一律不區分大小寫。每個要求標頭名稱都只會出現一次。

屬性

Stage

列舉

"onBeforeRequest"

"onBeforeSendHeaders"

"onHeadersReceived"

"onAuthRequired"

活動

onMessage

chrome.declarativeWebRequest.onMessage.addListener(
  callback: function,
)

當宣告式網路要求 API 的動作透過 declarativeWebRequest.SendMessageToExtension 傳送訊息時，就會觸發。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (details: object) => void

    • 詳細資料

      物件

      • documentId

        string optional

        提出要求的文件的 UUID。

      • 文件所在的生命週期。

      • frameId

        數字

        值 0 表示要求在主頁框中發生；正值表示要求發生子頁框的 ID。如果載入 (子) 頁框的文件 (type 是 main_frame 或 sub_frame)，frameId 代表這個頁框的 ID，而不是外部框架的 ID。分頁中的影格 ID 不得重複。

      • 導覽發生的影格類型。

      • 訊息

        字串

        呼叫指令碼傳送的訊息。

      • method

        字串

        標準 HTTP 方法。

      • parentDocumentId

        string optional

        擁有此影格的父項文件 UUID。如果沒有父項，則不會設定這個屬性。

      • parentFrameId

        數字

        包裝要求所傳送頁框的頁框 ID。如果沒有上層頁框，請設為 -1。

      • requestId

        字串

        要求的 ID。請求 ID 在單一瀏覽器工作階段中是獨一無二的。因此，這些參數可用於為同一個要求中的不同事件建立關聯。

      • 在此流程的各個階段

        階段

        網路要求觸發事件的階段。

      • tabId

        數字

        發生要求的分頁 ID。如果要求與分頁無關，請設為 -1。

      • timeStamp

        數字

        這個信號的觸發時間 (自 Epoch 紀元時間起算，以毫秒為單位)。

      • 要求資源的使用方式。

      • 網址

        字串

onRequest

提供由 addRules、removeRules 和 getRules 組成的宣告式事件 API。

條件

RequestMatcher

動作

AddRequestCookie

AddResponseCookie

AddResponseHeader

CancelRequest

EditRequestCookie

EditResponseCookie

RedirectRequest

RedirectToTransparentImage

RedirectToEmptyDocument

RedirectByRegEx

RemoveRequestCookie

RemoveResponseCookie

RemoveRequestHeader

RemoveResponseHeader

SetRequestHeader

SendMessageToExtension

IgnoreRules