chrome.webRequest

Mô tả

Dùng API chrome.webRequest để quan sát và phân tích lưu lượng truy cập cũng như để chặn, chặn hoặc sửa đổi các yêu cầu đang diễn ra.

Quyền

webRequest

Tệp kê khai

Bạn phải khai báo quyền "webRequest" trong tệp kê khai tiện ích để sử dụng yêu cầu web API, cùng với các quyền cần thiết của máy chủ lưu trữ. Để chặn một yêu cầu về tài nguyên phụ, tiện ích phải có quyền truy cập vào cả URL được yêu cầu và trình khởi tạo của URL đó. Ví dụ:

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

Kể từ Chrome 108, bạn có thể cung cấp thông tin đăng nhập không đồng bộ cho các sự kiện onAuthRequired nếu sử dụng "webRequest" và "webRequestAuthProvider" quyền truy cập.

Vòng đời của yêu cầu

API yêu cầu web xác định một nhóm sự kiện tuân theo vòng đời của một yêu cầu web. Bạn có thể sử dụng những sự kiện này để quan sát và phân tích lưu lượng truy cập. Một số sự kiện đồng bộ nhất định sẽ cho phép bạn chặn, chặn hoặc sửa đổi yêu cầu.

Vòng đời sự kiện của các yêu cầu thành công được minh hoạ ở đây, tiếp theo là các định nghĩa về sự kiện:

Vòng đời của một yêu cầu web từ góc độ API yêu cầu web

onBeforeRequest (không bắt buộc đồng bộ)
Kích hoạt khi có một yêu cầu sắp được thực hiện. Sự kiện này được gửi trước khi thực hiện bất kỳ kết nối TCP nào và có thể để huỷ hoặc chuyển hướng yêu cầu.
onBeforeSendHeaders (không bắt buộc đồng bộ)
Kích hoạt khi một yêu cầu sắp xảy ra và các tiêu đề ban đầu đã được chuẩn bị. Sự kiện là nhằm cho phép tiện ích thêm, sửa đổi và xoá tiêu đề của yêu cầu (*). Chiến lược phát hành đĩa đơn Sự kiện onBeforeSendHeaders được chuyển đến tất cả người đăng ký, vì vậy, những người đăng ký khác nhau có thể tìm cách sửa đổi yêu cầu; hãy xem phần Thông tin triển khai để biết cách xử lý vấn đề này. Sự kiện này có thể dùng để huỷ yêu cầu.
onSendHeaders
Kích hoạt sau khi tất cả các tiện ích đều đã có cơ hội sửa đổi tiêu đề của yêu cầu và hiển thị kết quả cuối cùng Phiên bản (*). Sự kiện này được kích hoạt trước khi tiêu đề được gửi đến mạng. Sự kiện này là cung cấp nhiều thông tin và được xử lý một cách không đồng bộ. Không cho phép sửa đổi hoặc huỷ yêu cầu.
onHeadersReceived (không bắt buộc đồng bộ)
Kích hoạt mỗi khi nhận được tiêu đề phản hồi HTTP(S). Do các lệnh chuyển hướng và quy trình xác thực yêu cầu này có thể xảy ra nhiều lần cho mỗi yêu cầu. Sự kiện này nhằm cho phép các tiện ích thêm, sửa đổi và xoá tiêu đề phản hồi, chẳng hạn như tiêu đề Content-Type đến. Việc lưu vào bộ nhớ đệm sẽ được xử lý trước khi sự kiện này được kích hoạt, vì vậy, hãy sửa đổi tiêu đề, chẳng hạn như Cache-Control (Kiểm soát bộ nhớ đệm) không ảnh hưởng đến bộ nhớ đệm của trình duyệt. Thao tác này cũng cho phép bạn huỷ hoặc chuyển hướng yêu cầu.
onAuthRequired (không bắt buộc đồng bộ)
Kích hoạt khi một yêu cầu đòi hỏi người dùng phải xác thực. Bạn có thể xử lý đồng bộ sự kiện này để cung cấp thông tin xác thực. Xin lưu ý rằng các tiện ích có thể cung cấp thông tin đăng nhập không hợp lệ. Trân trọng! không đi vào một vòng lặp vô hạn bằng cách liên tục cung cấp thông tin xác thực không hợp lệ. Thông tin này cũng có thể được dùng để hãy huỷ yêu cầu đó.
onBeforeRedirect
Kích hoạt khi lệnh chuyển hướng sắp được thực thi. Phản hồi HTTP có thể kích hoạt lệnh chuyển hướng hoặc bởi một tiện ích. Sự kiện này chỉ nhằm cung cấp thông tin và được xử lý không đồng bộ. Không cho phép bạn sửa đổi hoặc huỷ yêu cầu đó.
onResponseStarted
Kích hoạt khi nhận được byte đầu tiên của nội dung phản hồi. Đối với các yêu cầu HTTP, điều này có nghĩa là dòng trạng thái và tiêu đề phản hồi đều có sẵn. Sự kiện này nhằm cung cấp thông tin và đã được xử lý một cách không đồng bộ. Hành động này không cho phép sửa đổi hoặc huỷ yêu cầu.
onCompleted
Kích hoạt khi một yêu cầu đã được xử lý thành công.
onErrorOccurred
Kích hoạt khi không thể xử lý thành công yêu cầu.

API yêu cầu web đảm bảo rằng đối với mỗi yêu cầu, onCompleted hoặc onErrorOccurred kích hoạt dưới dạng sự kiện cuối cùng với một ngoại lệ: Nếu yêu cầu được chuyển hướng đến URL data://, onBeforeRedirect là sự kiện được báo cáo gần đây nhất.

* Lưu ý rằng API yêu cầu web trình bày bản tóm tắt của ngăn xếp mạng cho tiện ích. Trong nội bộ, một yêu cầu URL có thể được chia thành nhiều yêu cầu HTTP (ví dụ: để tìm nạp từng yêu cầu HTTP) phạm vi byte từ một tệp lớn) hoặc có thể được ngăn xếp mạng xử lý mà không cần giao tiếp với mạng. Vì lý do này, API không cung cấp tiêu đề HTTP cuối cùng được gửi đến mạng. Ví dụ: tiện ích sẽ không nhìn thấy tất cả các tiêu đề liên quan đến việc lưu vào bộ nhớ đệm.

Các tiêu đề sau đây hiện chưa được cung cấp cho sự kiện onBeforeSendHeaders. Danh sách này không được đảm bảo là hoàn chỉnh hoặc ổn định.

  • Ủy quyền
  • Kiểm soát bộ nhớ đệm
  • Kết nối
  • Thời lượng nội dung
  • Máy chủ
  • Nếu được sửa đổi từ
  • Nếu-Không-Khớp
  • Nếu phạm vi
  • Một phần dữ liệu
  • Tiếng Pragma
  • Cấp quyền proxy
  • Kết nối proxy
  • Transfer-Encoding

Kể từ Chrome 79, việc sửa đổi tiêu đề của yêu cầu sẽ ảnh hưởng đến tính năng Chia sẻ tài nguyên trên nhiều nguồn gốc (CORS) kiểm tra. Nếu tiêu đề được sửa đổi cho các yêu cầu từ nhiều nguồn không đáp ứng tiêu chí, thì điều này sẽ dẫn đến việc gửi yêu cầu kiểm tra CORS để hỏi máy chủ xem có thể chấp nhận các tiêu đề như vậy hay không. Nếu bạn thực sự cần sửa đổi tiêu đề theo cách vi phạm giao thức CORS, bạn cần chỉ định 'extraHeaders' trong opt_extraInfoSpec Mặt khác, việc sửa đổi tiêu đề phản hồi không hoạt động để đánh lừa CORS kiểm tra. Nếu cần đánh lừa giao thức CORS, bạn cũng cần chỉ định 'extraHeaders' cho thuộc tính nội dung sửa đổi phản hồi.

Kể từ Chrome 79, API webRequest không chặn các yêu cầu kiểm tra CORS và phản hồi theo mặc định. Quy trình kiểm tra CORS cho URL yêu cầu sẽ hiển thị với tiện ích nếu có trình nghe có 'extraHeaders' được chỉ định trong opt_extraInfoSpec cho URL yêu cầu. onBeforeRequest cũng có thể lấy 'extraHeaders' từ Chrome 79.

Kể từ Chrome 79, tiêu đề yêu cầu sau đây không được cung cấp và không thể sửa đổi hoặc bị xóa mà không chỉ định 'extraHeaders' trong opt_extraInfoSpec:

  • Điểm gốc

Kể từ Chrome 72, nếu bạn cần sửa đổi câu trả lời trước khi tính năng Chặn đọc trên nhiều nguồn gốc (CORB) có thể chặn phản hồi, bạn cần chỉ định 'extraHeaders' trong opt_extraInfoSpec.

Kể từ Chrome 72, các tiêu đề của yêu cầu sau đây không được cung cấp và không thể sửa đổi hoặc bị xoá mà không chỉ định 'extraHeaders' trong opt_extraInfoSpec:

  • Ngôn ngữ chấp nhận
  • Accept-Encoding
  • Giới thiệu
  • Cookie

Kể từ Chrome 72, tiêu đề phản hồi Set-Cookie chưa được cung cấp và không thể sửa đổi hoặc bị xoá mà không chỉ định 'extraHeaders' trong opt_extraInfoSpec.

Kể từ Chrome 89, bạn sẽ không thể sửa đổi tiêu đề phản hồi X-Frame-Options một cách hiệu quả hoặc bị xoá mà không chỉ định 'extraHeaders' trong opt_extraInfoSpec.

API webRequest chỉ đưa ra các yêu cầu mà tiện ích có quyền xem, dựa trên máy chủ lưu trữ quyền truy cập. Ngoài ra, chỉ các giao thức sau đây có thể truy cập được: http://, https://, ftp://, file://, ws:// (kể từ Chrome 58), wss:// (kể từ Chrome 58), urn: (kể từ Chrome 91) hoặc chrome-extension://. Ngoài ra, ngay cả một số yêu cầu nhất định với URL sử dụng một trong các giao thức nêu trên bị ẩn. Các đối tượng này bao gồm chrome-extension://other_extension_id, trong đó other_extension_id thì không mã nhận dạng tiện ích để xử lý yêu cầu, https://www.google.com/chrome và các thông tin nhạy cảm khác yêu cầu chức năng cốt lõi của trình duyệt. Ngoài ra, XMLHttpRequests đồng bộ từ tiện ích của bạn là ẩn khỏi việc chặn các trình xử lý sự kiện nhằm ngăn chặn tắc nghẽn. Xin lưu ý rằng với một số tập hợp các sự kiện có sẵn có thể bị giới hạn do bản chất của giao thức tương ứng. Ví dụ: đối với tệp: schema, chỉ có onBeforeRequest, onResponseStarted, onCompleted và onErrorOccurred có thể được gửi đi.

Kể từ Chrome 58, API webRequest hỗ trợ việc chặn yêu cầu bắt tay WebSocket. Vì quá trình bắt tay được thực hiện thông qua yêu cầu nâng cấp HTTP, nên quy trình bắt tay này phù hợp với yêu cầu hướng HTTP webRequest. Lưu ý rằng API không chặn:

  • Thông báo riêng lẻ được gửi qua kết nối WebSocket đã thiết lập.
  • WebSocket đóng kết nối.

Chuyển hướng không được hỗ trợ cho các yêu cầu WebSocket.

Kể từ Chrome 72, một tiện ích sẽ chỉ có thể chặn yêu cầu nếu tiện ích đó có máy chủ lưu trữ quyền đối với cả URL được yêu cầu và trình khởi tạo yêu cầu.

Kể từ Chrome 96, webRequest API hỗ trợ việc chặn WebTransport qua HTTP/3 yêu cầu bắt tay. Vì quá trình bắt tay được thực hiện thông qua yêu cầu CONNECT HTTP, nên luồng của quá trình này phù hợp với thành mô hình webRequest theo hướng HTTP. Lưu ý:

  • Sau khi phiên được thiết lập, tiện ích không thể quan sát hoặc can thiệp vào phiên thông qua webRequest API.
  • Việc sửa đổi tiêu đề của yêu cầu HTTP trong onBeforeSendHeaders sẽ bị bỏ qua.
  • Lệnh chuyển hướng và xác thực không được hỗ trợ trong WebTransport qua HTTP/3.

Khái niệm

Như phần sau giải thích, các sự kiện trong API yêu cầu web sử dụng mã yêu cầu và bạn có thể chỉ định bộ lọc và thông tin bổ sung (không bắt buộc) khi đăng ký trình nghe sự kiện.

Mã yêu cầu

Mỗi yêu cầu được xác định bằng một mã yêu cầu. Mã này là duy nhất trong một phiên trình duyệt và ngữ cảnh của tiện ích. Phương diện này không đổi trong suốt vòng đời của một yêu cầu và có thể được dùng để khớp các sự kiện cho cùng một yêu cầu. Lưu ý rằng nhiều yêu cầu HTTP được liên kết với một yêu cầu web trong trường hợp chuyển hướng HTTP hoặc xác thực HTTP.

Đăng ký trình nghe sự kiện

Để đăng ký trình nghe sự kiện cho một yêu cầu web, bạn sử dụng một biến thể trên addListener() thông thường . Ngoài việc chỉ định hàm callback, bạn phải chỉ định một đối số bộ lọc và có thể chỉ định một đối số thông tin bổ sung (không bắt buộc).

Ba đối số cho addListener() của API yêu cầu web có các định nghĩa sau:

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

Dưới đây là ví dụ về cách theo dõi sự kiện onBeforeRequest:

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

Mỗi lệnh gọi addListener() lấy một hàm callback bắt buộc làm tham số đầu tiên. Lệnh gọi lại này được chuyển từ điển chứa thông tin về yêu cầu URL hiện tại. Chiến lược phát hành đĩa đơn thông tin trong từ điển này phụ thuộc vào loại sự kiện cụ thể cũng như nội dung của opt_extraInfoSpec.

Nếu mảng opt_extraInfoSpec không bắt buộc chứa chuỗi 'blocking' (chỉ cho phép đối với các sự kiện cụ thể), hàm callback được xử lý đồng bộ. Điều đó có nghĩa là yêu cầu bị chặn cho đến khi hàm callback được trả về. Trong trường hợp này, lệnh gọi lại có thể trả về webRequest.BlockingResponse xác định vòng đời về sau của yêu cầu. Tuỳ thuộc vào vào ngữ cảnh, phản hồi này cho phép huỷ hoặc chuyển hướng một yêu cầu (onBeforeRequest), huỷ yêu cầu hoặc sửa đổi tiêu đề (onBeforeSendHeaders, onHeadersReceived) và huỷ yêu cầu hoặc cung cấp thông tin xác thực (onAuthRequired).

Nếu mảng opt_extraInfoSpec không bắt buộc chứa chuỗi 'asyncBlocking' (chỉ được phép cho onAuthRequired), tiện ích này có thể tạo webRequest.BlockingResponse một cách không đồng bộ.

webRequest.RequestFilter filter cho phép giới hạn các yêu cầu đối với sự kiện được kích hoạt theo nhiều phương diện:

URL
các mẫu URL như *://www.google.com/foo*bar.
Loại
Các loại yêu cầu như main_frame (một tài liệu được tải cho khung cấp cao nhất), sub_frame (một tài liệu được tải cho một khung được nhúng) và image (một hình ảnh trên một trang web). Xem webRequest.RequestFilter.
Mã thẻ
Giá trị nhận dạng của một thẻ.
Mã cửa sổ
Giá trị nhận dạng của một cửa sổ.

Tuỳ thuộc vào loại sự kiện, bạn có thể chỉ định các chuỗi trong opt_extraInfoSpec để yêu cầu thêm thông tin về yêu cầu. URL này chỉ dùng để cung cấp thông tin chi tiết về dữ liệu của yêu cầu khi được yêu cầu rõ ràng.

Chi tiết triển khai

Bạn cần nắm được một số thông tin triển khai quan trọng khi phát triển một phần mở rộng sử dụng API yêu cầu web:

web_accessible_resources

Khi một tiện ích sử dụng API webRequest để chuyển hướng một yêu cầu tài nguyên công khai đến một tài nguyên không truy cập được trên web, tiện ích đó sẽ bị chặn và dẫn đến lỗi. Điều trên vẫn đúng ngay cả khi tài nguyên không thể truy cập được trên web lại thuộc sở hữu của tiện ích chuyển hướng. Để khai báo tài nguyên dùng với các API declarativeWebRequest, bạn phải khai báo và điền sẵn mảng "web_accessible_resources" vào tệp kê khai như được nêu tại đây.

Giải quyết xung đột

Trong cách triển khai API yêu cầu web hiện tại, một yêu cầu được coi là bị huỷ nếu ít nhất một tiện ích hướng dẫn huỷ yêu cầu. Nếu tiện ích huỷ một yêu cầu, tất cả các tiện ích được thông báo thông qua một sự kiện onErrorOccurred. Chỉ một tiện ích có thể chuyển hướng yêu cầu hoặc sửa đổi tiêu đề cùng một lúc. Nếu có nhiều tiện ích cố gắng sửa đổi yêu cầu, thì tiện ích được cài đặt gần đây nhất sẽ chiến thắng và tất cả tiện ích khác sẽ bị bỏ qua. Tiện ích sẽ không được thông báo nếu thì lệnh sửa đổi hoặc chuyển hướng đã bị bỏ qua.

Lưu vào bộ nhớ đệm

Chrome sử dụng hai bộ nhớ đệm — một bộ nhớ đệm trên ổ đĩa và một bộ nhớ đệm trong bộ nhớ cực nhanh. Vòng đời của một bộ nhớ đệm trong bộ nhớ được gắn với toàn bộ thời gian của quá trình kết xuất, gần như tương ứng với một thẻ. Các yêu cầu được trả lời từ bộ nhớ đệm trong bộ nhớ sẽ không hiển thị với API yêu cầu web. Nếu một trình xử lý yêu cầu thay đổi hành vi của mình (ví dụ: hành vi theo các yêu cầu bị chặn), một thao tác làm mới trang đơn giản có thể không tuân theo hành vi đã thay đổi này. Để đảm bảo hành vi thay đổi vẫn đang diễn ra, hãy gọi handlerBehaviorChanged() để xoá bộ nhớ đệm trong bộ nhớ. Nhưng đừng làm thường xuyên; xoá bộ nhớ đệm là một thao tác rất tốn kém. Bạn không cần gọi điện handlerBehaviorChanged() sau khi đăng ký hoặc huỷ đăng ký một trình nghe sự kiện.

Dấu thời gian

Thuộc tính timestamp của các sự kiện yêu cầu web chỉ được đảm bảo là nhất quán nội bộ. So sánh một sự kiện với một sự kiện khác sẽ cung cấp cho bạn độ lệch chính xác giữa các sự kiện đó, nhưng việc so sánh chúng tới thời gian hiện tại bên trong tiện ích (ví dụ: qua (new Date()).getTime()) có thể mang lại kết quả không mong muốn.

Xử lý lỗi

Nếu bạn cố đăng ký một sự kiện có đối số không hợp lệ, thì hệ thống sẽ gửi lỗi JavaScript và trình xử lý sự kiện sẽ không được đăng ký. Nếu xảy ra lỗi trong khi xử lý sự kiện hoặc nếu một trình xử lý sự kiện trả về phản hồi chặn không hợp lệ, một thông báo lỗi được ghi vào và trình xử lý sẽ bị bỏ qua đối với yêu cầu đó.

Ví dụ

Ví dụ sau minh hoạ cách chặn tất cả yêu cầu gửi đến www.evil.com:

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

Vì sử dụng trình xử lý sự kiện chặn nên hàm này yêu cầu "webRequest" cũng như Quyền "webRequestBlocking" trong tệp kê khai.

Ví dụ sau đây đạt được cùng mục tiêu theo cách hiệu quả hơn bởi vì các yêu cầu không đã nhắm mục tiêu đến www.evil.com thì không cần truyền tới tiện ích:

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

Ví dụ sau minh hoạ cách xoá tiêu đề Tác nhân người dùng khỏi tất cả các yêu cầu:

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

Để dùng thử API chrome.webRequest, cài đặt mẫu webRequest từ chrome-extension-samples kho lưu trữ.

Loại

BlockingResponse

Trả về giá trị cho trình xử lý sự kiện có thông số 'chặn' Đã áp dụng extraInfoSpec. Cho phép trình xử lý sự kiện sửa đổi yêu cầu mạng.

Thuộc tính

  • authCredentials

    đối tượng không bắt buộc

    Chỉ được dùng làm phản hồi cho sự kiện onAuthrequired. Nếu được đặt, yêu cầu sẽ được thực hiện bằng thông tin đăng nhập đã cung cấp.

    • mật khẩu

      string

    • tên người dùng

      string

  • hủy

    boolean không bắt buộc

    Nếu đúng, yêu cầu sẽ bị huỷ. Thao tác này sẽ ngăn việc gửi yêu cầu. Bạn có thể dùng thông tin này làm phản hồi cho các sự kiện onBeforeRequest, onBeforeSendHeaders, onHeadersReceived và onAuthrequired.

  • redirectUrl

    chuỗi không bắt buộc

    Chỉ được dùng làm phản hồi cho các sự kiện onBeforeRequest và onHeadersReceived. Nếu được đặt, yêu cầu ban đầu sẽ bị chặn gửi/hoàn tất và thay vào đó sẽ được chuyển hướng đến URL đã cho. Cho phép chuyển hướng đến các giao thức không phải HTTP, chẳng hạn như data:. Lệnh chuyển hướng do thao tác chuyển hướng thực hiện sử dụng phương thức yêu cầu ban đầu cho lệnh chuyển hướng, ngoại trừ một trường hợp: Nếu lệnh chuyển hướng được bắt đầu ở giai đoạn onHeadersReceived, thì lệnh chuyển hướng sẽ được cấp bằng phương thức GET. Lệnh chuyển hướng từ các URL có giao thức ws:// và wss:// sẽ bị bỏ qua.

  • requestHeaders

    HttpHeaders không bắt buộc

    Chỉ được dùng làm phản hồi cho sự kiện onBeforeSendHeaders. Nếu được đặt, yêu cầu sẽ được thực hiện bằng các tiêu đề của yêu cầu này.

  • responseHeaders

    HttpHeaders không bắt buộc

    Chỉ được dùng làm phản hồi cho sự kiện onHeadersReceived. Nếu được đặt, máy chủ được giả định là đã phản hồi bằng những tiêu đề phản hồi này. Chỉ trả về responseHeaders nếu bạn thực sự muốn sửa đổi tiêu đề để giới hạn số lượng xung đột (chỉ một tiện ích có thể sửa đổi responseHeaders cho mỗi yêu cầu).

FormDataItem

Chrome 66 trở lên

Chứa dữ liệu được truyền trong dữ liệu biểu mẫu. Đối với dạng url được mã hoá, dữ liệu này được lưu trữ dưới dạng chuỗi nếu dữ liệu là chuỗi utf-8 và nếu không phải là ArrayBuffer. Đối với dữ liệu biểu mẫu, đó là ArrayBuffer. Nếu form-data biểu thị tệp đang tải lên, thì đó là chuỗi có tên tệp, nếu tên tệp được cung cấp.

Enum

ArrayBuffer

string

HttpHeaders

Một mảng tiêu đề HTTP. Mỗi tiêu đề được biểu thị dưới dạng một từ điển chứa các khoá name và value hoặc binaryValue.

Loại

object[]

Thuộc tính

  • binaryValue

    number[] không bắt buộc

    Giá trị của tiêu đề HTTP nếu nó không thể được đại diện bằng UTF-8, được lưu trữ dưới dạng giá trị byte riêng lẻ (0..255).

  • tên

    string

    Tên của tiêu đề HTTP.

  • value

    chuỗi không bắt buộc

    Giá trị của tiêu đề HTTP nếu tiêu đề này có thể được biểu thị bằng UTF-8.

IgnoredActionType

Chrome 70 trở lên

Enum

"redirect"

"request_headers"

&quot;response_headers&quot;

&quot;auth_credentials&quot;

OnAuthRequiredOptions

Chrome 44 trở lên

Enum

&quot;responseHeaders&quot;
Chỉ định tiêu đề phản hồi cần được đưa vào sự kiện.

"chặn"
Chỉ định yêu cầu bị chặn cho đến khi hàm callback trả về.

&quot;asyncBlocking&quot;
Chỉ định rằng hàm callback được xử lý không đồng bộ.

"extraHeaders"
Chỉ định rằng các tiêu đề có thể vi phạm quy trình Chia sẻ tài nguyên trên nhiều nguồn gốc (CORS).

OnBeforeRedirectOptions

Chrome 44 trở lên

Enum

&quot;responseHeaders&quot;
Chỉ định tiêu đề phản hồi cần được đưa vào sự kiện.

"extraHeaders"
Chỉ định rằng các tiêu đề có thể vi phạm quy trình Chia sẻ tài nguyên trên nhiều nguồn gốc (CORS).

OnBeforeRequestOptions

Chrome 44 trở lên

Enum

"chặn"
Chỉ định yêu cầu bị chặn cho đến khi hàm callback trả về.

&quot;requestBody&quot;
Chỉ định rằng cần đưa nội dung yêu cầu vào sự kiện.

"extraHeaders"
Chỉ định rằng các tiêu đề có thể vi phạm quy trình Chia sẻ tài nguyên trên nhiều nguồn gốc (CORS).

OnBeforeSendHeadersOptions

Chrome 44 trở lên

Enum

&quot;requestHeaders&quot;
Chỉ định rằng cần đưa tiêu đề của yêu cầu vào sự kiện.

"chặn"
Chỉ định yêu cầu bị chặn cho đến khi hàm callback trả về.

"extraHeaders"
Chỉ định rằng các tiêu đề có thể vi phạm quy trình Chia sẻ tài nguyên trên nhiều nguồn gốc (CORS).

OnCompletedOptions

Chrome 44 trở lên

Enum

&quot;responseHeaders&quot;
Chỉ định tiêu đề phản hồi cần được đưa vào sự kiện.

"extraHeaders"
Chỉ định rằng các tiêu đề có thể vi phạm quy trình Chia sẻ tài nguyên trên nhiều nguồn gốc (CORS).

OnErrorOccurredOptions

Chrome 79 trở lên

Giá trị

"extraHeaders"

OnHeadersReceivedOptions

Chrome 44 trở lên

Enum

"chặn"
Chỉ định yêu cầu bị chặn cho đến khi hàm callback trả về.

&quot;responseHeaders&quot;
Chỉ định tiêu đề phản hồi cần được đưa vào sự kiện.

"extraHeaders"
Chỉ định rằng các tiêu đề có thể vi phạm quy trình Chia sẻ tài nguyên trên nhiều nguồn gốc (CORS).

OnResponseStartedOptions

Chrome 44 trở lên

Enum

&quot;responseHeaders&quot;
Chỉ định tiêu đề phản hồi cần được đưa vào sự kiện.

"extraHeaders"
Chỉ định rằng các tiêu đề có thể vi phạm quy trình Chia sẻ tài nguyên trên nhiều nguồn gốc (CORS).

OnSendHeadersOptions

Chrome 44 trở lên

Enum

&quot;requestHeaders&quot;
Chỉ định rằng cần đưa tiêu đề của yêu cầu vào sự kiện.

"extraHeaders"
Chỉ định rằng các tiêu đề có thể vi phạm quy trình Chia sẻ tài nguyên trên nhiều nguồn gốc (CORS).

RequestFilter

Một đối tượng mô tả các bộ lọc để áp dụng cho sự kiện webRequest.

Thuộc tính

  • tabId

    số không bắt buộc

  • loại

    ResourceType[] không bắt buộc

    Danh sách các loại yêu cầu. Những yêu cầu không thể khớp với bất kỳ loại nào sẽ bị lọc ra.

  • url

    chuỗi[]

    Danh sách URL hoặc mẫu URL. Những yêu cầu không thể khớp với bất kỳ URL nào sẽ bị lọc ra.

  • windowId

    số không bắt buộc

ResourceType

Chrome 44 trở lên

Enum

"main_frame"
Chỉ định tài nguyên làm khung chính.

"sub_frame"
Chỉ định tài nguyên làm khung phụ.

"biểu định kiểu"
Chỉ định tài nguyên làm biểu định kiểu.

&quot;script&quot;
Chỉ định tài nguyên làm tập lệnh.

"image"
Chỉ định tài nguyên là hình ảnh.

"font"
Chỉ định tài nguyên làm phông chữ.

"đối tượng"
Chỉ định tài nguyên làm đối tượng.

&quot;xmlhttprequest&quot;
Chỉ định tài nguyên là XMLHttpRequest.

"ping"
Chỉ định tài nguyên làm ping.

&quot;csp_report&quot;
Chỉ định tài nguyên làm báo cáo Chính sách bảo mật nội dung (CSP).

"media"
Chỉ định tài nguyên làm đối tượng nội dung nghe nhìn.

"websocket"
Chỉ định tài nguyên là WebSocket.

"webbundle"
Chỉ định tài nguyên là WebBundle.

"other"
Chỉ định tài nguyên là loại không có trong các loại được liệt kê.

UploadData

Chứa dữ liệu được tải lên trong một yêu cầu URL.

Thuộc tính

  • byte

    bất kỳ không bắt buộc

    Một ArrayBuffer có bản sao dữ liệu.

  • tệp

    chuỗi không bắt buộc

    Một chuỗi có đường dẫn và tên của tệp.

Thuộc tính

MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES

Số lần tối đa mà handlerBehaviorChanged có thể được gọi trong mỗi khoảng thời gian duy trì 10 phút. handlerBehaviorChanged là một lệnh gọi hàm tốn kém và không nên được gọi thường xuyên.

Giá trị

20

Phương thức

handlerBehaviorChanged()

Lời hứa 
chrome.webRequest.handlerBehaviorChanged(
  callback?: function,
)

Cần được gọi khi hành vi của trình xử lý webRequest đã thay đổi để ngăn việc xử lý không chính xác do lưu vào bộ nhớ đệm. Lệnh gọi hàm này tiêu tốn nhiều tài nguyên. Đừng gọi thường xuyên.

Tham số

  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau: 

    () => void

Giá trị trả về

  • Lời hứa<vô hiệu>

    Chrome 116 trở lên

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

Sự kiện

onActionIgnored

Chrome 70 trở lên 
chrome.webRequest.onActionIgnored.addListener(
  callback: function,
)

Được kích hoạt khi bỏ qua nội dung sửa đổi đề xuất của một tiện ích đối với một yêu cầu mạng. Điều này xảy ra trong trường hợp xung đột với các tiện ích khác.

Tham số

  • số gọi lại

    hàm

    Tham số callback sẽ có dạng như sau: 

    (details: object) => void

    • chi tiết

      đối tượng

      • hành động

        IgnoredActionType

        Hành động được đề xuất đã bị bỏ qua.

      • requestId

        string

        Mã của yêu cầu. Mã yêu cầu là duy nhất trong một phiên trình duyệt. Do đó, chúng có thể được dùng để liên quan đến các sự kiện khác nhau của cùng một yêu cầu.

onAuthRequired

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

Được kích hoạt khi nhận được lỗi xác thực. Trình nghe có ba tuỳ chọn: có thể cung cấp thông tin xác thực, có thể huỷ yêu cầu và hiển thị trang lỗi, hoặc không thể thực hiện hành động nào đối với thông tin xác thực. Nếu bạn cung cấp thông tin đăng nhập không hợp lệ của người dùng, thì lệnh gọi này có thể được gọi nhiều lần cho cùng một yêu cầu. Lưu ý: Bạn chỉ phải chỉ định một trong các chế độ 'blocking' hoặc 'asyncBlocking' trong tham số extraInfoSpec.

Tham số

  • số gọi lại

    hàm

    Tham số callback sẽ có dạng như sau: 

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

    • chi tiết

      đối tượng

      • kẻ thách thức

        đối tượng

        Máy chủ yêu cầu xác thực.

        • người tổ chức

          string

        • cổng

          số

      • documentId

        string

        Chrome 106 trở lên

        Mã nhận dạng duy nhất (UUID) của tài liệu gửi yêu cầu.

      • Chrome 106 trở lên

        Vòng đời của tài liệu.

      • frameId

        số

        Giá trị 0 cho biết yêu cầu diễn ra trong khung chính; giá trị dương cho biết mã của khung phụ có yêu cầu. Nếu tài liệu của một khung (phụ) được tải (type là main_frame hoặc sub_frame), frameId sẽ cho biết mã nhận dạng của khung này, chứ không phải mã của khung bên ngoài. Mã khung là duy nhất trong một thẻ.

      • Chrome 106 trở lên

        Loại khung có yêu cầu.

      • trình khởi tạo

        chuỗi không bắt buộc

        Chrome 63 trở lên

        Nguồn gốc nơi yêu cầu được khởi tạo. Điều này không thay đổi thông qua chuyển hướng. Nếu đây là nguồn gốc không rõ ràng, thì chuỗi "null" sẽ được sử dụng.

      • isProxy

        boolean

        True để xác thực proxy, false cho WWW-Verify.

      • method

        string

        Phương thức HTTP chuẩn.

      • parentDocumentId

        chuỗi không bắt buộc

        Chrome 106 trở lên

        Mã nhận dạng duy nhất (UUID) của tài liệu gốc sở hữu khung này. Giá trị này không được thiết lập nếu không có cha mẹ.

      • parentFrameId

        số

        Mã nhận dạng của khung bao bọc khung đã gửi yêu cầu. Đặt thành -1 nếu không có khung gốc.

      • vùng

        chuỗi không bắt buộc

        Vùng xác thực do máy chủ cung cấp, nếu có.

      • requestId

        string

        Mã của yêu cầu. Mã yêu cầu là duy nhất trong một phiên trình duyệt. Do đó, chúng có thể được dùng để liên quan đến các sự kiện khác nhau của cùng một yêu cầu.

      • responseHeaders

        HttpHeaders không bắt buộc

        Các tiêu đề phản hồi HTTP đã nhận được cùng với phản hồi này.

      • lược đồ

        string

        Giao thức xác thực, ví dụ: Cơ bản hoặc thông báo.

      • statusCode

        số

        Chrome 43 trở lên

        Mã trạng thái HTTP chuẩn được máy chủ trả về.

      • statusLine

        string

        Dòng trạng thái HTTP của phản hồi hoặc "HTTP/0.9 200 OK" chuỗi cho phản hồi HTTP/0.9 (tức là phản hồi thiếu dòng trạng thái) hoặc chuỗi trống nếu không có tiêu đề.

      • tabId

        số

        Mã của thẻ diễn ra yêu cầu. Đặt thành -1 nếu yêu cầu không liên quan đến một thẻ.

      • timeStamp

        số

        Thời gian khi tín hiệu này được kích hoạt, tính bằng mili giây kể từ thời gian bắt đầu của hệ thống.

      • loại

        ResourceType

        Cách sử dụng tài nguyên được yêu cầu.

      • url

        string

    • asyncCallback

      hàm không bắt buộc

      Chrome 58 trở lên

      Tham số asyncCallback sẽ có dạng như sau: 

      (response: BlockingResponse) => void

    • returns

      BlockingResponse | chưa xác định

      Nếu "chặn" được chỉ định trong thuộc tính "extraInfoSpec" thì trình nghe sự kiện sẽ trả về một đối tượng thuộc loại này.

  • filter

    RequestFilter

  • extraInfoSpec

    OnAuthRequiredOptions[] không bắt buộc

onBeforeRedirect

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

Được kích hoạt khi lệnh chuyển hướng do máy chủ khởi tạo sắp xảy ra.

Tham số

  • số gọi lại

    hàm

    Tham số callback sẽ có dạng như sau: 

    (details: object) => void

    • chi tiết

      đối tượng

      • documentId

        string

        Chrome 106 trở lên

        Mã nhận dạng duy nhất (UUID) của tài liệu gửi yêu cầu.

      • Chrome 106 trở lên

        Vòng đời của tài liệu.

      • frameId

        số

        Giá trị 0 cho biết yêu cầu diễn ra trong khung chính; giá trị dương cho biết mã của khung phụ có yêu cầu. Nếu tài liệu của một khung (phụ) được tải (type là main_frame hoặc sub_frame), frameId sẽ cho biết mã nhận dạng của khung này, chứ không phải mã của khung bên ngoài. Mã khung là duy nhất trong một thẻ.

      • Chrome 106 trở lên

        Loại khung có yêu cầu.

      • fromCache

        boolean

        Cho biết liệu phản hồi này có được tìm nạp từ bộ nhớ đệm của ổ đĩa hay không.

      • trình khởi tạo

        chuỗi không bắt buộc

        Chrome 63 trở lên

        Nguồn gốc nơi yêu cầu được khởi tạo. Điều này không thay đổi thông qua chuyển hướng. Nếu đây là nguồn gốc không rõ ràng, thì chuỗi "null" sẽ được sử dụng.

      • ip

        chuỗi không bắt buộc

        Địa chỉ IP của máy chủ mà yêu cầu đã thực sự được gửi đến. Xin lưu ý rằng đó có thể là một địa chỉ IPv6 cố định.

      • method

        string

        Phương thức HTTP chuẩn.

      • parentDocumentId

        chuỗi không bắt buộc

        Chrome 106 trở lên

        Mã nhận dạng duy nhất (UUID) của tài liệu gốc sở hữu khung này. Chế độ này không được thiết lập nếu không có thư mục mẹ.

      • parentFrameId

        số

        Mã nhận dạng của khung bao bọc khung đã gửi yêu cầu. Đặt thành -1 nếu không có khung gốc.

      • redirectUrl

        string

        URL mới.

      • requestId

        string

        Mã của yêu cầu. Mã yêu cầu là duy nhất trong một phiên trình duyệt. Do đó, chúng có thể được dùng để liên quan đến các sự kiện khác nhau của cùng một yêu cầu.

      • responseHeaders

        HttpHeaders không bắt buộc

        Các tiêu đề phản hồi HTTP đã nhận được cùng với lệnh chuyển hướng này.

      • statusCode

        số

        Mã trạng thái HTTP chuẩn được máy chủ trả về.

      • statusLine

        string

        Dòng trạng thái HTTP của phản hồi hoặc "HTTP/0.9 200 OK" chuỗi cho phản hồi HTTP/0.9 (tức là phản hồi thiếu dòng trạng thái) hoặc chuỗi trống nếu không có tiêu đề.

      • tabId

        số

        Mã của thẻ diễn ra yêu cầu. Đặt thành -1 nếu yêu cầu không liên quan đến một thẻ.

      • timeStamp

        số

        Thời gian khi tín hiệu này được kích hoạt, tính bằng mili giây kể từ thời gian bắt đầu của hệ thống.

      • loại

        ResourceType

        Cách sử dụng tài nguyên được yêu cầu.

      • url

        string

  • filter

    RequestFilter

  • extraInfoSpec

    OnBeforeRedirectOptions[] không bắt buộc

onBeforeRequest

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

Được kích hoạt khi có yêu cầu sắp xảy ra.

Tham số

  • số gọi lại

    hàm

    Tham số callback sẽ có dạng như sau: 

    (details: object) => BlockingResponse | undefined

    • chi tiết

      đối tượng

      • documentId

        chuỗi không bắt buộc

        Chrome 106 trở lên

        Mã nhận dạng duy nhất (UUID) của tài liệu gửi yêu cầu.

      • documentLifecycle

        extensionTypes.DocumentLifecycle optional

        Chrome 106 trở lên

        Vòng đời của tài liệu.

      • frameId

        số

        Giá trị 0 cho biết yêu cầu diễn ra trong khung chính; giá trị dương cho biết mã của khung phụ có yêu cầu. Nếu tài liệu của một khung (phụ) được tải (type là main_frame hoặc sub_frame), frameId sẽ cho biết mã nhận dạng của khung này, chứ không phải mã của khung bên ngoài. Mã khung là duy nhất trong một thẻ.

      • frameType

        extensionTypes.FrameType optional

        Chrome 106 trở lên

        Loại khung có yêu cầu.

      • trình khởi tạo

        chuỗi không bắt buộc

        Chrome 63 trở lên

        Nguồn gốc nơi yêu cầu được khởi tạo. Điều này không thay đổi thông qua chuyển hướng. Nếu đây là nguồn gốc không rõ ràng, thì chuỗi "null" sẽ được sử dụng.

      • method

        string

        Phương thức HTTP chuẩn.

      • parentDocumentId

        chuỗi không bắt buộc

        Chrome 106 trở lên

        Mã nhận dạng duy nhất (UUID) của tài liệu gốc sở hữu khung này. Chế độ này không được thiết lập nếu không có thư mục mẹ.

      • parentFrameId

        số

        Mã nhận dạng của khung bao bọc khung đã gửi yêu cầu. Đặt thành -1 nếu không có khung gốc.

      • requestBody

        đối tượng không bắt buộc

        Chứa dữ liệu nội dung của yêu cầu HTTP. Chỉ được cung cấp nếu extraInfoSpec chứa 'requestBody'.

        • error

          chuỗi không bắt buộc

          Lỗi khi nhận dữ liệu cơ thể yêu cầu.

        • formData

          đối tượng không bắt buộc

          Nếu phương thức yêu cầu là POST và nội dung là một chuỗi các cặp khoá-giá trị được mã hoá bằng UTF8, được mã hoá dưới dạng multipart/form-data hoặc application/x-www-form-url encrypted, thì sẽ có từ điển này và cho mỗi khoá chứa danh sách tất cả các giá trị cho khoá đó. Nếu dữ liệu thuộc một loại phương tiện khác hoặc nếu dữ liệu đó không đúng định dạng, thì từ điển sẽ không xuất hiện. Giá trị mẫu của từ điển này là {'key': ['value1', 'value2']}.

        • thô

          UploadData[] không bắt buộc

          Nếu phương thức yêu cầu là PUT hoặc POST và nội dung chưa được phân tích cú pháp trong formData, thì các phần tử nội dung của yêu cầu chưa được phân tích cú pháp sẽ nằm trong mảng này.

      • requestId

        string

        Mã của yêu cầu. Mã yêu cầu là duy nhất trong một phiên trình duyệt. Do đó, chúng có thể được dùng để liên quan đến các sự kiện khác nhau của cùng một yêu cầu.

      • tabId

        số

        Mã của thẻ diễn ra yêu cầu. Đặt thành -1 nếu yêu cầu không liên quan đến một thẻ.

      • timeStamp

        số

        Thời gian khi tín hiệu này được kích hoạt, tính bằng mili giây kể từ thời gian bắt đầu của hệ thống.

      • loại

        ResourceType

        Cách sử dụng tài nguyên được yêu cầu.

      • url

        string

    • returns

      BlockingResponse | chưa xác định

      Nếu "chặn" được chỉ định trong thuộc tính "extraInfoSpec" thì trình nghe sự kiện sẽ trả về một đối tượng thuộc loại này.

  • filter

    RequestFilter

  • extraInfoSpec

    OnBeforeRequestOptions[] không bắt buộc

onBeforeSendHeaders

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

Được kích hoạt trước khi gửi yêu cầu HTTP, khi tiêu đề của yêu cầu có sẵn. Điều này có thể xảy ra sau khi kết nối TCP được thực hiện với máy chủ, nhưng trước khi bất kỳ dữ liệu HTTP nào được gửi.

Tham số

  • số gọi lại

    hàm

    Tham số callback sẽ có dạng như sau: 

    (details: object) => BlockingResponse | undefined

    • chi tiết

      đối tượng

      • documentId

        string

        Chrome 106 trở lên

        Mã nhận dạng duy nhất (UUID) của tài liệu gửi yêu cầu.

      • Chrome 106 trở lên

        Vòng đời của tài liệu.

      • frameId

        số

        Giá trị 0 cho biết yêu cầu diễn ra trong khung chính; giá trị dương cho biết mã của khung phụ có yêu cầu. Nếu tài liệu của một khung (phụ) được tải (type là main_frame hoặc sub_frame), frameId sẽ cho biết mã nhận dạng của khung này, chứ không phải mã của khung bên ngoài. Mã khung là duy nhất trong một thẻ.

      • Chrome 106 trở lên

        Loại khung có yêu cầu.

      • trình khởi tạo

        chuỗi không bắt buộc

        Chrome 63 trở lên

        Nguồn gốc nơi yêu cầu được khởi tạo. Điều này không thay đổi thông qua chuyển hướng. Nếu đây là nguồn gốc không rõ ràng, thì chuỗi "null" sẽ được sử dụng.

      • method

        string

        Phương thức HTTP chuẩn.

      • parentDocumentId

        chuỗi không bắt buộc

        Chrome 106 trở lên

        Mã nhận dạng duy nhất (UUID) của tài liệu gốc sở hữu khung này. Giá trị này không được thiết lập nếu không có cha mẹ.

      • parentFrameId

        số

        Mã nhận dạng của khung bao bọc khung đã gửi yêu cầu. Đặt thành -1 nếu không có khung gốc.

      • requestHeaders

        HttpHeaders không bắt buộc

        Tiêu đề của yêu cầu HTTP sẽ được gửi cùng với yêu cầu này.

      • requestId

        string

        Mã của yêu cầu. Mã yêu cầu là duy nhất trong một phiên trình duyệt. Do đó, chúng có thể được dùng để liên quan đến các sự kiện khác nhau của cùng một yêu cầu.

      • tabId

        số

        Mã của thẻ diễn ra yêu cầu. Đặt thành -1 nếu yêu cầu không liên quan đến một thẻ.

      • timeStamp

        số

        Thời gian khi tín hiệu này được kích hoạt, tính bằng mili giây kể từ thời gian bắt đầu của hệ thống.

      • loại

        ResourceType

        Cách sử dụng tài nguyên được yêu cầu.

      • url

        string

    • returns

      BlockingResponse | chưa xác định

      Nếu "chặn" được chỉ định trong thuộc tính "extraInfoSpec" thì trình nghe sự kiện sẽ trả về một đối tượng thuộc loại này.

  • filter

    RequestFilter

  • extraInfoSpec

    OnBeforeSendHeadersOptions[] không bắt buộc

onCompleted

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

Được kích hoạt khi hoàn tất một yêu cầu.

Tham số

  • số gọi lại

    hàm

    Tham số callback sẽ có dạng như sau: 

    (details: object) => void

    • chi tiết

      đối tượng

      • documentId

        string

        Chrome 106 trở lên

        Mã nhận dạng duy nhất (UUID) của tài liệu gửi yêu cầu.

      • Chrome 106 trở lên

        Vòng đời của tài liệu.

      • frameId

        số

        Giá trị 0 cho biết yêu cầu diễn ra trong khung chính; giá trị dương cho biết mã của khung phụ có yêu cầu. Nếu tài liệu của một khung (phụ) được tải (type là main_frame hoặc sub_frame), frameId sẽ cho biết mã nhận dạng của khung này, chứ không phải mã của khung bên ngoài. Mã khung là duy nhất trong một thẻ.

      • Chrome 106 trở lên

        Loại khung có yêu cầu.

      • fromCache

        boolean

        Cho biết liệu phản hồi này có được tìm nạp từ bộ nhớ đệm của ổ đĩa hay không.

      • trình khởi tạo

        chuỗi không bắt buộc

        Chrome 63 trở lên

        Nguồn gốc nơi yêu cầu được khởi tạo. Điều này không thay đổi thông qua chuyển hướng. Nếu đây là nguồn gốc không rõ ràng, thì chuỗi "null" sẽ được sử dụng.

      • ip

        chuỗi không bắt buộc

        Địa chỉ IP của máy chủ mà yêu cầu đã thực sự được gửi đến. Xin lưu ý rằng đó có thể là một địa chỉ IPv6 cố định.

      • method

        string

        Phương thức HTTP chuẩn.

      • parentDocumentId

        chuỗi không bắt buộc

        Chrome 106 trở lên

        Mã nhận dạng duy nhất (UUID) của tài liệu gốc sở hữu khung này. Chế độ này không được thiết lập nếu không có thư mục mẹ.

      • parentFrameId

        số

        Mã nhận dạng của khung bao bọc khung đã gửi yêu cầu. Đặt thành -1 nếu không có khung gốc.

      • requestId

        string

        Mã của yêu cầu. Mã yêu cầu là duy nhất trong một phiên trình duyệt. Do đó, chúng có thể được dùng để liên quan đến các sự kiện khác nhau của cùng một yêu cầu.

      • responseHeaders

        HttpHeaders không bắt buộc

        Các tiêu đề phản hồi HTTP đã nhận được cùng với phản hồi này.

      • statusCode

        số

        Mã trạng thái HTTP chuẩn được máy chủ trả về.

      • statusLine

        string

        Dòng trạng thái HTTP của phản hồi hoặc "HTTP/0.9 200 OK" chuỗi cho phản hồi HTTP/0.9 (tức là phản hồi thiếu dòng trạng thái) hoặc chuỗi trống nếu không có tiêu đề.

      • tabId

        số

        Mã của thẻ diễn ra yêu cầu. Đặt thành -1 nếu yêu cầu không liên quan đến một thẻ.

      • timeStamp

        số

        Thời gian khi tín hiệu này được kích hoạt, tính bằng mili giây kể từ thời gian bắt đầu của hệ thống.

      • loại

        ResourceType

        Cách sử dụng tài nguyên được yêu cầu.

      • url

        string

  • filter

    RequestFilter

  • extraInfoSpec

    OnCompletedOptions[] không bắt buộc

onErrorOccurred

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

Được kích hoạt khi xảy ra lỗi.

Tham số

  • số gọi lại

    hàm

    Tham số callback sẽ có dạng như sau: 

    (details: object) => void

    • chi tiết

      đối tượng

      • documentId

        string

        Chrome 106 trở lên

        Mã nhận dạng duy nhất (UUID) của tài liệu gửi yêu cầu. Giá trị này sẽ không xuất hiện nếu yêu cầu là một thao tác trong một khung.

      • Chrome 106 trở lên

        Vòng đời của tài liệu.

      • error

        string

        Nội dung mô tả về lỗi. Chuỗi này không đảm bảo duy trì khả năng tương thích ngược giữa các bản phát hành. Bạn không được phân tích cú pháp và hành động dựa trên nội dung của báo cáo.

      • frameId

        số

        Giá trị 0 cho biết yêu cầu diễn ra trong khung chính; giá trị dương cho biết mã của khung phụ có yêu cầu. Nếu tài liệu của một khung (phụ) được tải (type là main_frame hoặc sub_frame), frameId sẽ cho biết mã nhận dạng của khung này, chứ không phải mã của khung bên ngoài. Mã khung là duy nhất trong một thẻ.

      • Chrome 106 trở lên

        Loại khung có yêu cầu.

      • fromCache

        boolean

        Cho biết liệu phản hồi này có được tìm nạp từ bộ nhớ đệm của ổ đĩa hay không.

      • trình khởi tạo

        chuỗi không bắt buộc

        Chrome 63 trở lên

        Nguồn gốc nơi yêu cầu được khởi tạo. Điều này không thay đổi thông qua chuyển hướng. Nếu đây là nguồn gốc không rõ ràng, thì chuỗi "null" sẽ được sử dụng.

      • ip

        chuỗi không bắt buộc

        Địa chỉ IP của máy chủ mà yêu cầu đã thực sự được gửi đến. Xin lưu ý rằng đó có thể là một địa chỉ IPv6 cố định.

      • method

        string

        Phương thức HTTP chuẩn.

      • parentDocumentId

        chuỗi không bắt buộc

        Chrome 106 trở lên

        Mã nhận dạng duy nhất (UUID) của tài liệu gốc sở hữu khung này. Giá trị này không được thiết lập nếu không có cha mẹ.

      • parentFrameId

        số

        Mã nhận dạng của khung bao bọc khung đã gửi yêu cầu. Đặt thành -1 nếu không có khung gốc.

      • requestId

        string

        Mã của yêu cầu. Mã yêu cầu là duy nhất trong một phiên trình duyệt. Do đó, chúng có thể được dùng để liên quan đến các sự kiện khác nhau của cùng một yêu cầu.

      • tabId

        số

        Mã của thẻ diễn ra yêu cầu. Đặt thành -1 nếu yêu cầu không liên quan đến một thẻ.

      • timeStamp

        số

        Thời gian khi tín hiệu này được kích hoạt, tính bằng mili giây kể từ thời gian bắt đầu của hệ thống.

      • loại

        ResourceType

        Cách sử dụng tài nguyên được yêu cầu.

      • url

        string

  • filter

    RequestFilter

  • extraInfoSpec

    OnErrorOccurredOptions[] không bắt buộc

onHeadersReceived

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

Được kích hoạt khi nhận được tiêu đề phản hồi HTTP của một yêu cầu.

Tham số

  • số gọi lại

    hàm

    Tham số callback sẽ có dạng như sau: 

    (details: object) => BlockingResponse | undefined

    • chi tiết

      đối tượng

      • documentId

        string

        Chrome 106 trở lên

        Mã nhận dạng duy nhất (UUID) của tài liệu gửi yêu cầu.

      • Chrome 106 trở lên

        Vòng đời của tài liệu.

      • frameId

        số

        Giá trị 0 cho biết yêu cầu diễn ra trong khung chính; giá trị dương cho biết mã của khung phụ có yêu cầu. Nếu tài liệu của một khung (phụ) được tải (type là main_frame hoặc sub_frame), frameId sẽ cho biết mã nhận dạng của khung này, chứ không phải mã của khung bên ngoài. Mã khung là duy nhất trong một thẻ.

      • Chrome 106 trở lên

        Loại khung có yêu cầu.

      • trình khởi tạo

        chuỗi không bắt buộc

        Chrome 63 trở lên

        Nguồn gốc nơi yêu cầu được khởi tạo. Điều này không thay đổi thông qua chuyển hướng. Nếu đây là nguồn gốc không rõ ràng, thì chuỗi "null" sẽ được sử dụng.

      • method

        string

        Phương thức HTTP chuẩn.

      • parentDocumentId

        chuỗi không bắt buộc

        Chrome 106 trở lên

        Mã nhận dạng duy nhất (UUID) của tài liệu gốc sở hữu khung này. Giá trị này không được thiết lập nếu không có cha mẹ.

      • parentFrameId

        số

        Mã nhận dạng của khung bao bọc khung đã gửi yêu cầu. Đặt thành -1 nếu không có khung gốc.

      • requestId

        string

        Mã của yêu cầu. Mã yêu cầu là duy nhất trong một phiên trình duyệt. Do đó, chúng có thể được dùng để liên quan đến các sự kiện khác nhau của cùng một yêu cầu.

      • responseHeaders

        HttpHeaders không bắt buộc

        Các tiêu đề phản hồi HTTP đã nhận được cùng với phản hồi này.

      • statusCode

        số

        Chrome 43 trở lên

        Mã trạng thái HTTP chuẩn được máy chủ trả về.

      • statusLine

        string

        Dòng trạng thái HTTP của phản hồi hoặc "HTTP/0.9 200 OK" cho phản hồi HTTP/0.9 (ví dụ: phản hồi không có dòng trạng thái).

      • tabId

        số

        Mã của thẻ diễn ra yêu cầu. Đặt thành -1 nếu yêu cầu không liên quan đến một thẻ.

      • timeStamp

        số

        Thời gian khi tín hiệu này được kích hoạt, tính bằng mili giây kể từ thời gian bắt đầu của hệ thống.

      • loại

        ResourceType

        Cách sử dụng tài nguyên được yêu cầu.

      • url

        string

    • returns

      BlockingResponse | chưa xác định

      Nếu "chặn" được chỉ định trong thuộc tính "extraInfoSpec" thì trình nghe sự kiện sẽ trả về một đối tượng thuộc loại này.

  • filter

    RequestFilter

  • extraInfoSpec

    OnHeadersReceivedOptions[] không bắt buộc

onResponseStarted

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

Được kích hoạt khi nhận được byte đầu tiên của nội dung phản hồi. Đối với các yêu cầu HTTP, điều này có nghĩa là dòng trạng thái và tiêu đề phản hồi đang hoạt động.

Tham số

  • số gọi lại

    hàm

    Tham số callback sẽ có dạng như sau: 

    (details: object) => void

    • chi tiết

      đối tượng

      • documentId

        string

        Chrome 106 trở lên

        Mã nhận dạng duy nhất (UUID) của tài liệu gửi yêu cầu.

      • Chrome 106 trở lên

        Vòng đời của tài liệu.

      • frameId

        số

        Giá trị 0 cho biết yêu cầu diễn ra trong khung chính; giá trị dương cho biết mã của khung phụ có yêu cầu. Nếu tài liệu của một khung (phụ) được tải (type là main_frame hoặc sub_frame), frameId sẽ cho biết mã nhận dạng của khung này, chứ không phải mã của khung bên ngoài. Mã khung là duy nhất trong một thẻ.

      • Chrome 106 trở lên

        Loại khung có yêu cầu.

      • fromCache

        boolean

        Cho biết liệu phản hồi này có được tìm nạp từ bộ nhớ đệm của ổ đĩa hay không.

      • trình khởi tạo

        chuỗi không bắt buộc

        Chrome 63 trở lên

        Nguồn gốc nơi yêu cầu được khởi tạo. Điều này không thay đổi thông qua chuyển hướng. Nếu đây là nguồn gốc không rõ ràng, thì chuỗi "null" sẽ được sử dụng.

      • ip

        chuỗi không bắt buộc

        Địa chỉ IP của máy chủ mà yêu cầu đã thực sự được gửi đến. Xin lưu ý rằng đó có thể là một địa chỉ IPv6 cố định.

      • method

        string

        Phương thức HTTP chuẩn.

      • parentDocumentId

        chuỗi không bắt buộc

        Chrome 106 trở lên

        Mã nhận dạng duy nhất (UUID) của tài liệu gốc sở hữu khung này. Giá trị này không được thiết lập nếu không có cha mẹ.

      • parentFrameId

        số

        Mã nhận dạng của khung bao bọc khung đã gửi yêu cầu. Đặt thành -1 nếu không có khung gốc.

      • requestId

        string

        Mã của yêu cầu. Mã yêu cầu là duy nhất trong một phiên trình duyệt. Do đó, chúng có thể được dùng để liên quan đến các sự kiện khác nhau của cùng một yêu cầu.

      • responseHeaders

        HttpHeaders không bắt buộc

        Các tiêu đề phản hồi HTTP đã nhận được cùng với phản hồi này.

      • statusCode

        số

        Mã trạng thái HTTP chuẩn được máy chủ trả về.

      • statusLine

        string

        Dòng trạng thái HTTP của phản hồi hoặc "HTTP/0.9 200 OK" chuỗi cho phản hồi HTTP/0.9 (tức là phản hồi thiếu dòng trạng thái) hoặc chuỗi trống nếu không có tiêu đề.

      • tabId

        số

        Mã của thẻ diễn ra yêu cầu. Đặt thành -1 nếu yêu cầu không liên quan đến một thẻ.

      • timeStamp

        số

        Thời gian khi tín hiệu này được kích hoạt, tính bằng mili giây kể từ thời gian bắt đầu của hệ thống.

      • loại

        ResourceType

        Cách sử dụng tài nguyên được yêu cầu.

      • url

        string

  • filter

    RequestFilter

  • extraInfoSpec

    OnResponseStartedOptions[] không bắt buộc

onSendHeaders

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

Được kích hoạt ngay trước khi một yêu cầu sẽ được gửi đến máy chủ (nội dung sửa đổi các lệnh gọi lại onBeforeSendHeaders trước đó hiển thị vào thời điểm onSendHeaders được kích hoạt).

Tham số

  • số gọi lại

    hàm

    Tham số callback sẽ có dạng như sau: 

    (details: object) => void

    • chi tiết

      đối tượng

      • documentId

        string

        Chrome 106 trở lên

        Mã nhận dạng duy nhất (UUID) của tài liệu gửi yêu cầu.

      • Chrome 106 trở lên

        Vòng đời của tài liệu.

      • frameId

        số

        Giá trị 0 cho biết yêu cầu diễn ra trong khung chính; giá trị dương cho biết mã của khung phụ có yêu cầu. Nếu tài liệu của một khung (phụ) được tải (type là main_frame hoặc sub_frame), frameId sẽ cho biết mã nhận dạng của khung này, chứ không phải mã của khung bên ngoài. Mã khung là duy nhất trong một thẻ.

      • Chrome 106 trở lên

        Loại khung có yêu cầu.

      • trình khởi tạo

        chuỗi không bắt buộc

        Chrome 63 trở lên

        Nguồn gốc nơi yêu cầu được khởi tạo. Điều này không thay đổi thông qua chuyển hướng. Nếu đây là nguồn gốc không rõ ràng, thì chuỗi "null" sẽ được sử dụng.

      • method

        string

        Phương thức HTTP chuẩn.

      • parentDocumentId

        chuỗi không bắt buộc

        Chrome 106 trở lên

        Mã nhận dạng duy nhất (UUID) của tài liệu gốc sở hữu khung này. Giá trị này không được thiết lập nếu không có cha mẹ.

      • parentFrameId

        số

        Mã nhận dạng của khung bao bọc khung đã gửi yêu cầu. Đặt thành -1 nếu không có khung gốc.

      • requestHeaders

        HttpHeaders không bắt buộc

        Tiêu đề của yêu cầu HTTP đã được gửi đi cùng với yêu cầu này.

      • requestId

        string

        Mã của yêu cầu. Mã yêu cầu là duy nhất trong một phiên trình duyệt. Do đó, chúng có thể được dùng để liên quan đến các sự kiện khác nhau của cùng một yêu cầu.

      • tabId

        số

        Mã của thẻ diễn ra yêu cầu. Đặt thành -1 nếu yêu cầu không liên quan đến một thẻ.

      • timeStamp

        số

        Thời gian khi tín hiệu này được kích hoạt, tính bằng mili giây kể từ thời gian bắt đầu của hệ thống.

      • loại

        ResourceType

        Cách sử dụng tài nguyên được yêu cầu.

      • url

        string

  • filter

    RequestFilter

  • extraInfoSpec

    OnSendHeadersOptions[] không bắt buộc