browser.webRequest

Mô tả

Sử dụng API chrome.webRequest để quan sát và phân tích lưu lượng truy cập, đồng thời 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ủ lưu trữ cần thiết. Để chặn 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 của URL đó. Ví dụ:

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

webRequestBlocking

Bắt buộc để đă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 cài đặt theo chính sách.

webRequestAuthProvider

Bắt buộc phải sử dụng phương thức onAuthRequired. 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 yêu cầu

API yêu cầu web xác định một tập hợp các sự kiệ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 cho các yêu cầu thành công được minh hoạ dưới đây, theo sau là định nghĩa về sự kiện:

Vòng đời của một yêu cầu web theo góc nhìn của API webrequest

onBeforeRequest (đồng bộ không bắt buộc)
Kích hoạt khi sắp có yêu cầu. Sự kiện này được gửi trước khi có bất kỳ kết nối TCP nào và có thể được dùng để huỷ hoặc chuyển hướng yêu cầu.
onBeforeSendHeaders (đồng bộ không bắt buộc)
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 này nhằm cho phép các tiện ích thêm, sửa đổi và xoá tiêu đề của yêu cầu (*). Sự kiện onBeforeSendHeaders được truyền đến tất cả người đăng ký, vì vậy, những người đăng ký khác nhau có thể cố gắng sửa đổi yêu cầu; hãy xem phần Thông tin chi tiết về cách triển khai để biết cách xử lý vấn đề này. Sự kiện này có thể được dùng để 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 đề của yêu cầu và trình bày phiên bản cuối cùng (*). Sự kiện này được kích hoạt trước khi các tiêu đề được gửi đến mạng. Sự kiện này mang tính cung cấp thông tin và được xử lý không đồng bộ. Bạn không thể sửa đổi hoặc huỷ yêu cầu.
onHeadersReceived (đồng bộ không bắt buộc)
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à yêu cầu 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 đến. Các lệnh lưu vào bộ nhớ đệm được xử lý trước khi sự kiện này được kích hoạt, vì vậy, việc sửa đổi các tiêu đề như Cache-Control không ảnh hưởng đến bộ nhớ đệm của trình duyệt. Nó cũng cho phép bạn huỷ hoặc chuyển hướng yêu cầu.
onAuthRequired (đồng bộ không bắt buộc)
Kích hoạt khi một yêu cầu cần người dùng xác thực. Bạn có thể xử lý sự kiện này một cách đồ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 xác thực không hợp lệ. Hãy cẩn thận để không rơi vào 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ệ. Bạn cũng có thể dùng mã này để huỷ yêu cầu.
onBeforeRedirect
Kích hoạt khi sắp thực hiện lệnh chuyển hướng. Mã phản hồi HTTP hoặc một tiện ích có thể kích hoạt lệnh chuyển hướng. Sự kiện này mang tính thông tin và được xử lý không đồng bộ. Bạn không thể 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 chỉ mang tính thông tin và được xử lý không đồng bộ. Bạn không thể 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 một 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, ngoại trừ một trường hợp: Nếu một yêu cầu được chuyển hướng đến một URL data://, thì onBeforeRedirect sẽ 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 một bản tóm tắt về bộ phần cứng và phần mềm 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 từ một tệp lớn) hoặc có thể được xử lý bằng bộ phần cứng và phần mềm mạng 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 không thể 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 hiện không được cung cấp cho sự kiện onBeforeSendHeaders. Danh sách này không đảm bảo là đầy đủ hoặc ổn định.

  • Uỷ quyền
  • Cache-Control
  • Kết nối
  • Độ dài nội dung
  • Máy chủ
  • If-Modified-Since
  • If-None-Match
  • If-Range
  • Dữ liệu một phần
  • Pragma
  • Proxy-Authorization
  • Proxy-Connection
  • Mã hoá chuyển giao

Kể từ Chrome 79, việc sửa đổi tiêu đề của yêu cầu sẽ ảnh hưởng đến việc kiểm tra Chia sẻ tài nguyên khác nguồn gốc (CORS). Nếu tiêu đề đã sửa đổi cho các yêu cầu khác nguồn gốc không đáp ứng tiêu chí, thì hệ thống sẽ gửi một yêu cầu kiểm tra CORS preflight để 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, 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 có tác dụng đánh lừa các bước kiểm tra CORS. Nếu cần lừa giao thức CORS, bạn cũng cần chỉ định 'extraHeaders' cho các nội dung 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 kiểm tra trước CORS. Tiện ích có thể thấy yêu cầu kiểm tra CORS cho một URL yêu cầu nếu có một trình nghe có 'extraHeaders' được chỉ định trong opt_extraInfoSpec cho URL yêu cầu đó. onBeforeRequest cũng có thể mất 'extraHeaders' từ Chrome 79.

Kể từ Chrome 79, 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 xoá nếu không chỉ định 'extraHeaders' trong opt_extraInfoSpec:

  • Điểm gốc

Kể từ Chrome 72, nếu cần sửa đổi phản hồi trước khi Chặn đọc 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 đề yêu cầu sau đây 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:

  • Accept-Language
  • Chấp nhận mã hoá
  • Referer
  • Cookie

Kể từ Chrome 72, tiêu đề phản hồi Set-Cookie 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.

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ủ lưu trữ. Hơn nữa, chỉ có thể truy cập vào các lượ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 đồ nêu trên cũng bị ẩn. Các yêu cầu 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 liên quan đến chức năng của trình duyệt. Ngoài ra, các XMLHttpRequest đồng bộ từ tiện ích của bạn cũng bị ẩn khỏi trình xử lý sự kiện chặn để ngăn chặn tình trạng tắc nghẽn. Xin lưu ý rằng đối với một số lược đồ được hỗ trợ, nhóm 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 lược đồ file:, chỉ có thể gửi onBeforeRequest, onResponseStarted, onCompleted và onErrorOccurred.

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

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

Yêu cầu WebSocket không hỗ trợ lệnh chuyển hướng.

Kể từ Chrome 72, một tiện ích chỉ có thể chặn 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 khởi tạo yêu cầu.

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

  • Sau khi phiên được thiết lập, các tiện ích không thể quan sát hoặc can thiệp vào phiên thông qua API webRequest.
  • Thao tác sửa đổi tiêu đề của yêu cầu HTTP trong onBeforeSendHeaders sẽ bị bỏ qua.
  • Tính năng 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ã nhận dạng này là duy nhất trong một phiên trình duyệt và bối cảnh của một tiện ích. Giá trị này không đổi trong suốt vòng đời của một yêu cầu và có thể 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 đượ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ể của 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ố 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:

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

Mỗi lệnh gọi addListener() đều lấy 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ỉ được phép cho 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ề một webRequest.BlockingResponse 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 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), thì tiện ích có thể tạo webRequest.BlockingResponse không đồng bộ.

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

URL
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 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. Trường này được 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"
  ]
}

Xin lưu ý rằng bạn không cần có quyền này đối với tiện ích được cài đặt theo chính sách có quyền "webRequestBlocking".

Cách cung cấp thông tin đăng nhập đồng bộ:

browser.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 đăng nhập không đồng bộ:

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

Thông tin chi tiết về việc triển khai

Một số thông tin chi tiết về việc triển khai có thể quan trọng 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 đượ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 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 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 ghi lại 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 đượ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, tất cả tiện ích sẽ được thông báo bằng sự kiện onErrorOccurred. Mỗi lần chỉ có một tiện ích có thể chuyển hướng một yêu cầu hoặc sửa đổi một 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ẽ 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.

Đang lưu vào bộ nhớ đệm

Chrome sử dụng hai bộ nhớ đệm: bộ nhớ đệm của ổ đĩa và bộ nhớ đệm của bộ nhớ rất nhanh. Vòng đời của bộ nhớ đệm của bộ nhớ gắn liền với vòng đời của một quy trình kết xuất, tương ứng với một thẻ. Các yêu cầu được trả lời từ bộ nhớ đệm của 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 nó (ví dụ: hành vi theo đó các yêu cầu bị chặn), thì một lần 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 thay đổi về hành vi được áp dụng, hãy gọi handlerBehaviorChanged() để xoá bộ nhớ đệm của bộ nhớ. Tuy nhiên, đừng làm việc này thường xuyên vì 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 nhất quán trong nội bộ. Việc so sánh một sự kiện với một sự kiện khác sẽ cho bạn biết độ 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 bên trong tiện ích (ví dụ: thông qua (new Date()).getTime()) có thể cho ra kết quả không mong muốn.

Xử lý lỗi

Nếu bạn cố gắng đăng ký một sự kiện có đối số không hợp lệ, thì lỗi JavaScript sẽ được gửi 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 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 đây minh hoạ cách chặn tất cả yêu cầu đến www.evil.com:

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

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

Ví dụ sau đây đạ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 đến www.evil.com không cần được chuyển đến tiện ích:

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

Ví dụ sau đây minh hoạ cách xoá tiêu đề User-Agent khỏi tất cả yêu cầu:

browser.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 browser.webRequest, hãy cài đặt mẫu webRequest từ kho lưu trữ chrome-extension-samples.

Loại

BlockingResponse

Trả về giá trị cho các trình xử lý sự kiện có áp dụng extraInfoSpec "blocking". 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

    object 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 được cung cấp.

    • mật khẩu

      chuỗi

    • tên người dùng

      chuỗi

  • hủy

    boolean không bắt buộc

    Nếu đúng, yêu cầu sẽ bị huỷ. Điều này ngăn không cho yêu cầu được gửi. Bạn có thể dùng thuộc tính này để phản hồi 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, thì yêu cầu ban đầu sẽ không được gửi/hoàn tất mà đượ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 bắt đầu sẽ 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 đưa ra bằng phương thức GET. Lệnh chuyển hướng từ 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 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 đề để giới hạn số lượng xung đột (mỗi yêu cầu chỉ có thể sửa đổi responseHeaders một lần).

FormDataItem

Chrome 66 trở lên browser.* kể từ Chrome 148

Chứa dữ liệu được truyền trong dữ liệu biểu mẫu. Đối với biểu mẫu được mã hoá URL, dữ liệu sẽ đượ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 nếu không phải. Đối với dữ liệu biểu mẫu, đó là ArrayBuffer. Nếu dữ liệu biểu mẫu đại diện cho 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

chuỗi

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 không thể 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

    chuỗi

    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 có thể được biểu thị bằng UTF-8.

IgnoredActionType

Chrome 70 trở lên browser.* kể từ Chrome 148

Enum

"redirect"

"request_headers"

"response_headers"

"auth_credentials"

OnAuthRequiredOptions

Trình duyệt Chrome 44 trở lên .* kể từ Chrome 148

Enum

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

"blocking"
Chỉ định rằng 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 các tiêu đề có thể vi phạm quy tắc Chia sẻ tài nguyên khác nguồn gốc (CORS).

OnBeforeRedirectOptions

Trình duyệt Chrome 44 trở lên .* kể từ Chrome 148

Enum

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

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

OnBeforeRequestOptions

Trình duyệt Chrome 44 trở lên .* kể từ Chrome 148

Enum

"blocking"
Chỉ định rằng 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 phải được đưa vào sự kiện.

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

OnBeforeSendHeadersOptions

Trình duyệt Chrome 44 trở lên .* kể từ Chrome 148

Enum

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

"blocking"
Chỉ định rằng 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 tắc Chia sẻ tài nguyên khác nguồn gốc (CORS).

OnCompletedOptions

Trình duyệt Chrome 44 trở lên .* kể từ Chrome 148

Enum

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

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

OnErrorOccurredOptions

Chrome 79 trở lên browser.* kể từ Chrome 148

Giá trị

"extraHeaders"

OnHeadersReceivedOptions

Trình duyệt Chrome 44 trở lên .* kể từ Chrome 148

Enum

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

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

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

"securityInfo"
Chỉ định rằng SecurityInfo phải được đưa vào sự kiện.

"securityInfoRawDer"
Chỉ định rằng SecurityInfo có byte thô của chứng chỉ phải được đưa vào sự kiện.

OnResponseStartedOptions

Trình duyệt Chrome 44 trở lên .* kể từ Chrome 148

Enum

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

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

OnSendHeadersOptions

Trình duyệt Chrome 44 trở lên .* kể từ Chrome 148

Enum

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

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

RequestFilter

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

Thuộc tính

  • tabId

    number 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 khớp với bất kỳ loại nào sẽ bị lọc ra.

  • url

    string[]

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

  • windowId

    number không bắt buộc

ResourceType

Trình duyệt Chrome 44 trở lên .* kể từ Chrome 148

Enum

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

"sub_frame"
Chỉ định tài nguyên dưới dạng khung phụ.

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

"script"
Chỉ định tài nguyên là một tập lệnh.

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

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

"object"
Chỉ định tài nguyên dưới dạng một đối tượng.

"xmlhttprequest"
Chỉ định tài nguyên là một XMLHttpRequest.

"ping"
Chỉ định tài nguyên dưới dạng 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 dưới dạng đối tượng nội dung nghe nhì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 là một loại không có trong các loại được liệt kê.

SecurityInfo

Chrome 144 trở lên browser.* kể từ Chrome 148

Thuộc tính

  • chứng chỉ

    object[]

    Danh sách chứng chỉ

    • vân tay

      đối tượng

      Dấu vân tay của chứng chỉ.

      • sha256

        chuỗi

        vân tay số sha256 của chứng chỉ.

    • rawDER

      Không bắt buộc ArrayBuffer

      Byte thô của chứng chỉ máy chủ được mã hoá DER

  • tiểu bang

    chuỗi

    Trạng thái của kết nối. Một trong các giá trị secure, insecure, broken.

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 của 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 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()

browser.webRequest.handlerBehaviorChanged(): Promise<void>

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 tốn nhiều tài nguyên. Đừng gọi hàm này thường xuyên.

Giá trị trả về

  • Promise<void>

    Chrome 116 trở lên browser.* kể từ Chrome 148

Sự kiện

onActionIgnored

Chrome 70 trở lên browser.* kể từ Chrome 148 
browser.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 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.

Thông số

  • callback

    hàm

    Tham số callback 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

        chuỗi

        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ể sử dụng các giá trị này để liên kết các sự kiện khác nhau của cùng một yêu cầu.

onAuthRequired

browser.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ó 3 lựa chọn: cung cấp thông tin xác thực, huỷ yêu cầu và hiển thị trang lỗi hoặc không làm gì cả. Nếu thông tin đăng nhập của người dùng không hợp lệ, thì phương thức 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ỉ được chỉ định một trong hai chế độ 'blocking' hoặc 'asyncBlocking' trong tham số extraInfoSpec.

Thông số

  • callback

    hàm

    Tham số callback 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

          chuỗi

        • cổng

          số

      • documentId

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

        Chrome 106 trở lên browser.* kể từ Chrome 148

        UUID của tài liệu đưa ra yêu cầu.

      • Chrome 106 trở lên browser.* kể từ Chrome 148

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

      • frameId

        số

        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ã nhận dạng 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), thì frameId cho biết mã nhận dạng của khung này, chứ không phải mã nhận dạng của khung bên ngoài. Mã khung là duy nhất trong một thẻ.

      • Chrome 106 trở lên browser.* kể từ Chrome 148

        Loại khung mà yêu cầu xảy ra.

      • bên khởi xướng

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

        Chrome 63 trở lên trình duyệt.* kể từ Chrome 148

        Nguồn gốc nơi yêu cầu được bắt đầu. Điều này không thay đổi thông qua lệnh chuyển hướng. Nếu đây là một nguồn gốc mờ, chuỗi "null" sẽ được sử dụng.

      • isProxy

        boolean

        True cho Proxy-Authenticate, false cho WWW-Authenticate.

      • method

        chuỗi

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

      • parentDocumentId

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

        Chrome 106 trở lên browser.* kể từ Chrome 148

        UUID của tài liệu mẹ sở hữu khung này. Trường này không được đặt nếu không có phần tử 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 mẹ.

      • realm

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

        Phạm vi xác thực do máy chủ cung cấp (nếu có).

      • requestId

        chuỗi

        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ể sử dụng các giá trị này để liên kết 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

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

      • lược đồ

        chuỗi

        Giao thức xác thực, ví dụ: Cơ bản hoặc Chuỗi đại diện.

      • statusCode

        số

        Chrome 43 trở lên trình duyệt.* kể từ Chrome 148

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

      • statusLine

        chuỗi

        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à 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ã nhận dạng 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 thẻ.

      • timeStamp

        số

        Thời điểm 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

        chuỗi

    • asyncCallback

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

      Trình duyệt Chrome 58 trở lên .* kể từ Chrome 148

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

      (response: BlockingResponse) => void

    • returns

      BlockingResponse | undefined

      Nếu bạn chỉ định "blocking" trong tham 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

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

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

Thông số

  • callback

    hàm

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

    (details: object) => void

    • chi tiết

      đối tượng

      • documentId

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

        Chrome 106 trở lên browser.* kể từ Chrome 148

        UUID của tài liệu đưa ra yêu cầu.

      • Chrome 106 trở lên browser.* kể từ Chrome 148

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

      • frameId

        số

        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ã nhận dạng 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), thì frameId cho biết mã nhận dạng của khung này, chứ không phải mã nhận dạng của khung bên ngoài. Mã khung là duy nhất trong một thẻ.

      • Chrome 106 trở lên browser.* kể từ Chrome 148

        Loại khung mà yêu cầu xảy ra.

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

      • bên khởi xướng

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

        Chrome 63 trở lên trình duyệt.* kể từ Chrome 148

        Nguồn gốc nơi yêu cầu được bắt đầu. Điều này không thay đổi thông qua lệnh chuyển hướng. Nếu đây là một nguồn gốc mờ, 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 đây có thể là địa chỉ IPv6 cố định.

      • method

        chuỗi

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

      • parentDocumentId

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

        Chrome 106 trở lên browser.* kể từ Chrome 148

        UUID của tài liệu mẹ sở hữu khung này. Trường này không được đặt nếu không có phần tử 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 mẹ.

      • redirectUrl

        chuỗi

        URL mới.

      • requestId

        chuỗi

        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ể sử dụng các giá trị này để liên kết 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

        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 do máy chủ trả về.

      • statusLine

        chuỗi

        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à 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ã nhận dạng 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 thẻ.

      • timeStamp

        số

        Thời điểm 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

        chuỗi

  • filter

    RequestFilter

  • extraInfoSpec

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

onBeforeRequest

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

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

Thông số

  • callback

    hàm

    Tham số callback 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 browser.* kể từ Chrome 148

        UUID của tài liệu đưa ra yêu cầu.

      • documentLifecycle

        extensionTypes.DocumentLifecycle không bắt buộc

        Chrome 106 trở lên browser.* kể từ Chrome 148

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

      • frameId

        số

        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ã nhận dạng 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), thì frameId cho biết mã nhận dạng của khung này, chứ không phải mã nhận dạng 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 browser.* kể từ Chrome 148

        Loại khung mà yêu cầu xảy ra.

      • bên khởi xướng

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

        Chrome 63 trở lên trình duyệt.* kể từ Chrome 148

        Nguồn gốc nơi yêu cầu được bắt đầu. Điều này không thay đổi thông qua lệnh chuyển hướng. Nếu đây là một nguồn gốc mờ, chuỗi "null" sẽ được sử dụng.

      • method

        chuỗi

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

      • parentDocumentId

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

        Chrome 106 trở lên browser.* kể từ Chrome 148

        UUID của tài liệu mẹ sở hữu khung này. Trường này không được đặt nếu không có phần tử 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 mẹ.

      • requestBody

        object không bắt buộc

        Chứa dữ liệu nội dung 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 lấy dữ liệu nội dung yêu cầu.

        • formData

          object không bắt buộc

          Nếu phương thức yêu cầu là POST và phần 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-urlencoded, thì từ điển này sẽ xuất hiện và đối với mỗi khoá, từ điển này sẽ chứa danh sách tất cả giá trị cho khoá đó. Nếu dữ liệu thuộc loại nội dung nghe nhì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. Ví dụ về giá trị 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 cú pháp sẽ nằm trong mảng này.

      • requestId

        chuỗi

        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ể sử dụng các giá trị này để liên kết các sự kiện khác nhau của cùng một yêu cầu.

      • tabId

        số

        Mã nhận dạng 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 thẻ.

      • timeStamp

        số

        Thời điểm 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

        chuỗi

    • returns

      BlockingResponse | undefined

      Nếu bạn chỉ định "blocking" trong tham 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

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

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

Thông số

  • callback

    hàm

    Tham số callback 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 browser.* kể từ Chrome 148

        UUID của tài liệu đưa ra yêu cầu.

      • Chrome 106 trở lên browser.* kể từ Chrome 148

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

      • frameId

        số

        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ã nhận dạng 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), thì frameId cho biết mã nhận dạng của khung này, chứ không phải mã nhận dạng của khung bên ngoài. Mã khung là duy nhất trong một thẻ.

      • Chrome 106 trở lên browser.* kể từ Chrome 148

        Loại khung mà yêu cầu xảy ra.

      • bên khởi xướng

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

        Chrome 63 trở lên trình duyệt.* kể từ Chrome 148

        Nguồn gốc nơi yêu cầu được bắt đầu. Điều này không thay đổi thông qua lệnh chuyển hướng. Nếu đây là một nguồn gốc mờ, chuỗi "null" sẽ được sử dụng.

      • method

        chuỗi

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

      • parentDocumentId

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

        Chrome 106 trở lên browser.* kể từ Chrome 148

        UUID của tài liệu mẹ sở hữu khung này. Trường này không được đặt nếu không có phần tử 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 mẹ.

      • 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

        chuỗi

        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ể sử dụng các giá trị này để liên kết các sự kiện khác nhau của cùng một yêu cầu.

      • tabId

        số

        Mã nhận dạng 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 thẻ.

      • timeStamp

        số

        Thời điểm 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

        chuỗi

    • returns

      BlockingResponse | undefined

      Nếu bạn chỉ định "blocking" trong tham 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

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

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

Thông số

  • callback

    hàm

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

    (details: object) => void

    • chi tiết

      đối tượng

      • documentId

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

        Chrome 106 trở lên browser.* kể từ Chrome 148

        UUID của tài liệu đưa ra yêu cầu.

      • Chrome 106 trở lên browser.* kể từ Chrome 148

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

      • frameId

        số

        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ã nhận dạng 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), thì frameId cho biết mã nhận dạng của khung này, chứ không phải mã nhận dạng của khung bên ngoài. Mã khung là duy nhất trong một thẻ.

      • Chrome 106 trở lên browser.* kể từ Chrome 148

        Loại khung mà yêu cầu xảy ra.

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

      • bên khởi xướng

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

        Chrome 63 trở lên trình duyệt.* kể từ Chrome 148

        Nguồn gốc nơi yêu cầu được bắt đầu. Điều này không thay đổi thông qua lệnh chuyển hướng. Nếu đây là một nguồn gốc mờ, 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 đây có thể là địa chỉ IPv6 cố định.

      • method

        chuỗi

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

      • parentDocumentId

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

        Chrome 106 trở lên browser.* kể từ Chrome 148

        UUID của tài liệu mẹ sở hữu khung này. Trường này không được đặt nếu không có phần tử 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 mẹ.

      • requestId

        chuỗi

        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ể sử dụng các giá trị này để liên kết 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

        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 do máy chủ trả về.

      • statusLine

        chuỗi

        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à 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ã nhận dạng 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 thẻ.

      • timeStamp

        số

        Thời điểm 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

        chuỗi

  • filter

    RequestFilter

  • extraInfoSpec

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

onErrorOccurred

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

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

Thông số

  • callback

    hàm

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

    (details: object) => void

    • chi tiết

      đối tượng

      • documentId

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

        Chrome 106 trở lên browser.* kể từ Chrome 148

        UUID của tài liệu đưa ra yêu cầu. Giá trị này không xuất hiện nếu yêu cầu là thao tác điều hướng của một khung.

      • Chrome 106 trở lên browser.* kể từ Chrome 148

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

      • error

        chuỗi

        Nội dung mô tả về lỗi. Chuỗi này không được đả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 nó.

      • frameId

        số

        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ã nhận dạng 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), thì frameId cho biết mã nhận dạng của khung này, chứ không phải mã nhận dạng của khung bên ngoài. Mã khung là duy nhất trong một thẻ.

      • Chrome 106 trở lên browser.* kể từ Chrome 148

        Loại khung mà yêu cầu xảy ra.

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

      • bên khởi xướng

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

        Chrome 63 trở lên trình duyệt.* kể từ Chrome 148

        Nguồn gốc nơi yêu cầu được bắt đầu. Điều này không thay đổi thông qua lệnh chuyển hướng. Nếu đây là một nguồn gốc mờ, 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 đây có thể là địa chỉ IPv6 cố định.

      • method

        chuỗi

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

      • parentDocumentId

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

        Chrome 106 trở lên browser.* kể từ Chrome 148

        UUID của tài liệu mẹ sở hữu khung này. Trường này không được đặt nếu không có phần tử 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 mẹ.

      • requestId

        chuỗi

        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ể sử dụng các giá trị này để liên kết các sự kiện khác nhau của cùng một yêu cầu.

      • tabId

        số

        Mã nhận dạng 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 thẻ.

      • timeStamp

        số

        Thời điểm 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

        chuỗi

  • filter

    RequestFilter

  • extraInfoSpec

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

onHeadersReceived

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

Thông số

  • callback

    hàm

    Tham số callback 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 browser.* kể từ Chrome 148

        UUID của tài liệu đưa ra yêu cầu.

      • Chrome 106 trở lên browser.* kể từ Chrome 148

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

      • frameId

        số

        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ã nhận dạng 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), thì frameId cho biết mã nhận dạng của khung này, chứ không phải mã nhận dạng của khung bên ngoài. Mã khung là duy nhất trong một thẻ.

      • Chrome 106 trở lên browser.* kể từ Chrome 148

        Loại khung mà yêu cầu xảy ra.

      • bên khởi xướng

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

        Chrome 63 trở lên trình duyệt.* kể từ Chrome 148

        Nguồn gốc nơi yêu cầu được bắt đầu. Điều này không thay đổi thông qua lệnh chuyển hướng. Nếu đây là một nguồn gốc mờ, chuỗi "null" sẽ được sử dụng.

      • method

        chuỗi

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

      • parentDocumentId

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

        Chrome 106 trở lên browser.* kể từ Chrome 148

        UUID của tài liệu mẹ sở hữu khung này. Trường này không được đặt nếu không có phần tử 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 mẹ.

      • requestId

        chuỗi

        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ể sử dụng các giá trị này để liên kết 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

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

      • securityInfo

        SecurityInfo không bắt buộc

        Chrome 144 trở lên browser.* kể từ Chrome 148

        Thông tin về kết nối TLS/QUIC dùng cho kết nối cơ bản. Chỉ được cung cấp nếu securityInfo được chỉ định trong tham số extraInfoSpec.

      • statusCode

        số

        Chrome 43 trở lên trình duyệt.* kể từ Chrome 148

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

      • statusLine

        chuỗi

        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à phản hồi thiếu dòng trạng thái).

      • tabId

        số

        Mã nhận dạng 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 thẻ.

      • timeStamp

        số

        Thời điểm 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

        chuỗi

    • returns

      BlockingResponse | undefined

      Nếu bạn chỉ định "blocking" trong tham 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

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

Thông số

  • callback

    hàm

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

    (details: object) => void

    • chi tiết

      đối tượng

      • documentId

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

        Chrome 106 trở lên browser.* kể từ Chrome 148

        UUID của tài liệu đưa ra yêu cầu.

      • Chrome 106 trở lên browser.* kể từ Chrome 148

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

      • frameId

        số

        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ã nhận dạng 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), thì frameId cho biết mã nhận dạng của khung này, chứ không phải mã nhận dạng của khung bên ngoài. Mã khung là duy nhất trong một thẻ.

      • Chrome 106 trở lên browser.* kể từ Chrome 148

        Loại khung mà yêu cầu xảy ra.

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

      • bên khởi xướng

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

        Chrome 63 trở lên trình duyệt.* kể từ Chrome 148

        Nguồn gốc nơi yêu cầu được bắt đầu. Điều này không thay đổi thông qua lệnh chuyển hướng. Nếu đây là một nguồn gốc mờ, 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 đây có thể là địa chỉ IPv6 cố định.

      • method

        chuỗi

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

      • parentDocumentId

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

        Chrome 106 trở lên browser.* kể từ Chrome 148

        UUID của tài liệu mẹ sở hữu khung này. Trường này không được đặt nếu không có phần tử 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 mẹ.

      • requestId

        chuỗi

        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ể sử dụng các giá trị này để liên kết 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

        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 do máy chủ trả về.

      • statusLine

        chuỗi

        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à 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ã nhận dạng 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 thẻ.

      • timeStamp

        số

        Thời điểm 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

        chuỗi

  • filter

    RequestFilter

  • extraInfoSpec

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

onSendHeaders

browser.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 đó sẽ xuất hiện khi onSendHeaders được kích hoạt).

Thông số

  • callback

    hàm

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

    (details: object) => void

    • chi tiết

      đối tượng

      • documentId

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

        Chrome 106 trở lên browser.* kể từ Chrome 148

        UUID của tài liệu đưa ra yêu cầu.

      • Chrome 106 trở lên browser.* kể từ Chrome 148

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

      • frameId

        số

        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ã nhận dạng 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), thì frameId cho biết mã nhận dạng của khung này, chứ không phải mã nhận dạng của khung bên ngoài. Mã khung là duy nhất trong một thẻ.

      • Chrome 106 trở lên browser.* kể từ Chrome 148

        Loại khung mà yêu cầu xảy ra.

      • bên khởi xướng

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

        Chrome 63 trở lên trình duyệt.* kể từ Chrome 148

        Nguồn gốc nơi yêu cầu được bắt đầu. Điều này không thay đổi thông qua lệnh chuyển hướng. Nếu đây là một nguồn gốc mờ, chuỗi "null" sẽ được sử dụng.

      • method

        chuỗi

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

      • parentDocumentId

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

        Chrome 106 trở lên browser.* kể từ Chrome 148

        UUID của tài liệu mẹ sở hữu khung này. Trường này không được đặt nếu không có phần tử 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 mẹ.

      • requestHeaders

        HttpHeaders không bắt buộc

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

      • requestId

        chuỗi

        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ể sử dụng các giá trị này để liên kết các sự kiện khác nhau của cùng một yêu cầu.

      • tabId

        số

        Mã nhận dạng 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 thẻ.

      • timeStamp

        số

        Thời điểm 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

        chuỗi

  • filter

    RequestFilter

  • extraInfoSpec

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