chrome.declarativeWebRequest

說明

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

權限

declarativeWebRequest

如要使用這個 API，您必須在擴充功能資訊清單中宣告「declarativeWebRequest」權限，並提供主機權限。

{
  "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。

規則

Declarative Web Request API 遵循宣告式 API 的概念。您可以向 chrome.declarativeWebRequest.onRequest 事件物件註冊規則。

Declarative Web Request API 支援單一類型的比對條件，即 RequestMatcher。只有在符合所有列出的條件時， RequestMatcher 才會比對網路要求。使用者在多功能方塊中輸入 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]);

評估條件和動作

Declarative Web Request API 遵循 Web 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)。請注意，建議使用 Cookies API，因為這樣計算成本較低。

屬性

AddResponseCookie

將 Cookie 新增至回應或覆寫 Cookie (如果已存在名稱相同的其他 Cookie)。請注意，建議使用 Cookies API，因為這樣計算成本較低。

屬性

AddResponseHeader

將回應標頭新增至這項網頁要求的回應。由於多個回應標頭可能共用相同名稱，如要替換回應標頭，必須先移除，然後新增回應標頭。

屬性

CancelRequest

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

屬性

EditRequestCookie

編輯要求的一或多個 Cookie。請注意，建議使用 Cookies API，因為這樣計算成本較低。

屬性

EditResponseCookie

編輯一或多個回應 Cookie。請注意，建議使用 Cookies API，因為這樣計算成本較低。

屬性

FilterResponseCookie

HTTP 回應中的 Cookie 篩選器。

屬性

  • ageLowerBound

    數字 選填

    Cookie 存留時間的下限 (以目前時間之後的秒數指定)。只有到期日期和時間設為「現在 + ageLowerBound」或之後的 Cookie，才會符合這項條件。工作階段 Cookie 不符合這項篩選條件。系統會根據「max-age」或「expires」Cookie 屬性計算 Cookie 的生命週期。如果同時指定這兩項屬性，系統會使用「max-age」計算 Cookie 的存留時間。

  • ageUpperBound

    數字 選填

    Cookie 生命週期的上限 (以目前時間之後的秒數指定)。只有到期日期時間位於 [現在，現在 + ageUpperBound] 間隔的 Cookie，才會符合這項條件。工作階段 Cookie 和過期的 Cookie 不符合這項篩選條件。系統會根據「max-age」或「expires」Cookie 屬性計算 Cookie 的生命週期。如果同時指定這兩項屬性，系統會使用「max-age」計算 Cookie 的存留時間。

  • 網域

    字串 選填

    Domain Cookie 屬性的值。

  • 有效期限

    字串 選填

    Expires Cookie 屬性的值。

  • httpOnly

    字串 選填

    HttpOnly Cookie 屬性是否存在。

  • maxAge

    數字 選填

    Max-Age Cookie 屬性的值

  • 名稱

    字串 選填

    Cookie 的名稱。

  • 路徑

    字串 選填

    Path Cookie 屬性的值。

  • 安全

    字串 選填

    Secure Cookie 屬性是否存在。

  • sessionCookie

    布林值 選填

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

  • 值

    字串 選填

    Cookie 的值，可能以雙引號填補。

HeaderFilter

依據各種條件篩選要求標頭。系統會將多個條件視為合取。

屬性

  • nameContains

    字串 | 字串陣列 選用

    如果標頭名稱包含所有指定的字串，就會相符。

  • nameEquals

    字串 選填

    如果標頭名稱等於指定的字串，即為相符。

  • namePrefix

    字串 選填

    如果標頭名稱開頭為指定字串，則相符。

  • nameSuffix

    字串 選填

    如果標頭名稱結尾為指定字串，則相符。

  • valueContains

    字串 | 字串陣列 選用

    如果標頭值包含所有指定的字串，即為相符。

  • valueEquals

    字串 選填

    如果標頭值等於指定字串，則相符。

  • valuePrefix

    字串 選填

    如果標頭值開頭為指定字串，即為相符。

  • valueSuffix

    字串 選填

    如果標頭值結尾為指定字串，則相符。

IgnoreRules

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

屬性

  • 建構函式

    void

    constructor 函式如下所示： 

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

  • hasTag

    字串 選填

    如果設定了這個屬性，系統就會忽略含有指定標記的規則。這項忽略作業不會保留，只會影響相同網路要求階段的規則和動作。請注意，系統會依優先順序遞減的順序執行規則。這項操作會影響優先順序低於目前規則的規則。優先順序相同的規則可能會遭到忽略。

  • lowerPriorityThan

    數字 選填

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

RedirectByRegEx

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

屬性

  • 建構函式

    void

    constructor 函式如下所示： 

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

  • 來自

    字串

    比對模式，可能包含擷取群組。為了更貼近 JavaScript 規則運算式，擷取群組會以 Perl 語法 ($1、$2 等) 參照，而非 RE2 語法 (\1、\2 等)。

  • 到

    字串

    目的地模式。

RedirectRequest

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

屬性

RedirectToEmptyDocument

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

屬性

RedirectToTransparentImage

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

屬性

RemoveRequestCookie

移除一或多個要求 Cookie。請注意，建議使用 Cookies API，因為這樣計算成本較低。

屬性

RemoveRequestHeader

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

屬性

RemoveResponseCookie

移除一或多個回應 Cookie。請注意，建議使用 Cookies API，因為這樣計算成本較低。

屬性

RemoveResponseHeader

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

屬性

RequestCookie

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

屬性

  • 名稱

    字串 選填

    Cookie 的名稱。

  • 值

    字串 選填

    Cookie 的值，可能以雙引號填補。

RequestMatcher

根據各種條件比對網路事件。

屬性

  • 建構函式

    void

    constructor 函式如下所示： 

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

  • contentType

    字串陣列 選用

    如果回應的 MIME 媒體類型 (來自 HTTP Content-Type 標頭) 包含在清單中，即為相符。

  • excludeContentType

    字串陣列 選用

    如果回應的 MIME 媒體類型 (來自 HTTP Content-Type 標頭) 未列於清單中，則相符。

  • excludeRequestHeaders

    HeaderFilter[] 選用

    如果沒有任何 HeaderFilter 比對要求標頭，就會相符。

  • excludeResponseHeaders

    HeaderFilter[] 選用

    如果沒有任何 HeaderFilter 比對到任何回應標頭，就會相符。

  • firstPartyForCookiesUrl

    UrlFilter 選填

    已淘汰

    自第 82 版起會遭到忽略。

    如果要求的「第一方」網址符合 UrlFilter 的條件，就會相符。要求的第一方網址 (如有) 可能與要求目標網址不同，且說明第三方 Cookie 檢查時視為「第一方」的內容。

  • requestHeaders

    HeaderFilter[] 選用

    如果其中一個 HeaderFilter 與部分要求標頭相符，即為相符。

  • resourceType

    ResourceType[] optional

    如果要求的類型包含在清單中，就會相符。系統會篩除無法與任何類型相符的要求。

  • responseHeaders

    HeaderFilter[] 選用

    如果其中一個 HeaderFilter 比對到部分回應標頭，即為相符。

  • 階段

    階段[] 選用

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

  • thirdPartyForCookies

    布林值 選填

    已淘汰

    自 87 版起會遭到忽略。

    如果設為 true，則符合第三方 Cookie 政策的要求。如果設為 false，則會比對所有其他要求。

  • 網址

    UrlFilter 選填

    如果要求的網址符合 UrlFilter 的條件，就會相符。

ResponseCookie

HTTP 回應中的 Cookie 規格。

屬性

  • 網域

    字串 選填

    Domain Cookie 屬性的值。

  • 有效期限

    字串 選填

    Expires Cookie 屬性的值。

  • httpOnly

    字串 選填

    HttpOnly Cookie 屬性是否存在。

  • maxAge

    數字 選填

    Max-Age Cookie 屬性的值

  • 名稱

    字串 選填

    Cookie 的名稱。

  • 路徑

    字串 選填

    Path Cookie 屬性的值。

  • 安全

    字串 選填

    Secure Cookie 屬性是否存在。

  • 值

    字串 選填

    Cookie 的值，可能以雙引號填補。

SendMessageToExtension

觸發 declarativeWebRequest.onMessage 事件。

屬性

SetRequestHeader

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

屬性

Stage

列舉

「onBeforeRequest」

「onBeforeSendHeaders」

「onHeadersReceived」

「onAuthRequired」

事件

onMessage

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

透過宣告式網頁要求 API 的動作，經由 declarativeWebRequest.SendMessageToExtension 傳送訊息時觸發。

參數

  • callback

    函式

    callback 參數如下： 

    (details: object) => void

    • 詳細資料

      物件

      • documentId

        字串 選填

        提出要求的文件 UUID。

      • 文件所處的生命週期。

      • frameId

        數字

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

      • 發生導覽的頁框類型。

      • 訊息

        字串

        呼叫指令碼傳送的訊息。

      • 方法

        字串

        標準 HTTP 方法。

      • parentDocumentId

        字串 選填

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

      • parentFrameId

        數字

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

      • requestId

        字串

        要求的 ID。要求 ID 在瀏覽器工作階段中不得重複。因此，這些 ID 可用來關聯同一要求中的不同事件。

      • 在此流程的各個階段

        階段

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

      • tabId

        數字

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

      • timeStamp

        數字

        觸發這項信號的時間，以 Epoch 紀元時間起算的毫秒數表示。

      • 如何使用要求的資源。

      • 網址

        字串

onRequest

提供 Declarative Event API，包含 addRules、removeRules 和 getRules。

條件

RequestMatcher

動作

AddRequestCookie

AddResponseCookie

AddResponseHeader

CancelRequest

EditRequestCookie

EditResponseCookie

RedirectRequest

RedirectToTransparentImage

RedirectToEmptyDocument

RedirectByRegEx

RemoveRequestCookie

RemoveResponseCookie

RemoveRequestHeader

RemoveResponseHeader

SetRequestHeader

SendMessageToExtension

IgnoreRules