chrome.declarativeNetRequest

Mô tả

API chrome.declarativeNetRequest dùng để chặn hoặc sửa đổi các yêu cầu mạng bằng cách chỉ định các quy tắc khai báo. Điều này cho phép tiện ích sửa đổi các yêu cầu mạng mà không chặn các yêu cầu đó và xem nội dung của chúng, từ đó cung cấp nhiều quyền riêng tư hơn.

Quyền

declarativeNetRequest
declarativeNetRequestWithHostAccess

"declarativeNetRequest" và "declarativeNetRequestWithHostAccess" quyền đều cung cấp các chức năng tương tự. Sự khác biệt giữa chúng là khi quyền đã yêu cầu hoặc đã được cấp quyền.

"declarativeNetRequest"
Kích hoạt cảnh báo quyền tại thời điểm cài đặt nhưng cung cấp quyền truy cập ngầm vào Các quy tắc allow, allowAllRequests và block. Hãy sử dụng phương pháp này khi có thể để tránh cần yêu cầu toàn quyền truy cập vào máy chủ.
"declarativeNetRequestFeedback"
Bật tính năng gỡ lỗi cho các tiện ích đã giải nén, cụ thể là getMatchedRules() và onRuleMatchedDebug.
"declarativeNetRequestWithHostAccess"
Cảnh báo về quyền không xuất hiện tại thời điểm cài đặt, nhưng bạn phải yêu cầu máy chủ lưu trữ trước khi có thể thực hiện bất kỳ hành động nào trên máy chủ lưu trữ. Chiến dịch này là thích hợp khi bạn muốn sử dụng các quy tắc yêu cầu mạng khai báo trong một tiện ích đã có quyền lưu trữ mà không tạo thêm quyền các cảnh báo.

Phạm vi cung cấp

Chrome 84 trở lên

Tệp kê khai

Ngoài các quyền được mô tả trước đó, một số loại tập quy tắc, cụ thể là tập hợp quy tắc tĩnh, yêu cầu khai báo khoá tệp kê khai "declarative_net_request". Khoá này phải là một từ điển có một khoá duy nhất có tên là "rule_resources". Khoá này là một mảng chứa từ điển thuộc loại Ruleset, như minh hoạ trong phần sau. (Lưu ý rằng tên "Ruleset" không xuất hiện trong tệp JSON của tệp kê khai vì đó chỉ là một mảng.) Tập hợp quy tắc tĩnh sẽ được giải thích ở phần sau của tài liệu này.

{
  "name": "My extension",
  ...

  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    }, {
      "id": "ruleset_2",
      "enabled": false,
      "path": "rules_2.json"
    }]
  },
  "permissions": [
    "declarativeNetRequest",
    "declarativeNetRequestFeedback",
  ],
  "host_permissions": [
    "http://www.blogger.com/*",
    "http://*.google.com/*"
  ],
  ...
}

Quy tắc và bộ quy tắc

Để sử dụng API này, hãy chỉ định một hoặc nhiều tập hợp quy tắc. Một bộ quy tắc chứa một mảng quy tắc. Một quy tắc sẽ thực hiện một trong những việc sau:

  • Chặn một yêu cầu kết nối mạng.
  • Nâng cấp giản đồ (http lên https).
  • Ngăn chặn việc yêu cầu bị chặn bằng cách phủ định mọi quy tắc bị chặn phù hợp.
  • Chuyển hướng yêu cầu mạng.
  • Sửa đổi tiêu đề của yêu cầu hoặc phản hồi.

Có 3 loại tập hợp quy tắc, được quản lý theo những cách hơi khác nhau.

Động
Duy trì qua các phiên trình duyệt cũng như các bản nâng cấp tiện ích, đồng thời được quản lý bằng JavaScript khi tiện ích được sử dụng.
Phiên hoạt động
Xoá khi trình duyệt tắt và khi phiên bản mới của tiện ích được cài đặt. Các quy tắc trong phiên được quản lý bằng JavaScript khi đang sử dụng tiện ích.
Tĩnh
Đóng gói, cài đặt và cập nhật khi cài đặt hoặc nâng cấp một tiện ích. Các quy tắc tĩnh được lưu trữ trong tệp quy tắc có định dạng JSON và được liệt kê trong tệp kê khai.

Các bộ quy tắc trong phạm vi phiên hoạt động và động

Các tập quy tắc động và phiên được quản lý bằng JavaScript khi sử dụng tiện ích.

  • Các quy tắc động vẫn tồn tại qua các phiên hoạt động của trình duyệt và lượt nâng cấp tiện ích.
  • Các quy tắc phiên sẽ bị xoá khi trình duyệt tắt và khi phiên bản mới của tiện ích được cài đặt.

Chỉ có một trong mỗi loại bộ quy tắc này. Tiện ích có thể thêm hoặc xoá các quy tắc một cách linh động bằng cách gọi updateDynamicRules() và updateSessionRules(), miễn là giới hạn quy tắc không vượt quá giới hạn. Để biết thông tin về hạn mức quy tắc, hãy xem bài viết Giới hạn quy tắc. Bạn có thể xem ví dụ về mã này trong phần ví dụ về mã.

Tập hợp quy tắc tĩnh

Không giống như quy tắc động và quy tắc phiên, quy tắc tĩnh được đóng gói, cài đặt và cập nhật khi cài đặt hoặc nâng cấp tiện ích. Các khoá này được lưu trữ trong tệp quy tắc ở định dạng JSON, được biểu thị cho tiện ích bằng cách sử dụng khoá "declarative_net_request" và "rule_resources" như mô tả ở trên, cũng như một hoặc nhiều từ điển Ruleset. Từ điển Ruleset chứa đường dẫn đến tệp quy tắc, mã nhận dạng của bộ quy tắc có trong tệp và trạng thái bật hay tắt của bộ quy tắc. Hai yếu tố cuối cùng rất quan trọng khi bạn bật hoặc tắt bộ quy tắc theo cách lập trình.

{
  ...
  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    },
    ...
    ]
  }
  ...
}

Để kiểm tra tệp quy tắc, hãy tải tiện ích đã giải nén. Lỗi và cảnh báo về các quy tắc tĩnh không hợp lệ chỉ xuất hiện đối với những tiện ích đã giải nén. Các quy tắc tĩnh không hợp lệ trong những tiện ích đóng gói sẽ bị bỏ qua.

Xem xét nhanh

Những thay đổi đối với tập quy tắc tĩnh có thể đủ điều kiện để được xem xét nhanh. Xem xem xét nhanh các thay đổi đủ điều kiện.

Bật/tắt các quy tắc và bộ quy tắc tĩnh

Bạn có thể bật hoặc tắt cả quy tắc tĩnh riêng lẻ và tập quy tắc tĩnh hoàn chỉnh trong thời gian chạy.

Một bộ quy tắc và bộ quy tắc tĩnh đã bật sẽ được duy trì qua các phiên hoạt động của trình duyệt. Cả hai tài khoản này đều không được duy trì qua các bản cập nhật tiện ích, có nghĩa là chỉ những quy tắc mà bạn chọn thoát trong tệp quy tắc mới có sẵn sau khi cập nhật.

Vì lý do hiệu suất, cũng có giới hạn về số lượng quy tắc và tập hợp quy tắc có thể được bật cùng một lúc. Gọi getAvailableStaticRuleCount() để kiểm tra số lượng quy tắc bổ sung có thể được bật. Để biết thông tin về hạn mức quy tắc, hãy xem bài viết Giới hạn quy tắc.

Để bật hoặc tắt quy tắc tĩnh, hãy gọi updateStaticRules(). Phương thức này sẽ lấy một đối tượng UpdateStaticRulesOptions chứa các mảng mã nhận dạng của quy tắc để bật hoặc tắt. Các mã nhận dạng này được xác định bằng khoá "id" của từ điển Ruleset. Giới hạn tối đa là 5.000 quy tắc tĩnh bị tắt.

Để bật hoặc tắt quy tắc tĩnh, hãy gọi updateEnabledRulesets(). Phương thức này sẽ lấy một đối tượng UpdateRulesetOptions chứa các mảng mã nhận dạng của tập hợp quy tắc để bật hoặc tắt. Các mã nhận dạng này được xác định bằng khoá "id" của từ điển Ruleset.

Tạo quy tắc

Bất kể loại nào, quy tắc bắt đầu bằng 4 trường như được minh hoạ trong sau. Mặc dù các khoá "id" và "priority" nhận một số, nhưng các khoá "action" và "condition" có thể cung cấp một số điều kiện chặn và chuyển hướng. Quy tắc sau đây chặn mọi yêu cầu của tập lệnh bắt nguồn từ "foo.com" đến mọi URL có "abc" là chuỗi con.

{
  "id" : 1,
  "priority": 1,
  "action" : { "type" : "block" },
  "condition" : {
    "urlFilter" : "abc",
    "initiatorDomains" : ["foo.com"],
    "resourceTypes" : ["script"]
  }
}

So khớp URL

Yêu cầu ròng khai báo cho phép khớp các URL với một trong hai mẫu khớp với cú pháp hoặc biểu thức chính quy.

Cú pháp bộ lọc URL

Khoá "condition" của quy tắc cho phép khoá "urlFilter" thao tác với các URL trong miền đã chỉ định. Bạn tạo các mẫu bằng mã thông báo so khớp mẫu. Sau đây là một vài ví dụ.

urlFilter Khớp với Không phù hợp
"abc" https://abcd.com
https://example.com/abcd		 https://ab.com
"abc*d" https://abcd.com
https://example.com/abcxyzd		 https://abc.com
"||a.example.com" https://a.example.com/
https://b.a.example.com/xyz
https://a.example.company		 https://example.com/
"|https*" https://example.com http://example.com/
http://https.com
"example*^123|" https://example.com/123
http://abc.com/example?123		 https://example.com/1234
https://abc.com/example0123

Cụm từ thông dụng

Các điều kiện cũng có thể sử dụng biểu thức chính quy. Xem Khoá "regexFilter". Để tìm hiểu về áp dụng cho các điều kiện này, hãy xem Quy tắc sử dụng biểu thức chính quy.

Viết các điều kiện URL phù hợp

Hãy cẩn thận khi viết quy tắc để luôn khớp với toàn bộ miền. Nếu không, có thể khớp trong các trường hợp không mong muốn. Ví dụ: khi sử dụng thuộc tính cú pháp so khớp mẫu:

  • google.com khớp không chính xác với https://example.com/?param=google.com
  • ||google.com khớp không chính xác với https://google.company
  • https://www.google.com khớp không chính xác với https://example.com/?param=https://www.google.com

Tính năng nên dùng:

  • ||google.com/ khớp với tất cả đường dẫn và miền con.
  • |https://www.google.com/ khớp với tất cả các đường dẫn và không khớp với miền con.

Tương tự, hãy sử dụng các ký tự ^ và / để liên kết một biểu thức chính quy. Cho ví dụ: ^https:\/\/www\.google\.com\/ khớp với mọi đường dẫn trên https://www.google.com.

Đánh giá quy tắc

Trình duyệt áp dụng các quy tắc DNR trong nhiều giai đoạn trong vòng đời yêu cầu mạng.

Trước yêu cầu

Trước khi yêu cầu được thực hiện, tiện ích có thể chặn hoặc chuyển hướng (bao gồm cả việc nâng cấp giao thức từ HTTP lên HTTPS) bằng quy tắc so khớp.

Đối với mỗi tiện ích, trình duyệt sẽ xác định danh sách các quy tắc so khớp. Các quy tắc có hành động modifyHeaders không được đưa vào đây vì sẽ được xử lý sau. Ngoài ra, các quy tắc có điều kiện responseHeaders sẽ được xem xét sau (khi có tiêu đề phản hồi) và không được đưa vào.

Sau đó, đối với mỗi tiện ích, Chrome sẽ chọn tối đa một tiện ích cho mỗi yêu cầu. Chrome tìm thấy quy tắc so khớp bằng cách sắp xếp mọi quy tắc so khớp theo mức độ ưu tiên. Các quy tắc có cùng mức độ ưu tiên được sắp xếp theo hành động (allow hoặc allowAllRequests > block > upgradeScheme > redirect).

Nếu ứng cử viên là quy tắc allow hoặc allowAllRequests, hoặc khung yêu cầu được đưa ra khớp trước đó với quy tắc allowAllRequests có mức độ ưu tiên cao hơn hoặc bằng trong tiện ích này, thì yêu cầu "được phép" và tiện ích đó sẽ không ảnh hưởng đến yêu cầu đó.

Nếu có nhiều tiện ích muốn chặn hoặc chuyển hướng yêu cầu này, thì hệ thống sẽ chọn một thao tác cần thực hiện. Chrome thực hiện việc này bằng cách sắp xếp các quy tắc theo thứ tự block > redirect hoặc upgradeScheme > allow hoặc allowAllRequests. Nếu 2 quy tắc cùng loại, thì Chrome sẽ chọn quy tắc trong tiện ích được cài đặt gần đây nhất.

Trước khi gửi tiêu đề của yêu cầu

Trước khi Chrome gửi tiêu đề của yêu cầu đến máy chủ, các tiêu đề sẽ được cập nhật dựa trên các quy tắc modifyHeaders trùng khớp.

Trong một tiện ích, Chrome sẽ tạo danh sách các nội dung sửa đổi cần thực hiện bằng cách tìm tất cả quy tắc modifyHeaders phù hợp. Tương tự như trước, chỉ những quy tắc có mức độ ưu tiên cao hơn bất kỳ quy tắc allow hoặc allowAllRequests nào phù hợp mới được đưa vào.

Các quy tắc này được Chrome áp dụng theo thứ tự sao cho các quy tắc từ tiện ích được cài đặt gần đây hơn luôn được đánh giá trước các quy tắc của tiện ích cũ hơn. Ngoài ra, các quy tắc có mức độ ưu tiên cao hơn của một tiện ích luôn được áp dụng trước các quy tắc có mức độ ưu tiên thấp hơn của cùng một tiện ích. Đáng chú ý là ngay cả trên các tiện ích:

  • Nếu quy tắc nối thêm vào tiêu đề, thì các quy tắc có mức độ ưu tiên thấp hơn chỉ có thể thêm vào tiêu đề đó. Không được phép thực hiện các thao tác đặt và xoá.
  • Nếu quy tắc đặt tiêu đề, thì chỉ những quy tắc có mức độ ưu tiên thấp hơn từ cùng một tiện ích mới có thể thêm vào tiêu đề đó. Bạn không được phép sửa đổi những yếu tố nào khác.
  • Nếu quy tắc xóa tiêu đề, thì các quy tắc có mức độ ưu tiên thấp hơn không thể sửa đổi tiêu đề thêm nữa.

Sau khi nhận được phản hồi

Sau khi nhận được tiêu đề phản hồi, Chrome sẽ đánh giá các quy tắc có điều kiện responseHeaders.

Sau khi sắp xếp các quy tắc này theo action và priority và loại trừ mọi quy tắc bị một quy tắc allow hoặc allowAllRequests phù hợp trở thành thừa (các quy tắc này giống với các bước trong phần "Trước khi yêu cầu"), Chrome có thể chặn hoặc chuyển hướng yêu cầu thay cho một tiện ích.

Xin lưu ý rằng nếu một yêu cầu được gửi đến giai đoạn này thì yêu cầu đó đã được gửi đến máy chủ và máy chủ đã nhận được dữ liệu như nội dung yêu cầu. Quy tắc chặn hoặc chuyển hướng có điều kiện tiêu đề phản hồi sẽ vẫn chạy – nhưng thực sự không thể chặn hoặc chuyển hướng yêu cầu.

Đối với quy tắc chặn, trang xử lý yêu cầu này. Trang đưa ra yêu cầu nhận được phản hồi bị chặn và Chrome sớm chấm dứt yêu cầu. Trong trường hợp có quy tắc chuyển hướng, Chrome sẽ thực hiện một yêu cầu mới đến URL được chuyển hướng. Hãy nhớ cân nhắc xem những hành vi này có đáp ứng kỳ vọng về quyền riêng tư cho tiện ích của bạn hay không.

Nếu yêu cầu không bị chặn hoặc chuyển hướng, Chrome sẽ áp dụng mọi quy tắc modifyHeaders. Việc áp dụng các nội dung sửa đổi cho tiêu đề phản hồi sẽ hoạt động theo cách tương tự như mô tả trong phần "Trước khi tiêu đề yêu cầu được gửi". Việc áp dụng nội dung sửa đổi cho tiêu đề của yêu cầu sẽ không có tác dụng gì vì yêu cầu đã được thực hiện.

Quy tắc an toàn

Quy tắc an toàn được định nghĩa là các quy tắc có hành động là block, allow, allowAllRequests hoặc upgradeScheme. Những quy tắc này phải tuân theo hạn mức quy tắc động.

Hạn mức quy tắc

Việc tải và đánh giá các quy tắc trong trình duyệt sẽ phát sinh chi phí hiệu suất, nên sẽ có một số giới hạn được áp dụng khi sử dụng API. Giới hạn phụ thuộc vào loại mà bạn đang sử dụng.

Quy tắc cố định

Quy tắc tĩnh là những quy tắc được chỉ định trong tệp quy tắc được khai báo trong tệp kê khai. Một tiện ích có thể chỉ định tối đa 100 quy tắc tĩnh trong khoá tệp kê khai "rule_resources", nhưng bạn chỉ có thể bật tối đa 50 tập quy tắc này tại một thời điểm. Phần sau được gọi là MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. Nói chung, các quy tắc đó được đảm bảo ít nhất 30.000 quy tắc. Đây được gọi là GUARANTEED_MINIMUM_STATIC_RULES.

Số lượng quy tắc có sẵn sau đó phụ thuộc vào số lượng quy tắc được bật bởi tất cả tiện ích được cài đặt trên trình duyệt của người dùng. Bạn có thể tìm thấy số này trong thời gian chạy bằng cách gọi getAvailableStaticRuleCount(). Bạn có thể xem ví dụ về mã này trong phần ví dụ về mã.

Quy tắc phiên

Một tiện ích có thể có tối đa 5.000 quy tắc phiên. Thông tin này hiển thị dưới dạng MAX_NUMBER_OF_SESSION_RULES.

Trước Chrome 120, có giới hạn 5.000 quy tắc động và quy tắc phiên kết hợp.

Các quy tắc động

Một phần mở rộng có thể có ít nhất 5.000 quy tắc linh động. Thông tin này hiển thị dưới dạng MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES.

Kể từ Chrome 121, sẽ có giới hạn lớn hơn về 30.000 quy tắc cho các quy tắc động an toàn. được hiển thị dưới dạng MAX_NUMBER_OF_DYNAMIC_RULES. Bất kỳ hạng nào quy tắc không an toàn được thêm trong giới hạn 5.000 cũng sẽ được tính vào giới hạn này.

Trước Chrome 120, có giới hạn kết hợp là 5.000 quy tắc phiên và quy tắc động.

Quy tắc sử dụng biểu thức chính quy

Tất cả các loại quy tắc đều có thể sử dụng biểu thức chính quy; tuy nhiên, tổng số quy tắc biểu thức chính quy của mỗi loại không được vượt quá 1000. Đây được gọi là MAX_NUMBER_OF_REGEX_RULES.

Ngoài ra, mỗi quy tắc phải nhỏ hơn 2KB khi được biên dịch. Điều này gần như tương quan với độ phức tạp của quy tắc. Nếu cố gắng tải một quy tắc vượt quá giới hạn này, bạn sẽ thấy một cảnh báo như sau và quy tắc này sẽ bị bỏ qua.

rules_1.json: Rule with id 1 specified a more complex regex than allowed
as part of the "regexFilter" key.

Hoạt động tương tác với trình chạy dịch vụ

declarativeNetRequest chỉ áp dụng cho các yêu cầu tiếp cận ngăn xếp mạng. Trong đó bao gồm cả các phản hồi từ bộ nhớ đệm HTTP, nhưng có thể không bao gồm các phản hồi đi qua trình xử lý onfetch của một trình chạy dịch vụ. declarativeNetRequest sẽ không ảnh hưởng đến các phản hồi do trình chạy dịch vụ tạo hoặc được truy xuất từ CacheStorage, nhưng sẽ ảnh hưởng đến các lệnh gọi đến fetch() được thực hiện trong trình chạy dịch vụ.

Tài nguyên có thể truy cập trên web

Quy tắc declarativeNetRequest không thể chuyển hướng từ một yêu cầu tài nguyên công khai đến tài nguyên không truy cập được trên web. Thao tác này sẽ kích hoạt lỗi. Điều này cũng đúng ngay cả khi tài nguyên có thể truy cập trên web được chỉ định thuộc sở hữu của tiện ích chuyển hướng. Để khai báo tài nguyên cho declarativeNetRequest, hãy dùng mảng "web_accessible_resources" của tệp kê khai.

Sửa đổi tiêu đề

Thao tác nối chỉ được hỗ trợ cho các tiêu đề sau: accept, accept-encoding, accept-language, access-control-request-headers, cache-control, connection, content-language, cookie, forwarded, if-match, if-none-match, keep-alive, range, te, trailer, transfer-encoding, upgrade, user-agent, via, want-digest, x-forwarded-for.

Ví dụ

Ví dụ về mã

Cập nhật các quy tắc động

Ví dụ sau đây trình bày cách gọi updateDynamicRules(). Quy trình cho updateSessionRules() giống nhau.

// Get arrays containing new and old rules
const newRules = await getNewRules();
const oldRules = await chrome.declarativeNetRequest.getDynamicRules();
const oldRuleIds = oldRules.map(rule => rule.id);

// Use the arrays to update the dynamic rules
await chrome.declarativeNetRequest.updateDynamicRules({
  removeRuleIds: oldRuleIds,
  addRules: newRules
});

Cập nhật tập quy tắc tĩnh

Ví dụ sau đây minh hoạ cách bật và tắt tập hợp quy tắc khi xem xét số lượng tập hợp quy tắc có sẵn và số lượng tối đa tập hợp quy tắc tĩnh được bật. Bạn sẽ thực hiện việc này khi số lượng quy tắc tĩnh bạn cần vượt quá số lượng được cho phép. Để làm được điều này, bạn phải cài đặt một số tập quy tắc rồi tắt một số tập quy tắc (đặt "Enabled" thành false trong tệp kê khai).

async function updateStaticRules(enableRulesetIds, disableCandidateIds) {
  // Create the options structure for the call to updateEnabledRulesets()
  let options = { enableRulesetIds: enableRulesetIds }
  // Get the number of enabled static rules
  const enabledStaticCount = await chrome.declarativeNetRequest.getEnabledRulesets();
  // Compare rule counts to determine if anything needs to be disabled so that
  // new rules can be enabled
  const proposedCount = enableRulesetIds.length;
  if (enabledStaticCount + proposedCount > chrome.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS) {
    options.disableRulesetIds = disableCandidateIds
  }
  // Update the enabled static rules
  await chrome.declarativeNetRequest.updateEnabledRulesets(options);
}

Ví dụ về quy tắc

Các ví dụ sau minh hoạ cách Chrome ưu tiên các quy tắc trong tiện ích. Khi xem xét các quy tắc đó, bạn nên mở các quy tắc mức độ ưu tiên trong một cửa sổ riêng.

"Mức độ ưu tiên" khoá

Những ví dụ này yêu cầu quyền của máy chủ để sử dụng *://*.example.com/*.

Để xác định mức độ ưu tiên của một URL cụ thể, hãy xem khoá "priority" (do nhà phát triển xác định), khoá "action" và khoá "urlFilter". Các ví dụ này đề cập đến tệp quy tắc mẫu được hiển thị bên dưới.

Điều hướng đến https://google.com
Có hai quy tắc áp dụng cho URL này: quy tắc có mã nhận dạng 1 và 4. Quy tắc có mã 1 được áp dụng vì hành động "block" có mức độ ưu tiên cao hơn hành động "redirect". Các quy tắc còn lại không áp dụng vì dành cho các URL dài hơn.
Chuyển đến https://google.com/1234
Vì URL dài hơn nên quy tắc có mã 2 hiện đã khớp với các quy tắc có mã 1 và 4. Quy tắc có mã 2 được áp dụng vì "allow" có mức độ ưu tiên cao hơn "block" và "redirect".
Điều hướng đến https://google.com/12345
Cả 4 quy tắc đều khớp với URL này. Quy tắc có mã nhận dạng 3 được áp dụng vì mức độ ưu tiên do nhà phát triển xác định là cao nhất trong nhóm.
[
  {
    "id": 1,
    "priority": 1,
    "action": { "type": "block" },
    "condition": {"urlFilter": "||google.com/", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 2,
    "priority": 1,
    "action": { "type": "allow" },
    "condition": { "urlFilter": "||google.com/123", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 3,
    "priority": 2,
    "action": { "type": "block" },
    "condition": { "urlFilter": "||google.com/12345", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 4,
    "priority": 1,
    "action": { "type": "redirect", "redirect": { "url": "https://example.com" } },
    "condition": { "urlFilter": "||google.com/", "resourceTypes": ["main_frame"] }
  },
]

Chuyển hướng

Ví dụ bên dưới yêu cầu quyền của máy chủ đối với *://*.example.com/*.

Ví dụ sau cho thấy cách chuyển hướng một yêu cầu từ example.com đến một trang trong chính tiện ích. Đường dẫn tiện ích /a.jpg phân giải thành chrome-extension://EXTENSION_ID/a.jpg, trong đó EXTENSION_ID là mã nhận dạng tiện ích. Để làm được điều này, tệp kê khai phải khai báo /a.jpg dưới dạng tài nguyên có thể truy cập trên web.

{
  "id": 1,
  "priority": 1,
  "action": { "type": "redirect", "redirect": { "extensionPath": "/a.jpg" } },
  "condition": {
    "urlFilter": "||https://www.example.com/",
    "resourceTypes": ["main_frame"]
  }
}

URL sau sử dụng khoá "transform" để chuyển hướng đến một miền con của example.com. Công cụ này sử dụng điểm neo tên miền ("||") để chặn các yêu cầu bằng giao thức bất kỳ từ example.com. Khoá "scheme" trong "transform" chỉ định rằng các lệnh chuyển hướng đến miền con sẽ luôn sử dụng "https".

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": {
      "transform": { "scheme": "https", "host": "new.example.com" }
    }
  },
  "condition": {
    "urlFilter": "||example.com/",
    "resourceTypes": ["main_frame"]
  }
}

Ví dụ sau đây sử dụng biểu thức chính quy để chuyển hướng từ https://www.abc.xyz.com/path đến https://abc.xyz.com/path. Trong khoá "regexFilter", hãy lưu ý cách thoát dấu chấm và nhóm thu thập sẽ chọn "abc" hoặc "def". Khoá "regexSubstitution" chỉ định kết quả trùng khớp đầu tiên được trả về của biểu thức chính quy bằng cách sử dụng "\1". Trong trường hợp này, "abc" được lấy từ URL được chuyển hướng và đặt vào phần thay thế.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": {
      "regexSubstitution": "https://\\1.xyz.com/"
    }
  },
  "condition": {
    "regexFilter": "^https://www\\.(abc|def)\\.xyz\\.com/",
    "resourceTypes": [
      "main_frame"
    ]
  }
}

Tiêu đề

Ví dụ sau đây xoá tất cả cookie khỏi cả khung chính và mọi khung phụ.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "modifyHeaders",
    "requestHeaders": [{ "header": "cookie", "operation": "remove" }]
  },
  "condition": { "resourceTypes": ["main_frame", "sub_frame"] }
}

Loại

DomainType

Phần này mô tả liệu yêu cầu là của bên thứ nhất hay bên thứ ba trong khung mà yêu cầu bắt nguồn. Yêu cầu được coi là bên thứ nhất nếu có cùng miền (eTLD+1) với khung mà yêu cầu phát sinh.

Enum

"firstParty"
Yêu cầu mạng là bên thứ nhất trong khung mà yêu cầu đó bắt nguồn.

"thirdParty"
Yêu cầu mạng là bên thứ ba đối với khung mà yêu cầu đó bắt nguồn.

ExtensionActionOptions

Chrome 88 trở lên

Thuộc tính

  • displayActionCountAsBadgeText

    boolean không bắt buộc

    Liệu có tự động hiển thị số hành động cho một trang dưới dạng văn bản huy hiệu của tiện ích hay không. Lựa chọn ưu tiên này vẫn được duy trì trong nhiều phiên.

  • tabUpdate

    TabActionCountUpdate không bắt buộc

    Chrome 89 trở lên

    Thông tin chi tiết về cách điều chỉnh số hành động của thẻ.

GetDisabledRuleIdsOptions

Chrome 111 trở lên

Thuộc tính

  • rulesetId

    string

    Mã nhận dạng tương ứng với một Ruleset tĩnh.

GetRulesFilter

Chrome 111 trở lên

Thuộc tính

  • ruleIds

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

    Nếu bạn chỉ định thì chỉ những quy tắc có mã nhận dạng trùng khớp mới được đưa vào.

HeaderInfo

Chrome 128 trở lên

Thuộc tính

  • excludedValues

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

    Nếu được chỉ định, điều kiện này sẽ không khớp nếu tiêu đề tồn tại nhưng giá trị của tiêu đề chứa ít nhất một phần tử trong danh sách này. Hàm này sử dụng cú pháp mẫu so khớp tương tự như values.

  • tiêu đề

    string

    Tên tiêu đề. Điều kiện này chỉ khớp với tên nếu chưa chỉ định cả values và excludedValues.

  • giá trị

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

    Nếu được chỉ định, điều kiện này sẽ khớp nếu giá trị của tiêu đề khớp với ít nhất một mẫu trong danh sách này. Điều này hỗ trợ việc so khớp giá trị tiêu đề không phân biệt chữ hoa chữ thường cùng với các cấu trúc sau:

    '*' : Khớp với số lượng ký tự bất kỳ.

    '?' : Không khớp hoặc khớp với một ký tự.

    '*' và '?' có thể được thoát bằng dấu gạch chéo ngược, ví dụ: '\*'. và '\?'

HeaderOperation

Chrome 86 trở lên

Phần này mô tả các thao tác có thể thực hiện cho "modifyHeaders" .

Enum

"nối"
Thêm mục nhập mới cho tiêu đề đã chỉ định. Thao tác này không hỗ trợ cho tiêu đề của yêu cầu.

"set"
Đặt một giá trị mới cho tiêu đề đã chỉ định, xoá mọi tiêu đề hiện có có cùng tên.

"remove"
Xoá tất cả các mục cho tiêu đề đã chỉ định.

IsRegexSupportedResult

Chrome 87 trở lên

Thuộc tính

  • isSupported

    boolean

  • lý do

    UnsupportedRegexReason Không bắt buộc

    Chỉ định lý do khiến biểu thức chính quy không được hỗ trợ. Chỉ được cung cấp nếu isSupported là false.

MatchedRule

Thuộc tính

  • ruleId

    số

    Mã của quy tắc trùng khớp.

  • rulesetId

    string

    Mã của Ruleset chứa quy tắc này. Đối với một quy tắc bắt nguồn từ bộ quy tắc động, giá trị này sẽ bằng DYNAMIC_RULESET_ID.

MatchedRuleInfo

Thuộc tính

  • quy tắc

    MatchedRule

  • tabId

    số

    TabId của thẻ là nơi bắt nguồn yêu cầu nếu thẻ vẫn đang hoạt động. Trường hợp còn lại là -1.

  • timeStamp

    số

    Thời gian so khớp quy tắc. Dấu thời gian sẽ tương ứng với quy ước JavaScript về thời gian, tức là số mili giây kể từ thời gian bắt đầu của hệ thống.

MatchedRuleInfoDebug

Thuộc tính

MatchedRulesFilter

Thuộc tính

  • minTimeStamp

    số không bắt buộc

    Nếu được chỉ định, chỉ khớp với các quy tắc sau dấu thời gian đã cho.

  • tabId

    số không bắt buộc

    Nếu được chỉ định, chỉ khớp các quy tắc cho thẻ đã cho. Khớp với các quy tắc không được liên kết với bất kỳ thẻ đang hoạt động nào nếu bạn đặt thành -1.

ModifyHeaderInfo

Chrome 86 trở lên

Thuộc tính

  • tiêu đề

    string

    Tên của tiêu đề sẽ được sửa đổi.

  • hoạt động

    HeaderOperation

    Thao tác sẽ được thực hiện trên tiêu đề.

  • value

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

    Giá trị mới cho tiêu đề. Phải được chỉ định cho các thao tác append và set.

QueryKeyValue

Thuộc tính

  • phím

    string

  • replaceOnly

    boolean không bắt buộc

    Chrome 94 trở lên

    Nếu đúng, khoá truy vấn chỉ được thay thế nếu đã có. Nếu không, khoá này cũng sẽ được thêm vào nếu bị thiếu. Giá trị mặc định là false.

  • value

    string

QueryTransform

Thuộc tính

  • addOrReplaceParams

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

    Danh sách cặp khoá-giá trị của truy vấn sẽ được thêm hoặc thay thế.

  • removeParams

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

    Danh sách khoá truy vấn cần xoá.

Redirect

Thuộc tính

  • extensionPath

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

    Đường dẫn tương ứng với thư mục tiện ích. Nên bắt đầu bằng '/'.

  • regexSubstitution

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

    Mẫu thay thế cho các quy tắc chỉ định regexFilter. Kết quả trùng khớp đầu tiên của regexFilter trong URL sẽ được thay thế bằng mẫu này. Trong regexSubstitution, bạn có thể dùng các chữ số thoát dấu gạch chéo ngược (\1 đến \9) để chèn các nhóm thu thập tương ứng. \0 đề cập đến toàn bộ văn bản trùng khớp.

  • biến đổi

    URLTransform không bắt buộc

    Các phép biến đổi URL cần thực hiện.

  • url

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

    URL chuyển hướng. Không được phép chuyển hướng đến các URL JavaScript.

RegexOptions

Chrome 87 trở lên

Thuộc tính

  • isCaseSensitive

    boolean không bắt buộc

    Liệu regex được chỉ định có phân biệt chữ hoa chữ thường hay không. Mặc định là đúng.

  • biểu thức chính quy

    string

    Expresson thông thường để kiểm tra.

  • requireCapturing

    boolean không bắt buộc

    Liệu regex được chỉ định có yêu cầu chụp ảnh hay không. Chỉ yêu cầu chụp lại đối với quy tắc chuyển hướng chỉ định hành động regexSubstition. Giá trị mặc định là "false".

RequestDetails

Thuộc tính

  • documentId

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

    Chrome 106 trở lên

    Giá trị nhận dạng duy nhất cho tài liệu của khung nếu yêu cầu này là dành cho một khung.

  • documentLifecycle

    DocumentLifecycle không bắt buộc

    Chrome 106 trở lên

    Vòng đời của tài liệu khung, nếu yêu cầu này là dành cho một khung.

  • frameId

    số

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

  • frameType

    FrameType không bắt buộc

    Chrome 106 trở lên

    Loại khung, nếu yêu cầu này là dành cho một khung.

  • trình khởi tạo

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

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

  • method

    string

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

  • parentDocumentId

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

    Chrome 106 trở lên

    Giá trị nhận dạng duy nhất cho tài liệu gốc của khung, nếu yêu cầu này là dành cho một khung và 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 gốc.

  • requestId

    string

    Mã của yêu cầu. Mã yêu cầu là duy nhất trong một phiên trình duyệt.

  • tabId

    số

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

  • loại

    ResourceType

    Loại tài nguyên của yêu cầu.

  • url

    string

    URL của yêu cầu.

RequestMethod

Chrome 91 trở lên

Phần này mô tả phương thức yêu cầu HTTP của một yêu cầu mạng.

Enum

"kết nối"

"xoá"

"get"

"head"

"options"

"bản vá"

"bài đăng"

"put"

"khác"

ResourceType

Phần này mô tả loại tài nguyên của yêu cầu mạng.

Enum

"main_frame"

"sub_frame"

"stylesheet"

"script"

"hình ảnh"

"font"

"đối tượng"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"webtransport"

"webbundle"

"khác"

Rule

Thuộc tính

  • hành động

    RuleAction

    Hành động cần thực hiện nếu quy tắc này phù hợp.

  • điều kiện

    RuleCondition

    Điều kiện mà quy tắc này được kích hoạt.

  • id

    số

    Mã nhận dạng duy nhất cho một quy tắc. Bắt buộc và phải >= 1.

  • của chiến dịch

    số không bắt buộc

    Mức độ ưu tiên của quy tắc. Giá trị mặc định là 1 Nếu được chỉ định, giá trị này phải >= 1.

RuleAction

Thuộc tính

  • chuyển hướng

    Chuyển hướng không bắt buộc

    Mô tả cách chuyển hướng được thực hiện. Chỉ hợp lệ với các quy tắc chuyển hướng.

  • requestHeaders

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

    Chrome 86 trở lên

    Các tiêu đề của yêu cầu cần sửa đổi cho yêu cầu. Chỉ hợp lệ nếu RuleActionType là "modifyHeaders".

  • responseHeaders

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

    Chrome 86 trở lên

    Các tiêu đề phản hồi cần sửa đổi cho yêu cầu. Chỉ hợp lệ nếu RuleActionType là "modifyHeaders".

  • Loại hành động cần thực hiện.

RuleActionType

Mô tả loại tác vụ cần thực hiện nếu RuleCondition đã cho phù hợp.

Enum

"block"
Chặn yêu cầu mạng.

"redirect"
Chuyển hướng yêu cầu mạng.

"allow"
Cho phép yêu cầu mạng. Yêu cầu sẽ không bị chặn nếu có quy tắc cho phép phù hợp với yêu cầu đó.

"upgradeScheme"
Nâng cấp giao thức của URL yêu cầu mạng thành https nếu yêu cầu là http hoặc ftp.

"modifyHeaders"
Sửa đổi tiêu đề của yêu cầu/phản hồi từ yêu cầu mạng.

"allowAllRequests"
Cho phép tất cả các yêu cầu trong một hệ phân cấp khung, bao gồm cả chính yêu cầu khung đó.

RuleCondition

Thuộc tính

  • domainType

    DomainType không bắt buộc

    Chỉ định xem yêu cầu mạng là của bên thứ nhất hay bên thứ ba đối với miền mà yêu cầu đó bắt nguồn. Nếu bạn bỏ qua, tất cả yêu cầu đều được chấp nhận.

  • tên miền

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

    Không dùng nữa kể từ Chrome 101

    Thay vào đó, hãy sử dụng initiatorDomains

    Quy tắc này sẽ chỉ khớp với các yêu cầu mạng bắt nguồn từ danh sách domains.

  • excludedDomains

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

    Không dùng nữa kể từ Chrome 101

    Thay vào đó, hãy sử dụng excludedInitiatorDomains

    Quy tắc này sẽ không khớp với các yêu cầu mạng bắt nguồn từ danh sách của excludedDomains.

  • excludedInitiatorDomains

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

    Chrome 101 trở lên

    Quy tắc này sẽ không khớp với các yêu cầu mạng bắt nguồn từ danh sách của excludedInitiatorDomains. Nếu danh sách này trống hoặc bị bỏ qua, thì không có miền nào bị loại trừ. Yêu cầu này sẽ được ưu tiên hơn initiatorDomains.

    Lưu ý:

    • Các miền phụ như "a.example.com" cũng được cho phép.
    • Mục nhập chỉ được chứa ký tự ASCII.
    • Sử dụng phương thức mã hoá punycode cho các miền quốc tế hoá.
    • URL này khớp với trình khởi tạo yêu cầu chứ không phải với URL yêu cầu.
    • Miền phụ của các miền được liệt kê cũng bị loại trừ.
  • excludedRequestDomains

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

    Chrome 101 trở lên

    Quy tắc này sẽ không khớp với các yêu cầu mạng khi miền khớp với một miền trong danh sách excludedRequestDomains. Nếu danh sách này trống hoặc bị bỏ qua, thì không có miền nào bị loại trừ. Yêu cầu này sẽ được ưu tiên hơn requestDomains.

    Lưu ý:

    • Các miền phụ như "a.example.com" cũng được cho phép.
    • Mục nhập chỉ được chứa ký tự ASCII.
    • Sử dụng phương thức mã hoá punycode cho các miền quốc tế hoá.
    • Miền phụ của các miền được liệt kê cũng bị loại trừ.
  • excludedRequestMethods

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

    Chrome 91 trở lên

    Danh sách phương thức yêu cầu mà quy tắc sẽ không khớp. Chỉ được chỉ định một trong hai requestMethods và excludedRequestMethods. Nếu bạn không chỉ định phương thức nào trong số này, thì tất cả phương thức yêu cầu đều được so khớp.

  • excludedResourceTypes

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

    Danh sách các loại tài nguyên mà quy tắc sẽ không khớp. Chỉ được chỉ định một trong hai resourceTypes và excludedResourceTypes. Nếu không có tài nguyên nào trong số đó được chỉ định, thì tất cả các loại tài nguyên ngoại trừ "main_frame" bị chặn.

  • excludedResponseHeaders

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

    Chrome 128 trở lên

    Quy tắc sẽ không khớp nếu yêu cầu khớp với bất kỳ điều kiện nào về tiêu đề phản hồi trong danh sách này (nếu được chỉ định). Nếu bạn chỉ định cả excludedResponseHeaders và responseHeaders, thì thuộc tính excludedResponseHeaders sẽ được ưu tiên.

  • excludedTabIds

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

    Chrome 92 trở lên

    Danh sách tabs.Tab.id mà quy tắc không khớp. Mã tabs.TAB_ID_NONE không bao gồm các yêu cầu không bắt nguồn từ thẻ. Chỉ được hỗ trợ cho các quy tắc trong phạm vi phiên hoạt động.

  • initiatorDomains

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

    Chrome 101 trở lên

    Quy tắc này sẽ chỉ khớp với các yêu cầu mạng bắt nguồn từ danh sách initiatorDomains. Nếu bạn bỏ qua danh sách này, thì quy tắc này sẽ áp dụng cho các yêu cầu từ tất cả các miền. Danh sách trống không được phép.

    Lưu ý:

    • Các miền phụ như "a.example.com" cũng được cho phép.
    • Mục nhập chỉ được chứa ký tự ASCII.
    • Sử dụng phương thức mã hoá punycode cho các miền quốc tế hoá.
    • URL này khớp với trình khởi tạo yêu cầu chứ không phải với URL yêu cầu.
    • Các miền phụ của các miền có trong danh sách cũng sẽ được so khớp.
  • isUrlFilterCaseSensitive

    boolean không bắt buộc

    Liệu urlFilter hay regexFilter (bất kỳ giá trị nào được chỉ định) có phân biệt chữ hoa chữ thường hay không. Mặc định là sai.

  • regexFilter

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

    Biểu thức chính quy để so khớp với URL yêu cầu mạng. Việc này tuân theo cú pháp RE2.

    Lưu ý: Bạn chỉ có thể chỉ định một trong hai giá trị urlFilter hoặc regexFilter.

    Lưu ý: regexFilter chỉ được chứa các ký tự ASCII. Mã này được so khớp với một url trong đó máy chủ lưu trữ được mã hoá theo định dạng punycode (trong trường hợp miền được quốc tế hoá) và mọi ký tự không phải ASCII khác đều được mã hoá bằng URL bằng utf-8.

  • requestDomains

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

    Chrome 101 trở lên

    Quy tắc này sẽ chỉ so khớp các yêu cầu mạng khi miền khớp với một yêu cầu trong danh sách requestDomains. Nếu bạn bỏ qua danh sách này, thì quy tắc này sẽ áp dụng cho các yêu cầu từ tất cả các miền. Danh sách trống không được phép.

    Lưu ý:

    • Các miền phụ như "a.example.com" cũng được cho phép.
    • Mục nhập chỉ được chứa ký tự ASCII.
    • Sử dụng phương thức mã hoá punycode cho các miền quốc tế hoá.
    • Các miền phụ của các miền có trong danh sách cũng sẽ được so khớp.
  • requestMethods

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

    Chrome 91 trở lên

    Danh sách phương thức yêu cầu HTTP mà quy tắc có thể so khớp. Danh sách trống không được phép.

    Lưu ý: Việc chỉ định một điều kiện cho quy tắc requestMethods cũng sẽ loại trừ các yêu cầu không phải HTTP, trong khi việc chỉ định excludedRequestMethods thì không.

  • resourceTypes

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

    Danh sách các loại tài nguyên mà quy tắc có thể khớp. Danh sách trống không được phép.

    Lưu ý: bạn phải chỉ định thuộc tính này cho các quy tắc allowAllRequests và chỉ được bao gồm các loại tài nguyên sub_frame và main_frame.

  • responseHeaders

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

    Chrome 128 trở lên

    Quy tắc sẽ khớp nếu yêu cầu khớp với bất kỳ điều kiện nào về tiêu đề phản hồi trong danh sách này (nếu được chỉ định).

  • tabIds

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

    Chrome 92 trở lên

    Danh sách tabs.Tab.id mà quy tắc cần khớp. Mã tabs.TAB_ID_NONE khớp với các yêu cầu không bắt nguồn từ một thẻ. Danh sách trống không được phép. Chỉ được hỗ trợ cho các quy tắc trong phạm vi phiên hoạt động.

  • urlFilter

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

    Mẫu được so khớp với URL yêu cầu mạng. Cấu trúc được hỗ trợ:

    '*' : Ký tự đại diện: Khớp với số lượng ký tự bất kỳ.

    '|' : Quảng cáo cố định cuối màn hình bên trái/phải: Nếu được sử dụng ở một trong hai đầu mẫu, hãy chỉ định phần đầu/cuối của url tương ứng.

    '||' : Neo tên miền: Nếu được sử dụng ở đầu mẫu, chỉ định phần đầu của miền (phụ) của URL.

    '^' : Ký tự dấu phân cách: Ký tự này khớp với bất kỳ ký tự nào ngoại trừ chữ cái, chữ số hoặc một trong các ký tự sau: _, -, . hoặc %. Tên này cũng khớp với phần cuối của URL.

    Do đó, urlFilter bao gồm các phần sau: (phần neo tên trái/tên miền không bắt buộc) + mẫu + (phần neo phải không bắt buộc).

    Nếu bạn bỏ qua thì tất cả URL đều khớp. Chuỗi trống không được phép.

    Không cho phép mẫu bắt đầu bằng ||*. Thay vào đó, hãy sử dụng *.

    Lưu ý: Bạn chỉ có thể chỉ định một trong hai giá trị urlFilter hoặc regexFilter.

    Lưu ý: urlFilter chỉ được chứa các ký tự ASCII. Mã này được so khớp với một url trong đó máy chủ lưu trữ được mã hoá theo định dạng punycode (trong trường hợp miền được quốc tế hoá) và mọi ký tự không phải ASCII khác đều được mã hoá bằng URL bằng utf-8. Ví dụ: khi URL yêu cầu là http://abc.р chơi?q=bởi ngày nào, urlFilter sẽ được so khớp với URL http://abc.xn--p1ai/?q=%D1%84.

Ruleset

Thuộc tính

  • đang bật

    boolean

    Liệu bộ quy tắc có được bật theo mặc định hay không.

  • id

    string

    Một chuỗi không trống xác định duy nhất bộ quy tắc. ID bắt đầu bằng '_' được dành riêng để sử dụng nội bộ.

  • đường dẫn

    string

    Đường dẫn của bộ quy tắc JSON liên quan đến thư mục tiện ích.

RulesMatchedDetails

Thuộc tính

  • rulesMatchedInfo

    MatchedRuleInfo[]

    Quy tắc khớp với bộ lọc đã cho.

TabActionCountUpdate

Chrome 89 trở lên

Thuộc tính

  • tăng dần

    số

    Số tiền làm tăng số lượng thao tác của thẻ. Giá trị âm sẽ làm giảm số lượng.

  • tabId

    số

    Thẻ để cập nhật số lượng hành động.

TestMatchOutcomeResult

Chrome 103 trở lên

Thuộc tính

  • matchedRules

    MatchedRule[]

    Các quy tắc (nếu có) phù hợp với yêu cầu giả định.

TestMatchRequestDetails

Chrome 103 trở lên

Thuộc tính

  • trình khởi tạo

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

    URL của trình khởi tạo (nếu có) cho yêu cầu giả định.

  • method

    RequestMethod không bắt buộc

    Phương thức HTTP chuẩn của yêu cầu giả định. Mặc định là "get" đối với các yêu cầu HTTP và bị bỏ qua đối với các yêu cầu không phải HTTP.

  • responseHeaders

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

    Đang chờ xử lý

    Các tiêu đề do một phản hồi giả định cung cấp nếu yêu cầu không bị chặn hoặc chuyển hướng trước khi được gửi. Được biểu thị dưới dạng một đối tượng ánh xạ tên tiêu đề với một danh sách các giá trị chuỗi. Nếu không được chỉ định, phản hồi giả định sẽ trả về tiêu đề phản hồi trống. Điều này có thể khớp với các quy tắc khớp với việc không có tiêu đề. Ví dụ: {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}

  • tabId

    số không bắt buộc

    Mã nhận dạng của thẻ mà yêu cầu giả định diễn ra. Không cần tương ứng với một mã thẻ thực. Giá trị mặc định là -1, nghĩa là yêu cầu đó không liên quan đến thẻ nào.

  • loại

    ResourceType

    Loại tài nguyên của yêu cầu giả định.

  • url

    string

    URL của yêu cầu giả định.

UnsupportedRegexReason

Chrome 87 trở lên

Mô tả lý do tại sao một biểu thức chính quy nhất định không được hỗ trợ.

Enum

"syntaxError"
Biểu thức chính quy có cú pháp không chính xác hoặc sử dụng các tính năng không có trong cú pháp RE2.

"memoryLimitExceeded"
Biểu thức chính quy vượt quá giới hạn bộ nhớ.

UpdateRuleOptions

Chrome 87 trở lên

Thuộc tính

  • addRules

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

    Quy tắc cần thêm.

  • removeRuleIds

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

    Mã của các quy tắc cần xoá. Mọi mã nhận dạng không hợp lệ đều sẽ bị bỏ qua.

UpdateRulesetOptions

Chrome 87 trở lên

Thuộc tính

  • disableRulesetIds

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

    Tập hợp mã nhận dạng tương ứng với một Ruleset tĩnh cần tắt.

  • enableRulesetIds

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

    Bộ mã nhận dạng tương ứng với một Ruleset tĩnh mà bạn nên bật.

UpdateStaticRulesOptions

Chrome 111 trở lên

Thuộc tính

  • disableRuleIds

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

    Bộ mã nhận dạng tương ứng với các quy tắc trong Ruleset cần tắt.

  • enableRuleIds

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

    Bộ mã nhận dạng tương ứng với các quy tắc trong Ruleset cần bật.

  • rulesetId

    string

    Mã nhận dạng tương ứng với một Ruleset tĩnh.

URLTransform

Thuộc tính

  • mảnh

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

    Mảnh mới cho yêu cầu. Nên để trống, trong trường hợp mảnh hiện tại bị xoá; hoặc phải bắt đầu bằng '#'.

  • người tổ chức

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

    Máy chủ lưu trữ mới cho yêu cầu.

  • mật khẩu

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

    Mật khẩu mới cho yêu cầu.

  • đường dẫn

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

    Đường dẫn mới cho yêu cầu. Nếu trống thì đường dẫn hiện có sẽ bị xoá.

  • cổng

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

    Cổng mới cho yêu cầu. Nếu trống thì cổng hiện tại sẽ bị xoá.

  • truy vấn

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

    Truy vấn mới cho yêu cầu. Phải để trống, trong trường hợp truy vấn hiện tại bị xoá; hoặc nên bắt đầu bằng '?'.

  • queryTransform

    QueryTransform không bắt buộc

    Thêm, xoá hoặc thay thế cặp khoá-giá trị của truy vấn.

  • lược đồ

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

    Giao thức mới cho yêu cầu. Các giá trị được phép là "http", "https", "ftp" và "chrome-extension".

  • tên người dùng

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

    Tên người dùng mới cho yêu cầu.

Thuộc tính

DYNAMIC_RULESET_ID

Mã quy tắc cho các quy tắc động do tiện ích thêm vào.

Giá trị

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

Khoảng thời gian mà bạn có thể thực hiện lệnh gọi MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules (được chỉ định bằng phút). Các lệnh gọi bổ sung sẽ không thực hiện được ngay lập tức và đặt runtime.lastError. Lưu ý: getMatchedRules cuộc gọi liên kết với một cử chỉ của người dùng sẽ được miễn hạn mức.

Giá trị

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89 trở lên

Số lượng quy tắc tĩnh tối thiểu được đảm bảo cho một tiện ích trên các tập hợp quy tắc tĩnh đã bật. Mọi quy tắc vượt quá giới hạn này sẽ được tính vào giới hạn quy tắc tĩnh trên toàn cầu.

Giá trị

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

Số lần getMatchedRules có thể được gọi trong khoảng thời gian GETMATCHEDRULES_QUOTA_INTERVAL.

Giá trị

20

MAX_NUMBER_OF_DYNAMIC_RULES

Số lượng quy tắc động tối đa mà một tiện ích có thể thêm.

Giá trị

30000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94 trở lên

Số lượng Rulesets tĩnh tối đa mà một tiện ích có thể bật tại một thời điểm bất kỳ.

Giá trị

50

MAX_NUMBER_OF_REGEX_RULES

Số lượng quy tắc biểu thức chính quy tối đa mà một tiện ích có thể thêm vào. Giới hạn này được đánh giá riêng cho bộ quy tắc linh động và các quy tắc được chỉ định trong tệp tài nguyên quy tắc.

Giá trị

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120 trở lên

Số lượng quy tắc tối đa trong phạm vi phiên hoạt động mà một tiện ích có thể thêm.

Giá trị

5000

MAX_NUMBER_OF_STATIC_RULESETS

Số lượng Rulesets tĩnh tối đa mà một tiện ích có thể chỉ định trong khoá kê khai "rule_resources".

Giá trị

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120 trở lên

Số lượng tối đa "không an toàn" các quy tắc linh động mà một tiện ích có thể thêm.

Giá trị

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120 trở lên

Số lượng tối đa "không an toàn" quy tắc trong phạm vi phiên hoạt động mà tiện ích có thể thêm.

Giá trị

5000

SESSION_RULESET_ID

Chrome 90 trở lên

Mã quy tắc cho các quy tắc trong phạm vi phiên hoạt động do tiện ích thêm vào.

Giá trị

"_session"

Phương thức

getAvailableStaticRuleCount()

Lời hứa Chrome 89 trở lên 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
)

Trả về số lượng quy tắc tĩnh mà tiện ích có thể bật trước khi đạt đến giới hạn quy tắc tĩnh chung.

Tham số

  • số gọi lại

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

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

    (count: number) => void

    • số lượng

      số

Giá trị trả về

  • Promise<number>

    Chrome 91 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 cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

getDisabledRuleIds()

Lời hứa Chrome 111 trở lên 
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
  callback?: function,
)

Trả về danh sách các quy tắc tĩnh trong Ruleset cho trước hiện đang bị vô hiệu hoá.

Tham số

  • Chỉ định bộ quy tắc để truy vấn.

  • số gọi lại

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

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

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      số[]

Giá trị trả về

  • Cam kết<number[]>

    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 cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

getDynamicRules()

Lời hứa 
chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
  callback?: function,
)

Trả về tập hợp các quy tắc động hiện tại cho tiện ích. Phương thức gọi có thể tuỳ ý lọc danh sách các quy tắc đã tìm nạp bằng cách chỉ định một filter.

Tham số

  • filter

    GetRulesFilter không bắt buộc

    Chrome 111 trở lên

    Đối tượng để lọc danh sách các quy tắc đã tìm nạp.

  • số gọi lại

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

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

    (rules: Rule[]) => void

Giá trị trả về

  • Cam kết<Quy tắc[]>

    Chrome 91 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 cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

getEnabledRulesets()

Lời hứa 
chrome.declarativeNetRequest.getEnabledRulesets(
  callback?: function,
)

Trả về id cho tập hợp các tập quy tắc tĩnh được bật hiện tại.

Tham số

  • số gọi lại

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

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

    (rulesetIds: string[]) => void

    • rulesetIds

      chuỗi[]

Giá trị trả về

  • Promise&lt;string[]&gt;

    Chrome 91 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 cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

getMatchedRules()

Lời hứa 
chrome.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
  callback?: function,
)

Trả về tất cả quy tắc khớp với tiện ích. Phương thức gọi có thể tuỳ ý lọc danh sách các quy tắc phù hợp bằng cách chỉ định một filter. Phương thức này chỉ dành cho các tiện ích có quyền "declarativeNetRequestFeedback" hoặc đã cấp quyền "activeTab" cho tabId được chỉ định trong filter. Lưu ý: Các quy tắc không được liên kết với tài liệu đang hoạt động và được so khớp cách đây hơn năm phút sẽ không được trả về.

Tham số

Giá trị trả về

  • Promise&lt;RulesMatchedDetails&gt;

    Chrome 91 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 cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

getSessionRules()

Lời hứa Chrome 90 trở lên 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
  callback?: function,
)

Trả về tập hợp quy tắc trong phạm vi phiên hiện tại cho tiện ích. Phương thức gọi có thể tuỳ ý lọc danh sách các quy tắc đã tìm nạp bằng cách chỉ định một filter.

Tham số

  • filter

    GetRulesFilter không bắt buộc

    Chrome 111 trở lên

    Đối tượng để lọc danh sách các quy tắc đã tìm nạp.

  • số gọi lại

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

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

    (rules: Rule[]) => void

Giá trị trả về

  • Cam kết<Quy tắc[]>

    Chrome 91 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 cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

isRegexSupported()

Lời hứa Chrome 87 trở lên 
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
  callback?: function,
)

Kiểm tra xem biểu thức chính quy đã cho có được hỗ trợ làm điều kiện của quy tắc regexFilter hay không.

Tham số

Giá trị trả về

  • Promise&lt;IsRegexSupportedResult&gt;

    Chrome 91 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 cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

setExtensionActionOptions()

Lời hứa Chrome 88 trở lên 
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
  callback?: function,
)

Định cấu hình xem có hiển thị số thao tác cho các thẻ dưới dạng văn bản huy hiệu của thao tác với tiện ích hay không, đồng thời cung cấp cách tăng số thao tác đó.

Tham số

  • số gọi lại

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

    Chrome 89 trở lên

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

    () => void

Giá trị trả về

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

    Chrome 91 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 cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

testMatchOutcome()

Lời hứa Chrome 103 trở lên 
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
)

Kiểm tra xem có bất kỳ quy tắc declarativeNetRequest nào của tiện ích phù hợp với yêu cầu giả định hay không. Lưu ý: Chỉ dành cho tiện ích đã giải nén vì tiện ích này chỉ được sử dụng trong quá trình phát triển tiện ích.

Tham số

Giá trị trả về

  • Promise&lt;TestMatchOutcomeResult&gt;

    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 cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

updateDynamicRules()

Lời hứa 
chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
  callback?: function,
)

Sửa đổi bộ quy tắc động hiện tại cho phần mở rộng. Trước tiên, các quy tắc có mã nhận dạng trong options.removeRuleIds sẽ bị xoá, sau đó các quy tắc có trong options.addRules sẽ được thêm. Lưu ý:

  • Quá trình cập nhật này diễn ra dưới dạng một thao tác ở cấp nguyên tử: thêm và xoá tất cả quy tắc đã chỉ định, hoặc trả về một lỗi.
  • Các quy tắc này sẽ được duy trì trong các phiên hoạt động của trình duyệt và qua các lần cập nhật tiện ích.
  • Bạn không thể dùng hàm này để xoá các quy tắc tĩnh được chỉ định trong gói tiện ích.
  • MAX_NUMBER_OF_DYNAMIC_RULES là số lượng quy tắc động tối đa mà một tiện ích có thể thêm. Số lượng quy tắc không an toàn không được vượt quá MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES.

Tham số

  • tùy chọn

    UpdateRuleOptions

    Chrome 87 trở lên
  • số gọi lại

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

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

    () => void

Giá trị trả về

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

    Chrome 91 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 cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

updateEnabledRulesets()

Lời hứa 
chrome.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
  callback?: function,
)

Cập nhật tập hợp các bộ quy tắc tĩnh được bật cho tiện ích. Trước tiên, tập hợp quy tắc có mã nhận dạng trong options.disableRulesetIds sẽ được xoá, sau đó các tập quy tắc có trong options.enableRulesetIds sẽ được thêm vào. Xin lưu ý rằng một tập hợp các bộ quy tắc tĩnh đã bật sẽ được duy trì trong các phiên hoạt động chứ không phải qua các bản cập nhật tiện ích, tức là khoá tệp kê khai rule_resources sẽ xác định tập hợp các bộ quy tắc tĩnh được bật trên mỗi bản cập nhật tiện ích.

Tham số

  • tùy chọn

    UpdateRulesetOptions

    Chrome 87 trở lên
  • số gọi lại

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

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

    () => void

Giá trị trả về

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

    Chrome 91 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 cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

updateSessionRules()

Lời hứa Chrome 90 trở lên 
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
  callback?: function,
)

Sửa đổi tập hợp quy tắc trong phạm vi phiên hiện tại cho tiện ích. Trước tiên, các quy tắc có mã nhận dạng trong options.removeRuleIds sẽ bị xoá, sau đó các quy tắc có trong options.addRules sẽ được thêm. Lưu ý:

  • Quá trình cập nhật này diễn ra dưới dạng một thao tác ở cấp nguyên tử: thêm và xoá tất cả quy tắc đã chỉ định, hoặc trả về một lỗi.
  • Những quy tắc này không được duy trì trong các phiên và được sao lưu trong bộ nhớ.
  • MAX_NUMBER_OF_SESSION_RULES là số lượng quy tắc phiên tối đa mà một tiện ích có thể thêm.

Tham số

  • tùy chọn

    UpdateRuleOptions

  • số gọi lại

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

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

    () => void

Giá trị trả về

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

    Chrome 91 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 cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

updateStaticRules()

Lời hứa Chrome 111 trở lên 
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
  callback?: function,
)

Tắt và bật từng quy tắc tĩnh riêng lẻ trong Ruleset. Các thay đổi đối với các quy tắc thuộc về Ruleset đã tắt sẽ có hiệu lực vào lần bật tính năng này tiếp theo.

Tham số

  • số gọi lại

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

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

    () => void

Giá trị trả về

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

    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 cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

Sự kiện

onRuleMatchedDebug

chrome.declarativeNetRequest.onRuleMatchedDebug.addListener(
  callback: function,
)

Được kích hoạt khi quy tắc được so khớp với yêu cầu. Chỉ dành cho các tiện ích đã giải nén có quyền "declarativeNetRequestFeedback" vì quyền này chỉ dùng cho mục đích gỡ lỗi.

Tham số