chrome.declarativeNetRequest

Mô tả

API chrome.declarativeNetRequest được 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 các tiện ích sửa đổi 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, nhờ đó mang lại quyền riêng tư cao hơn.

Quyền

declarativeNetRequest
declarativeNetRequestWithHostAccess

Quyền "declarativeNetRequest" và "declarativeNetRequestWithHostAccess" cung cấp các chức năng tương tự. Điểm khác biệt giữa hai loại này là thời điểm quyền được yêu cầu hoặc cấp.

"declarativeNetRequest"
Kích hoạt cảnh báo về quyền tại thời điểm cài đặt nhưng cung cấp quyền truy cập ngầm ẩn vào các quy tắc allow, allowAllRequests và block. Hãy sử dụng phương thức này khi có thể để không cần yêu cầu quyền truy cập đầy đủ vào máy chủ lưu trữ.
"declarativeNetRequestFeedback"
Bật các tính năng gỡ lỗi cho tiện ích chưa đóng gói, cụ thể là getMatchedRules() và onRuleMatchedDebug.
"declarativeNetRequestWithHostAccess"
Cảnh báo về quyền sẽ không xuất hiện khi cài đặt, nhưng bạn phải yêu cầu quyền của máy chủ lưu trữ trước khi có thể thực hiện bất kỳ thao tác nào trên máy chủ lưu trữ. Điều này phù 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 truy cập vào máy chủ lưu trữ mà không tạo thêm 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 nhóm quy tắc (cụ thể là nhóm quy tắc tĩnh) yêu cầu bạn 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 các từ điển thuộc loại Ruleset, như minh hoạ trong phần sau. (Xin lưu ý rằng tên "Ruleset" không xuất hiện trong JSON của tệp kê khai vì đây chỉ là một mảng.) Bộ 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à nhóm quy tắc

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

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

Có 3 loại nhóm quy tắc và mỗi loại được quản lý theo cách hơi khác nhau.

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

Nhóm quy tắc động và nhóm quy tắc trong phạm vi phiên hoạt động

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

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

Chỉ có một loại quy tắc trong số 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à không vượt quá giới hạn quy tắc. Để biết thông tin về giới hạn quy tắc, hãy xem phần Giới hạn quy tắc. Bạn có thể xem ví dụ về trường hợp này trong phần ví dụ về mã.

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

Không giống như các quy tắc động và quy tắc phiên, các quy tắc tĩnh được đóng gói, cài đặt và cập nhật khi một tiện ích được cài đặt hoặc nâng cấp. Các tệp này được lưu trữ trong các tệp quy tắc ở định dạng JSON, được chỉ định cho tiện ích bằng cách sử dụng các 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 cho nhóm quy tắc có trong tệp và nhóm quy tắc đó có được bật hay không. Hai thuộc tính cuối cùng rất quan trọng khi bạn bật hoặc tắt một nhóm quy tắc theo cách có lập trình.

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

Để kiểm thử các tệp quy tắc, hãy tải tiện ích của bạn ở trạng thái chưa đóng gói. 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 các tiện ích chưa được đóng gói. Các quy tắc tĩnh không hợp lệ trong tiện ích đóng gói sẽ bị bỏ qua.

Quy trình xem xét nhanh

Các thay đổi đối với bộ quy tắc tĩnh có thể đủ điều kiện được xem xét nhanh. Hãy xem quy trình xem xét nhanh đối với những thay đổi đủ điều kiện.

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

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

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

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

Để bật hoặc tắt các quy tắc tĩnh, hãy gọi updateStaticRules(). Phương thức này lấy một đối tượng UpdateStaticRulesOptions chứa các mảng mã nhận dạng của các quy tắc cần bật hoặc tắt. Các mã nhận dạng đượ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ị vô hiệu hoá.

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

Xây dựng quy tắc

Bất kể loại nào, một quy tắc đều bắt đầu bằng 4 trường như minh hoạ dưới đây. Mặc dù các khoá "id" và "priority" có 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 tất cả các yêu cầu tập lệnh bắt nguồn từ "foo.com" đến mọi URL có "abc" làm chuỗi con.

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

URL trùng khớp

Declarative Net Request cung cấp khả năng so khớp URL bằng cú pháp so khớp mẫu hoặc biểu thức chính quy.

Cú pháp bộ lọc URL

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

urlFilter Liên kết Không khớ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ề các giới hạn áp dụng cho những điều kiện này, hãy xem Các quy tắc sử dụng biểu thức chính quy.

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

Hãy cẩn thận khi viết các quy tắc để luôn so khớp toàn bộ miền. Nếu không, quy tắc của bạn có thể khớp trong những trường hợp không mong muốn. Ví dụ: khi sử dụng 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

Bạn nên sử dụng:

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

Tương tự, hãy dùng các ký tự ^ và / để cố định một biểu thức chính quy. 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 sẽ áp dụng các quy tắc DNR trong nhiều giai đoạn của vòng đời yêu cầu mạng.

Trước khi yêu cầu

Trước khi một 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 giản đồ từ HTTP lên HTTPS) yêu cầu đó bằng một quy tắc trùng khớp.

Đối với mỗi tiện ích, trình duyệt sẽ xác định một danh sách các quy tắc trùng khớp. Những quy tắc có hành động modifyHeaders sẽ không được đưa vào đây vì những quy tắc này 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 đề xuất cho mỗi yêu cầu. Chrome tìm thấy một quy tắc phù hợp bằng cách sắp xếp tất cả các quy tắc phù hợ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 quy tắc đề xuất là quy tắc allow hoặc allowAllRequests, hoặc khung mà yêu cầu được đưa ra trước đây đã khớp với quy tắc allowAllRequests có mức độ ưu tiên cao hơn hoặc bằng từ tiện ích này, thì yêu cầu sẽ được "cho 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ì một hành động duy nhất sẽ được chọ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 hai quy tắc thuộc cùng một loại, Chrome sẽ chọn quy tắc của tiện ích được cài đặt gần đây nhất.

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

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

Trong một tiện ích duy nhất, Chrome sẽ tạo danh sách các nội dung cần sửa đổi bằng cách tìm tất cả các quy tắc modifyHeaders phù hợp. Tương tự như trước đây, 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.

Chrome sẽ áp dụng các quy tắc này theo thứ tự sao cho các quy tắc của tiện ích mới cài đặt luôn được đánh giá trước các quy tắc của tiện ích cũ. 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 một quy tắc nối vào một tiêu đề, thì các quy tắc có mức độ ưu tiên thấp hơn chỉ có thể nối vào tiêu đề đó. Không được phép thực hiện các thao tác đặt và xoá.
  • Nếu một quy tắc đặt tiêu đề, thì chỉ các quy tắc có mức độ ưu tiên thấp hơn trong 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 gì khác.
  • Nếu một quy tắc xoá tiêu đề, thì các quy tắc có mức độ ưu tiên thấp hơn sẽ không thể sửa đổi thêm tiêu đề đó.

Sau khi nhận được câu trả lờ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, đồng thời loại trừ mọi quy tắc dư thừa do quy tắc allow hoặc allowAllRequests trùng khớp (việc này diễn ra tương tự như các bước trong phần "Trước khi có 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 đã đế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. Một quy tắc chặn hoặc chuyển hướng có điều kiện về tiêu đề phản hồi vẫn sẽ chạy, nhưng không thể chặn hoặc chuyển hướng yêu cầu.

Trong trường hợp có quy tắc chặn, trang đưa ra yêu cầu sẽ nhận được phản hồi bị chặn và Chrome sẽ chấm dứt yêu cầu sớm. Trong trường hợp có quy tắc chuyển hướng, Chrome sẽ đưa ra 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 sửa đổi cho tiêu đề phản hồi 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 các sửa đổi đối với tiêu đề yêu cầu 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 xác định là quy tắc có hành động là block, allow, allowAllRequests hoặc upgradeScheme. Các quy tắc này phải tuân theo hạn mức quy tắc động cao hơn.

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ẽ làm giảm hiệu suất, vì vậy, một số giới hạn sẽ được áp dụng khi bạn sử dụng API này. Giới hạn phụ thuộc vào loại quy tắc mà bạn đang sử dụng.

Quy tắc tĩnh

Quy tắc tĩnh là những quy tắc được chỉ định trong các 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 tập hợp quy tắc tĩnh trong khoá "rule_resources" của tệp kê khai, nhưng mỗi lần chỉ có thể bật 50 tập hợp quy tắc trong số này. Sau này được gọi là MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. Nhìn chung, các bộ quy tắc đó đảm bảo có í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 mà tất cả các tiện ích được cài đặt trên trình duyệt của người dùng bật. Bạn có thể tìm thấy số này tại thời gian chạy bằng cách gọi getAvailableStaticRuleCount(). Bạn có thể xem ví dụ về trường hợp 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 được tiết lộ dưới dạng MAX_NUMBER_OF_SESSION_RULES.

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

Các quy tắc động

Một tiện ích có thể có ít nhất 5.000 quy tắc linh hoạt. Thông tin này được tiết lộ dưới dạng MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES.

Kể từ Chrome 121, có giới hạn lớn hơn là 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. Mọi 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 động và quy tắc phiên.

Các 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á 1.000. Đây được gọi là MAX_NUMBER_OF_REGEX_RULES.

Ngoài ra, mỗi quy tắc phải nhỏ hơn 2 KB sau khi được biên dịch. Điều này 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 đó sẽ bị bỏ qua.

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

Tương tác với các worker dịch vụ

declarativeNetRequest chỉ áp dụng cho những yêu cầu đạt đến ngăn xếp mạng. Điều này bao gồm 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 thông qua trình xử lý onfetch của worker dịch vụ. declarativeNetRequest sẽ không ảnh hưởng đến các phản hồi do worker dịch vụ tạo hoặ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 worker dịch vụ.

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

Một 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 một tài nguyên không thể truy cập qua web. Việc này sẽ gây ra lỗi. Điều này vẫn áp dụng ngay cả khi tài nguyên có thể truy cập trên web được chỉ định thuộc về tiện ích chuyển hướng. Để khai báo tài nguyên cho declarativeNetRequest, hãy sử 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 quy tắc động

Ví dụ sau đây trình bày cách gọi updateDynamicRules(). Quy trình cho updateSessionRules() cũng tương tự.

// 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 bộ quy tắc tĩnh

Ví dụ sau đây cho thấy cách bật và tắt nhóm quy tắc trong khi xem xét số lượng nhóm quy tắc tĩnh có sẵn và số lượng nhóm quy tắc tĩnh tối đa được bật. Bạn sẽ làm việc này khi số lượng quy tắc tĩnh bạn cần vượt quá số lượng được phép. Để điều này hoạt động, bạn phải cài đặt một số nhóm quy tắc và vô hiệu hoá một số nhóm 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 đây minh hoạ cách Chrome ưu tiên các quy tắc trong một tiện ích. Khi xem xét các quy tắc này, bạn có thể muốn mở các quy tắc ưu tiên trong một cửa sổ riêng.

Khoá "priority"

Các ví dụ này yêu cầu quyền truy cập vào máy chủ để *://*.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 xuất hiện bên dưới chúng.

Chuyển đến https://google.com
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ã nhận dạng 1 sẽ áp dụng vì các thao tác "block" có mức độ ưu tiên cao hơn các thao tác "redirect". Các quy tắc còn lại không áp dụng vì chúng dành cho các URL dài hơn.
Chuyển đến https://google.com/1234
Do URL dài hơn, quy tắc có mã nhận dạng 2 hiện cũng trùng khớp ngoài các quy tắc có mã nhận dạng 1 và 4. Quy tắc có mã nhận dạng 2 sẽ áp dụng vì "allow" có mức độ ưu tiên cao hơn "block" và "redirect".
Chuyển đế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 sẽ á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 truy cập vào máy chủ lưu trữ đối với *://*.example.com/*.

Ví dụ sau đây 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 của tiện ích /a.jpg sẽ phân giải thành chrome-extension://EXTENSION_ID/a.jpg, trong đó EXTENSION_ID là mã nhận dạng của tiện ích. Để hoạt động, tệp kê khai phải khai báo /a.jpg là một tài nguyên có thể truy cập qua web.

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

Sau đây sử dụng khoá "transform" để chuyển hướng đến một miền con của example.com. Khoá này sử dụng một điểm neo tên miền ("||") để chặn các yêu cầu có bất kỳ lược đồ nào 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 các dấu chấm được thoát và nhóm ghi nhận chọn "abc" hoặc "def". Khoá "regexSubstitution" chỉ định kết quả 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 thu thập từ URL chuyển hướng và đặt trong 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 sẽ 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

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

Enum

"firstParty"
Yêu cầu mạng là bên thứ nhất đối với khung hình 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 hình 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

    Có tự động hiển thị số lượt 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 được duy trì trong các 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ố lượt hành động của thẻ.

GetDisabledRuleIdsOptions

Chrome 111 trở lên

Thuộc tính

  • rulesetId

    chuỗi

    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 được chỉ định, 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. Thao tác này sử dụng cú pháp mẫu so khớp giống như values.

  • tiêu đề

    chuỗi

    Tên của tiêu đề. Điều kiện này chỉ so khớp theo tên nếu bạn không 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. Việc phân tích cú pháp này hỗ trợ tính năng 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ớp với 0 hoặc 1 ký tự.

    Bạn có thể dùng dấu gạch chéo ngược để thoát ký tự '*' và '?', ví dụ: '\*' và '\?'

HeaderOperation

Chrome 86 trở lên

Mục này mô tả các thao tác có thể có đối với quy tắc "modifyHeaders".

Enum

"append"
Thêm một mục mới cho tiêu đề đã chỉ định. Thao tác này không được hỗ trợ cho tiêu đề 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 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ã nhận dạng của một quy tắc so khớp.

  • rulesetId

    chuỗi

    Mã nhận dạng của Ruleset mà quy tắc này thuộc về. Đối với một quy tắc bắt nguồn từ bộ quy tắc linh độ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ẻ nơi bắt nguồn yêu cầu nếu thẻ đó vẫn đang hoạt động. Nếu không thì là -1.

  • timeStamp

    số

    Thời gian quy tắc được so khớp. 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

    number không bắt buộc

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

  • tabId

    number không bắt buộc

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

ModifyHeaderInfo

Chrome 86 trở lên

Thuộc tính

  • tiêu đề

    chuỗi

    Tên của tiêu đề cần sửa đổi.

  • operation

    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 đề. Bạn phải chỉ định cho các thao tác append và set.

QueryKeyValue

Thuộc tính

  • phím

    chuỗi

  • replaceOnly

    boolean không bắt buộc

    Chrome 94 trở lên

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

  • value

    chuỗi

QueryTransform

Thuộc tính

  • addOrReplaceParams

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

    Danh sách các cặp khoá-giá trị truy vấn cần thêm hoặc thay thế.

  • removeParams

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

    Danh sách các 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. Phải 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 một regexFilter. Nội dung 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ố có dấu gạch chéo ngược (\1 đến \9) để chèn các nhóm chụ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

    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

    chuỗi

    Biểu thức chính quy cần kiểm tra.

  • requireCapturing

    boolean không bắt buộc

    regex được chỉ định có yêu cầu chụp hay không. Bạn chỉ cần ghi lại đối với các quy tắc chuyển hướng chỉ định một thao tác 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 của 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 xảy ra trong khung chính; giá trị dương cho biết mã nhận dạng của một khung phụ mà yêu cầu xảy ra. Nếu tài liệu của một khung (phụ) được tải (type là main_frame hoặc sub_frame), frameId 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ã nhận dạng 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 hình, nếu yêu cầu này là dành cho khung hình.

  • 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 bắt đầu. Thông tin 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 không minh bạch, thì chuỗi "null" sẽ được dùng.

  • method

    chuỗi

    Phương thức HTTP tiêu 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 mẹ của khung, nếu yêu cầu này là dành cho một khung và có một khung 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ã nhận dạng 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ã nhận dạng của thẻ mà yêu cầu diễn ra. Đặt thành -1 nếu yêu cầu không liên quan đến thẻ.

  • loại

    ResourceType

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

  • url

    chuỗi

    URL của yêu cầu.

RequestMethod

Chrome 91 trở lên

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

Enum

"connect"

"delete"

"get"

"head"

"options"

"patch"

"post"

"put"

"other"

ResourceType

Mục 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"

"image"

"font"

"object"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"webtransport"

"webbundle"

"other"

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 được đáp ứng.

  • điều kiện

    RuleCondition

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

  • id

    số

    Mã nhận dạng riêng biệt của một quy tắc. Bắt buộc và phải lớn hơn hoặc bằng 1.

  • của chiến dịch

    number không bắt buộc

    Mức độ ưu tiên của quy tắc. Giá trị mặc định là 1. Khi được chỉ định, giá trị này phải lớn hơn hoặc bằng 1.

RuleAction

Thuộc tính

  • chuyển hướng

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

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

  • requestHeaders

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

    Chrome 86 trở lên

    Tiêu đề 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

    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 hành động cần thực hiện nếu một RuleCondition nhất định trùng khớ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ó một quy tắc cho phép khớ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 đề 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ệ thống phân cấp khung, bao gồm cả 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 tham số này, tất cả các yêu cầu sẽ đượ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ỉ so khớp 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 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 excludedInitiatorDomains. Nếu bạn để trống hoặc bỏ qua danh sách này, thì sẽ không có miền nào bị loại trừ. Thao tác này được ưu tiên hơn initiatorDomains.

    Lưu ý:

    • Bạn cũng được phép sử dụng các miền phụ như "a.example.com".
    • Các 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á.
    • Điều này so khớp với trình khởi tạo yêu cầu chứ không phải URL yêu cầu.
    • Miền phụ của các miền được liệt kê cũng sẽ bị loại trừ.
  • excludedRequestDomains

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

    Chrome 101 trở lên

    Quy tắc 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 bạn để trống hoặc bỏ qua danh sách này, thì sẽ không có miền nào bị loại trừ. Thao tác này được ưu tiên hơn requestDomains.

    Lưu ý:

    • Bạn cũng được phép sử dụng các miền phụ như "a.example.com".
    • Các 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 sẽ bị loại trừ.
  • excludedRequestMethods

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

    Chrome 91 trở lên

    Danh sách các phương thức yêu cầu mà quy tắc sẽ không khớp. Bạn chỉ nên chỉ định một trong hai thuộc tính requestMethods và excludedRequestMethods. Nếu bạn không chỉ định cả hai, thì tất cả cá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. Bạn chỉ nên chỉ định một trong hai thuộc tính resourceTypes và excludedResourceTypes. Nếu bạn không chỉ định loại nào, thì tất cả các loại tài nguyên ngoại trừ "main_frame" đều 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 được khớp. Mã nhận dạng tabs.TAB_ID_NONE loại trừ những yêu cầu không bắt nguồn từ một thẻ. Chỉ được hỗ trợ cho các quy tắc theo phạm vi phiên.

  • initiatorDomains

    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 bắt nguồn từ danh sách initiatorDomains. Nếu bạn bỏ qua danh sách này, quy tắc sẽ được áp dụng cho các yêu cầu từ tất cả các miền. Không được phép để trống danh sách.

    Lưu ý:

    • Bạn cũng được phép sử dụng các miền phụ như "a.example.com".
    • Các 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á.
    • Điều này so khớp với trình khởi tạo yêu cầu chứ không phải URL yêu cầu.
    • Các miền phụ của những miền được liệt kê cũng được so khớp.
  • isUrlFilterCaseSensitive

    boolean không bắt buộc

    urlFilter hoặc regexFilter (bất kể bạn chỉ định thuộc tính nào) 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. Điều 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. Tham số này được so khớp với một URL mà máy chủ được mã hoá ở định dạng punycode (trong trường hợp miền quốc tế hoá) và mọi ký tự không phải ASCII khác đều được mã hoá URL ở định dạ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 miền trong danh sách requestDomains. Nếu bạn bỏ qua danh sách này, quy tắc sẽ được áp dụng cho các yêu cầu từ tất cả các miền. Không được phép để trống danh sách.

    Lưu ý:

    • Bạn cũng được phép sử dụng các miền phụ như "a.example.com".
    • Các 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 những miền được liệt kê cũng được so khớp.
  • requestMethods

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

    Chrome 91 trở lên

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

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

  • 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ể so khớp. Không được phép để trống danh sách.

    Lưu ý: bạn phải chỉ định thuộc tính này cho các quy tắc allowAllRequests và chỉ có thể 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 tiêu đề phản hồi nào 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 phải khớp. Mã nhận dạng tabs.TAB_ID_NONE khớp với những yêu cầu không bắt nguồn từ một thẻ. Không được phép để trống danh sách. Chỉ được hỗ trợ cho các quy tắc theo phạm vi phiên.

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

    '|' : Điểm neo bên trái/phải: Nếu được dùng ở một trong hai đầu của mẫu, thì sẽ chỉ định điểm bắt đầu/kết thúc của URL tương ứng.

    '||' : Điểm neo tên miền: Nếu được dùng ở đầu mẫu, thì điểm neo này sẽ chỉ định điểm bắt đầu của một (miền phụ) của URL.

    "^" : Ký tự phân cách: Ký tự này khớp với mọi ký tự, ngoại trừ chữ cái, chữ số hoặc một trong các ký tự sau: _, -, . hoặc %. Điều 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: (neo bên trái/tên miền không bắt buộc) + mẫu + (neo bên phải không bắt buộc).

    Nếu bạn bỏ qua, tất cả URL sẽ được so khớp. Không được phép dùng chuỗi trống.

    Không được phép sử dụng 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. Tham số này được so khớp với một URL mà máy chủ được mã hoá ở định dạng punycode (trong trường hợp miền quốc tế hoá) và mọi ký tự không phải ASCII khác đều được mã hoá URL ở định dạng UTF-8. Ví dụ: khi URL yêu cầu là http://abc.рф?q=ф, 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

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

  • id

    chuỗi

    Một chuỗi không trống xác định duy nhất bộ quy tắc. Các mã nhận dạng bắt đầu bằng "_" là dành riêng cho mục đích sử dụng nội bộ.

  • đường dẫn

    chuỗi

    Đường dẫn của bộ quy tắc JSON tương ứng với thư mục tiện ích.

RulesMatchedDetails

Thuộc tính

  • rulesMatchedInfo

    MatchedRuleInfo[]

    Các 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ố lượng cần tăng cho số lượt hành động của thẻ. Giá trị âm sẽ làm giảm số lượng.

  • tabId

    số

    Thẻ mà bạn muốn cập nhật số lượt hành động.

TestMatchOutcomeResult

Chrome 103 trở lên

Thuộc tính

  • matchedRules

    MatchedRule[]

    Các quy tắc (nếu có) khớ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 tiêu chuẩn của yêu cầu giả định. Giá trị mặc định là "get" cho 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

    Chrome 129 trở lên

    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 đề đến 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, có thể khớp với các quy tắc khớp khi không có tiêu đề. Ví dụ: {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}

  • tabId

    number 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 phải tương ứng với mã nhận dạng thẻ thực. Giá trị mặc định là -1, tức là yêu cầu không liên quan đến thẻ.

  • loại

    ResourceType

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

  • url

    chuỗi

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

UnsupportedRegexReason

Chrome 87 trở lên

Mô tả lý do khiến 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

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

    Các quy tắc cần thêm.

  • removeRuleIds

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

    Mã nhận dạng 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 bị vô hiệu hoá.

  • enableRulesetIds

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

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

UpdateStaticRulesOptions

Chrome 111 trở lên

Thuộc tính

  • disableRuleIds

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

    Tập hợp các mã nhận dạng tương ứng với các quy tắc trong Ruleset để tắt.

  • enableRuleIds

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

    Tập hợp mã nhận dạng tương ứng với các quy tắc trong Ruleset để bật.

  • rulesetId

    chuỗi

    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. Phải là chuỗi trống, trong trường hợp đó, phân đoạn hiện có sẽ 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 bạn để trống, đườ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, cổng hiện có 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 là một chuỗi trống (trong trường hợp này, truy vấn hiện có sẽ bị xoá) hoặc phải bắt đầu bằng dấu "?".

  • queryTransform

    QueryTransform không bắt buộc

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

  • lược đồ

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

    Lượ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ã nhận dạng nhóm quy tắc cho các quy tắc linh động do tiện ích này thêm.

Giá trị

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

Khoảng thời gian mà bạn có thể thực hiện cuộc gọi MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules, được chỉ định bằng phút. Các lệnh gọi bổ sung sẽ thất bại ngay lập tức và đặt runtime.lastError. Lưu ý: Các lệnh gọi getMatchedRules 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 tối thiểu các quy tắc tĩnh được đảm bảo cho một tiện ích trên các nhóm 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 toàn cầu.

Giá trị

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

Số lần bạn có thể gọi getMatchedRules 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 tối đa Rulesets phần mở rộng tĩnh mà một phần mở rộng 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. Giới hạn này được đánh giá riêng cho tập hợp các quy tắc độ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 ở phạm vi phiên mà một tiện ích có thể thêm.

Giá trị

5000

MAX_NUMBER_OF_STATIC_RULESETS

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

Giá trị

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120 trở lên

Số lượng tối đa các quy tắc động "không an toàn" 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 các quy tắc có phạm vi phiên "không an toàn" mà một tiện ích có thể thêm.

Giá trị

5000

SESSION_RULESET_ID

Chrome 90 trở lên

Mã nhận dạng bộ quy tắc cho các quy tắc trong phạm vi phiên do tiện ích thêm.

Giá trị

"_session"

Phương thức

getAvailableStaticRuleCount()

Chrome 89 trở lên 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(): Promise<number>

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

Giá trị trả về

  • Promise<number>

    Chrome 91 trở lên

getDisabledRuleIds()

Chrome 111 trở lên 
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
): Promise<number[]>

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

Thông số

Giá trị trả về

  • Promise<number[]>

getDynamicRules()

chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
): Promise<Rule[]>

Trả về bộ quy tắc linh động hiện tại cho tiện ích. Người 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.

Thông số

  • filter

    GetRulesFilter không bắt buộc

    Chrome 111 trở lên

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

Giá trị trả về

  • Promise<Rule[]>

    Chrome 91 trở lên

getEnabledRulesets()

chrome.declarativeNetRequest.getEnabledRulesets(): Promise<string[]>

Trả về mã nhận dạng cho nhóm quy tắc tĩnh hiện tại đã bật.

Giá trị trả về

  • Promise<string[]>

    Chrome 91 trở lên

getMatchedRules()

chrome.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
): Promise<RulesMatchedDetails>

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

Thông số

  • filter

    MatchedRulesFilter không bắt buộc

    Một đối tượng để lọc danh sách các quy tắc trùng khớp.

Giá trị trả về

getSessionRules()

Chrome 90 trở lên 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
): Promise<Rule[]>

Trả về tập hợp hiện tại gồm các quy tắc theo phạm vi phiên cho tiện ích. Người 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.

Thông số

  • filter

    GetRulesFilter không bắt buộc

    Chrome 111 trở lên

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

Giá trị trả về

  • Promise<Rule[]>

    Chrome 91 trở lên

isRegexSupported()

Chrome 87 trở lên 
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
): Promise<IsRegexSupportedResult>

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

Thông số

  • regexOptions

    RegexOptions

    Biểu thức chính quy cần kiểm tra.

Giá trị trả về

setExtensionActionOptions()

Chrome 88 trở lên 
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
): Promise<void>

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

Thông số

Giá trị trả về

  • Promise<void>

    Chrome 91 trở lên

testMatchOutcome()

Chrome 103 trở lên 
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
): Promise<TestMatchOutcomeResult>

Kiểm tra xem có quy tắc declarativeNetRequest nào của tiện ích khớp với một yêu cầu giả định hay không. Lưu ý: Chỉ có sẵn cho các tiện ích chưa đóng gói vì tính năng này chỉ dùng trong quá trình phát triển tiện ích.

Thông số

Giá trị trả về

updateDynamicRules()

chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
): Promise<void>

Sửa đổi bộ quy tắc động hiện tại cho tiện ích. Các quy tắc có mã nhận dạng được liệt kê trong options.removeRuleIds sẽ bị xoá trước, sau đó các quy tắc được cung cấp trong options.addRules sẽ được thêm vào. Lưu ý:

  • Quá trình cập nhật này diễn ra dưới dạng một thao tác đơn lẻ: tất cả các quy tắc được chỉ định sẽ được thêm và xoá, hoặc một lỗi sẽ được trả về.
  • Các quy tắc này được duy trì trong các phiên trình duyệt và trong các bản cập nhật tiện ích.
  • Bạn không thể xoá các quy tắc tĩnh được chỉ định trong gói tiện ích bằng hàm này.
  • MAX_NUMBER_OF_DYNAMIC_RULES là số lượng quy tắc linh hoạt 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.

Thông số

Giá trị trả về

  • Promise<void>

    Chrome 91 trở lên

updateEnabledRulesets()

chrome.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
): Promise<void>

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

Thông số

Giá trị trả về

  • Promise<void>

    Chrome 91 trở lên

updateSessionRules()

Chrome 90 trở lên 
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
): Promise<void>

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

  • Quá trình cập nhật này diễn ra dưới dạng một thao tác đơn lẻ: tất cả các quy tắc được chỉ định sẽ được thêm và xoá, hoặc một lỗi sẽ được trả về.
  • Các quy tắc này không được duy trì trong các phiên và được sao lưu vào 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.

Thông số

Giá trị trả về

  • Promise<void>

    Chrome 91 trở lên

updateStaticRules()

Chrome 111 trở lên 
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
): Promise<void>

Tắt và bật các quy tắc tĩnh riêng lẻ trong một Ruleset. Những thay đổi đối với các quy tắc thuộc Ruleset bị vô hiệu hoá sẽ có hiệu lực vào lần tiếp theo khi quy tắc đó được bật.

Thông số

Giá trị trả về

  • Promise<void>

Sự kiện

onRuleMatchedDebug

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

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

Thông số