chrome.declarativeWebRequest

說明

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

權限

declarativeWebRequest

您必須在擴充功能資訊清單中宣告「larativeWebRequest」權限，以及主機權限，才能使用這個 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 事件物件中註冊規則。

宣告式 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，因為這麼做的費用較低。

屬性

AddResponseCookie

在回應中加入 Cookie 或覆寫 Cookie，以免其他 Cookie 已經有同名的情況。請注意，建議使用 Cookie API，因為這麼做的費用較低。

屬性

AddResponseHeader

將回應標頭新增至這個網路要求的回應。多個回應標頭可能會共用相同的名稱，因此如要更換標頭，請先移除標頭再新增回應標頭。

屬性

CancelRequest

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

屬性

EditRequestCookie

編輯一或多個要求的 Cookie。請注意，建議使用 Cookie API，因為這麼做的費用較低。

屬性

EditResponseCookie

編輯一或多個回應 Cookie。請注意，建議使用 Cookie API，因為這麼做的費用較低。

屬性

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[] optional

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

  • nameEquals

    字串 選用

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

  • namePrefix

    字串 選用

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

  • nameSuffix

    字串 選用

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

  • valueContains

    string|string[] optional

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

  • valueEquals

    字串 選用

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

  • valuePrefix

    字串 選用

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

  • valueSuffix

    字串 選用

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

IgnoreRules

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

屬性

  • 建構函式

    void

    constructor 函式如下所示：

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

  • hasTag

    字串 選用

    設定後，系統就會忽略含有指定標記的規則。此忽略不會保留，只會影響在相同網路要求階段的規則及動作。請注意，規則是依優先順序遞減執行。這項操作會影響低於目前規則的規則。系統不一定會忽略優先順序相同的規則。

  • 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 篩選器或規格。

屬性

  • 名稱

    字串 選用

    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，則會比對所有其他要求。

  • url

    UrlFilter 選用

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

ResponseCookie

HTTP 回應中的 Cookie 規格。

屬性

  • 網域

    字串 選用

    網域 Cookie 屬性的值。

  • 有效期限

    字串 選用

    Expiration Cookie 屬性的值。

  • httpOnly

    字串 選用

    存在 HttpOnly Cookie 屬性。

  • maxAge

    數字 選填

    Max-Age Cookie 屬性的值

  • 名稱

    字串 選用

    Cookie 的名稱。

  • path

    字串 選用

    路徑 Cookie 屬性的值。

  • 安全

    字串 選用

    內容是否存在安全 Cookie 屬性。

  • 值

    字串 選用

    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

        字串 選用

        提出要求的文件 UUID。

      • 文件的生命週期。

      • frameId

        號碼

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

      • 導覽所在的頁框類型。

      • 訊息

        字串

        呼叫指令碼所傳送的訊息。

      • method

        字串

        標準 HTTP 方法。

      • parentDocumentId

        字串 選用

        擁有這個頁框的上層文件 UUID。如果沒有父項，就無法設定這個屬性。

      • parentFrameId

        號碼

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

      • requestId

        字串

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

      • 在此流程的各個階段

        階段

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

      • tabId

        號碼

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

      • timeStamp

        號碼

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

      • 要求資源的使用情況。

      • url

        字串

onRequest

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

條件

RequestMatcher

動作

AddRequestCookie

AddResponseCookie

AddResponseHeader

CancelRequest

EditRequestCookie

EditResponseCookie

RedirectRequest

RedirectToTransparentImage

RedirectToEmptyDocument

RedirectByRegEx

RemoveRequestCookie

RemoveResponseCookie

RemoveRequestHeader

RemoveResponseHeader

SetRequestHeader

SendMessageToExtension

IgnoreRules