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]);

敬上

注意：請務必一次大量註冊或取消註冊規則，因為 每項作業都會重新建立內部資料結構。重建作業 雖然所費不貲，但有助於快速執行數十萬個網址的網址比對演算法。 Events API 的效能部分提供了進一步的效能提示。

評估條件和動作

宣告式 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		✓

注意：您可以使用「階段」進一步限制適用的階段屬性。

注意：重新導向動作啟動的重新導向會使用原始要求方法來進行重新導向 例外：如果重新導向是在 `onHeadersReceived` 階段啟動，則重新導向 才會透過「GET」方法發出

範例：您可將 「new chrome.declarativeWebRequest.RequestMatcher({contentType: ["image/jpeg"]})」條件，並使用 「new chrome.declarativeWebRequest.CancelRequest()」動作，因為兩者可供評估 「onHeadersReceived」階段不過，您無法將要求比對器與 「new chrome.declarativeWebRequest.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

    AddRequestCookie

  • returns

    AddRequestCookie

• 餅乾

  RequestCookie

  要加入請求的 Cookie。沒有未定義的欄位。

AddResponseCookie

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

屬性

• 建構函式

  void

  constructor 函式如下所示：

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

  • arg

    AddResponseCookie

  • returns

    AddResponseCookie

• 餅乾

  ResponseCookie

  要加入回應的 Cookie。必須指定名稱和值。

AddResponseHeader

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

屬性

• 建構函式

  void

  constructor 函式如下所示：

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

  • arg

    AddResponseHeader

  • returns

    AddResponseHeader

• 名稱

  字串

  HTTP 回應標頭名稱。

• 值

  字串

  HTTP 回應標頭值。

CancelRequest

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

屬性

• 建構函式

  void

  constructor 函式如下所示：

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

  • arg

    CancelRequest

  • returns

    CancelRequest

EditRequestCookie

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

屬性

• 建構函式

  void

  constructor 函式如下所示：

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

  • arg

    EditRequestCookie

  • returns

    EditRequestCookie

• 篩選器

  RequestCookie

  篩選出將修改的 Cookie。系統會忽略所有空白項目。

• 修改

  RequestCookie

  某些屬性在連至篩選器的 Cookie 中應覆寫。系統會移除設為空白字串的屬性。

EditResponseCookie

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

屬性

• 建構函式

  void

  constructor 函式如下所示：

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

  • arg

    EditResponseCookie

  • returns

    EditResponseCookie

• 篩選器

  FilterResponseCookie

  篩選出將修改的 Cookie。系統會忽略所有空白項目。

• 修改

  ResponseCookie

  某些屬性在連至篩選器的 Cookie 中應覆寫。系統會移除設為空白字串的屬性。

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) => {...}

  • arg

    IgnoreRules

  • returns

    IgnoreRules

• hasTag

  string optional

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

• lowerPriorityThan

  編號 選填

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

RedirectByRegEx

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

屬性

• 建構函式

  void

  constructor 函式如下所示：

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

  • arg

    RedirectByRegEx

  • returns

    RedirectByRegEx

• 來自

  字串

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

• 到

  字串

  目的地模式。

RedirectRequest

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

屬性

• 建構函式

  void

  constructor 函式如下所示：

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

  • arg

    RedirectRequest

  • returns

    RedirectRequest

• redirectUrl

  字串

  要求重新導向的目的地。

RedirectToEmptyDocument

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

屬性

• 建構函式

  void

  constructor 函式如下所示：

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

  • arg

    RedirectToEmptyDocument

  • returns

    RedirectToEmptyDocument

RedirectToTransparentImage

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

屬性

• 建構函式

  void

  constructor 函式如下所示：

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

  • arg

    RedirectToTransparentImage

  • returns

    RedirectToTransparentImage

RemoveRequestCookie

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

屬性

• 建構函式

  void

  constructor 函式如下所示：

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

  • arg

    RemoveRequestCookie

  • returns

    RemoveRequestCookie

• 篩選器

  RequestCookie

  篩選出要移除的 Cookie。系統會忽略所有空白項目。

RemoveRequestHeader

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

屬性

• 建構函式

  void

  constructor 函式如下所示：

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

  • arg

    RemoveRequestHeader

  • returns

    RemoveRequestHeader

• 名稱

  字串

  HTTP 要求標頭名稱 (不區分大小寫)。

RemoveResponseCookie

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

屬性

• 建構函式

  void

  constructor 函式如下所示：

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

  • arg

    RemoveResponseCookie

  • returns

    RemoveResponseCookie

• 篩選器

  FilterResponseCookie

  篩選出要移除的 Cookie。系統會忽略所有空白項目。

RemoveResponseHeader

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

屬性

• 建構函式

  void

  constructor 函式如下所示：

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

  • arg

    RemoveResponseHeader

  • returns

    RemoveResponseHeader

• 名稱

  字串

  HTTP 要求標頭名稱 (不區分大小寫)。

• 值

  string optional

  HTTP 要求標頭值 (不區分大小寫)。

RequestCookie

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

屬性

• 名稱

  string optional

  Cookie 的名稱。

• 值

  string optional

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

RequestMatcher

依各種標準比對網路事件。

屬性

• 建構函式

  void

  constructor 函式如下所示：

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

  • arg

    RequestMatcher

  • returns

    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 事件。

屬性

• 建構函式

  void

  constructor 函式如下所示：

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

  • arg

    SendMessageToExtension

  • returns

    SendMessageToExtension

• 訊息

  字串

  要傳遞給事件處理常式的字典的 message 屬性中的值。

SetRequestHeader

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

屬性

• 建構函式

  void

  constructor 函式如下所示：

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

  • arg

    SetRequestHeader

  • returns

    SetRequestHeader

• 名稱

  字串

  HTTP 要求標頭名稱。

• 值

  字串

  HTTP 要求標頭值。

Stage

列舉

"onBeforeRequest"

"onBeforeSendHeaders"

"onHeadersReceived"

"onAuthRequired"

活動

onMessage

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

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

參數

• 回呼

  函式

  callback 參數如下所示：

  (details: object) => void

  • 詳細資料

    物件

    • documentId

      string optional

      提出要求的文件的 UUID。

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      文件所在的生命週期。

    • frameId

      數字

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

    • frameType

      extensionTypes.FrameType

      導覽發生的影格類型。

    • 訊息

      字串

      呼叫指令碼傳送的訊息。

    • method

      字串

      標準 HTTP 方法。

    • parentDocumentId

      string optional

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

    • parentFrameId

      數字

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

    • requestId

      字串

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

    • 在此流程的各個階段

      階段

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

    • tabId

      數字

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

    • timeStamp

      數字

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

    • 類型

      webRequest.ResourceType

      要求資源的使用方式。

    • 網址

      字串

onRequest

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

條件

RequestMatcher

動作

AddRequestCookie

AddResponseCookie

AddResponseHeader

CancelRequest

EditRequestCookie

EditResponseCookie

RedirectRequest

RedirectToTransparentImage

RedirectToEmptyDocument

RedirectByRegEx

RemoveRequestCookie

RemoveResponseCookie

RemoveRequestHeader

RemoveResponseHeader

SetRequestHeader

SendMessageToExtension

IgnoreRules