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 các tiện ích sửa đổi các yêu cầu mạng mà không cần chặn và xem nội dung của các yêu cầu đó, nhờ đó tăng cường quyền riêng tư.

Quyền

declarativeNetRequest
declarativeNetRequestWithHostAccess

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

"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 tính năng này khi có thể để tránh phải 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 các tiện ích chưa 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 quyền của 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ữ. Đ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 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 quy tắc, cụ thể là 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 các từ điển thuộc loại Ruleset, như minh hoạ dưới đây. (Lưu ý rằng tên "Ruleset" (Bộ quy tắc) không xuất hiện trong JSON của tệp kê khai vì đó chỉ là một mảng.) Quy tắc tĩnh đượ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 bộ quy tắc. Bộ quy tắc chứa một mảng các quy tắc. Một quy tắc sẽ thực hiện một trong những việc sau:

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

Có ba loại quy tắc, đượ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à bản 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
Được xoá khi trình duyệt tắt và khi cài đặt phiên bản mới của tiện ích. Các quy tắc phiên được quản lý bằng JavaScript 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 có định dạng JSON và được liệt kê trong tệp kê khai.

Quy tắc trong phạm vi phiên và quy tắc động

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

  • Các quy tắc động vẫn tồn tại trong các phiên trình duyệt và bản 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 bạn cài đặt phiên bản mới của tiện ích.

Mỗi loại quy tắc chỉ có một. Tiện ích có thể tự động thêm hoặc xoá các quy tắc vào chú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 bài viết Giới hạn quy tắc. Bạn có thể xem ví dụ về việc này trong phần ví dụ về mã.

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 một tiện ích được cài đặt hoặc nâng cấp. Các quy tắc này được lưu trữ trong tệp quy tắc ở định dạng JSON, được chỉ định 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 cho bộ quy tắc có trong tệp và liệu bộ quy tắc đó có đang bật hay tắt. Hai thuộc tính cuối cùng rất quan trọng khi bạn bật hoặc tắt quy tắc theo phương thức lập trình.

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

Để kiểm thử tệp quy tắc, hãy tải phần mở rộng đã giải nén. Lỗi và cảnh báo về 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 giải nén. Các quy tắc tĩnh không hợp lệ trong các tiện ích đã đóng gói sẽ bị bỏ qua.

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. Xem phần quy trình xem xét ưu tiên đối với những thay đổi đủ điều kiện.

Bật và tắt 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.

Tập hợp các quy tắc tĩnh và bộ quy tắc đã bật sẽ được duy trì trong các phiên trình duyệt. Cả hai đều không được duy trì trong các bản cập nhật tiện ích, nghĩa là chỉ những quy tắc bạn chọn để 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, cũng có giới hạn về số lượng quy tắc và bộ 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ể bật. Để biết thông tin về giới hạn 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 nhận một đối tượng UpdateStaticRulesOptions chứa các mảng mã nhận dạng của các quy tắc để 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 nhóm quy tắc tĩnh, hãy gọi updateEnabledRulesets(). Phương thức này nhận một đối tượng UpdateRulesetOptions chứa các mảng mã nhận dạng của các bộ quy tắc để 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ạ 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 tất cả các yêu cầu tập lệnh bắt nguồn từ "foo.com" đến bất kỳ URL nào có "abc" làm 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 mạng khai báo 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 quy tắc cho phép khoá "urlFilter" thực hiện hành động trên các URL trong một miền cụ thể. 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

Đ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 các điều kiện này, hãy xem phần Quy tắc sử dụng biểu thức chính quy.

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

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, quy tắc của bạn có thể khớp trong các tình huống 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

Hãy cân nhắc sử dụng:

  • ||google.com/, khớp với tất cả đường dẫn và tất 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 sử dụng các ký tự ^ và / để liên kết 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 á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 yêu cầu được thực hiện, một 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) yêu cầu đó bằng một quy tắc phù hợ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 khớp. Các quy tắc có hành động modifyHeaders không được đưa vào đây vì chúng 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 chọn tối đa một đề xuất cho mỗi yêu cầu. Chrome tìm 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 đề xuất là quy tắc allow hoặc allowAllRequests, hoặc khung mà yêu cầu đang được thực hiện trước đó đã so khớp với quy tắc allowAllRequests có mức độ ưu tiên cao hơn hoặc bằng với 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ì hệ thống sẽ chọn một hành động duy nhất để 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 hai quy tắc thuộc cùng một loại, thì Chrome sẽ chọn quy tắc từ tiện ích được cài đặt gần đây nhất.

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

Trước khi Chrome gửi tiêu đề yêu cầu đến máy chủ, 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 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 mọi quy tắc allow hoặc allowAllRequests trùng khớp mới được đưa vào.

Chrome á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 đượ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 một quy tắc được 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 cho phép 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 đề đó. Không được phép sửa đổi nội dung nào khác.
  • Nếu một quy tắc xoá một tiêu đề, thì các quy tắc có mức ưu tiên thấp hơn không thể sửa đổi thêm tiêu đề đó.

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 bằng đ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 bị thừa do quy tắc allow hoặc allowAllRequests trùng khớp (quy trình này diễn ra giống hệt như các bước trong phần "Trước khi yêu cầu"), Chrome có thể thay mặt một tiện ích chặn hoặc chuyển hướng yêu cầu.

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. Quy tắc chặn hoặc chuyển hướng có điều kiện tiêu đề phản hồi vẫn sẽ chạy nhưng không thể thực sự chặn hoặc chuyển hướng yêu cầu.

Trong trường hợp quy tắc chặn, việc này sẽ do trang đã gửi yêu cầu nhận được phản hồi bị chặn xử lý và Chrome sẽ chấm dứt sớm yêu cầu đó. Trong trường hợp có quy tắc chuyển hướng, Chrome sẽ tạo 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ư đối với 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 hoạt động giống như mô tả trong phần "Trước khi gửi tiêu đề yêu cầu". Việc áp dụng nội dung sửa đổi cho tiêu đề yêu cầu sẽ không có tác dụng 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à các 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 tăng lê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ẽ gây hao tổn hiệu suất, vì vậy, một số giới hạn sẽ áp dụng khi sử dụng API. Giới hạn phụ thuộc vào loại quy tắc 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 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 nhóm quy tắc tĩnh trong khoá tệp kê khai "rule_resources", nhưng mỗi lần chỉ có thể bật 50 nhóm quy tắc trong số này. Lớp sau được gọi là MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. Tổng cộng, các bộ quy tắc đó đượ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 được bật bởi tất cả các tiện ích đã 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ề việc 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 hiển thị dưới dạng MAX_NUMBER_OF_SESSION_RULES.

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

Các quy tắc động

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

Kể từ Chrome 121, giới hạn lớn hơn là 30.000 quy tắc sẽ được áp dụng 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 5.000 quy tắc phiên và quy tắc linh động kết hợp.

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 có kích thước dưới 2 KB sau khi biên dịch. Điều này tương quan gần đúng 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 worker dịch vụ

declarativeNetRequest chỉ áp dụng cho các yêu cầu đế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 đi 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 ra 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 hỗ trợ tiếp cận trên web

Quy tắc declarativeNetRequest không thể chuyển hướng từ yêu cầu tài nguyên công khai sang tài nguyên không truy cập được trên web. Việc này sẽ kích hoạt lỗi. Điều này vẫn đúng ngay cả khi tài nguyên truy cập được 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 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 biết cách bật và tắt các bộ quy tắc trong khi xem xét số lượng bộ quy tắc tĩnh có sẵn và số lượng bộ quy tắc tĩnh được bật tối đa. Bạn sẽ làm việc này khi số lượng quy tắc tĩnh cần thiết vượt quá số lượng được phép. Để tính năng này hoạt động, bạn phải cài đặt một số bộ quy tắc và tắt một số bộ quy tắc khá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 nê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 của máy chủ đối với *://*.example.com/*.

Để tí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 tham chiếu đến tệp quy tắc mẫu hiển thị bên dưới.

Chuyển đến https://google.com
Hai quy tắc áp dụng cho URL này: các quy tắc có mã nhận dạng 1 và 4. Quy tắc có mã nhận dạng 1 sẽ được á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 URL dài hơn.
Chuyển đến https://google.com/1234
Do URL dài hơ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ã nhận dạng 2 sẽ được á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ẽ đượ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 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 mở rộng /a.jpg 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. Để tính năng này hoạt động, tệp kê khai phải khai báo /a.jpg là 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"]
  }
}

Phần sau sử dụng khoá "transform" để chuyển hướng đến một miền con của example.com. Phần này sử dụng neo tên miền ("||") để chặn các yêu cầu có bất kỳ giao thứ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 thoát dấu chấm và nhóm nhận dạng 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 lấy từ URL được chuyển hướng và được đặ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 xoá tất cả cookie khỏi cả khung chính và mọi khung con.

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

Loại

DomainType

Thuộc tính 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. Một yêu cầu được coi là của bên thứ nhất nếu yêu cầu đó có cùng miền (eTLD+1) với khung hình nơi 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 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 được duy trì trong các phiên hoạt động.

  • 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

    chuỗi

    Mã nhận dạng tương ứng với 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. Phương thức này sử dụng cú pháp mẫu khớp giống như values.

  • tiêu đề

    chuỗi

    Tên của tiêu đề. Điều kiện này chỉ khớp với 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. Phương thức 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ớp với 0 hoặc 1 ký tự.

    Bạn có thể thoát ký tự "*" và "?" 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 đố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 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ả mục nhập 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 không hỗ trợ biểu thức chính quy. Chỉ được cung cấp nếu isSupported là sai.

MatchedRule

Thuộc tính

  • ruleId

    số

    Mã nhận dạng của quy tắc trùng khớp.

  • rulesetId

    chuỗi

    Mã 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ẻ bắt nguồn yêu cầu nếu thẻ đó vẫn hoạt động. Nếu không -1.

  • timeStamp

    số

    Thời gian 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 với các quy tắc cho thẻ đã cho. Khớp với các quy tắc không liên kết với thẻ nào đang hoạt động nếu bạn đặt giá trị này 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.

  • toán tử

    HeaderOperation

    Thao tác cần 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

    chuỗi

  • 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 khoá đó đã có sẵn. Nếu không, khoá này cũng đượ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ặ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 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 dấu "/".

  • regexSubstitution

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

    Mẫu thay thế cho các quy tắc chỉ định 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ể sử 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 nhận dạng 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 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

    chuỗi

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

  • requireCapturing

    boolean không bắt buộc

    Liệu regex được chỉ định có yêu cầu chụp hay không. Bạn chỉ cần chụp ảnh cho các 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à 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à 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ã của khung phụ trong đó yêu cầu xảy ra. Nếu tài liệu của một khung (phụ) được tải (type là main_frame hoặc sub_frame), frameId sẽ cho biết mã nhận dạng của khung này, chứ không phải mã nhận dạng của khung bên ngoài. Mã khung là duy nhất trong một thẻ.

  • frameType

    FrameType không bắt buộc

    Chrome 106 trở lên

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

  • trình khởi tạo

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

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

  • method

    chuỗi

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

  • parentDocumentId

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

    Chrome 106 trở lên

    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à cho một khung và có khung mẹ.

  • parentFrameId

    số

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

  • requestId

    chuỗi

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

  • tabId

    số

    Mã của thẻ nơi diễn ra yêu cầu. Đặ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

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"

"patch"

"post"

"put"

"other"

ResourceType

Thuộc tính 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 khớp.

  • đ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 duy nhấ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

    số 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, 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

    Các 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

    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 hành động cần thực hiện nếu một RuleCondition nhất định 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ó 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 lên 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 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 nơi yêu cầu đó bắt nguồn. Nếu bạn bỏ qua, tất cả yêu cầu sẽ được chấp nhận.

  • tên miền

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

    Ngừng sử dụng 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

    Ngừng sử dụng 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 danh sách này trống hoặc bị bỏ qua, thì sẽ không có miền nào bị loại trừ. Phương thức này được ưu tiên hơn initiatorDomains.

    Lưu ý:

    • Bạn cũng được phép sử dụng tên miền phụ như "a.example.com".
    • Các mục nhập chỉ được chứa ký tự ASCII.
    • Sử dụng mã hoá punycode cho các miền quốc tế hoá.
    • Giá trị 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 con 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 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ì sẽ không có miền nào bị loại trừ. Phương thức này được ưu tiên hơn requestDomains.

    Lưu ý:

    • Bạn cũng được phép sử dụng tên miền phụ như "a.example.com".
    • Các mục nhập chỉ được chứa ký tự ASCII.
    • Sử dụng mã hoá punycode cho các miền quốc tế hoá.
    • Miền con 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. Chỉ được 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ả 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 thuộc tính resourceTypes và excludedResourceTypes. Nếu bạn không chỉ định cả hai, tất cả các loại tài nguyên ngoại trừ "main_frame" sẽ bị chặn.

  • excludedResponseHeaders

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

    Chrome 128 trở lên

    Quy tắc không 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). 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ã tabs.TAB_ID_NONE loại trừ các yêu cầu không bắt nguồn từ một thẻ. Chỉ hỗ trợ cho các quy tắc ở 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ả miền. Không được để danh sách trống.

    Lưu ý:

    • Bạn cũng được phép sử dụng tên miền phụ như "a.example.com".
    • Các mục nhập chỉ được chứa ký tự ASCII.
    • Sử dụng mã hoá punycode cho các miền quốc tế hoá.
    • Giá trị 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 con của các miền được liệt kê cũng đượ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. Cú pháp này tuân theo cú pháp RE2.

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

    Lưu ý: regexFilter chỉ được tạo thành từ các ký tự ASCII. Giá trị này được so khớp với một URL mà máy chủ lưu trữ được mã hoá ở đị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 được mã hoá URL ở 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ả miền. Không được để danh sách trống.

    Lưu ý:

    • Bạn cũng được phép sử dụng tên miền phụ như "a.example.com".
    • Các mục nhập chỉ được chứa ký tự ASCII.
    • Sử dụng mã hoá punycode cho các miền quốc tế hoá.
    • Miền con của các 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 để danh sách trống.

    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, 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 để danh sách trống.

    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 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 sẽ so 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ẻ. Không được để trống danh sách. Chỉ hỗ trợ cho các quy tắc ở 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ỳ.

    '|' : Neo trái/phải: Nếu được sử dụng ở một đầu của mẫu, hãy chỉ định đầu/cuối URL tương ứng.

    '||' : Neo tên miền: Nếu được sử dụng ở đầu mẫu, hãy chỉ định vị trí bắt đầu của 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 %. Phầ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: (mục tiêu Trái/Tên miền không bắt buộc) + mẫu + (mục tiêu 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 để 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 tạo thành từ các ký tự ASCII. Giá trị này được so khớp với một URL mà máy chủ lưu trữ được mã hoá ở đị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 được mã hoá URL ở 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

    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 giúp xác định duy nhất bộ quy tắc. Mã nhận dạng bắt đầu bằng "_" được dành riêng cho mục đích sử dụng nội bộ.

  • đường dẫn

    chuỗi

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

  • tabId

    số

    Thẻ cần cập nhật số 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 đối tượng 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

    Chrome 129 trở lên

    Các tiêu đề do 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 liên kết tên tiêu đề với 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ề các tiêu đề phản hồi trống. Các tiêu đề này 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

    số không bắt buộc

    Mã của thẻ nơi diễn ra yêu cầu giả định. Không cần phải tương ứng với 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ẻ.

  • 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 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[] optional

    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ệ 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 các 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

    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 các 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 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 trống, trong trường hợp này, mảnh hiện có sẽ bị xoá; hoặc phải bắt đầu bằng dấu "#".

  • người tổ chức

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

    Máy chủ 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, đườ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 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ặ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ó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 theo phút. Các lệnh gọi bổ sung sẽ không thành công 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ủa các quy tắc tĩnh được đảm bảo cho một tiện ích trên các bộ 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 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.

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 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 trong phạm vi phiên tối đa 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á 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 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 quy tắc trong 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ã bộ quy tắc cho các quy tắc ở phạm vi phiên do tiện ích thêm.

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à một tiện ích có thể bật trước khi đạt đến giới hạn quy tắc tĩnh chung.

Tham số

  • lệnh gọi lại

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

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

    (count: number) => void

    • số lượng

      số

Giá trị trả về

  • Promise<số>

    Chrome 91 trở lên

    Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một 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 hiện đang bị tắt.

Tham số

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

  • lệnh gọi lại

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

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

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      number[]

Giá trị trả về

  • Promise<number[]>

    Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

getDynamicRules()

Promise 
chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
  callback?: function,
)

Trả về tập hợp 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 filter.

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

  • lệnh gọi lại

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

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

    (rules: Rule[]) => void

Giá trị trả về

  • Promise<Rule[]>

    Chrome 91 trở lên

    Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

getEnabledRulesets()

Promise 
chrome.declarativeNetRequest.getEnabledRulesets(
  callback?: function,
)

Trả về mã nhận dạng cho tập hợp quy tắc tĩnh hiện đang bật.

Tham số

  • lệnh gọi lại

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

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

    (rulesetIds: string[]) => void

    • rulesetIds

      string[]

Giá trị trả về

  • Promise<string[]>

    Chrome 91 trở lên

    Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

getMatchedRules()

Promise 
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 đã so khớp bằng cách chỉ định filter. Phương thức này chỉ dành cho các tiện ích có quyền "declarativeNetRequestFeedback" hoặc được cấp quyền "activeTab" cho tabId được chỉ định trong filter. Lưu ý: Hệ thống sẽ không trả về các quy tắc không liên kết với tài liệu đang hoạt động và đã được so khớp cách đây hơn 5 phút.

Tham số

Giá trị trả về

  • Chrome 91 trở lên

    Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một 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 hiện tại trong phạm vi phiên 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 filter.

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

  • lệnh gọi lại

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

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

    (rules: Rule[]) => void

Giá trị trả về

  • Promise<Rule[]>

    Chrome 91 trở lên

    Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một 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 quy tắc regexFilter hay không.

Tham số

Giá trị trả về

  • Chrome 91 trở lên

    Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một 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 số 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 mở rộng hay không và cung cấp cách để tăng số hành động đó.

Tham số

  • lệnh gọi lại

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

    Chrome 89 trở lên

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

    () => void

Giá trị trả về

  • Promise<void>

    Chrome 91 trở lên

    Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

testMatchOutcome()

Promise Chrome 103 trở lên 
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
)

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

Tham số

Giá trị trả về

  • Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

updateDynamicRules()

Promise 
chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
  callback?: function,
)

Sửa đổi bộ quy tắc động hiện tại cho tiện ích. Trước tiên, các quy tắc có mã được liệt kê trong options.removeRuleIds sẽ bị xoá, sau đó các quy tắc được cung cấp 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 nguyên tử: tất cả các quy tắ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 độ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
  • lệnh gọi lại

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

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

    () => void

Giá trị trả về

  • Promise<void>

    Chrome 91 trở lên

    Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

updateEnabledRulesets()

Promise 
chrome.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
  callback?: function,
)

Cập nhật tập hợp các bộ quy tắc tĩnh đã bật cho tiện ích. Trước tiên, các bộ quy tắc có mã nhận dạng được liệt kê trong options.disableRulesetIds sẽ bị xoá, sau đó các bộ 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á tệp kê khai rule_resources sẽ xác định tập hợp các quy tắc tĩnh đã 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
  • lệnh gọi lại

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

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

    () => void

Giá trị trả về

  • Promise<void>

    Chrome 91 trở lên

    Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một 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 bộ quy tắc hiện tại trong phạm vi phiên cho tiện ích. Trước tiên, các quy tắc có mã được liệt kê trong options.removeRuleIds sẽ bị xoá, sau đó các quy tắc được cung cấp 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 nguyên tử: tất cả các quy tắ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 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

  • lệnh gọi lại

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

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

    () => void

Giá trị trả về

  • Promise<void>

    Chrome 91 trở lên

    Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một 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 trong Ruleset. Các thay đổi đối với quy tắc thuộc Ruleset bị tắt sẽ có hiệu lực vào lần tiếp theo khi Ruleset được bật.

Tham số

  • lệnh gọi lại

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

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

    () => void

Giá trị trả về

  • Promise<void>

    Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

Sự kiện

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 giải nén có quyền "declarativeNetRequestFeedback" vì tiện ích này chỉ dùng cho mục đích gỡ lỗi.

Tham số