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

declarativeNetRequestFeedback
host_permissions

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ên, một số loại nhóm quy tắc (cụ thể là nhóm 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ạ bên dưới. (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/*"
  ],
  ...
}

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

Để 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.

Một vài phần tiếp theo sẽ giải thích chi tiết về các loại bộ quy tắc.

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.

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.

Để 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"]
  }
}

urlFilter có các ký tự trùng khớp

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. Dưới đây là một số 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://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

Mức độ ưu tiên của quy tắc

Các quy tắc được kích hoạt bởi những yêu cầu được gửi từ các trang web. Nếu nhiều quy tắc trùng khớp với một yêu cầu cụ thể, thì bạn phải ưu tiên các quy tắc đó. Phần này giải thích cách các quy tắc này được ưu tiên. Việc ưu tiên diễn ra theo 2 giai đoạn.

  1. Mức độ ưu tiên được xác định cho các quy tắc trong một tiện ích.
  2. Nếu có nhiều tiện ích có thể áp dụng một quy tắc cho một yêu cầu, thì mức độ ưu tiên sẽ được xác định cho tất cả các tiện ích phù hợp với một yêu cầu cụ thể.

Hãy nghĩ đến việc so khớp theo cách này: bất kỳ quy tắc nào mà một tiện ích cụ thể ưu tiên sẽ được ưu tiên so với các quy tắc của những tiện ích khác.

Mức độ ưu tiên của quy tắc trong một tiện ích

Trong một tiện ích duy nhất, mức độ ưu tiên được xác định bằng quy trình sau:

  1. Quy tắc có mức độ ưu tiên cao nhất do nhà phát triển xác định (nói cách khác, trường "priority") sẽ được trả về.

  2. Nếu có nhiều quy tắc có mức độ ưu tiên cao nhất do nhà phát triển xác định, thì các quy tắc sẽ được ưu tiên bằng cách sử dụng trường "action" theo thứ tự sau:

    1. allow
    2. allowAllRequests
    3. block
    4. upgradeScheme
    5. redirect

  3. Nếu loại hành động không phải là block hoặc redirect, thì mọi quy tắc modifyHeaders phù hợp đều được đánh giá. Xin lưu ý rằng nếu có bất kỳ quy tắc nào có mức độ ưu tiên do nhà phát triển xác định thấp hơn mức độ ưu tiên được chỉ định cho allow và allowAllRequests, thì các quy tắc đó sẽ bị bỏ qua.

  4. Nếu nhiều quy tắc sửa đổi cùng một tiêu đề, thì việc sửa đổi sẽ được xác định bằng trường "priority" do nhà phát triển xác định và bằng các thao tác được chỉ định.

    • 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ì các quy tắc có mức độ ưu tiên thấp hơn chỉ 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 đề đó.

Mức độ ưu tiên của quy tắc giữa các tiện ích

Nếu chỉ có một tiện ích có quy tắc khớp với một yêu cầu, thì quy tắc đó sẽ được áp dụng. Nhưng nếu có nhiều tiện ích phù hợp với một yêu cầu, thì quy trình sau đây sẽ được sử dụng:

  1. Các quy tắc được ưu tiên bằng cách sử dụng trường "action", theo thứ tự sau:

    1. block
    2. redirect hoặc upgradeScheme
    3. allow hoặc allowAllRequests

  2. Nếu có nhiều quy tắc trùng khớp, thì tiện ích được cài đặt gần đây nhất sẽ được ưu tiê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 50 ruleset tĩnh trong khoá "rule_resources" của tệp kê khai, nhưng chỉ có thể bật 10 ruleset trong số này cùng một lúc. 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 động và quy tắc trong phiên

Các giới hạn áp dụng cho quy tắc động và quy tắc phiên đơn giản hơn so với quy tắc tĩnh. Tổng số lượng của cả hai không được vượt quá 5.000. Đây được gọi là MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES.

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ư bên dưới và quy tắc đó sẽ bị bỏ qua.

rules_1.json: Rule with id 1 specified a more complext 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.

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ụ dưới đâ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()

Promise Chrome 89 trở lên 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
): 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.

Thông số

  • callback

    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<number>

    Chrome 91 trở lên

    Các promise chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

getDisabledRuleIds()

Promise Chrome 111 trở lên 
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
  callback?: function,
): 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ố

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

  • callback

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

    Các promise chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

getDynamicRules()

Promise 
chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
  callback?: function,
): 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.

  • callback

    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

    Các promise chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

getEnabledRulesets()

Promise 
chrome.declarativeNetRequest.getEnabledRulesets(
  callback?: function,
): Promise<string[]>

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

Thông số

  • callback

    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

    Các promise chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

getMatchedRules()

Promise 
chrome.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
  callback?: function,
): 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ố

Giá trị trả về

  • Chrome 91 trở lên

    Các promise chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

getSessionRules()

Promise Chrome 90 trở lên 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
  callback?: function,
): 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.

  • callback

    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

    Các promise chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

isRegexSupported()

Promise Chrome 87 trở lên 
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
  callback?: function,
): 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ố

Giá trị trả về

  • Chrome 91 trở lên

    Các promise chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

setExtensionActionOptions()

Promise Chrome 88 trở lên 
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
  callback?: function,
): 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ố

  • callback

    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

    Các promise chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

testMatchOutcome()

Promise Chrome 103 trở lên 
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
): 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ề

  • Các promise chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

updateDynamicRules()

Promise 
chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
  callback?: function,
): 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ố

  • tùy chọn

    UpdateRuleOptions

    Chrome 87 trở lên
  • callback

    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

    Các promise chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

updateEnabledRulesets()

Promise 
chrome.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
  callback?: function,
): 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ố

  • tùy chọn

    UpdateRulesetOptions

    Chrome 87 trở lên
  • callback

    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

    Các promise chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

updateSessionRules()

Promise Chrome 90 trở lên 
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
  callback?: function,
): 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ố

  • tùy chọn

    UpdateRuleOptions

  • callback

    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

    Các promise chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

updateStaticRules()

Promise Chrome 111 trở lên 
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
  callback?: function,
): 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ố

  • callback

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

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

    () => void

Giá trị trả về

  • Promise<void>

    Các promise chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng 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 đó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ố