Trang này được dịch bởi Cloud Translation API.

chrome.webRequest

Nội dung mô tả

Sử 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

Bạn phải khai báo quyền "webRequest" trong tệp kê khai tiện ích để sử dụng API yêu cầu web, cùng với quyền của máy chủ cần thiết. Để chặn một yêu cầu 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 URL. Ví dụ:

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

webRequestBlocking

Bắt buộc phải đăng ký trình xử lý sự kiện chặn. Kể từ Manifest V3, tính năng này chỉ dành cho các tiện ích đã cài đặt theo chính sách.

webRequestAuthProvider

Bắt buộc phải sử dụng phương thức onAuthRequired. Hãy xem phần Xử lý việc xác thực.

Khái niệm và cách sử dụng

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

API yêu cầu web xác định một tập hợp các 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 các 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ạ dưới đây, theo sau 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 độ của API yêu cầu web

onBeforeRequest (không bắt buộc đồng bộ): Kích hoạt khi yêu cầu sắp xảy ra. Sự kiện này được gửi trước khi thực hiện kết nối TCP với bất kỳ kết nối nào và có thể dùng để 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 yêu cầu sắp xảy ra và tiêu đề ban đầu đã được chuẩn bị. Sự kiện này nhằm cho phép tiện ích thêm, sửa đổi và xoá tiêu đề của yêu cầu (*). Sự kiện onBeforeSendHeaders được chuyển tới tất cả người đăng ký, vì vậy, nhiều người đăng ký có thể tìm cách sửa đổi yêu cầu; hãy xem phần Chi tiết triển khai để biết cách xử lý. Bạn có thể dùng sự kiện này để huỷ yêu cầu.
onSendHeaders: Kích hoạt sau khi tất cả tiện ích đều có cơ hội sửa đổi tiêu đề yêu cầu và hiển thị phiên bản (*) cuối cùng. 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 mang tính thông tin và được xử lý không đồng bộ. Thao tác này 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 một tiêu đề phản hồi HTTP(S). Do các yêu cầu chuyển hướng và xác thực, điề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 được gửi đến. Các lệnh lưu vào bộ nhớ đệm được xử lý trước khi kích hoạt sự kiện này. Vì vậy, việc sửa đổi các tiêu đề như Cache-Control sẽ 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. Sự kiện này có thể được xử lý đồng bộ để 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ệ. Hãy cẩn thận để 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 đăng nhập không hợp lệ. Thao tác này cũng có thể dùng để huỷ yêu cầu.
onBeforeRedirect: Kích hoạt khi một lệnh chuyển hướng sắp được thực thi. Lệnh chuyển hướng có thể được kích hoạt bởi mã phản hồi HTTP hoặc bởi một tiện ích. Sự kiện này chỉ nhằm mục đích cung cấp thông tin và được xử lý không đồng bộ. Thao tác này 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 có sẵn. Sự kiện này nhằm cung cấp thông tin và được xử lý không đồng bộ. Tuy nhiên, bạn không thể sửa đổi hoặc huỷ yêu cầu.
onCompleted: Kích hoạt khi 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 sẽ được kích hoạt dưới dạng sự kiện cuối cùng với một ngoại lệ: Nếu một yêu cầu được chuyển hướng đến URL data://, thì 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 hiển thị 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 dải byte riêng lẻ trong 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 các tiêu đề HTTP cuối cùng được gửi tới mạng. Ví dụ: tất cả tiêu đề có liên quan đến việc lưu vào bộ nhớ đệm sẽ không hiển thị với tiện ích.

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

Ủy quyền
Kiểm soát bộ nhớ đệm
Kết nối
Content-Length
Thành phần lưu trữ
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
Pragma
Cấp quyền proxy
Kết nối proxy
Chuyển-Mã hoá

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

Kể từ Chrome 79, theo mặc định, API webRequest không chặn các yêu cầu và phản hồi thử nghiệm CORS. Quá trình kiểm tra CORS cho một URL yêu cầu sẽ hiển thị với tiện ích nếu có một trình nghe với '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 đề của yêu cầu sau đây sẽ không được cung cấp và không thể sửa đổi hoặc xoá nếu không chỉ định 'extraHeaders' trong opt_extraInfoSpec:

Điểm gốc

Lưu ý: Việc sửa đổi tiêu đề của yêu cầu Origin có thể không hoạt động như dự kiến và có thể gây ra lỗi không mong muốn trong hoạt động kiểm tra ChromeOS của phản hồi. Lý do là mặc dù các tiện ích chỉ có thể sửa đổi tiêu đề của yêu cầu Origin (Nguồn gốc), nhưng chúng không thể thay đổi request origin hoặc trình khởi tạo. Đây là một khái niệm được xác định trong thông số Tìm nạp để thể hiện bên bắt đầu yêu cầu. Trong trường hợp như vậy, máy chủ có thể cho phép truy cập CORS cho yêu cầu đã sửa đổi và đặt Origin của tiêu đề vào tiêu đề Access-Control-Allow-Origin trong phản hồi. Tuy nhiên, giá trị này sẽ không khớp với request origin không thể thay đổi và sẽ dẫn đến lỗi CORS.

Kể từ Chrome 72, nếu cần sửa đổi phản hồi trước khi 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 sẽ không được cung cấp và không thể sửa đổi hoặc xoá nếu không chỉ định 'extraHeaders' trong opt_extraInfoSpec:

Ngôn ngữ chấp nhận
Chấp nhận-mã hoá
Người giới thiệu
Bánh quy

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

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

Lưu ý: Việc chỉ định 'extraHeaders' trong opt_extraInfoSpec có thể có tác động tiêu cực đến hiệu suất. Do đó, bạn chỉ nên sử dụng thuộc tính này khi thực sự cần thiết.

API webRequest chỉ hiển thị các yêu cầu mà tiện ích có quyền xem, dựa trên quyền của máy chủ. Hơn nữa, bạn chỉ có thể truy cập vào các giao thức sau: 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 có URL sử dụng một trong các lược đồ ở trên cũng bị ẩn. Các phương thức này bao gồm chrome-extension://other_extension_id, trong đó other_extension_id không phải là mã nhận dạng của tiện ích để xử lý yêu cầu, https://www.google.com/chrome và các yêu cầu nhạy cảm khác đối với chức năng của trình duyệt. Ngoài ra, các API XMLHttpRequest đồng bộ từ tiện ích sẽ được ẩn khỏi việc chặn các trình xử lý sự kiện để ngăn tình trạng tắc nghẽn. Xin lưu ý rằng đối với một số giao thức được hỗ trợ, tập hợp các sự kiện có sẵn có thể bị giới hạn do tính chất của giao thức tương ứng. Ví dụ: đối với tệp: lược đồ, chỉ onBeforeRequest, onResponseStarted, onCompleted và onErrorOccurred mới có thể được gửi.

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

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

Lệnh 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 một yêu cầu nếu có quyền của máy chủ lưu trữ đối với cả URL được yêu cầu và trình tạo yêu cầu.

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

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

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 một tiện ích. Tham số này vẫn không đổi trong suốt vòng đời của một yêu cầu và có thể được dùng để so khớp các sự kiện cho cùng một yêu cầu. Xin lưu ý rằng một số yêu cầu HTTP sẽ được liên kết tớ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ể trong hàm addListener() thông thường. Ngoài việc chỉ định hàm callback, bạn phải chỉ định một đối số 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() nhận một hàm callback bắt buộc làm tham số đầu tiên. Hàm callback này được truyền một từ điển chứa thông tin về yêu cầu URL hiện tại. 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ể), thì hàm callback sẽ được xử lý đồng bộ. Điều đó có nghĩa là yêu cầu đó sẽ bị chặn cho đến khi hàm callback trả về. Trong trường hợp này, lệnh gọi lại có thể trả về webRequest.BlockingResponse giúp xác định vòng đời tiếp theo của yêu cầu. Tuỳ thuộc 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 đối với onAuthRequired), thì tiện ích 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 về những sự kiện được kích hoạt theo nhiều phương diện:

URL: Các mẫu URL, chẳng hạn như *://www.google.com/foo*bar.
Loại: Các loại yêu cầu như main_frame (tài liệu được tải cho khung cấp cao nhất), sub_frame (tài liệu được tải cho khung được nhúng) và image (hình ảnh trên trang web). Hãy 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 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. Thuộc tính này dùng để cung cấp thông tin chi tiết về dữ liệu của yêu cầu chỉ khi được yêu cầu rõ ràng.

Xử lý việc xác thực

Để xử lý các yêu cầu xác thực HTTP, hãy thêm quyền "webRequestAuthProvider" vào tệp kê khai:

{
  "permissions": [
    "webRequest",
    "webRequestAuthProvider"
  ]
}

Lưu ý rằng quyền này không bắt buộc đối với tiện ích đã cài đặt theo chính sách có quyền "webRequestBlocking".

Cách cung cấp thông tin xác thực một cách đồng bộ:

chrome.webRequest.onAuthRequired.addListener((details) => {
    return {
      authCredentials: {
        username: 'guest',
        password: 'guest'
      }
    };
  },
  { urls: ['https://httpbin.org/basic-auth/guest/guest'] },
  ['blocking']
);

Cách cung cấp thông tin xác thực không đồng bộ:

chrome.webRequest.onAuthRequired.addListener((details, callback) => {
    callback({
      authCredentials: {
        username: 'guest',
        password: 'guest'
      }
    });
  },
  { urls: ['https://httpbin.org/basic-auth/guest/guest'] },
  ['asyncBlocking']
);

Thông tin triển khai

Bạn có thể cần nắm được một số thông tin triển khai khi phát triển một tiện ích 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 yêu cầu tài nguyên công khai đến một tài nguyên không thể truy cập 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 trên web thuộc sở hữu của tiện ích chuyển hướng. Để khai báo tài nguyên sẽ 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" trong tệp kê khai như được nêu tại đây.

Giải quyết xung đột

Trong cách triển khai hiện tại của API yêu cầu web, một yêu cầu sẽ được coi là đã huỷ nếu có ít nhất một tiện ích hướng dẫn huỷ yêu cầu. Nếu một tiện ích huỷ yêu cầu, thì tất cả các tiện ích sẽ được thông báo bằng một sự kiện onErrorOccurred. Tại một thời điểm, chỉ có một tiện ích có thể chuyển hướng một yêu cầu hoặc sửa đổi tiêu đề. 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ả các tiện ích khác sẽ bị bỏ qua. Tiện ích sẽ không được thông báo nếu hướng dẫn sửa đổi hoặc chuyển hướng của tiện ích đó đã bị bỏ qua.

Chức năng 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ớ rất nhanh. Thời gian tồn tại của một bộ nhớ đệm trong bộ nhớ được đính kèm với vòng đời của một quá trình kết xuất, tương đương với một thẻ. API yêu cầu web sẽ không xem được các yêu cầu được trả lời từ bộ nhớ đệm trong bộ nhớ. Nếu trình xử lý yêu cầu thay đổi hành vi (ví dụ: hành vi theo mà yêu cầu bị chặn), thì một thao tác làm mới trang đơn giản có thể sẽ không tuân theo hành vi đã thay đổi này. Để đảm bảo thay đổi về hành vi được diễn ra, hãy gọi handlerBehaviorChanged() để xoá bộ nhớ đệm trong bộ nhớ. Nhưng đừng làm việc này thường xuyên; việc xoá bộ nhớ đệm là một thao tác rất tốn kém. Bạn không cần gọi handlerBehaviorChanged() sau khi đăng ký hoặc huỷ đăng ký 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ộ. Việc so sánh một sự kiện với một sự kiện khác sẽ cho ra kết quả chênh lệch chính xác giữa các sự kiện đó, nhưng việc so sánh các sự kiện đó với thời gian hiện tại trong tiện ích (ví dụ: thông qua (new Date()).getTime()) có thể cho kết quả không mong muốn.

Xử lý lỗi

Nếu bạn cố đăng ký một sự kiện bằng các đối số không hợp lệ, lỗi JavaScript sẽ xảy ra 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 trình xử lý sự kiện trả về phản hồi chặn không hợp lệ, thì thông báo lỗi sẽ được ghi lại vào bảng điều khiển của tiện ích 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 đế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 một trình xử lý sự kiện chặn, nên hàm này cần có quyền "webRequest" cũng như quyền "webRequestBlocking" trong tệp kê khai.

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

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

Ví dụ sau đây minh hoạ cách xoá tiêu đề Tác nhân người dùng khỏi tất 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, hãy cài đặt mẫu webRequest trong kho lưu trữ chrome-extension-samples.

Loại

BlockingResponse

Trả về giá trị cho trình xử lý sự kiện có áp dụng additionalInfoSpec 'chặn'. Cho phép trình xử lý sự kiện sửa đổi các 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 onAuthRequire. 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
huỷ

boolean không bắt buộc

Nếu đúng, yêu cầu sẽ bị huỷ. Điều này ngăn yêu cầu được gửi đi. Thông tin này có thể được dùng 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 bạn đặt chính sách này, hệ thống sẽ ngăn gửi/hoàn tất yêu cầu ban đầu và thay vào đó, yêu cầu đó 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:. Các lệnh chuyển hướng do hành động chuyển hướng khởi tạo sẽ sử dụng phương thức yêu cầu ban đầu để chuyển hướng, với một ngoại lệ: Nếu lệnh chuyển hướng được khởi tạo ở giai đoạn onHeadersReceived, thì lệnh chuyển hướng sẽ được cấp bằng phương thức GET. Các 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 đề yêu cầu này.
responseHeaders

HttpHeaders không bắt buộc

Chỉ được dùng để phản hồi sự kiện onHeadersReceived. Nếu được đặt, máy chủ sẽ được giả định là đã phản hồi bằng các 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 đề để hạn chế 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á, nó được lưu trữ dưới dạng chuỗi nếu dữ liệu là chuỗi utf-8 và dưới dạng ArrayBuffer. Đối với dữ liệu biểu mẫu, dữ liệu đó là ArrayBuffer. Nếu dữ liệu biểu mẫu biểu thị tệp tải lên, thì đó là chuỗi kèm theo tên tệp, nếu tên tệp được cung cấp.

Liệt kê

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

đối tượng[]

Thuộc tính

binaryValue

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

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

string

Tên tiêu đề HTTP.
value

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

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

IgnoredActionType

Chrome 70 trở lên

Liệt kê

"request_headers"

"response_headers"

"auth_credentials"

OnAuthRequiredOptions

Chrome 44 trở lên

Liệt kê

"responseHeaders"
Chỉ định rằng tiêu đề phản hồi phải đượ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ề.

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

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

OnBeforeRedirectOptions

Chrome 44 trở lên

Liệt kê

"responseHeaders"
Chỉ định rằng tiêu đề phản hồi phải được đưa vào sự kiện.

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

OnBeforeRequestOptions

Chrome 44 trở lên

Liệt kê

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

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

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

OnBeforeSendHeadersOptions

Chrome 44 trở lên

Liệt kê

"requestHeaders"
Chỉ định rằng tiêu đề yêu cầu sẽ đượ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ề.

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

OnCompletedOptions

Chrome 44 trở lên

Liệt kê

"responseHeaders"
Chỉ định rằng tiêu đề phản hồi phải được đưa vào sự kiện.

"extraHeaders"
Chỉ định rằng tiêu đề có thể vi phạm chế độ 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

Liệt kê

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

"responseHeaders"
Chỉ định rằng tiêu đề phản hồi phải được đưa vào sự kiện.

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

OnResponseStartedOptions

Chrome 44 trở lên

Liệt kê

"responseHeaders"
Chỉ định rằng tiêu đề phản hồi phải được đưa vào sự kiện.

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

OnSendHeadersOptions

Chrome 44 trở lên

Liệt kê

"requestHeaders"
Chỉ định rằng tiêu đề yêu cầu sẽ được đưa vào sự kiện.

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

RequestFilter

Đố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. Các yêu cầu không khớp với bất kỳ loại nào trong số các loại này sẽ bị lọc ra.
urls

chuỗi[]

Danh sách URL hoặc mẫu URL. Các yêu cầu không 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

Liệt kê

"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.

"script"
Chỉ định tài nguyên dưới dạng tập lệnh.

"image"
Chỉ định tài nguyên dưới dạng hình ảnh.

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

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

"xmlhttprequest"
Chỉ định tài nguyên dưới dạng XMLHttpRequest.

"ping"
Chỉ định tài nguyên dưới dạng lệnh ping.

"csp_report"
Chỉ định tài nguyên dưới dạng 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 đa phương tiện.

"websocket"
Chỉ định tài nguyên dưới dạng WebSocket.

"webbundle"
Chỉ định tài nguyên dưới dạng WebBundle.

"other"
Chỉ định tài nguyên dưới dạng 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

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

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

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

Một chuỗi ký tự có đường dẫn và tên 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 liên tục 10 phút. handlerBehaviorChanged là một lệnh gọi hàm tốn kém không nên được gọi thường xuyên.

Giá trị

Phương thức

handlerBehaviorChanged()

Cam kết

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 chặ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 rất tốn kém. Đừng gọi điện 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ề

Promise<void>

Chrome 116 trở lên

Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến 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 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 bị bỏ qua. Đ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 đó, bạn có thể dùng chúng để liên kết nhiều sự kiện 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 này 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ử thách đó. Nếu bạn cung cấp thông tin đăng nhập không hợp lệ của người dùng, hệ thống có thể gọi phương thức này nhiều lần cho cùng một yêu cầu. Lưu ý: Bạn chỉ được 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
  - người thách đấu
    
    đối tượng
    
    Máy chủ yêu cầu xác thực.
    
    người tổ chức
    
    string
    
    cổng
    
    number
  - 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.
  - documentLifecycle
    
    extensionTypes.DocumentLifecycle
    
    Chrome 106 trở lên
    
    Vòng đời của tài liệu.
  - frameId
    
    number
    
    Giá trị 0 cho biết yêu cầu xảy ra trong khung chính; giá trị dương cho biết mã của khung phụ nơi yêu cầu xảy ra. 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ã 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
    
    Chrome 106 trở lên
    
    Loại khung hình xuất hiện 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 nơi đưa ra yêu cầu. Điều này không thay đổi qua các lệnh chuyển hướng. Nếu đây là một nguồn gốc không rõ ràng, thì chuỗi "null" (null) sẽ được sử dụng.
  - isProxy
    
    boolean
    
    "True" đối với Proxy-Auth, còn đối với phương thức xác thực www.." là "false".
  - method
    
    string
    
    Phương thức HTTP tiêu 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 mẹ sở hữu khung này. Tuỳ chọn này không được đặt nếu không có cha mẹ.
  - parentFrameId
    
    number
    
    Mã của khung bao bọc khung đã gửi yêu cầu. Đặt thành -1 nếu không có khung mẹ nào.
  - 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 đó, bạn có thể dùng chúng để liên kết nhiều sự kiện 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
    
    Cơ chế xác thực (ví dụ: Cơ bản hoặc Chuỗi đại diện).
  - statusCode
    
    number
    
    Chrome 43 trở lên
    
    Mã trạng thái HTTP tiêu 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 chuỗi 'HTTP/0.9 200 OK' cho phản hồi HTTP/0.9 (tức là các 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
    
    number
    
    Mã của thẻ nơi yêu cầu diễn ra. Đặt thành -1 nếu yêu cầu không liên quan đến một thẻ.
  - timeStamp
    
    number
    
    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 tài nguyên được yêu cầu sẽ được sử dụng.
  - 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
```
  - phản hồi
    
    BlockingResponse
- giá trị trả về
  BlockingResponse|không xác định
  
  Nếu bạn chỉ định chế độ "chặn" trong thông số "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 một 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.
  - documentLifecycle
    
    extensionTypes.DocumentLifecycle
    
    Chrome 106 trở lên
    
    Vòng đời của tài liệu.
  - frameId
    
    number
    
    Giá trị 0 cho biết yêu cầu xảy ra trong khung chính; giá trị dương cho biết mã của khung phụ nơi yêu cầu xảy ra. 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ã 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
    
    Chrome 106 trở lên
    
    Loại khung hình xuất hiện 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 nơi đưa ra yêu cầu. Điều này không thay đổi qua các lệnh chuyển hướng. Nếu đây là một nguồn gốc không rõ ràng, thì chuỗi "null" (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 tới. Xin lưu ý rằng đó có thể là một địa chỉ IPv6 cố định.
  - method
    
    string
    
    Phương thức HTTP tiêu 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 mẹ sở hữu khung này. Tuỳ chọn này không được đặt nếu không có cha mẹ.
  - parentFrameId
    
    number
    
    Mã của khung bao bọc khung đã gửi yêu cầu. Đặt thành -1 nếu không có khung mẹ nào.
  - 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 đó, bạn có thể dùng chúng để liên kết nhiều sự kiện 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
    
    number
    
    Mã trạng thái HTTP tiêu 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 chuỗi 'HTTP/0.9 200 OK' cho phản hồi HTTP/0.9 (tức là các 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
    
    number
    
    Mã của thẻ nơi yêu cầu diễn ra. Đặt thành -1 nếu yêu cầu không liên quan đến một thẻ.
  - timeStamp
    
    number
    
    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 tài nguyên được yêu cầu sẽ được sử dụng.
  - 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 không bắt buộc
    
    Chrome 106 trở lên
    
    Vòng đời của tài liệu.
  - frameId
    
    number
    
    Giá trị 0 cho biết yêu cầu xảy ra trong khung chính; giá trị dương cho biết mã của khung phụ nơi yêu cầu xảy ra. 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ã 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 không bắt buộc
    
    Chrome 106 trở lên
    
    Loại khung hình xuất hiện 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 nơi đưa ra yêu cầu. Điều này không thay đổi qua các lệnh chuyển hướng. Nếu đây là một nguồn gốc không rõ ràng, thì chuỗi "null" (null) sẽ được sử dụng.
  - method
    
    string
    
    Phương thức HTTP tiêu 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 mẹ sở hữu khung này. Tuỳ chọn này không được đặt nếu không có cha mẹ.
  - parentFrameId
    
    number
    
    Mã của khung bao bọc khung đã gửi yêu cầu. Đặt thành -1 nếu không có khung mẹ nào.
  - 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 nội dung của 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-urlcoded, thì từ điển này sẽ có sẵn và mỗi khoá đều chứa danh sách tất cả giá trị của khoá đó. Nếu dữ liệu thuộc một loại nội dung nghe nhìn khác hoặc không đúng định dạng thì sẽ không có từ điển. Một 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 yêu cầu chưa được phân tích 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 đó, bạn có thể dùng chúng để liên kết nhiều sự kiện của cùng một yêu cầu.
  - tabId
    
    number
    
    Mã của thẻ nơi yêu cầu diễn ra. Đặt thành -1 nếu yêu cầu không liên quan đến một thẻ.
  - timeStamp
    
    number
    
    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 tài nguyên được yêu cầu sẽ được sử dụng.
  - url
    
    string
- giá trị trả về
  BlockingResponse|không xác định
  
  Nếu bạn chỉ định chế độ "chặn" trong thông số "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 với máy chủ, nhưng trước khi bất kỳ dữ liệu HTTP nào được gửi đ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.
  - documentLifecycle
    
    extensionTypes.DocumentLifecycle
    
    Chrome 106 trở lên
    
    Vòng đời của tài liệu.
  - frameId
    
    number
    
    Giá trị 0 cho biết yêu cầu xảy ra trong khung chính; giá trị dương cho biết mã của khung phụ nơi yêu cầu xảy ra. 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ã 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
    
    Chrome 106 trở lên
    
    Loại khung hình xuất hiện 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 nơi đưa ra yêu cầu. Điều này không thay đổi qua các lệnh chuyển hướng. Nếu đây là một nguồn gốc không rõ ràng, thì chuỗi "null" (null) sẽ được sử dụng.
  - method
    
    string
    
    Phương thức HTTP tiêu 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 mẹ sở hữu khung này. Tuỳ chọn này không được đặt nếu không có cha mẹ.
  - parentFrameId
    
    number
    
    Mã của khung bao bọc khung đã gửi yêu cầu. Đặt thành -1 nếu không có khung mẹ nào.
  - requestHeaders
    
    HttpHeaders không bắt buộc
    
    Tiêu đề của yêu cầu HTTP sẽ đượ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 đó, bạn có thể dùng chúng để liên kết nhiều sự kiện của cùng một yêu cầu.
  - tabId
    
    number
    
    Mã của thẻ nơi yêu cầu diễn ra. Đặt thành -1 nếu yêu cầu không liên quan đến một thẻ.
  - timeStamp
    
    number
    
    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 tài nguyên được yêu cầu sẽ được sử dụng.
  - url
    
    string
- giá trị trả về
  BlockingResponse|không xác định
  
  Nếu bạn chỉ định chế độ "chặn" trong thông số "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 yêu cầu được hoàn tấ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.
  - documentLifecycle
    
    extensionTypes.DocumentLifecycle
    
    Chrome 106 trở lên
    
    Vòng đời của tài liệu.
  - frameId
    
    number
    
    Giá trị 0 cho biết yêu cầu xảy ra trong khung chính; giá trị dương cho biết mã của khung phụ nơi yêu cầu xảy ra. 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ã 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
    
    Chrome 106 trở lên
    
    Loại khung hình xuất hiện 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 nơi đưa ra yêu cầu. Điều này không thay đổi qua các lệnh chuyển hướng. Nếu đây là một nguồn gốc không rõ ràng, thì chuỗi "null" (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 tới. Xin lưu ý rằng đó có thể là một địa chỉ IPv6 cố định.
  - method
    
    string
    
    Phương thức HTTP tiêu 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 mẹ sở hữu khung này. Tuỳ chọn này không được đặt nếu không có cha mẹ.
  - parentFrameId
    
    number
    
    Mã của khung bao bọc khung đã gửi yêu cầu. Đặt thành -1 nếu không có khung mẹ nào.
  - 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 đó, bạn có thể dùng chúng để liên kết nhiều sự kiện 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
    
    number
    
    Mã trạng thái HTTP tiêu 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 chuỗi 'HTTP/0.9 200 OK' cho phản hồi HTTP/0.9 (tức là các 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
    
    number
    
    Mã của thẻ nơi yêu cầu diễn ra. Đặt thành -1 nếu yêu cầu không liên quan đến một thẻ.
  - timeStamp
    
    number
    
    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 tài nguyên được yêu cầu sẽ được sử dụng.
  - 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à thành phần điều hướng trong một khung.
  - documentLifecycle
    
    extensionTypes.DocumentLifecycle
    
    Chrome 106 trở lên
    
    Vòng đời của tài liệu.
  - error
    
    string
    
    Nội dung mô tả lỗi. Chuỗi này không đảm bảo sẽ 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 thông báo.
  - frameId
    
    number
    
    Giá trị 0 cho biết yêu cầu xảy ra trong khung chính; giá trị dương cho biết mã của khung phụ nơi yêu cầu xảy ra. 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ã 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
    
    Chrome 106 trở lên
    
    Loại khung hình xuất hiện 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 nơi đưa ra yêu cầu. Điều này không thay đổi qua các lệnh chuyển hướng. Nếu đây là một nguồn gốc không rõ ràng, thì chuỗi "null" (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 tới. Xin lưu ý rằng đó có thể là một địa chỉ IPv6 cố định.
  - method
    
    string
    
    Phương thức HTTP tiêu 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 mẹ sở hữu khung này. Tuỳ chọn này không được đặt nếu không có cha mẹ.
  - parentFrameId
    
    number
    
    Mã của khung bao bọc khung đã gửi yêu cầu. Đặt thành -1 nếu không có khung mẹ nào.
  - 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 đó, bạn có thể dùng chúng để liên kết nhiều sự kiện của cùng một yêu cầu.
  - tabId
    
    number
    
    Mã của thẻ nơi yêu cầu diễn ra. Đặt thành -1 nếu yêu cầu không liên quan đến một thẻ.
  - timeStamp
    
    number
    
    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 tài nguyên được yêu cầu sẽ được sử dụng.
  - 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.
  - documentLifecycle
    
    extensionTypes.DocumentLifecycle
    
    Chrome 106 trở lên
    
    Vòng đời của tài liệu.
  - frameId
    
    number
    
    Giá trị 0 cho biết yêu cầu xảy ra trong khung chính; giá trị dương cho biết mã của khung phụ nơi yêu cầu xảy ra. 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ã 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
    
    Chrome 106 trở lên
    
    Loại khung hình xuất hiện 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 nơi đưa ra yêu cầu. Điều này không thay đổi qua các lệnh chuyển hướng. Nếu đây là một nguồn gốc không rõ ràng, thì chuỗi "null" (null) sẽ được sử dụng.
  - method
    
    string
    
    Phương thức HTTP tiêu 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 mẹ sở hữu khung này. Tuỳ chọn này không được đặt nếu không có cha mẹ.
  - parentFrameId
    
    number
    
    Mã của khung bao bọc khung đã gửi yêu cầu. Đặt thành -1 nếu không có khung mẹ nào.
  - 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 đó, bạn có thể dùng chúng để liên kết nhiều sự kiện của cùng một yêu cầu.
  - responseHeaders
    
    HttpHeaders không bắt buộc
    
    Tiêu đề phản hồi HTTP đã nhận được cùng với phản hồi này.
  - statusCode
    
    number
    
    Chrome 43 trở lên
    
    Mã trạng thái HTTP tiêu 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 chuỗi 'HTTP/0.9 200 OK' cho phản hồi HTTP/0.9 (tức là các phản hồi thiếu dòng trạng thái).
  - tabId
    
    number
    
    Mã của thẻ nơi yêu cầu diễn ra. Đặt thành -1 nếu yêu cầu không liên quan đến một thẻ.
  - timeStamp
    
    number
    
    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 tài nguyên được yêu cầu sẽ được sử dụng.
  - url
    
    string
- giá trị trả về
  BlockingResponse|không xác định
  
  Nếu bạn chỉ định chế độ "chặn" trong thông số "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 có sẵn.

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.
  - documentLifecycle
    
    extensionTypes.DocumentLifecycle
    
    Chrome 106 trở lên
    
    Vòng đời của tài liệu.
  - frameId
    
    number
    
    Giá trị 0 cho biết yêu cầu xảy ra trong khung chính; giá trị dương cho biết mã của khung phụ nơi yêu cầu xảy ra. 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ã 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
    
    Chrome 106 trở lên
    
    Loại khung hình xuất hiện 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 nơi đưa ra yêu cầu. Điều này không thay đổi qua các lệnh chuyển hướng. Nếu đây là một nguồn gốc không rõ ràng, thì chuỗi "null" (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 tới. Xin lưu ý rằng đó có thể là một địa chỉ IPv6 cố định.
  - method
    
    string
    
    Phương thức HTTP tiêu 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 mẹ sở hữu khung này. Tuỳ chọn này không được đặt nếu không có cha mẹ.
  - parentFrameId
    
    number
    
    Mã của khung bao bọc khung đã gửi yêu cầu. Đặt thành -1 nếu không có khung mẹ nào.
  - 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 đó, bạn có thể dùng chúng để liên kết nhiều sự kiện 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
    
    number
    
    Mã trạng thái HTTP tiêu 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 chuỗi 'HTTP/0.9 200 OK' cho phản hồi HTTP/0.9 (tức là các 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
    
    number
    
    Mã của thẻ nơi yêu cầu diễn ra. Đặt thành -1 nếu yêu cầu không liên quan đến một thẻ.
  - timeStamp
    
    number
    
    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 tài nguyên được yêu cầu sẽ được sử dụng.
  - 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 được gửi đến máy chủ (các nội dung sửa đổi của lệnh gọi lại onBeforeSendHeaders trước đó hiển thị vào thời điểm kích hoạt onSendHeaders).

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.
  - documentLifecycle
    
    extensionTypes.DocumentLifecycle
    
    Chrome 106 trở lên
    
    Vòng đời của tài liệu.
  - frameId
    
    number
    
    Giá trị 0 cho biết yêu cầu xảy ra trong khung chính; giá trị dương cho biết mã của khung phụ nơi yêu cầu xảy ra. 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ã 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
    
    Chrome 106 trở lên
    
    Loại khung hình xuất hiện 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 nơi đưa ra yêu cầu. Điều này không thay đổi qua các lệnh chuyển hướng. Nếu đây là một nguồn gốc không rõ ràng, thì chuỗi "null" (null) sẽ được sử dụng.
  - method
    
    string
    
    Phương thức HTTP tiêu 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 mẹ sở hữu khung này. Tuỳ chọn này không được đặt nếu không có cha mẹ.
  - parentFrameId
    
    number
    
    Mã của khung bao bọc khung đã gửi yêu cầu. Đặt thành -1 nếu không có khung mẹ nào.
  - 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 đó, bạn có thể dùng chúng để liên kết nhiều sự kiện của cùng một yêu cầu.
  - tabId
    
    number
    
    Mã của thẻ nơi yêu cầu diễn ra. Đặt thành -1 nếu yêu cầu không liên quan đến một thẻ.
  - timeStamp
    
    number
    
    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 tài nguyên được yêu cầu sẽ được sử dụng.
  - url
    
    string
filter

RequestFilter
extraInfoSpec

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