chrome.webRequest

說明

使用 chrome.webRequest API 觀察及分析流量，以及攔截、封鎖或修改傳輸中的要求。

權限

webRequest

資訊清單

您必須在擴充功能資訊清單中宣告 "webRequest" 權限，才能使用網路要求 API，以及必要的主機權限。如要攔截子資源要求， 擴充功能必須同時具有要求網址及其發起者的存取權。例如：

{
  "name": "My extension",
  ...
  "permissions": [
    "webRequest"
  ],
  "host_permissions": [
    "*://*.google.com/*"
  ],
  ...
}

自 Chrome 108 起，如果您使用 "webRequest" 和 "webRequestAuthProvider"，即可透過非同步方式為 onAuthRequired 事件提供憑證 授予其要求的權限。

要求的生命週期

網路要求 API 可定義一組遵循網路要求生命週期的事件。別擔心！您可以使用 以觀察及分析流量某些同步事件可讓您攔截、 封鎖或修改要求

下方為成功要求的事件生命週期，其次是事件定義：

從網路要求 API 的角度來看，網路要求的生命週期

onBeforeRequest (選擇性同步處理)
在即將發生要求時啟動。這個事件會在建立任何 TCP 連線之前傳送，且 用於取消或重新導向要求
onBeforeSendHeaders (選擇性同步處理)
在即將發生且初始標頭已備妥時啟動。事件是 用途是允許擴充功能新增、修改及刪除要求標頭 (*)。 onBeforeSendHeaders 事件會傳給所有訂閱者，因此不同的訂閱者可能會試圖 修改要求；請參閱「導入詳情」一節，瞭解處理方法。這項活動 可用於取消要求。
onSendHeaders
在所有延伸模組都有機會修改要求標頭後啟動，並顯示 (*) 版本。事件會在標頭傳送至網路之前觸發。這個活動是 並以非同步的方式處理
不允許修改或取消要求。
onHeadersReceived (選擇性同步處理)
每次收到 HTTP(S) 回應標頭時啟動。因重新導向和驗證而終止 因應單一請求可能會多次發生這個事件的用途是讓擴充功能 新增、修改和刪除回應標頭，例如傳入的 Content-Type 標頭。快取 指令會在觸發這個事件之前加以處理，因此修改 Cache-Control 等標頭 不會影響瀏覽器的快取。還可讓您取消或重新導向要求。
onAuthRequired (選擇性同步處理)
在要求需要使用者驗證時啟動。這個事件可同步處理 提供驗證憑證請注意，擴充功能可能會提供無效的憑證。敬祝平安 且不會因重複提供無效憑證而進入無限迴圈。這項功能也能用於 取消要求。
onBeforeRedirect
在即將執行重新導向時啟動。重新導向可透過 HTTP 回應觸發 程式碼或擴充功能這是資訊事件，並以非同步方式處理。不允許 修改或取消要求。
onResponseStarted
在收到回應主體的第一個位元組時啟動。對於 HTTP 要求，這表示 可提供狀態行和回應標頭。這是提供資訊與處理的活動 以非同步方式載入物件
不允許修改或取消要求。
onCompleted
在成功處理要求時啟動。
onErrorOccurred
在系統無法成功處理要求時啟動。

網路要求 API 會保證每項要求 (onCompleted 或 onErrorOccurred) 不會 做為最終事件觸發，但有一個例外狀況：如果要求重新導向至 data:// 網址。 「onBeforeRedirect」是上次回報的事件。

*。 請注意，網路要求 API 會向擴充功能提供網路堆疊的抽象化。 在內部，一個網址要求可以拆分成多個 HTTP 要求 (例如， 位元組範圍，通常來自大型檔案)，或可由網路堆疊處理，無需與 更是如此因此，API 不提供傳送至 更是如此舉例來說，擴充功能不會顯示與快取相關的所有標頭。

onBeforeSendHeaders 事件目前未提供下列標頭。這份清單 無法保證一定完整或穩定

  • 授權
  • Cache-Control
  • 連線
  • 內容長度
  • 主機
  • 如果修改日期
  • 如果不相符
  • 如果範圍
  • 部分資料
  • 普拉格瑪文
  • Proxy 授權
  • Proxy 連線
  • Transfer-Encoding

自 Chrome 79 起，要求標頭修改會影響跨來源資源共用 (CORS) 檢查。如果修改的跨來源請求標頭不符合條件，就會導致 傳送 CORS 預檢，詢問伺服器是否可接受這類標頭。如果真的需要 為了違反 CORS 通訊協定而修改標頭，請在'extraHeaders' opt_extraInfoSpec。另一方面，回應標頭的修改無法欺騙 CORS 檢查。如果您需要參照 CORS 通訊協定，則您還必須為相關要求指定 'extraHeaders' 回應修改。

從 Chrome 79 開始，webRequest API 不會攔截 CORS 預檢要求和 回應。系統會向擴充功能顯示要求網址的 CORS 預檢， 已在要求網址的 opt_extraInfoSpec 中指定 'extraHeaders' 的事件監聽器。 onBeforeRequest 也可以從 Chrome 79 取得'extraHeaders'。

自 Chrome 79 版本起，系統不提供下列要求標頭，也無法修改或 已移除，而且未在 opt_extraInfoSpec 中指定 'extraHeaders'：

  • 來源
，瞭解如何調查及移除這項存取權。

從 Chrome 72 版開始，如需在跨來源讀取封鎖前修改回應， (CORB) 可以封鎖回應，您必須在 opt_extraInfoSpec 中指定 'extraHeaders'。

從 Chrome 72 開始，下列要求標頭不提供且無法修改 或在 opt_extraInfoSpec 中未指定 'extraHeaders' 就已移除：

  • 接受語言
  • Accept-Encoding
  • 參照網址
  • Cookie

自 Chrome 72 版本起，系統未提供 Set-Cookie 回應標頭，且無法修改 或在 opt_extraInfoSpec 中未指定 'extraHeaders' 就已移除

從 Chrome 第 89 版開始，無法有效修改 X-Frame-Options 回應標頭 或在 opt_extraInfoSpec 未指定 'extraHeaders' 的情況下移除

webRequest API 只會公開擴充功能有權查看的要求 (透過 主機要求) 權限。此外，只有下列配置可以存取：http://、https://、 ftp://、file://、ws:// (自 Chrome 58 起)、wss:// (自 Chrome 58 起)、urn: (自 Chrome 91 起)，或 chrome-extension://。此外，即使某些要求包含使用上述其中一種配置的網址 隱藏起來。包括非other_extension_id的chrome-extension://other_extension_id 處理要求、https://www.google.com/chrome 和其他機密內容的擴充功能 ID 要求核心功能。此外，來自擴充功能的同步 XMLHttpRequests 也 才會封鎖事件處理常式，以防止死結。請注意 支援的可用事件集可能會因為 對應的通訊協定例如，針對檔案：配置、只有 onBeforeRequest 可能會分派 onResponseStarted、onCompleted 和 onErrorOccurred。

自 Chrome 58 起，webRequest API 支援攔截 WebSocket 握手要求。 由於握手是透過 HTTP 升級要求來完成，因此其流程會配合 HTTP 導向 webRequest 模型中)。請注意，這個 API 不會攔截：

  • 透過已建立的 WebSocket 連線傳送個別訊息。
  • WebSocket 關閉連線。

WebSocket 要求不支援重新導向。

從 Chrome 72 版開始，擴充功能只能攔截含有主機的要求 要求提出的網址和要求發起者

自 Chrome 96 起，webRequest API 支援透過 HTTP/3 攔截 WebTransport 握手要求。由於握手是透過 HTTP CONNECT 要求完成，因此其流程符合 轉換為 HTTP 導向的 webRequest 模型請注意：

  • 建立工作階段後，擴充功能就無法透過 webRequest API)。
  • 在 onBeforeSendHeaders 中修改 HTTP 要求標頭會遭到忽略。
  • 透過 HTTP/3 的 WebTransport 不支援重新導向和驗證。

概念

以下各節說明網路要求 API 中的事件使用要求 ID。您可以 註冊事件接聽程式時，可選擇指定篩選器和額外資訊。

要求 ID

每個要求都有一個要求 ID 可供識別。這個 ID 不得與瀏覽器工作階段中的 有關擴充功能的背景資訊在要求的生命週期內，此常數保持不變，可以使用 以便比對同一個要求的事件請注意，多個 HTTP 要求會對應至一個網路要求 因為 HTTP 重新導向或 HTTP 驗證的情況

註冊事件監聽器

如要為網路要求註冊事件監聽器，請使用一般 addListener() 上的變化版本 函式。除了指定回呼函式之外，您還必須指定篩選器引數，也可以指定選用的額外資訊引數。

網路要求 API addListener() 的三個引數具有下列定義：

var callback = function(details) {...};
var filter = {...};
var opt_extraInfoSpec = [...];

以下是監聽 onBeforeRequest 事件的範例：

chrome.webRequest.onBeforeRequest.addListener(
    callback, filter, opt_extraInfoSpec);

每個 addListener() 呼叫都會使用必要的回呼函式做為第一個參數。這個回呼 函式傳遞的字典含有目前網址要求的相關資訊。 這個字典中的資訊取決於特定的事件類型，以及 opt_extraInfoSpec。

如果選用的 opt_extraInfoSpec 陣列包含 'blocking' 字串 (只有 特定事件)，系統會同步處理回呼函式。也就是說 封鎖，直到回呼函式傳回為止。在這種情況下，回呼可以傳回 webRequest.BlockingResponse，用於決定要求的後續生命週期。視情況而定 而此回應會允許取消或重新導向要求 (onBeforeRequest)， 取消要求或修改標頭 (onBeforeSendHeaders、onHeadersReceived)，以及 取消要求或提供驗證憑證 (onAuthRequired)。

如果選用的 opt_extraInfoSpec 陣列包含 'asyncBlocking' 字串 (只有 允許用於 onAuthRequired)，則擴充功能可以產生 webRequest.BlockingResponse 以非同步方式載入物件

webRequest.RequestFilter filter 可限制哪些要求來自能事件 在不同維度觸發的

網址
網址模式，例如 *://www.google.com/foo*bar。
類型
要求類型，例如 main_frame (為頂層頁框載入的文件)、sub_frame ( 已載入嵌入頁框的文件) 和 image (網站上的圖片)。詳情請見 webRequest.RequestFilter。
分頁 ID
分頁 ID。
視窗 ID
視窗的 ID。

視事件類型而定，您可以在 opt_extraInfoSpec 中指定字串，以要求額外的 關於要求的相關資訊只會用於提供要求資料的詳細資訊 允許系統明確要求

實作詳情

開發使用 網路要求 API：

web_accessible_resources

如果擴充功能使用 webRequest API 將公開資源要求重新導向至無法透過網路存取的資源，則系統會封鎖該擴充功能並導致錯誤。即使重新導向擴充功能擁有的網頁無法存取資源，上述機制仍適用。如要宣告用於宣告式 WebRequest API 的資源，您必須依這裡在資訊清單中宣告 "web_accessible_resources" 陣列並填入。

衝突解決

在目前的網路要求 API 實作中，如果 至少有一個擴充功能指示取消要求。如果擴充功能取消要求， 擴充功能會透過 onErrorOccurred 事件收到通知。只有一個擴充功能能將 一次要求或修改標頭如果有多個擴充功能嘗試修改要求， 系統會優先採用最近安裝的擴充功能，並忽略所有其他擴充功能。如果發生以下情況，擴充功能不會通知任何擴充功能： 並忽略了修改或重新導向的指示。

快取

Chrome 採用兩種快取技術，分別是磁碟上的快取，以及非常快速的記憶體內快取。YouTube 音樂的生命週期 記憶體內快取屬於轉譯程序的生命週期，大致相當於一個分頁。 網路要求 API 無法查看記憶體內快取回應的要求。如果 要求處理常式會變更其行為 (例如根據 封鎖)，就算只是重新整理網頁，也可能不會遵循這項變更行為。為確保行為 變更後，請呼叫 handlerBehaviorChanged() 來清除記憶體內快取。但切勿嘗試 經常；清除快取是一項成本高昂的作業您不需要撥打電話 註冊或取消註冊事件監聽器後，為 handlerBehaviorChanged()。

時間戳記

網路要求事件的 timestamp 屬性只能確保「內部」一致。 比較一個事件與另一個事件可為您提供正確的偏移量，不過在比較 然後才變成擴充功能中目前的時間 (例如透過 (new Date()).getTime()) 會產生非預期的結果

處理錯誤

如果您嘗試註冊事件時使用了無效引數，系統會擲回 JavaScript 錯誤，且 事件處理常式不會註冊。如果系統在處理事件或 事件處理常式傳回無效的封鎖回應，那麼擴充功能的 ，系統就會忽略該要求的處理常式。

範例

以下範例說明如何封鎖所有對 www.evil.com 的要求：

chrome.webRequest.onBeforeRequest.addListener(
  function(details) {
    return {cancel: details.url.indexOf("://www.evil.com/") != -1};
  },
  {urls: ["<all_urls>"]},
  ["blocking"]
);

由於這個函式使用封鎖事件處理常式，因此需要 "webRequest" 和 "webRequestBlocking" 權限。

以下範例能以更有效率的方式達成同一目標，因為請求 指定至 www.evil.com 不需要傳遞至擴充功能：

chrome.webRequest.onBeforeRequest.addListener(
  function(details) { return {cancel: true}; },
  {urls: ["*://www.evil.com/*"]},
  ["blocking"]
);

以下範例說明如何從所有要求中刪除 User-Agent 標頭：

chrome.webRequest.onBeforeSendHeaders.addListener(
  function(details) {
    for (var i = 0; i < details.requestHeaders.length; ++i) {
      if (details.requestHeaders[i].name === 'User-Agent') {
        details.requestHeaders.splice(i, 1);
        break;
      }
    }
    return {requestHeaders: details.requestHeaders};
  },
  {urls: ["<all_urls>"]},
  ["blocking", "requestHeaders"]
);

如要試用 chrome.webRequest API， 安裝 chrome-extension-samples 中的 webRequest 範例 Cloud Storage 也提供目錄同步處理功能

類型

BlockingResponse

傳回具有「blocking」的事件處理常式值已套用 extraInfoSpec。允許事件處理常式修改網路要求。

屬性

  • authCredentials

    物件 optional

    只做為對 onAuthRequired 事件的回應。一旦設定，要求就會使用提供的憑證提出。

    • 密碼

      字串

    • 使用者名稱

      字串

  • 取消

    布林值 選填

    如果為 true，系統會取消要求。這樣可以避免傳送要求。這可做為對 onBeforeRequest、onBeforeSendHeaders、onHeadersReceived 和 onAuthRequired 事件的回應。

  • redirectUrl

    string optional

    只能做為回應 onBeforeRequest 和 onHeadersReceived 事件的回應。如果設定此屬性，原始要求就不會傳送/完成，而會重新導向至指定網址。允許前往 data: 等非 HTTP 配置。重新導向動作發起的重新導向會使用原始要求方法來進行重新導向，但有一個例外：如果重新導向是在 onHeadersReceived 階段啟動，則系統會使用 GET 方法發出重新導向。系統會忽略來自具有 ws:// 和 wss:// 配置的網址重新導向。

  • requestHeaders

    HttpHeaders 選用

    只能做為對 onBeforeSendHeaders 事件的回應。如果已設定，系統會改用這些要求標頭發出要求。

  • responseHeaders

    HttpHeaders 選用

    只做為回應 onHeadersReceived 事件的回應。如果已設定，系統會假設伺服器已改為回應這些回應標頭。只有在您想要修改標頭，以限制衝突次數時，才傳回 responseHeaders (每次要求只能有一個擴充功能修改 responseHeaders)。

FormDataItem

Chrome 66 以上版本

包含表單資料內傳送的資料。若是 url 編碼，如果資料是 utf-8 字串，則會儲存為字串，反之則會儲存為 ArrayBuffer。對表單資料而言，則為 ArrayBuffer。如果 form-data 代表上傳檔案，則該字串由檔案名稱字串 (如有提供) 提供。

列舉

ArrayBuffer

字串

HttpHeaders

HTTP 標頭陣列。每個標頭都會表示為包含 name 和 value 或 binaryValue 鍵的字典。

類型

object[]

屬性

  • binaryValue

    number[] 選填

    如果 HTTP 標頭無法以 UTF-8 表示，會以個別位元組值 (0..255) 表示。

  • 名稱

    字串

    HTTP 標頭的名稱。

  • 值

    string optional

    HTTP 標頭的值 (如果可用 UTF-8 表示)。

IgnoredActionType

Chrome 70 以上版本

列舉

"redirect"

"request_headers"

&quot;response_headers&quot;

&quot;auth_credentials&quot;

OnAuthRequiredOptions

Chrome 44 以上版本

列舉

&quot;responseHeaders&quot;
指定回應標頭應包含在事件中。

"blocking"
指定要求遭到封鎖，直到回呼函式傳回為止。

&quot;asyncBlocking&quot;
指定系統以非同步方式處理回呼函式。

"extraHeaders"
指出標頭可能違反跨來源資源分享 (CORS)。

OnBeforeRedirectOptions

Chrome 44 以上版本

列舉

&quot;responseHeaders&quot;
指定回應標頭應包含在事件中。

"extraHeaders"
指出標頭可能違反跨來源資源分享 (CORS)。

OnBeforeRequestOptions

Chrome 44 以上版本

列舉

"blocking"
指定要求遭到封鎖，直到回呼函式傳回為止。

&quot;requestBody&quot;
表示要求主體應包含在事件中。

"extraHeaders"
指出標頭可能違反跨來源資源分享 (CORS)。

OnBeforeSendHeadersOptions

Chrome 44 以上版本

列舉

&quot;requestHeaders&quot;
指定要求標頭應包含在活動中。

"blocking"
指定要求遭到封鎖，直到回呼函式傳回為止。

"extraHeaders"
指出標頭可能違反跨來源資源分享 (CORS)。

OnCompletedOptions

Chrome 44 以上版本

列舉

&quot;responseHeaders&quot;
指定回應標頭應包含在事件中。

"extraHeaders"
指出標頭可能違反跨來源資源分享 (CORS)。

OnErrorOccurredOptions

Chrome 79 以上版本

值

"extraHeaders"

OnHeadersReceivedOptions

Chrome 44 以上版本

列舉

"blocking"
指定要求遭到封鎖，直到回呼函式傳回為止。

&quot;responseHeaders&quot;
指定回應標頭應包含在事件中。

"extraHeaders"
指出標頭可能違反跨來源資源分享 (CORS)。

OnResponseStartedOptions

Chrome 44 以上版本

列舉

&quot;responseHeaders&quot;
指定回應標頭應包含在事件中。

"extraHeaders"
指出標頭可能違反跨來源資源分享 (CORS)。

OnSendHeadersOptions

Chrome 44 以上版本

列舉

&quot;requestHeaders&quot;
指定要求標頭應包含在活動中。

"extraHeaders"
指出標頭可能違反跨來源資源分享 (CORS)。

RequestFilter

這個物件會說明要套用至 webRequest 事件的篩選器。

屬性

  • tabId

    編號 選填

  • 類型

    ResourceType[] 選用

    要求類型的清單。系統會篩除無法與任何類型相符的請求。

  • 網址

    string[]

    網址或網址模式清單。系統會篩除與任何網址都不相符的要求。

  • windowId

    編號 選填

ResourceType

Chrome 44 以上版本

列舉

"main_frame"
將資源指定為主要頁框。

"sub_frame"
將資源指定為子頁框。

"stylesheet"
將資源指定為樣式表。

&quot;script&quot;
將資源指定為指令碼。

"image"
將資源指定為圖片。

"font"
將資源指定為字型。

"object"
將資源指定為物件。

&quot;xmlhttprequest&quot;
將資源指定為 XMLHttpRequest。

"ping"
將資源指定為連線偵測 (ping)。

&quot;csp_report&quot;
將資源指定為內容安全政策 (CSP) 報告。

"media"
將資源指定為媒體物件。

"websocket"
將資源指定為 WebSocket。

"webbundle"
將資源指定為 WebBundle。

"other"
將資源指定為未包含在所列類型中的類型。

UploadData

包含透過網址要求上傳的資料。

屬性

  • 位元組

    任何選用

    含有資料副本的 ArrayBuffer。

  • 檔案

    string optional

    含有檔案路徑和名稱的字串。

屬性

MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES

每 10 分鐘持續間隔可呼叫 handlerBehaviorChanged 的次數上限。handlerBehaviorChanged 是不應經常呼叫的昂貴函式呼叫。

值

20

方法

handlerBehaviorChanged()

Promise 
chrome.webRequest.handlerBehaviorChanged(
  callback?: function,
)

當 webRequest 處理常式的行為變更時，需呼叫此項目，以防止快取因快取而不正確的處理。這個函式呼叫所費不貲。不要常常稱呼它。

參數

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 116 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

活動

onActionIgnored

Chrome 70 以上版本 
chrome.webRequest.onActionIgnored.addListener(
  callback: function,
)

忽略擴充功能對網路要求的提議修改時觸發。以免與其他擴充功能發生衝突時。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (details: object) => void

    • 詳細資料

      物件

      • 已忽略的建議動作。

      • requestId

        字串

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

onAuthRequired

chrome.webRequest.onAuthRequired.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnAuthRequiredOptions[],
)

收到驗證失敗時觸發。事件監聽器提供三個選項：提供驗證憑證、可以取消要求並顯示錯誤頁面，或者針對驗證未採取任何行動。如果提供的使用者憑證無效，系統可能會針對同一個要求多次呼叫此方法。請注意，只有在 extraInfoSpec 參數中只能指定 'blocking' 或 'asyncBlocking' 的其中一種模式。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (details: object, asyncCallback?: function) => BlockingResponse | undefined

    • 詳細資料

      物件

      • 挑戰者

        物件

        要求驗證的伺服器。

        • 主機

          字串

        • 通訊埠

          數字

      • documentId

        字串

        Chrome 106 以上版本

        提出要求的文件的 UUID。

      • Chrome 106 以上版本

        文件所在的生命週期。

      • frameId

        數字

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

      • Chrome 106 以上版本

        要求發生的影格類型。

      • 發起者

        string optional

        Chrome 63 以上版本

        發出要求的來源。這不會因為重新導向而改變。如果來源不透明，字串「null」

      • isProxy

        布林值

        「Proxy-Authenticate」為「true」，WWW-Authenticate 則為「false」。

      • method

        字串

        標準 HTTP 方法。

      • parentDocumentId

        string optional

        Chrome 106 以上版本

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

      • parentFrameId

        數字

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

      • 領域

        string optional

        伺服器提供的驗證領域 (如果有的話)。

      • requestId

        字串

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

      • responseHeaders

        HttpHeaders 選用

        與這個回應一起收到的 HTTP 回應標頭。

      • 架構

        字串

        驗證配置，例如「基本」或「摘要」。

      • statusCode

        數字

        Chrome 43 以上版本

        伺服器傳回的標準 HTTP 狀態碼。

      • statusLine

        字串

        回應的 HTTP 狀態行或「HTTP/0.9 200 OK」HTTP/0.9 回應的字串 (也就是沒有狀態行的回應)，如果沒有標頭，則為空白字串。

      • tabId

        數字

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

      • timeStamp

        數字

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

      • 類型

        ResourceType

        要求資源的使用方式。

      • 網址

        字串

    • asyncCallback

      函式 選用

      Chrome 58 以上版本

      asyncCallback 參數如下所示： 

      (response: BlockingResponse) => void

    • returns

      BlockingResponse |未定義

      如果「封鎖」參數，事件監聽器應會傳回此類型的物件。

  • 篩選器

    RequestFilter

  • extraInfoSpec

    OnAuthRequiredOptions[] 選用

onBeforeRedirect

chrome.webRequest.onBeforeRedirect.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnBeforeRedirectOptions[],
)

在即將發生伺服器啟動的重新導向時觸發。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (details: object) => void

    • 詳細資料

      物件

      • documentId

        字串

        Chrome 106 以上版本

        提出要求的文件的 UUID。

      • Chrome 106 以上版本

        文件所在的生命週期。

      • frameId

        數字

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

      • Chrome 106 以上版本

        要求發生的影格類型。

      • fromCache

        布林值

        指出這個回應是擷取自磁碟快取。

      • 發起者

        string optional

        Chrome 63 以上版本

        發出要求的來源。這不會因為重新導向而改變。如果來源不透明，字串「null」

      • ip

        string optional

        要求實際接收的伺服器 IP 位址。請注意，該位址可能是常值 IPv6 位址。

      • method

        字串

        標準 HTTP 方法。

      • parentDocumentId

        string optional

        Chrome 106 以上版本

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

      • parentFrameId

        數字

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

      • redirectUrl

        字串

        新網址

      • requestId

        字串

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

      • responseHeaders

        HttpHeaders 選用

        與這個重新導向一起收到的 HTTP 回應標頭。

      • statusCode

        數字

        伺服器傳回的標準 HTTP 狀態碼。

      • statusLine

        字串

        回應的 HTTP 狀態行或「HTTP/0.9 200 OK」HTTP/0.9 回應的字串 (也就是沒有狀態行的回應)，如果沒有標頭，則為空白字串。

      • tabId

        數字

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

      • timeStamp

        數字

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

      • 類型

        ResourceType

        要求資源的使用方式。

      • 網址

        字串

  • 篩選器

    RequestFilter

  • extraInfoSpec

    OnBeforeRedirectOptions[] 選用

onBeforeRequest

chrome.webRequest.onBeforeRequest.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnBeforeRequestOptions[],
)

在即將發生要求時觸發。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (details: object) => BlockingResponse | undefined

    • 詳細資料

      物件

      • documentId

        string optional

        Chrome 106 以上版本

        提出要求的文件的 UUID。

      • documentLifecycle

        extensionTypes.DocumentLifecycle optional

        Chrome 106 以上版本

        文件所在的生命週期。

      • frameId

        數字

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

      • frameType

        extensionTypes.FrameType optional

        Chrome 106 以上版本

        要求發生的影格類型。

      • 發起者

        string optional

        Chrome 63 以上版本

        發出要求的來源。這不會因為重新導向而改變。如果來源不透明，字串「null」

      • method

        字串

        標準 HTTP 方法。

      • parentDocumentId

        string optional

        Chrome 106 以上版本

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

      • parentFrameId

        數字

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

      • requestBody

        物件 optional

        包含 HTTP 要求主體資料。只有在 extraInfoSpec 包含「requestBody」時才會提供。

        • 錯誤

          string optional

          取得要求主體資料時發生錯誤。

        • formData

          物件 optional

          如果要求方法為 POST，且主體是一連串以 UTF8 編碼、編碼為 multipart/form-data 或 application/x-www-form-url 編碼的鍵/值組合，則這個字典會顯示，且每個鍵都包含該鍵的所有值清單。如果資料是其他媒體類型，或格式錯誤，系統就不會顯示字典。此字典的範例值為 {'key': ['value1', 'value2']}。

        • 原始

          UploadData[] 選用

          如果要求方法為 PUT 或 POST，且 formData 中尚未剖析主體，則未剖析的要求主體元素會包含在這個陣列中。

      • requestId

        字串

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

      • tabId

        數字

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

      • timeStamp

        數字

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

      • 類型

        ResourceType

        要求資源的使用方式。

      • 網址

        字串

    • returns

      BlockingResponse |未定義

      如果「封鎖」參數，事件監聽器應會傳回此類型的物件。

  • 篩選器

    RequestFilter

  • extraInfoSpec

    OnBeforeRequestOptions[] 選用

onBeforeSendHeaders

chrome.webRequest.onBeforeSendHeaders.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnBeforeSendHeadersOptions[],
)

有要求標頭可用時，會在傳送 HTTP 要求前觸發。這種情況可能會在系統傳送 TCP 連線至伺服器後、傳送任何 HTTP 資料之前發生。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (details: object) => BlockingResponse | undefined

    • 詳細資料

      物件

      • documentId

        字串

        Chrome 106 以上版本

        提出要求的文件的 UUID。

      • Chrome 106 以上版本

        文件所在的生命週期。

      • frameId

        數字

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

      • Chrome 106 以上版本

        要求發生的影格類型。

      • 發起者

        string optional

        Chrome 63 以上版本

        發出要求的來源。這不會因為重新導向而改變。如果來源不透明，字串「null」

      • method

        字串

        標準 HTTP 方法。

      • parentDocumentId

        string optional

        Chrome 106 以上版本

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

      • parentFrameId

        數字

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

      • requestHeaders

        HttpHeaders 選用

        與此要求一起送出的 HTTP 要求標頭。

      • requestId

        字串

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

      • tabId

        數字

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

      • timeStamp

        數字

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

      • 類型

        ResourceType

        要求資源的使用方式。

      • 網址

        字串

    • returns

      BlockingResponse |未定義

      如果「封鎖」參數，事件監聽器應會傳回此類型的物件。

  • 篩選器

    RequestFilter

  • extraInfoSpec

    OnBeforeSendHeadersOptions[] 選用

onCompleted

chrome.webRequest.onCompleted.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnCompletedOptions[],
)

要求完成時觸發。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (details: object) => void

    • 詳細資料

      物件

      • documentId

        字串

        Chrome 106 以上版本

        提出要求的文件的 UUID。

      • Chrome 106 以上版本

        文件所在的生命週期。

      • frameId

        數字

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

      • Chrome 106 以上版本

        要求發生的影格類型。

      • fromCache

        布林值

        指出這個回應是擷取自磁碟快取。

      • 發起者

        string optional

        Chrome 63 以上版本

        發出要求的來源。這不會因為重新導向而改變。如果來源不透明，字串「null」

      • ip

        string optional

        要求實際接收的伺服器 IP 位址。請注意，該位址可能是常值 IPv6 位址。

      • method

        字串

        標準 HTTP 方法。

      • parentDocumentId

        string optional

        Chrome 106 以上版本

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

      • parentFrameId

        數字

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

      • requestId

        字串

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

      • responseHeaders

        HttpHeaders 選用

        與這個回應一起收到的 HTTP 回應標頭。

      • statusCode

        數字

        伺服器傳回的標準 HTTP 狀態碼。

      • statusLine

        字串

        回應的 HTTP 狀態行或「HTTP/0.9 200 OK」HTTP/0.9 回應的字串 (也就是沒有狀態行的回應)，如果沒有標頭，則為空白字串。

      • tabId

        數字

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

      • timeStamp

        數字

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

      • 類型

        ResourceType

        要求資源的使用方式。

      • 網址

        字串

  • 篩選器

    RequestFilter

  • extraInfoSpec

    OnCompletedOptions[] 選用

onErrorOccurred

chrome.webRequest.onErrorOccurred.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnErrorOccurredOptions[],
)

發生錯誤時觸發。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (details: object) => void

    • 詳細資料

      物件

      • documentId

        字串

        Chrome 106 以上版本

        提出要求的文件的 UUID。如果要求是影格導覽，則不會顯示這個值。

      • Chrome 106 以上版本

        文件所在的生命週期。

      • 錯誤

        字串

        錯誤說明。這個字串「不保證」能在各版本之間保有回溯相容性。您不得剖析及根據其內容採取行動。

      • frameId

        數字

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

      • Chrome 106 以上版本

        要求發生的影格類型。

      • fromCache

        布林值

        指出這個回應是擷取自磁碟快取。

      • 發起者

        string optional

        Chrome 63 以上版本

        發出要求的來源。這不會因為重新導向而改變。如果來源不透明，字串「null」

      • ip

        string optional

        要求實際接收的伺服器 IP 位址。請注意，該位址可能是常值 IPv6 位址。

      • method

        字串

        標準 HTTP 方法。

      • parentDocumentId

        string optional

        Chrome 106 以上版本

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

      • parentFrameId

        數字

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

      • requestId

        字串

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

      • tabId

        數字

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

      • timeStamp

        數字

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

      • 類型

        ResourceType

        要求資源的使用方式。

      • 網址

        字串

  • 篩選器

    RequestFilter

  • extraInfoSpec

    OnErrorOccurredOptions[] 選用

onHeadersReceived

chrome.webRequest.onHeadersReceived.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnHeadersReceivedOptions[],
)

收到要求的 HTTP 回應標頭時觸發。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (details: object) => BlockingResponse | undefined

    • 詳細資料

      物件

      • documentId

        字串

        Chrome 106 以上版本

        提出要求的文件的 UUID。

      • Chrome 106 以上版本

        文件所在的生命週期。

      • frameId

        數字

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

      • Chrome 106 以上版本

        要求發生的影格類型。

      • 發起者

        string optional

        Chrome 63 以上版本

        發出要求的來源。這不會因為重新導向而改變。如果來源不透明，字串「null」

      • method

        字串

        標準 HTTP 方法。

      • parentDocumentId

        string optional

        Chrome 106 以上版本

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

      • parentFrameId

        數字

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

      • requestId

        字串

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

      • responseHeaders

        HttpHeaders 選用

        隨此回應收到的 HTTP 回應標頭。

      • statusCode

        數字

        Chrome 43 以上版本

        伺服器傳回的標準 HTTP 狀態碼。

      • statusLine

        字串

        回應的 HTTP 狀態行或「HTTP/0.9 200 OK」HTTP/0.9 回應的字串 (亦即沒有狀態行的回應)。

      • tabId

        數字

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

      • timeStamp

        數字

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

      • 類型

        ResourceType

        要求資源的使用方式。

      • 網址

        字串

    • returns

      BlockingResponse |未定義

      如果「封鎖」參數，事件監聽器應會傳回此類型的物件。

  • 篩選器

    RequestFilter

  • extraInfoSpec

    OnHeadersReceivedOptions[] 選用

onResponseStarted

chrome.webRequest.onResponseStarted.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnResponseStartedOptions[],
)

收到回應主體的第一個位元組時觸發。如果是 HTTP 要求，這表示狀態行和回應標頭可供使用。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (details: object) => void

    • 詳細資料

      物件

      • documentId

        字串

        Chrome 106 以上版本

        提出要求的文件的 UUID。

      • Chrome 106 以上版本

        文件所在的生命週期。

      • frameId

        數字

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

      • Chrome 106 以上版本

        要求發生的影格類型。

      • fromCache

        布林值

        指出這個回應是擷取自磁碟快取。

      • 發起者

        string optional

        Chrome 63 以上版本

        發出要求的來源。這不會因為重新導向而改變。如果來源不透明，字串「null」

      • ip

        string optional

        要求實際接收的伺服器 IP 位址。請注意，該位址可能是常值 IPv6 位址。

      • method

        字串

        標準 HTTP 方法。

      • parentDocumentId

        string optional

        Chrome 106 以上版本

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

      • parentFrameId

        數字

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

      • requestId

        字串

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

      • responseHeaders

        HttpHeaders 選用

        與這個回應一起收到的 HTTP 回應標頭。

      • statusCode

        數字

        伺服器傳回的標準 HTTP 狀態碼。

      • statusLine

        字串

        回應的 HTTP 狀態行或「HTTP/0.9 200 OK」HTTP/0.9 回應的字串 (也就是沒有狀態行的回應)，如果沒有標頭，則為空白字串。

      • tabId

        數字

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

      • timeStamp

        數字

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

      • 類型

        ResourceType

        要求資源的使用方式。

      • 網址

        字串

  • 篩選器

    RequestFilter

  • extraInfoSpec

    OnResponseStartedOptions[] optional

onSendHeaders

chrome.webRequest.onSendHeaders.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnSendHeadersOptions[],
)

在要求傳送至伺服器之前就觸發 (在啟動 onSendHeaders 時可看到先前 onBeforeSendHeaders 回呼的修改)。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (details: object) => void

    • 詳細資料

      物件

      • documentId

        字串

        Chrome 106 以上版本

        提出要求的文件的 UUID。

      • Chrome 106 以上版本

        文件所在的生命週期。

      • frameId

        數字

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

      • Chrome 106 以上版本

        要求發生的影格類型。

      • 發起者

        string optional

        Chrome 63 以上版本

        發出要求的來源。這不會因為重新導向而改變。如果來源不透明，字串「null」

      • method

        字串

        標準 HTTP 方法。

      • parentDocumentId

        string optional

        Chrome 106 以上版本

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

      • parentFrameId

        數字

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

      • requestHeaders

        HttpHeaders 選用

        與此要求一起送出的 HTTP 要求標頭。

      • requestId

        字串

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

      • tabId

        數字

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

      • timeStamp

        數字

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

      • 類型

        ResourceType

        要求資源的使用方式。

      • 網址

        字串

  • 篩選器

    RequestFilter

  • extraInfoSpec

    OnSendHeadersOptions[] 選用