ตอนนี้ Chrome รองรับเนมสเปซ browser.* ที่ได้มาตรฐานแล้ว (พร้อมใช้งานตั้งแต่ Chrome 148 เป็นต้นไป) เรากำลังทยอยอัปเดตเอกสารประกอบ อ่านเพิ่มเติมในคู่มือการเปลี่ยนผ่าน

Google ใช้เทคโนโลยี AI เพื่อแปลเนื้อหาเป็นภาษาที่คุณต้องการ การแปลโดย AI อาจมีข้อผิดพลาด

browser.declarativeNetRequest

คำอธิบาย

API chrome.declarativeNetRequest ใช้เพื่อบล็อกหรือแก้ไขคำขอเครือข่ายโดยการระบุกฎที่ประกาศ ซึ่งจะช่วยให้ส่วนขยายแก้ไขคำขอเครือข่ายได้โดยไม่ต้องสกัดกั้นและดูเนื้อหาของคำขอ จึงให้ความเป็นส่วนตัวมากขึ้น

สิทธิ์

declarativeNetRequest
declarativeNetRequestWithHostAccess

สิทธิ์ "declarativeNetRequest" และ "declarativeNetRequestWithHostAccess" มีความสามารถเหมือนกัน ความแตกต่างระหว่าง 2 วิธีนี้คือเวลาที่ขอหรือให้สิทธิ์

"declarativeNetRequest": ทริกเกอร์คำเตือนสิทธิ์เมื่อติดตั้ง แต่ให้สิทธิ์เข้าถึงโดยนัยสำหรับกฎ allow, allowAllRequests และ block ใช้ตัวเลือกนี้เมื่อเป็นไปได้เพื่อหลีกเลี่ยง ความจำเป็นในการขอสิทธิ์เข้าถึงโฮสต์แบบเต็ม
"declarativeNetRequestFeedback": เปิดใช้ฟีเจอร์การแก้ไขข้อบกพร่องสำหรับส่วนขยายที่ไม่ได้แพ็ก โดยเฉพาะ getMatchedRules() และ onRuleMatchedDebug
"declarativeNetRequestWithHostAccess": คำเตือนเกี่ยวกับสิทธิ์จะไม่แสดงในเวลาที่ติดตั้ง แต่คุณต้องขอสิทธิ์เข้าถึงโฮสต์ก่อนจึงจะดำเนินการใดๆ กับโฮสต์ได้ วิธีนี้เหมาะสำหรับกรณีที่คุณต้องการใช้กฎคำขอสุทธิแบบประกาศในส่วนขยายที่มีสิทธิ์ของโฮสต์อยู่แล้วโดยไม่สร้างคำเตือนเพิ่มเติม

ความพร้อมใช้งาน

Chrome 84 ขึ้นไป browser.* ตั้งแต่ Chrome 148

ไฟล์ Manifest

นอกเหนือจากสิทธิ์ที่อธิบายไว้ก่อนหน้านี้แล้ว กฎบางประเภท โดยเฉพาะกฎแบบคงที่ ต้องมีการประกาศคีย์ไฟล์ Manifest "declarative_net_request" ซึ่งควรเป็นพจนานุกรมที่มีคีย์เดียวชื่อ "rule_resources" คีย์นี้เป็นอาร์เรย์ที่มีพจนานุกรมประเภท Ruleset ดังที่แสดงด้านล่าง (โปรดทราบว่าชื่อ "Ruleset" จะไม่ปรากฏใน JSON ของไฟล์ Manifest เนื่องจากเป็นเพียงอาร์เรย์) เราจะอธิบายชุดกฎแบบคงที่ในส่วนถัดไปของเอกสารนี้

{
  "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/*"
  ],
  ...
}

กฎและชุดกฎ

หากต้องการใช้ API นี้ ให้ระบุชุดกฎอย่างน้อย 1 ชุด ชุดกฎประกอบด้วยอาร์เรย์ของกฎ กฎเดียวจะดำเนินการอย่างใดอย่างหนึ่งต่อไปนี้

บล็อกคำขอเครือข่าย
อัปเกรดสคีมา (http เป็น https)
ป้องกันไม่ให้คำขอถูกบล็อกโดยการลบล้างกฎที่ถูกบล็อกที่ตรงกัน
เปลี่ยนเส้นทางคำขอเครือข่าย
แก้ไขส่วนหัวของคำขอหรือการตอบกลับ

กฎมี 3 ประเภท ซึ่งจัดการด้วยวิธีที่แตกต่างกันเล็กน้อย

ไดนามิก: คงอยู่ตลอดเซสชันของเบราว์เซอร์และการอัปเกรดส่วนขยาย และได้รับการจัดการโดยใช้ JavaScript ขณะที่ส่วนขยายมีการใช้งานอยู่
เซสชัน: ระบบจะล้างข้อมูลเมื่อเบราว์เซอร์ปิดลงและเมื่อมีการติดตั้งส่วนขยายเวอร์ชันใหม่ กฎเซสชันจะได้รับการจัดการโดยใช้ JavaScript ขณะที่ใช้ส่วนขยาย
คงที่: จัดแพ็กเกจ ติดตั้ง และอัปเดตเมื่อมีการติดตั้งหรืออัปเกรดส่วนขยาย กฎแบบคงที่จะจัดเก็บไว้ในไฟล์กฎที่จัดรูปแบบ JSON และแสดงอยู่ในไฟล์ Manifest

ชุดกฎแบบไดนามิกและระดับเซสชัน

กฎแบบไดนามิกและกฎเซสชันจะได้รับการจัดการโดยใช้ JavaScript ขณะที่ส่วนขยายกำลังใช้งานอยู่

กฎแบบไดนามิกจะยังคงอยู่ตลอดเซสชันของเบราว์เซอร์และการอัปเกรดส่วนขยาย
ระบบจะล้างกฎเซสชันเมื่อปิดเบราว์เซอร์และเมื่อติดตั้งส่วนขยายเวอร์ชันใหม่

กฎแต่ละประเภทจะมีเพียงกฎเดียวเท่านั้น ส่วนขยายสามารถเพิ่มหรือนำกฎออกจากชุดกฎได้แบบไดนามิกโดยเรียกใช้ updateDynamicRules() และ updateSessionRules() หากไม่เกินขีดจำกัดของกฎ ดูข้อมูลเกี่ยวกับขีดจำกัดของกฎได้ที่ขีดจำกัดของกฎ คุณดูตัวอย่างของกรณีนี้ได้ในส่วนตัวอย่างโค้ด

ชุดกฎแบบคงที่

กฎแบบคงที่จะได้รับการจัดแพ็กเกจ ติดตั้ง และอัปเดตเมื่อมีการติดตั้งหรืออัปเกรดส่วนขยาย ซึ่งต่างจากกฎแบบไดนามิกและกฎเซสชัน โดยจะจัดเก็บไว้ในไฟล์กฎในรูปแบบ JSON ซึ่งจะระบุไว้ในส่วนขยายโดยใช้คีย์ "declarative_net_request" และ "rule_resources" ตามที่อธิบายไว้ข้างต้น รวมถึงพจนานุกรม Ruleset อย่างน้อย 1 รายการ พจนานุกรม Ruleset มีเส้นทางไปยังไฟล์กฎ รหัสสำหรับชุดกฎที่อยู่ในไฟล์ และสถานะว่าชุดกฎเปิดหรือปิดใช้อยู่ 2 รายการสุดท้ายมีความสำคัญเมื่อคุณเปิดหรือปิดใช้ชุดกฎแบบเป็นโปรแกรม

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

หากต้องการทดสอบไฟล์กฎ ให้โหลดส่วนขยายที่คลายแพ็กแล้ว ข้อผิดพลาดและคำเตือนเกี่ยวกับกฎแบบคงที่ที่ไม่ถูกต้องจะแสดงสำหรับส่วนขยายที่ไม่ได้แพ็กเท่านั้น ระบบจะไม่สนใจกฎแบบคงที่ที่ไม่ถูกต้องในส่วนขยายที่แพ็กไว้

การตรวจสอบแบบเร่งด่วน

การเปลี่ยนแปลงกฎแบบคงที่อาจมีสิทธิ์รับการตรวจสอบแบบเร่งด่วน ดูการตรวจสอบแบบเร่งด่วนสำหรับการเปลี่ยนแปลงที่มีสิทธิ์

เปิดและปิดใช้กฎและชุดกฎแบบคงที่

คุณสามารถเปิดหรือปิดใช้ทั้งกฎแบบคงที่แต่ละข้อและชุดกฎแบบคงที่ทั้งหมดได้ขณะรันไทม์

ชุดกฎและชุดกฎแบบคงที่ที่เปิดใช้จะยังคงอยู่ตลอดเซสชันของเบราว์เซอร์ ทั้ง 2 อย่างนี้จะไม่คงอยู่ในการอัปเดตส่วนขยาย ซึ่งหมายความว่าหลังจากอัปเดตแล้ว จะมีเฉพาะกฎที่คุณเลือกไว้ในไฟล์กฎเท่านั้นที่ใช้ได้

นอกจากนี้ เพื่อประสิทธิภาพในการทำงาน ระบบยังจำกัดจำนวนกฎและชุดกฎที่เปิดใช้พร้อมกันได้ด้วย เรียกใช้ getAvailableStaticRuleCount() เพื่อตรวจสอบจำนวนกฎเพิ่มเติมที่อาจเปิดใช้อยู่ ดูข้อมูลเกี่ยวกับขีดจำกัดของกฎได้ที่ขีดจำกัดของกฎ

หากต้องการเปิดหรือปิดใช้กฎแบบคงที่ ให้เรียกใช้ updateStaticRules() เมธอดนี้ใช้ออบเจ็กต์ UpdateStaticRulesOptions ซึ่งมีอาร์เรย์ของรหัสของกฎที่จะเปิดหรือปิดใช้ ระบบจะกำหนดรหัสโดยใช้คีย์ "id" ของพจนานุกรม Ruleset กฎแบบคงที่ที่ปิดใช้มีจำนวนสูงสุดได้ 5,000 ข้อ

หากต้องการเปิดหรือปิดใช้กฎแบบคงที่ ให้เรียกใช้ updateEnabledRulesets() เมธอดนี้จะใช้ออบเจ็กต์ UpdateRulesetOptions ซึ่งมีอาร์เรย์ของรหัสของชุดกฎที่จะเปิดหรือปิดใช้ ระบบจะกำหนดรหัสโดยใช้คีย์ "id" ของพจนานุกรม Ruleset

สร้างกฎ

ไม่ว่าจะเป็นประเภทใด กฎจะเริ่มต้นด้วย 4 ช่องดังที่แสดงด้านล่าง แม้ว่าคีย์ "id" และ "priority" จะใช้ตัวเลข แต่คีย์ "action" และ "condition" อาจมีเงื่อนไขการบล็อกและการเปลี่ยนเส้นทางหลายรายการ กฎต่อไปนี้จะบล็อกคำขอสคริปต์ทั้งหมดที่มาจาก "foo.com" ไปยัง URL ใดก็ตามที่มี "abc" เป็นสตริงย่อย

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

การจับคู่ URL

Declarative Net Request ช่วยให้คุณจับคู่ URL กับไวยากรณ์การจับคู่รูปแบบหรือนิพจน์ทั่วไปได้

ไวยากรณ์ตัวกรอง URL

คีย์ "condition" ของกฎอนุญาตให้ใช้คีย์ "urlFilter" เพื่อดำเนินการกับ URL ภายใต้โดเมนที่ระบุ คุณสร้างรูปแบบโดยใช้โทเค็นการจับคู่รูปแบบ ลองดูตัวอย่างต่อไปนี้

`urlFilter`	การจับคู่	ไม่ตรงกัน
`"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

นิพจน์ทั่วไป

นอกจากนี้ เงื่อนไขยังใช้นิพจน์ทั่วไปได้ด้วย ดูคีย์ "regexFilter" หากต้องการดูข้อมูลเกี่ยวกับขีดจำกัดที่มีผลกับเงื่อนไขเหล่านี้ โปรดดูหัวข้อกฎที่ใช้นิพจน์ทั่วไป

เขียนเงื่อนไข URL ที่ดี

โปรดระมัดระวังเมื่อเขียนกฎให้ตรงกับทั้งโดเมนเสมอ ไม่เช่นนั้น กฎอาจจับคู่ในสถานการณ์ที่ไม่คาดคิด ตัวอย่างเช่น เมื่อใช้ไวยากรณ์การจับคู่รูปแบบ ให้ทำดังนี้

google.com จับคู่กับ https://example.com/?param=google.com ไม่ถูกต้อง
||google.com จับคู่กับ https://google.company ไม่ถูกต้อง
https://www.google.com จับคู่กับ https://example.com/?param=https://www.google.com ไม่ถูกต้อง

ลองใช้:

||google.com/ ซึ่งตรงกับเส้นทางและโดเมนย่อยทั้งหมด
|https://www.google.com/ ซึ่งตรงกับเส้นทางทั้งหมดและไม่มีโดเมนย่อย

ในทำนองเดียวกัน ให้ใช้อักขระ ^ และ / เพื่อยึดนิพจน์ทั่วไป เช่น ^https:\/\/www\.google\.com\/ จะตรงกับเส้นทางใดก็ได้ใน https://www.google.com

การประเมินกฎ

เบราว์เซอร์จะใช้กฎ DNR ในขั้นตอนต่างๆ ของวงจรคำขอเครือข่าย

ก่อนส่งคำขอ

ก่อนที่จะส่งคำขอ ส่วนขยายสามารถบล็อกหรือเปลี่ยนเส้นทาง (รวมถึงอัปเกรดรูปแบบจาก HTTP เป็น HTTPS) คำขอด้วยกฎที่ตรงกันได้

เบราว์เซอร์จะกำหนดรายการกฎที่ตรงกันสำหรับส่วนขยายแต่ละรายการ กฎที่มีการดำเนินการmodifyHeadersจะไม่รวมอยู่ในนี้ เนื่องจากจะมีการจัดการในภายหลัง นอกจากนี้ ระบบจะพิจารณากฎที่มีเงื่อนไข responseHeaders ในภายหลัง (เมื่อส่วนหัวการตอบกลับพร้อมใช้งาน) และจะไม่รวมไว้

จากนั้น Chrome จะเลือกผู้สมัครอย่างมาก 1 รายต่อคำขอสำหรับส่วนขยายแต่ละรายการ Chrome จะค้นหากฎที่ตรงกันโดยจัดเรียงกฎที่ตรงกันทั้งหมดตามลำดับความสำคัญ กฎที่มีลำดับความสำคัญเท่ากันจะจัดเรียงตามการดำเนินการ (allow หรือ allowAllRequests > block > upgradeScheme > redirect)

หากตัวเลือกเป็นกฎ allow หรือ allowAllRequests หรือเฟรมที่ส่งคำขอเคยตรงกับกฎ allowAllRequests ที่มีลำดับความสำคัญสูงกว่าหรือเท่ากันจากส่วนขยายนี้ คำขอจะ "ได้รับอนุญาต" และส่วนขยายจะไม่มีผลกับคำขอ

หากมีส่วนขยายมากกว่า 1 รายการที่ต้องการบล็อกหรือเปลี่ยนเส้นทางคำขอนี้ ระบบจะเลือกการดำเนินการเดียว Chrome จะดำเนินการนี้โดยจัดเรียงกฎตามลำดับ block > redirect หรือ upgradeScheme > allow หรือ allowAllRequests หากกฎ 2 ข้อเป็นประเภทเดียวกัน Chrome จะเลือกกฎจากส่วนขยายที่ติดตั้งล่าสุด

ข้อควรระวัง: ผู้ให้บริการเบราว์เซอร์ตกลงที่จะไม่กำหนดมาตรฐานลำดับการทำงานของกฎที่มีการดำเนินการและลำดับความสำคัญเดียวกัน ซึ่งอาจเปลี่ยนแปลงระหว่างการเรียกใช้หรือเวอร์ชันของเบราว์เซอร์ แม้ว่าจะกระจายระหว่างชุดกฎหลายประเภท (เช่น กฎแบบคงที่และกฎเซสชัน) เมื่อลำดับมีความสำคัญ คุณควรระบุลำดับความสำคัญอย่างชัดเจนเสมอ

ก่อนส่งส่วนหัวของคำขอ

ก่อนที่ Chrome จะส่งส่วนหัวของคำขอไปยังเซิร์ฟเวอร์ ระบบจะอัปเดตส่วนหัวตามกฎ modifyHeaders ที่ตรงกัน

ภายในส่วนขยายเดียว Chrome จะสร้างรายการการแก้ไขที่จะดำเนินการโดยค้นหากฎ modifyHeaders ที่ตรงกันทั้งหมด เช่นเดียวกับก่อนหน้านี้ ระบบจะรวมเฉพาะกฎที่มีลำดับความสำคัญสูงกว่ากฎ allow หรือ allowAllRequests ที่ตรงกันเท่านั้น

Chrome จะใช้กฎเหล่านี้ตามลำดับ โดยกฎจากส่วนขยายที่ติดตั้งล่าสุดจะได้รับการประเมินก่อนกฎจากส่วนขยายที่เก่ากว่าเสมอ นอกจากนี้ ระบบจะใช้กฎที่มีลำดับความสำคัญสูงกว่าจากส่วนขยายหนึ่งก่อนกฎที่มีลำดับความสำคัญต่ำกว่าจากส่วนขยายเดียวกันเสมอ โดยเฉพาะอย่างยิ่งในส่วนขยายต่างๆ ดังนี้

หากกฎต่อท้ายส่วนหัว กฎที่มีลำดับความสำคัญต่ำกว่าจะต่อท้ายส่วนหัวนั้นได้เท่านั้น ไม่อนุญาตให้ดำเนินการตั้งค่าและนำออก
หากกฎตั้งค่าส่วนหัวไว้ เฉพาะกฎที่มีลำดับความสำคัญต่ำกว่าจากส่วนขยายเดียวกันเท่านั้นที่จะเพิ่มต่อท้ายส่วนหัวนั้นได้ ไม่อนุญาตให้ทำการแก้ไขอื่นๆ
หากกฎนำส่วนหัวออก กฎที่มีลำดับความสำคัญต่ำกว่าจะแก้ไขส่วนหัวเพิ่มเติมไม่ได้

เมื่อได้รับคำตอบแล้ว

เมื่อได้รับส่วนหัวการตอบกลับแล้ว Chrome จะประเมินกฎที่มีเงื่อนไข responseHeaders

หลังจากจัดเรียงกฎเหล่านี้ตาม action และ priority และยกเว้นกฎที่ซ้ำซ้อนกับกฎ allow หรือ allowAllRequests ที่ตรงกัน (ซึ่งจะเกิดขึ้นเหมือนกับขั้นตอนใน "ก่อนคำขอ") Chrome อาจบล็อกหรือเปลี่ยนเส้นทางคำขอในนามของส่วนขยาย

โปรดทราบว่าหากคำขอมาถึงขั้นตอนนี้ แสดงว่าระบบได้ส่งคำขอไปยังเซิร์ฟเวอร์แล้ว และเซิร์ฟเวอร์ได้รับข้อมูล เช่น เนื้อหาคำขอแล้ว กฎการบล็อกหรือเปลี่ยนเส้นทางที่มีเงื่อนไขส่วนหัวการตอบกลับจะยังคงทำงาน แต่ไม่สามารถบล็อกหรือเปลี่ยนเส้นทางคำขอได้จริง

ในกรณีของกฎการบล็อก หน้านี้จะได้รับการจัดการโดยหน้าที่ส่งคำขอซึ่งได้รับการตอบกลับว่าถูกบล็อก และ Chrome จะสิ้นสุดคำขอก่อนกำหนด ในกรณีของกฎการเปลี่ยนเส้นทาง Chrome จะส่งคำขอใหม่ไปยัง URL ที่เปลี่ยนเส้นทาง อย่าลืมพิจารณาว่าลักษณะการทำงานเหล่านี้เป็นไปตามความคาดหวังด้านความเป็นส่วนตัวสำหรับส่วนขยายของคุณหรือไม่

หากคำขอไม่ถูกบล็อกหรือเปลี่ยนเส้นทาง Chrome จะใช้กฎ modifyHeaders การใช้การแก้ไขกับส่วนหัวการตอบกลับจะทำงานในลักษณะเดียวกับที่อธิบายไว้ใน "ก่อนส่งส่วนหัวของคำขอ" การใช้การแก้ไขกับส่วนหัวของคำขอจะไม่มีผลใดๆ เนื่องจากมีการส่งคำขอไปแล้ว

กฎความปลอดภัย

กฎที่ปลอดภัยหมายถึงกฎที่มีการดำเนินการเป็น block, allow, allowAllRequests หรือ upgradeScheme กฎเหล่านี้ขึ้นอยู่กับโควต้ากฎแบบไดนามิกที่เพิ่มขึ้น

ขีดจํากัดของกฎ

การโหลดและการประเมินกฎในเบราว์เซอร์มีค่าใช้จ่ายเพิ่มเติมด้านประสิทธิภาพ ดังนั้นจึงมีข้อจำกัดบางประการเมื่อใช้ API โดยขีดจำกัดจะขึ้นอยู่กับประเภทของกฎที่คุณใช้

กฎแบบคงที่

กฎแบบคงที่คือกฎที่ระบุไว้ในไฟล์กฎที่ประกาศในไฟล์ Manifest ส่วนขยายสามารถระบุชุดกฎแบบคงที่ได้สูงสุด 100 ชุดโดยเป็นส่วนหนึ่งของคีย์ไฟล์ Manifest "rule_resources" แต่จะเปิดใช้ชุดกฎเหล่านี้ได้ครั้งละ 50 ชุดเท่านั้น ซึ่งเรียกว่า MAX_NUMBER_OF_ENABLED_STATIC_RULESETS โดยรวมแล้ว ชุดกฎเหล่านั้นจะรับประกันกฎอย่างน้อย 30,000 ข้อ ซึ่งเรียกว่า GUARANTEED_MINIMUM_STATIC_RULES

จำนวนกฎที่ใช้ได้หลังจากนั้นจะขึ้นอยู่กับจำนวนกฎที่เปิดใช้โดยส่วนขยายทั้งหมดที่ติดตั้งในเบราว์เซอร์ของผู้ใช้ คุณสามารถดูหมายเลขนี้ได้ที่รันไทม์โดยเรียกใช้ getAvailableStaticRuleCount() คุณดูตัวอย่างของกรณีนี้ได้ในส่วนตัวอย่างโค้ด

หมายเหตุ: ตั้งแต่ Chrome 128 เป็นต้นไป หากผู้ใช้ปิดใช้ส่วนขยายผ่าน chrome://extensions กฎแบบคงที่ของส่วนขยายจะไม่นับรวมในขีดจำกัดกฎแบบคงที่ส่วนกลางอีกต่อไป ซึ่งอาจทำให้โควต้ากฎแบบคงที่สำหรับส่วนขยายอื่นๆ ว่างลง แต่ก็หมายความว่าเมื่อเปิดใช้ส่วนขยายอีกครั้ง ส่วนขยายอาจมีกฎแบบคงที่ที่ใช้ได้น้อยกว่าเดิม

กฎเซสชัน

ส่วนขยายมีกฎเซสชันได้สูงสุด 5,000 ข้อ ซึ่งจะแสดงเป็น MAX_NUMBER_OF_SESSION_RULES

ก่อน Chrome 120 มีการจำกัดกฎแบบไดนามิกและกฎเซสชันรวมกันไว้ที่ 5, 000 ข้อ

กฎแบบไดนามิก

ส่วนขยายมีกฎแบบไดนามิกได้อย่างน้อย 5,000 ข้อ ซึ่งจะแสดงเป็น MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

ตั้งแต่ Chrome 121 เป็นต้นไป จะมีขีดจำกัดที่มากขึ้นเป็น 30,000 กฎสำหรับกฎแบบไดนามิกที่ปลอดภัย ซึ่งแสดงเป็น MAX_NUMBER_OF_DYNAMIC_RULES กฎที่ไม่ปลอดภัยที่เพิ่มภายในขีดจำกัด 5,000 รายการจะนับรวมในขีดจำกัดนี้ด้วย

ก่อน Chrome 120 มีขีดจำกัดกฎแบบไดนามิกและกฎเซสชันรวมกัน 5, 000 ข้อ

กฎที่ใช้นิพจน์ทั่วไป

กฎทุกประเภทใช้นิพจน์ทั่วไปได้ แต่จำนวนกฎนิพจน์ทั่วไปทั้งหมดของแต่ละประเภทต้องไม่เกิน 1, 000 รายการ ซึ่งเรียกว่า MAX_NUMBER_OF_REGEX_RULES

นอกจากนี้ กฎแต่ละข้อต้องมีขนาดไม่เกิน 2 KB เมื่อคอมไพล์แล้ว ซึ่งจะสัมพันธ์กับความซับซ้อนของกฎโดยประมาณ หากพยายามโหลดกฎที่เกินขีดจำกัดนี้ คุณจะเห็นคำเตือนดังต่อไปนี้และระบบจะไม่สนใจกฎดังกล่าว

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

การโต้ตอบกับ Service Worker

declarativeNetRequest จะมีผลกับคำขอที่เข้าถึงสแต็กเครือข่ายเท่านั้น ซึ่งรวมถึงการตอบกลับจากแคช HTTP แต่อาจไม่รวมการตอบกลับที่ผ่านเครื่องจัดการ onfetch ของ Service Worker declarativeNetRequest จะไม่ส่งผลต่อการตอบกลับที่สร้างโดย Service Worker หรือดึงมาจาก CacheStorage แต่จะส่งผลต่อการเรียกใช้ fetch() ที่ทำใน Service Worker

แหล่งข้อมูลที่เข้าถึงได้บนเว็บ

กฎ declarativeNetRequest ไม่สามารถเปลี่ยนเส้นทางจากคำขอทรัพยากรสาธารณะไปยังทรัพยากรที่เข้าถึงไม่ได้บนเว็บ เนื่องจากจะทำให้เกิดข้อผิดพลาด ซึ่งรวมถึงกรณีที่ส่วนขยายที่เปลี่ยนเส้นทางเป็นเจ้าของทรัพยากรที่เข้าถึงได้บนเว็บที่ระบุด้วย หากต้องการประกาศทรัพยากรสำหรับ declarativeNetRequest ให้ใช้อาร์เรย์ "web_accessible_resources" ของไฟล์ Manifest

การแก้ไขส่วนหัว

การดำเนินการต่อท้ายรองรับเฉพาะส่วนหัวของคำขอต่อไปนี้ 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 รายการที่อนุญาตนี้คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ (ข้อบกพร่อง 449152902)

เมื่อต่อท้ายส่วนหัวของคำขอหรือส่วนหัวการตอบกลับ เบราว์เซอร์จะใช้ตัวคั่นที่เหมาะสมหากเป็นไปได้

ตัวอย่าง

ตัวอย่างโค้ด

อัปเดตกฎแบบไดนามิก

ตัวอย่างต่อไปนี้แสดงวิธีเรียกใช้ updateDynamicRules() ขั้นตอนสำหรับ updateSessionRules() จะเหมือนกัน

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

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

อัปเดตชุดกฎแบบคงที่

ตัวอย่างต่อไปนี้แสดงวิธีเปิดและปิดใช้ชุดกฎโดยพิจารณาจากจำนวนชุดกฎแบบคงที่ที่ใช้ได้และจำนวนสูงสุดของชุดกฎแบบคงที่ที่เปิดใช้ คุณจะดำเนินการนี้เมื่อจำนวนกฎแบบคงที่ที่ต้องการเกินจำนวนที่อนุญาต เพื่อให้วิธีนี้ได้ผล คุณควรติดตั้งชุดกฎบางชุดโดยปิดใช้ชุดกฎบางชุด (ตั้งค่า "Enabled" เป็น false ภายในไฟล์ Manifest)

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 browser.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 > browser.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS) {
    options.disableRulesetIds = disableCandidateIds
  }
  // Update the enabled static rules
  await browser.declarativeNetRequest.updateEnabledRulesets(options);
}

ตัวอย่างกฎ

ตัวอย่างต่อไปนี้แสดงวิธีที่ Chrome จัดลำดับความสำคัญของกฎในส่วนขยาย เมื่อตรวจสอบ คุณอาจต้องเปิดกฎการจัดลำดับความสำคัญในหน้าต่างแยกต่างหาก

คีย์ "priority"

ตัวอย่างเหล่านี้ต้องใช้สิทธิ์ของโฮสต์ใน *://*.example.com/*

หากต้องการหาลำดับความสำคัญของ URL หนึ่งๆ ให้ดูที่คีย์ "priority" (ที่นักพัฒนาซอฟต์แวร์กำหนด) คีย์ "action" และคีย์ "urlFilter" ตัวอย่างเหล่านี้อ้างอิงถึงไฟล์กฎตัวอย่างที่แสดงด้านล่าง

การนำทางไปยัง https://google.com: กฎ 2 ข้อครอบคลุม URL นี้ ได้แก่ กฎที่มีรหัส 1 และ 4 กฎที่มีรหัส 1 จะมีผลเนื่องจากการดำเนินการ"block"มีลำดับความสำคัญสูงกว่าการดำเนินการ"redirect" กฎที่เหลือจะไม่มีผลเนื่องจากมีไว้สำหรับ URL ที่ยาวกว่า
การนำทางไปยัง https://google.com/1234: เนื่องจาก URL ยาวขึ้น กฎที่มีรหัส 2 จึงตรงกันด้วย นอกเหนือจากกฎที่มีรหัส 1 และ 4 กฎที่มีรหัส 2 จะมีผลเนื่องจาก "allow" มีลำดับความสำคัญสูงกว่า "block" และ "redirect"
การไปยัง https://google.com/12345: กฎทั้ง 4 ข้อตรงกับ URL นี้ กฎที่มีรหัส 3 จะมีผลบังคับใช้เนื่องจากลำดับความสำคัญที่นักพัฒนาแอปกำหนดไว้สูงที่สุดในกลุ่ม

[
  {
    "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"] }
  },
]

การเปลี่ยนเส้นทาง

ตัวอย่างด้านล่างต้องใช้สิทธิ์ของโฮสต์ใน *://*.example.com/*

ตัวอย่างต่อไปนี้แสดงวิธีเปลี่ยนเส้นทางคำขอจาก example.com ไปยังหน้าภายในส่วนขยายเอง เส้นทางส่วนขยาย /a.jpg จะเปลี่ยนเป็น chrome-extension://EXTENSION_ID/a.jpg โดยที่ EXTENSION_ID คือรหัสของส่วนขยาย เพื่อให้ฟีเจอร์นี้ทำงานได้ ไฟล์ Manifest ควรประกาศ /a.jpg เป็นทรัพยากรที่เข้าถึงได้บนเว็บ

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

ตัวอย่างต่อไปนี้ใช้คีย์ "transform" เพื่อเปลี่ยนเส้นทางไปยังโดเมนย่อยของ example.com โดยใช้ Anchor ชื่อโดเมน ("||") เพื่อสกัดกั้นคำขอที่มีรูปแบบใดก็ได้จาก example.com คีย์ "scheme" ใน "transform" ระบุว่าการเปลี่ยนเส้นทางไปยังโดเมนย่อยจะใช้ "https" เสมอ

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

ตัวอย่างต่อไปนี้ใช้นิพจน์ทั่วไปเพื่อเปลี่ยนเส้นทางจาก https://www.abc.xyz.com/path ไปยัง https://abc.xyz.com/path ในคีย์ "regexFilter" ให้สังเกตวิธีหลีกเลี่ยงจุดและแคปเจอร์กรุ๊ปจะเลือก "abc" หรือ "def" คีย์ "regexSubstitution" จะระบุรายการที่ตรงกันรายการแรกที่แสดงผลของนิพจน์ทั่วไปโดยใช้ "\1" ในกรณีนี้ ระบบจะบันทึก "abc" จาก URL ที่เปลี่ยนเส้นทางและวางไว้ในการแทนที่

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

ส่วนหัว

ตัวอย่างต่อไปนี้จะนำคุกกี้ทั้งหมดออกจากทั้งเฟรมหลักและเฟรมย่อย

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

ประเภท

DomainType

ซึ่งจะอธิบายว่าคำขอเป็นของบุคคลที่หนึ่งหรือบุคคลที่สามในเฟรมที่คำขอเริ่มต้นขึ้น คำขอจะถือว่าเป็นของบุคคลที่หนึ่งหากมีโดเมน (eTLD+1) เดียวกันกับเฟรมที่คำขอเริ่มต้นขึ้น

ค่าแจกแจง

"firstParty"
คำขอเครือข่ายเป็นบุคคลที่หนึ่งสำหรับเฟรมที่คำขอเริ่มต้นขึ้น

"thirdParty"
คำขอเครือข่ายเป็นของบุคคลที่สามสำหรับเฟรมที่คำขอเริ่มต้นขึ้น

ExtensionActionOptions

Chrome 88 ขึ้นไป browser.* ตั้งแต่ Chrome 148

พร็อพเพอร์ตี้

displayActionCountAsBadgeText

บูลีน ไม่บังคับ

กำหนดว่าจะแสดงจำนวนการดำเนินการสำหรับหน้าเว็บเป็นข้อความป้ายของส่วนขยายโดยอัตโนมัติหรือไม่ ค่ากำหนดนี้จะคงอยู่ในเซสชันต่างๆ
tabUpdate

TabActionCountUpdate ไม่บังคับ

Chrome 89 ขึ้นไป browser.* ตั้งแต่ Chrome 148

รายละเอียดเกี่ยวกับวิธีปรับจำนวนการดำเนินการของแท็บ

GetDisabledRuleIdsOptions

Chrome 111 ขึ้นไป browser.* ตั้งแต่ Chrome 148

พร็อพเพอร์ตี้

rulesetId

สตริง

รหัสที่สอดคล้องกับ Ruleset แบบคงที่

GetRulesFilter

Chrome 111 ขึ้นไป browser.* ตั้งแต่ Chrome 148

พร็อพเพอร์ตี้

ruleIds

number[] ไม่บังคับ

หากระบุ ระบบจะรวมเฉพาะกฎที่มีรหัสที่ตรงกันเท่านั้น

HeaderInfo

Chrome 128 ขึ้นไป browser.* ตั้งแต่ Chrome 148

พร็อพเพอร์ตี้

excludedValues

string[] ไม่บังคับ

หากระบุ เงื่อนไขนี้จะไม่ตรงกันหากมีส่วนหัวอยู่ แต่ค่าของส่วนหัวมีองค์ประกอบอย่างน้อย 1 รายการในรายการนี้ ซึ่งใช้ไวยากรณ์รูปแบบการจับคู่เดียวกันกับ values
ส่วนหัว

สตริง

ชื่อของส่วนหัว เงื่อนไขนี้จะจับคู่กับชื่อก็ต่อเมื่อไม่ได้ระบุทั้ง values และ excludedValues
values

string[] ไม่บังคับ

หากระบุ เงื่อนไขนี้จะตรงกันหากค่าของส่วนหัวตรงกับรูปแบบอย่างน้อย 1 รูปแบบในรายการนี้ ซึ่งรองรับการจับคู่ค่าส่วนหัวที่ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ รวมถึงโครงสร้างต่อไปนี้

'*' : จับคู่อักขระจำนวนเท่าใดก็ได้

"?" : จับคู่อักขระ 0 หรือ 1 ตัว

คุณสามารถหลีกเลี่ยง "*" และ "?" ได้ด้วยแบ็กสแลช เช่น "\*" และ "\?"

HeaderOperation

Chrome 86 ขึ้นไป browser.* ตั้งแต่ Chrome 148

ส่วนนี้อธิบายการดำเนินการที่เป็นไปได้สำหรับกฎ "modifyHeaders"

ค่าแจกแจง

"append"
เพิ่มรายการใหม่สำหรับส่วนหัวที่ระบุ เมื่อแก้ไขส่วนหัวของคำขอ การดำเนินการนี้จะรองรับเฉพาะส่วนหัวที่เฉพาะเจาะจงเท่านั้น

"set"
ตั้งค่าใหม่สำหรับส่วนหัวที่ระบุ โดยนำส่วนหัวที่มีอยู่ซึ่งมีชื่อเดียวกันออก

"remove"
นำรายการทั้งหมดสำหรับส่วนหัวที่ระบุออก

IsRegexSupportedResult

Chrome 87 ขึ้นไป browser.* ตั้งแต่ Chrome 148

พร็อพเพอร์ตี้

isSupported

บูลีน
เหตุผล

UnsupportedRegexReason ไม่บังคับ

ระบุสาเหตุที่ไม่รองรับนิพจน์ทั่วไป ระบุเฉพาะในกรณีที่ isSupported เป็นเท็จ

MatchedRule

พร็อพเพอร์ตี้

ruleId

ตัวเลข

รหัสของกฎการจับคู่
rulesetId

สตริง

รหัสของ Ruleset ที่กฎนี้เป็นของ สำหรับกฎที่มาจากชุดกฎแบบไดนามิก ค่านี้จะเท่ากับ DYNAMIC_RULESET_ID

MatchedRuleInfo

พร็อพเพอร์ตี้

กฎ

MatchedRule
tabId

ตัวเลข

tabId ของแท็บที่ส่งคำขอ หากแท็บยังทำงานอยู่ Else -1.
timeStamp

ตัวเลข

เวลาที่กฎตรงกัน การประทับเวลาจะสอดคล้องกับรูปแบบเวลาของ JavaScript เช่น จำนวนมิลลิวินาทีนับตั้งแต่จุดเริ่มต้น

MatchedRuleInfoDebug

พร็อพเพอร์ตี้

ส่งคำขอ

RequestDetails

รายละเอียดเกี่ยวกับคำขอที่ตรงกับกฎ
กฎ

MatchedRule

MatchedRulesFilter

พร็อพเพอร์ตี้

minTimeStamp

number ไม่บังคับ

หากระบุไว้ ระบบจะจับคู่กฎหลังจากมีการประทับเวลาที่ระบุเท่านั้น
tabId

number ไม่บังคับ

หากระบุไว้ ระบบจะจับคู่กฎสำหรับแท็บที่ระบุเท่านั้น จับคู่กฎที่ไม่ได้เชื่อมโยงกับแท็บที่ใช้งานอยู่หากตั้งค่าเป็น -1

ModifyHeaderInfo

Chrome 86 ขึ้นไป browser.* ตั้งแต่ Chrome 148

พร็อพเพอร์ตี้

ส่วนหัว

สตริง

ชื่อของส่วนหัวที่จะแก้ไข
การดำเนินการ

HeaderOperation

การดำเนินการที่จะทำกับส่วนหัว
value

สตริง ไม่บังคับ

ค่าใหม่สำหรับส่วนหัว ต้องระบุสำหรับการดำเนินการ append และ set

QueryKeyValue

พร็อพเพอร์ตี้

แป้น

สตริง
replaceOnly

บูลีน ไม่บังคับ

Chrome 94 ขึ้นไป เบราว์เซอร์* ตั้งแต่ Chrome 148

หากเป็นจริง ระบบจะแทนที่คีย์การค้นหาเฉพาะในกรณีที่มีอยู่แล้วเท่านั้น ไม่เช่นนั้น ระบบจะเพิ่มคีย์ด้วยหากไม่มี ค่าเริ่มต้นคือ "เท็จ"
value

สตริง

QueryTransform

พร็อพเพอร์ตี้

addOrReplaceParams

QueryKeyValue[] ไม่บังคับ

รายการคู่คีย์-ค่าของคำค้นหาที่จะเพิ่มหรือแทนที่
removeParams

string[] ไม่บังคับ

รายการคีย์การค้นหาที่จะนำออก

Redirect

พร็อพเพอร์ตี้

extensionPath

สตริง ไม่บังคับ

เส้นทางที่สัมพันธ์กับไดเรกทอรีส่วนขยาย ควรขึ้นต้นด้วย "/"
regexSubstitution

สตริง ไม่บังคับ

รูปแบบการแทนที่สำหรับกฎที่ระบุ regexFilter ระบบจะแทนที่รายการแรกที่ตรงกับ regexFilter ภายใน URL ด้วยรูปแบบนี้ ภายใน regexSubstitution คุณสามารถใช้ตัวเลขที่หลีกด้วยแบ็กสแลช (\1 ถึง \9) เพื่อแทรกแคปเจอร์กรุ๊ปที่เกี่ยวข้องได้ \0 หมายถึงข้อความที่ตรงกันทั้งหมด
การเปลี่ยนรูปแบบ

URLTransform ไม่บังคับ

การเปลี่ยนรูปแบบ URL ที่จะดำเนินการ
URL

สตริง ไม่บังคับ

URL เปลี่ยนเส้นทาง ไม่อนุญาตให้เปลี่ยนเส้นทางไปยัง URL ของ JavaScript

RegexOptions

Chrome 87 ขึ้นไป browser.* ตั้งแต่ Chrome 148

พร็อพเพอร์ตี้

isCaseSensitive

บูลีน ไม่บังคับ

regexที่ระบุคำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่หรือไม่ ค่าเริ่มต้นคือ true
นิพจน์ทั่วไป

สตริง

นิพจน์ทั่วไปที่จะตรวจสอบ
requireCapturing

บูลีน ไม่บังคับ

regex ที่ระบุต้องมีการบันทึกหรือไม่ การบันทึกจำเป็นสำหรับกฎการเปลี่ยนเส้นทางที่ระบุการดำเนินการ regexSubstition เท่านั้น ค่าเริ่มต้นคือเท็จ

RequestDetails

พร็อพเพอร์ตี้

documentId

สตริง ไม่บังคับ

Chrome 106 ขึ้นไป browser.* ตั้งแต่ Chrome 148

ตัวระบุที่ไม่ซ้ำกันสำหรับเอกสารของเฟรม หากคำขอนี้มีไว้สำหรับเฟรม
documentLifecycle

DocumentLifecycle ไม่บังคับ

Chrome 106 ขึ้นไป browser.* ตั้งแต่ Chrome 148

วงจรของเอกสารของเฟรม หากคำขอนี้มีไว้สำหรับเฟรม
frameId

ตัวเลข

ค่า 0 บ่งชี้ว่าคำขอเกิดขึ้นในเฟรมหลัก ค่าบวกบ่งชี้รหัสของเฟรมย่อยที่คำขอเกิดขึ้น หากโหลดเอกสารของ (เฟรมย่อย) (type คือ main_frame หรือ sub_frame) frameId จะระบุรหัสของเฟรมนี้ ไม่ใช่รหัสของเฟรมนอก รหัสเฟรมจะไม่ซ้ำกันภายในแท็บ
frameType

FrameType ไม่บังคับ

Chrome 106 ขึ้นไป browser.* ตั้งแต่ Chrome 148

ประเภทของเฟรม หากคำขอนี้มีไว้สำหรับเฟรม
ผู้เริ่ม

สตริง ไม่บังคับ

ต้นทางที่เริ่มคำขอ ซึ่งจะไม่เปลี่ยนแปลงผ่านการเปลี่ยนเส้นทาง หากเป็นต้นทางแบบทึบแสง ระบบจะใช้สตริง "null"
method

สตริง

เมธอด HTTP มาตรฐาน
parentDocumentId

สตริง ไม่บังคับ

Chrome 106 ขึ้นไป browser.* ตั้งแต่ Chrome 148

ตัวระบุที่ไม่ซ้ำกันสำหรับเอกสารหลักของเฟรม หากคำขอนี้มีไว้สำหรับเฟรมและมีรายการหลัก
parentFrameId

ตัวเลข

รหัสของเฟรมที่รวมเฟรมที่ส่งคำขอ ตั้งค่าเป็น -1 หากไม่มีเฟรมระดับบนสุด
requestId

สตริง

รหัสของคำขอ รหัสคำขอจะไม่ซ้ำกันภายในเซสชันของเบราว์เซอร์
tabId

ตัวเลข

รหัสของแท็บที่มีคำขอเกิดขึ้น ตั้งค่าเป็น -1 หากคำขอไม่เกี่ยวข้องกับแท็บ
ประเภท

ResourceType

ประเภททรัพยากรของคำขอ
URL

สตริง

URL ของคำขอ

RequestMethod

Chrome 91 ขึ้นไป browser.* ตั้งแต่ Chrome 148

ซึ่งจะอธิบายเมธอดคำขอ HTTP ของคำขอเครือข่าย

ค่าแจกแจง

"connect"

"delete"

"get"

"head"

"options"

"patch"

"post"

"put"

"other"

ResourceType

ซึ่งอธิบายประเภททรัพยากรของคำขอเครือข่าย

ค่าแจกแจง

"main_frame"

"sub_frame"

"stylesheet"

"script"

"image"

"font"

"object"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"webtransport"

"webbundle"

"other"

Rule

พร็อพเพอร์ตี้

การดำเนินการ

RuleAction

การดำเนินการที่ต้องทำหากตรงกับกฎนี้
เงื่อนไข

RuleCondition

เงื่อนไขที่จะเรียกใช้กฎนี้
id

ตัวเลข

รหัสที่ระบุกฎแบบไม่ซ้ำกัน ต้องระบุและควรมีค่า >= 1
ลำดับความสำคัญ

number ไม่บังคับ

ลำดับความสำคัญของกฎ ค่าเริ่มต้นคือ 1 เมื่อระบุแล้ว ควรมีค่า >= 1

RuleAction

พร็อพเพอร์ตี้

เปลี่ยนเส้นทาง

Redirect ไม่บังคับ

อธิบายวิธีดำเนินการเปลี่ยนเส้นทาง ใช้ได้กับกฎการเปลี่ยนเส้นทางเท่านั้น
requestHeaders

ModifyHeaderInfo[] ไม่บังคับ

Chrome 86 ขึ้นไป browser.* ตั้งแต่ Chrome 148

ส่วนหัวของคำขอที่จะแก้ไขสำหรับคำขอ ใช้ได้เฉพาะเมื่อ RuleActionType เป็น "modifyHeaders"
responseHeaders

ModifyHeaderInfo[] ไม่บังคับ

Chrome 86 ขึ้นไป browser.* ตั้งแต่ Chrome 148

ส่วนหัวการตอบกลับที่จะแก้ไขสำหรับคำขอ ใช้ได้เฉพาะเมื่อ RuleActionType เป็น "modifyHeaders"
ประเภท

RuleActionType

ประเภทการดำเนินการที่จะทำ

RuleActionType

อธิบายประเภทการดำเนินการที่ต้องทำหาก RuleCondition ที่ระบุตรงกัน

ค่าแจกแจง

"block"
บล็อกคำขอเครือข่าย

"redirect"
เปลี่ยนเส้นทางคำขอเครือข่าย

"allow"
อนุญาตคำขอเครือข่าย ระบบจะไม่สกัดกั้นคำขอหากมีกฎการอนุญาตที่ตรงกับคำขอดังกล่าว

"upgradeScheme"
อัปเกรดรูปแบบ URL ของคำขอเครือข่ายเป็น HTTPS หากคำขอเป็น HTTP หรือ FTP

"modifyHeaders"
แก้ไขส่วนหัวของคำขอ/ส่วนหัวการตอบกลับจากคำขอเครือข่าย

"allowAllRequests"
อนุญาตคำขอทั้งหมดภายในลำดับชั้นของเฟรม รวมถึงคำขอเฟรมเอง

RuleCondition

พร็อพเพอร์ตี้

domainType

DomainType ไม่บังคับ

ระบุว่าคำขอเครือข่ายเป็นแบบบุคคลที่หนึ่งหรือบุคคลที่สามสำหรับโดเมนที่เป็นต้นทาง หากไม่ระบุ ระบบจะยอมรับคำขอทั้งหมด
โดเมน

string[] ไม่บังคับ

เลิกใช้งานตั้งแต่ Chrome 101

ใช้ initiatorDomains แทน
กฎจะจับคู่เฉพาะคำขอเครือข่ายที่มาจากรายการ domains เท่านั้น
excludedDomains

string[] ไม่บังคับ

เลิกใช้งานตั้งแต่ Chrome 101

ใช้ excludedInitiatorDomains แทน
กฎจะไม่จับคู่คำขอเครือข่ายที่มาจากรายการ excludedDomains
excludedInitiatorDomains

string[] ไม่บังคับ

Chrome 101 ขึ้นไป browser.* ตั้งแต่ Chrome 148

กฎจะไม่จับคู่คำขอเครือข่ายที่มาจากรายการ excludedInitiatorDomains หากรายการว่างเปล่าหรือละเว้น ระบบจะไม่ยกเว้นโดเมนใดๆ ซึ่งจะมีความสำคัญเหนือ initiatorDomains

หมายเหตุ:
- นอกจากนี้ยังอนุญาตให้ใช้โดเมนย่อย เช่น "a.example.com" ด้วย
- รายการต้องประกอบด้วยอักขระ ASCII เท่านั้น
- ใช้การเข้ารหัส Punycode สำหรับโดเมนที่เป็นสากล
- ซึ่งจะจับคู่กับผู้เริ่มคำขอ ไม่ใช่ URL ของคำขอ
- ระบบจะยกเว้นโดเมนย่อยของโดเมนที่ระบุด้วย
excludedRequestDomains

string[] ไม่บังคับ

Chrome 101 ขึ้นไป browser.* ตั้งแต่ Chrome 148

กฎจะไม่จับคู่คำขอเครือข่ายเมื่อโดเมนตรงกับโดเมนจากรายการ excludedRequestDomains หากรายการว่างเปล่าหรือละเว้น ระบบจะไม่ยกเว้นโดเมนใดๆ ซึ่งจะมีความสำคัญเหนือ requestDomains

หมายเหตุ:
- นอกจากนี้ยังอนุญาตให้ใช้โดเมนย่อย เช่น "a.example.com" ด้วย
- รายการต้องประกอบด้วยอักขระ ASCII เท่านั้น
- ใช้การเข้ารหัส Punycode สำหรับโดเมนที่เป็นสากล
- ระบบจะยกเว้นโดเมนย่อยของโดเมนที่ระบุด้วย
excludedRequestMethods

RequestMethod[] ไม่บังคับ

Chrome 91 ขึ้นไป browser.* ตั้งแต่ Chrome 148

รายการเมธอดคำขอที่กฎจะไม่จับคู่ ควรระบุ requestMethods หรือ excludedRequestMethods เพียงรายการเดียวเท่านั้น หากไม่ได้ระบุทั้ง 2 รายการ ระบบจะจับคู่เมธอดคำขอทั้งหมด
excludedResourceTypes

ResourceType[] ไม่บังคับ

รายการประเภททรัพยากรที่กฎจะไม่จับคู่ ควรระบุ resourceTypes หรือ excludedResourceTypes เพียงรายการเดียวเท่านั้น หากไม่ได้ระบุทั้ง 2 อย่าง ระบบจะบล็อกทรัพยากรทุกประเภท ยกเว้น "main_frame"
excludedResponseHeaders

HeaderInfo[] ไม่บังคับ

Chrome 128 ขึ้นไป browser.* ตั้งแต่ Chrome 148

กฎจะไม่ตรงกันหากคำขอตรงกับเงื่อนไขส่วนหัวการตอบกลับในรายการนี้ (หากระบุ) หากระบุทั้ง excludedResponseHeaders และ responseHeaders พร็อพเพอร์ตี้ excludedResponseHeaders จะมีความสำคัญเหนือกว่า
excludedTabIds

number[] ไม่บังคับ

Chrome 92 ขึ้นไป browser.* ตั้งแต่ Chrome 148

รายการ tabs.Tab.id ที่กฎไม่ควรจับคู่ รหัส tabs.TAB_ID_NONE จะยกเว้นคำขอที่ไม่ได้มาจากแท็บ รองรับเฉพาะกฎที่กำหนดขอบเขตระดับเซสชันเท่านั้น
excludedTopDomains

string[] ไม่บังคับ

Chrome 145 ขึ้นไป browser.* ตั้งแต่ Chrome 148

กฎจะไม่จับคู่คำขอเครือข่ายเมื่อโดเมนของเฟรมระดับบนสุดที่เชื่อมโยงตรงกับโดเมนจากรายการ excludedTopDomains หากรายการว่างเปล่าหรือละเว้น ระบบจะไม่ยกเว้นโดเมนใดๆ ซึ่งจะมีความสำคัญเหนือ topDomains

หมายเหตุ:
- นอกจากนี้ยังอนุญาตให้ใช้โดเมนย่อย เช่น "a.example.com" ด้วย
- รายการต้องประกอบด้วยอักขระ ASCII เท่านั้น
- ใช้การเข้ารหัส Punycode สำหรับโดเมนที่เป็นสากล
- ระบบจะยกเว้นโดเมนย่อยของโดเมนที่ระบุด้วย
- สำหรับคำขอที่ไม่มีเฟรมระดับบนสุดที่เชื่อมโยง (เช่น คำขอที่เริ่มต้นโดย ServiceWorker) ระบบจะพิจารณาโดเมนของผู้เริ่มต้นคำขอแทน
initiatorDomains

string[] ไม่บังคับ

Chrome 101 ขึ้นไป browser.* ตั้งแต่ Chrome 148

กฎจะจับคู่เฉพาะคำขอเครือข่ายที่มาจากรายการ initiatorDomains เท่านั้น หากละเว้นรายการ ระบบจะใช้กฎกับคำขอจากโดเมนทั้งหมด ไม่อนุญาตให้ใช้รายการที่ว่างเปล่า

หมายเหตุ:
- นอกจากนี้ยังอนุญาตให้ใช้โดเมนย่อย เช่น "a.example.com" ด้วย
- รายการต้องประกอบด้วยอักขระ ASCII เท่านั้น
- ใช้การเข้ารหัส Punycode สำหรับโดเมนที่เป็นสากล
- ซึ่งจะจับคู่กับผู้เริ่มคำขอ ไม่ใช่ URL ของคำขอ
- โดเมนย่อยของโดเมนที่ระบุจะตรงกันด้วย
isUrlFilterCaseSensitive

บูลีน ไม่บังคับ

urlFilter หรือ regexFilter (ตามที่ระบุ) คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่หรือไม่ ค่าเริ่มต้นคือ false
regexFilter

สตริง ไม่บังคับ

นิพจน์ทั่วไปที่จะจับคู่กับ URL คำขอเครือข่าย ซึ่งเป็นไปตามไวยากรณ์ RE2

หมายเหตุ: คุณระบุได้เพียง urlFilter หรือ regexFilter อย่างใดอย่างหนึ่งเท่านั้น

หมายเหตุ: regexFilter ต้องประกอบด้วยอักขระ ASCII เท่านั้น ซึ่งจะจับคู่กับ URL ที่โฮสต์เข้ารหัสในรูปแบบ Punycode (ในกรณีที่เป็นโดเมนสากล) และอักขระอื่นๆ ที่ไม่ใช่ ASCII จะเข้ารหัส URL ใน UTF-8
requestDomains

string[] ไม่บังคับ

Chrome 101 ขึ้นไป browser.* ตั้งแต่ Chrome 148

กฎจะจับคู่คำขอเครือข่ายก็ต่อเมื่อโดเมนตรงกับโดเมนจากรายการ requestDomains เท่านั้น หากละเว้นรายการ ระบบจะใช้กฎกับคำขอจากโดเมนทั้งหมด ไม่อนุญาตให้ใช้รายการที่ว่างเปล่า

หมายเหตุ:
- นอกจากนี้ยังอนุญาตให้ใช้โดเมนย่อย เช่น "a.example.com" ด้วย
- รายการต้องประกอบด้วยอักขระ ASCII เท่านั้น
- ใช้การเข้ารหัส Punycode สำหรับโดเมนที่เป็นสากล
- โดเมนย่อยของโดเมนที่ระบุจะตรงกันด้วย
requestMethods

RequestMethod[] ไม่บังคับ

Chrome 91 ขึ้นไป browser.* ตั้งแต่ Chrome 148

รายการเมธอดคำขอ HTTP ที่กฎสามารถจับคู่ได้ ไม่อนุญาตให้ใช้รายการที่ว่างเปล่า

หมายเหตุ: การระบุเงื่อนไขกฎ requestMethods จะยกเว้นคำขอที่ไม่ใช่ HTTP(S) ด้วย ส่วนการระบุ excludedRequestMethods จะไม่ยกเว้น
resourceTypes

ResourceType[] ไม่บังคับ

รายการประเภททรัพยากรที่กฎสามารถจับคู่ได้ ไม่อนุญาตให้ใช้รายการที่ว่างเปล่า

หมายเหตุ: ต้องระบุค่านี้สำหรับกฎ allowAllRequests และอาจรวมเฉพาะประเภททรัพยากร sub_frame และ main_frame เท่านั้น
responseHeaders

HeaderInfo[] ไม่บังคับ

Chrome 128 ขึ้นไป browser.* ตั้งแต่ Chrome 148

กฎจะตรงกันหากคำขอตรงกับเงื่อนไขส่วนหัวการตอบกลับในรายการนี้ (หากระบุ)
tabIds

number[] ไม่บังคับ

Chrome 92 ขึ้นไป browser.* ตั้งแต่ Chrome 148

รายการ tabs.Tab.id ที่กฎควรตรงกัน รหัส tabs.TAB_ID_NONE จะจับคู่กับคำขอที่ไม่ได้มาจากแท็บ ไม่อนุญาตให้ใช้รายการที่ว่างเปล่า รองรับเฉพาะกฎที่กำหนดขอบเขตระดับเซสชันเท่านั้น
topDomains

string[] ไม่บังคับ

Chrome 145 ขึ้นไป browser.* ตั้งแต่ Chrome 148

กฎจะจับคู่คำขอเครือข่ายก็ต่อเมื่อโดเมนของเฟรมระดับบนสุดที่เชื่อมโยงตรงกับโดเมนจากรายการ topDomains หากละเว้นรายการ ระบบจะใช้กฎกับคำขอที่เชื่อมโยงกับโดเมนเฟรมระดับบนสุดทั้งหมด ไม่อนุญาตให้ใช้รายการที่ว่างเปล่า

หมายเหตุ:
- นอกจากนี้ยังอนุญาตให้ใช้โดเมนย่อย เช่น "a.example.com" ด้วย
- รายการต้องประกอบด้วยอักขระ ASCII เท่านั้น
- ใช้การเข้ารหัส Punycode สำหรับโดเมนที่เป็นสากล
- โดเมนย่อยของโดเมนที่ระบุจะตรงกันด้วย
- สำหรับคำขอที่ไม่มีเฟรมระดับบนสุดที่เชื่อมโยง (เช่น คำขอที่เริ่มต้นโดย ServiceWorker) ระบบจะพิจารณาโดเมนของผู้เริ่มต้นคำขอแทน
urlFilter

สตริง ไม่บังคับ

รูปแบบที่ตรงกับ URL คำขอเครือข่าย โครงสร้างที่รองรับ:

'*' : ไวลด์การ์ด: จับคู่อักขระจำนวนเท่าใดก็ได้

'|' : Anchor ซ้าย/ขวา: หากใช้ที่ส่วนท้ายของรูปแบบ จะระบุจุดเริ่มต้น/จุดสิ้นสุดของ URL ตามลำดับ

'||' : Anchor ชื่อโดเมน: หากใช้ที่จุดเริ่มต้นของรูปแบบ จะระบุจุดเริ่มต้นของ (โดเมนย่อย) ของ URL

'^' : อักขระตัวคั่น: อักขระนี้จะจับคู่กับอักขระใดก็ได้ ยกเว้นตัวอักษร ตัวเลข หรืออักขระต่อไปนี้ _, -, . หรือ % ซึ่งจะจับคู่กับส่วนท้ายของ URL ด้วย

ดังนั้น urlFilter จึงประกอบด้วยส่วนต่างๆ ต่อไปนี้ (Anchor ด้านซ้าย/ชื่อโดเมนที่ไม่บังคับ) + รูปแบบ + (Anchor ด้านขวาที่ไม่บังคับ)

หากละเว้น ระบบจะจับคู่ URL ทั้งหมด ไม่อนุญาตให้ใช้สตริงว่างเปล่า

ไม่อนุญาตให้ใช้รูปแบบที่ขึ้นต้นด้วย ||* โปรดใช้ * แทน

หมายเหตุ: คุณระบุได้เพียง urlFilter หรือ regexFilter อย่างใดอย่างหนึ่งเท่านั้น

หมายเหตุ: urlFilter ต้องประกอบด้วยอักขระ ASCII เท่านั้น ซึ่งจะจับคู่กับ URL ที่โฮสต์เข้ารหัสในรูปแบบ Punycode (ในกรณีที่เป็นโดเมนสากล) และอักขระอื่นๆ ที่ไม่ใช่ ASCII จะเข้ารหัส URL ใน UTF-8 ตัวอย่างเช่น เมื่อ URL คำขอคือ http://abc.рф?q=ф ระบบจะจับคู่ urlFilter กับ URL http://abc.xn--p1ai/?q=%D1%84

RuleConditionKeys

Chrome 145 ขึ้นไป browser.* ตั้งแต่ Chrome 148

ค่าแจกแจง

"urlFilter"

"regexFilter"

"isUrlFilterCaseSensitive"

"initiatorDomains"

"excludedInitiatorDomains"

"requestDomains"

"excludedRequestDomains"

"topDomains"

"excludedTopDomains"

"domains"

"excludedDomains"

"resourceTypes"

"excludedResourceTypes"

"requestMethods"

"excludedRequestMethods"

"domainType"

"tabIds"

"excludedTabIds"

"responseHeaders"

"excludedResponseHeaders"

Ruleset

พร็อพเพอร์ตี้

เปิดอยู่

บูลีน

เปิดใช้ชุดกฎโดยค่าเริ่มต้นหรือไม่
id

สตริง

สตริงที่ไม่ใช่ค่าว่างซึ่งระบุชุดกฎโดยไม่ซ้ำกัน รหัสที่ขึ้นต้นด้วย "_" สงวนไว้สำหรับการใช้งานภายใน
เส้นทาง

สตริง

เส้นทางของกฎ JSON ที่สัมพันธ์กับไดเรกทอรีส่วนขยาย

RulesMatchedDetails

พร็อพเพอร์ตี้

rulesMatchedInfo

MatchedRuleInfo[]

กฎที่ตรงกับตัวกรองที่ระบุ

TabActionCountUpdate

Chrome 89 ขึ้นไป browser.* ตั้งแต่ Chrome 148

พร็อพเพอร์ตี้

การเพิ่มขึ้น

ตัวเลข

จำนวนที่จะเพิ่มจำนวนการดำเนินการของแท็บ ค่าลบจะลดจำนวนลง
tabId

ตัวเลข

แท็บที่จะอัปเดตจำนวนการดำเนินการ

TestMatchOutcomeResult

Chrome 103 ขึ้นไป browser.* ตั้งแต่ Chrome 148

พร็อพเพอร์ตี้

matchedRules

MatchedRule[]

กฎ (หากมี) ที่ตรงกับคำขอสมมติ

TestMatchRequestDetails

Chrome 103 ขึ้นไป browser.* ตั้งแต่ Chrome 148

พร็อพเพอร์ตี้

ผู้เริ่ม

สตริง ไม่บังคับ

URL ของตัวเริ่มต้น (หากมี) สำหรับคำขอสมมติ
method

RequestMethod ไม่บังคับ

เมธอด HTTP มาตรฐานของคำขอสมมติ ค่าเริ่มต้นคือ "get" สำหรับคำขอ HTTP และระบบจะไม่สนใจสำหรับคำขอที่ไม่ใช่ HTTP
responseHeaders

object ไม่บังคับ

Chrome 129 ขึ้นไป browser.* ตั้งแต่ Chrome 148

ส่วนหัวที่ได้จากการตอบกลับสมมติในกรณีที่คำขอไม่ถูกบล็อกหรือเปลี่ยนเส้นทางก่อนที่จะส่ง แสดงเป็นออบเจ็กต์ที่แมปชื่อส่วนหัวกับรายการค่าสตริง หากไม่ได้ระบุ การตอบกลับสมมติจะแสดงส่วนหัวการตอบกลับที่ว่างเปล่า ซึ่งอาจตรงกับกฎที่ตรงกับการไม่มีส่วนหัว เช่น {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}
tabId

number ไม่บังคับ

รหัสของแท็บที่คำขอสมมติเกิดขึ้น ไม่จำเป็นต้องสอดคล้องกับรหัสแท็บจริง ค่าเริ่มต้นคือ -1 ซึ่งหมายความว่าคำขอไม่เกี่ยวข้องกับแท็บ
topUrl

สตริง ไม่บังคับ

Chrome 145 ขึ้นไป browser.* ตั้งแต่ Chrome 148

URL เฟรมระดับบนสุดที่เชื่อมโยง (หากมี) สำหรับคำขอ
ประเภท

ResourceType

ประเภททรัพยากรของคำขอสมมติ
URL

สตริง

URL ของคำขอสมมติ

UnsupportedRegexReason

Chrome 87 ขึ้นไป browser.* ตั้งแต่ Chrome 148

อธิบายสาเหตุที่ระบบไม่รองรับนิพจน์ทั่วไปที่ระบุ

ค่าแจกแจง

"syntaxError"
นิพจน์ทั่วไปมีไวยากรณ์ไม่ถูกต้อง หรือใช้ฟีเจอร์ที่ไม่มีในไวยากรณ์ RE2

"memoryLimitExceeded"
นิพจน์ทั่วไปเกินขีดจำกัดหน่วยความจำ

UpdateRuleOptions

Chrome 87 ขึ้นไป browser.* ตั้งแต่ Chrome 148

พร็อพเพอร์ตี้

addRules

Rule[] ไม่บังคับ

กฎที่จะเพิ่ม
removeRuleIds

number[] ไม่บังคับ

รหัสของกฎที่จะนำออก ระบบจะไม่สนใจรหัสที่ไม่ถูกต้อง

UpdateRulesetOptions

Chrome 87 ขึ้นไป browser.* ตั้งแต่ Chrome 148

พร็อพเพอร์ตี้

disableRulesetIds

string[] ไม่บังคับ

ชุดรหัสที่สอดคล้องกับ Ruleset แบบคงที่ซึ่งควรปิดใช้
enableRulesetIds

string[] ไม่บังคับ

ชุดรหัสที่สอดคล้องกับ Ruleset แบบคงที่ที่ควรเปิดใช้

UpdateStaticRulesOptions

Chrome 111 ขึ้นไป browser.* ตั้งแต่ Chrome 148

พร็อพเพอร์ตี้

disableRuleIds

number[] ไม่บังคับ

ชุดรหัสที่สอดคล้องกับกฎใน Ruleset ที่จะปิดใช้
enableRuleIds

number[] ไม่บังคับ

ชุดรหัสที่สอดคล้องกับกฎใน Ruleset ที่จะเปิดใช้
rulesetId

สตริง

รหัสที่สอดคล้องกับ Ruleset แบบคงที่

URLTransform

พร็อพเพอร์ตี้

Fragment

สตริง ไม่บังคับ

ส่วนย่อยใหม่สำหรับคำขอ ควรเว้นว่างไว้ ซึ่งในกรณีนี้ระบบจะล้าง Fragment ที่มีอยู่ หรือควรขึ้นต้นด้วย "#"
ผู้จัด

สตริง ไม่บังคับ

โฮสต์ใหม่สำหรับคำขอ
รหัสผ่าน

สตริง ไม่บังคับ

รหัสผ่านใหม่สำหรับคำขอ
เส้นทาง

สตริง ไม่บังคับ

เส้นทางใหม่สำหรับคำขอ หากเว้นว่างไว้ ระบบจะล้างเส้นทางที่มีอยู่
พอร์ต

สตริง ไม่บังคับ

พอร์ตใหม่สำหรับคำขอ หากเว้นว่างไว้ ระบบจะล้างพอร์ตที่มีอยู่
query

สตริง ไม่บังคับ

คำค้นหาใหม่สำหรับคำขอ ควรเว้นว่างไว้ ซึ่งในกรณีนี้ระบบจะล้างการค้นหาที่มีอยู่ หรือควรขึ้นต้นด้วย "?"
queryTransform

QueryTransform ไม่บังคับ

เพิ่ม นำออก หรือแทนที่คู่คีย์-ค่าของคำค้นหา
สคีม

สตริง ไม่บังคับ

รูปแบบใหม่สำหรับคำขอ ค่าที่อนุญาตคือ "http", "https", "ftp" และ "chrome-extension"
ชื่อผู้ใช้

สตริง ไม่บังคับ

ชื่อผู้ใช้ใหม่สำหรับคำขอ

พร็อพเพอร์ตี้

DYNAMIC_RULESET_ID

รหัสชุดกฎสำหรับกฎแบบไดนามิกที่เพิ่มโดยส่วนขยาย

ค่า

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

ช่วงเวลาที่สามารถโทรออกได้ MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules ครั้ง โดยระบุเป็นนาที การเรียกใช้เพิ่มเติมจะล้มเหลวทันทีและตั้งค่า runtime.lastError หมายเหตุ: การเรียก getMatchedRules ที่เชื่อมโยงกับท่าทางผู้ใช้จะได้รับการยกเว้นจากโควต้า

ค่า

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89 ขึ้นไป browser.* ตั้งแต่ Chrome 148

จำนวนกฎแบบคงที่ขั้นต่ำที่รับประกันสำหรับส่วนขยายในชุดกฎแบบคงที่ที่เปิดใช้ กฎที่เกินขีดจำกัดนี้จะนับรวมในขีดจำกัดกฎแบบคงที่ส่วนกลาง

ค่า

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

จำนวนครั้งที่เรียกใช้ getMatchedRules ได้ภายในระยะเวลา GETMATCHEDRULES_QUOTA_INTERVAL

ค่า

MAX_NUMBER_OF_DYNAMIC_RULES

จำนวนกฎแบบไดนามิกสูงสุดที่ส่วนขยายสามารถเพิ่มได้

ค่า

30000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94 ขึ้นไป เบราว์เซอร์* ตั้งแต่ Chrome 148

จำนวนสูงสุดของ Rulesets แบบคงที่ที่ส่วนขยายสามารถเปิดใช้ได้ในแต่ละครั้ง

ค่า

MAX_NUMBER_OF_REGEX_RULES

จำนวนกฎนิพจน์ทั่วไปสูงสุดที่ส่วนขยายเพิ่มได้ ระบบจะประเมินขีดจำกัดนี้แยกกันสำหรับชุดกฎแบบไดนามิกและกฎที่ระบุไว้ในไฟล์ทรัพยากรกฎ

ค่า

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120 ขึ้นไป browser.* ตั้งแต่ Chrome 148

จำนวนกฎที่กำหนดขอบเขตเซสชันสูงสุดที่ส่วนขยายสามารถเพิ่มได้

ค่า

5000

MAX_NUMBER_OF_STATIC_RULESETS

จำนวนสูงสุดของ Rulesets แบบคงที่ที่ส่วนขยายสามารถระบุได้เป็นส่วนหนึ่งของคีย์ไฟล์ Manifest "rule_resources"

ค่า

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120 ขึ้นไป browser.* ตั้งแต่ Chrome 148

จำนวนกฎแบบไดนามิกที่ "ไม่ปลอดภัย" สูงสุดที่ส่วนขยายสามารถเพิ่มได้

ค่า

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120 ขึ้นไป browser.* ตั้งแต่ Chrome 148

จำนวนสูงสุดของกฎที่กำหนดขอบเขตเซสชัน "ไม่ปลอดภัย" ที่ส่วนขยายสามารถเพิ่มได้

ค่า

5000

SESSION_RULESET_ID

Chrome 90 ขึ้นไป เบราว์เซอร์* ตั้งแต่ Chrome 148

รหัสชุดกฎสำหรับกฎระดับเซสชันซึ่งเพิ่มโดยส่วนขยาย

ค่า

"_session"

เมธอด

getAvailableStaticRuleCount()

Chrome 89 ขึ้นไป browser.* ตั้งแต่ Chrome 148

browser.declarativeNetRequest.getAvailableStaticRuleCount(): Promise<number>

แสดงผลจำนวนกฎแบบคงที่ที่ส่วนขยายสามารถเปิดใช้ได้ก่อนที่จะถึงขีดจำกัดกฎแบบคงที่ทั่วโลก

การคืนสินค้า

Promise<number>

Chrome 91 ขึ้นไป browser.* ตั้งแต่ Chrome 148

getDisabledRuleIds()

Chrome 111 ขึ้นไป browser.* ตั้งแต่ Chrome 148

browser.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
): Promise<number[]>

แสดงรายการกฎแบบคงที่ใน Ruleset ที่ระบุซึ่งปิดใช้อยู่ในปัจจุบัน

พารามิเตอร์

ตัวเลือก

GetDisabledRuleIdsOptions

ระบุชุดกฎที่จะค้นหา

การคืนสินค้า

Promise<number[]>

Promise ที่แก้ไขด้วยรายการรหัสที่สอดคล้องกับกฎที่ปิดใช้ในชุดกฎนั้น

getDynamicRules()

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

แสดงผลชุดกฎแบบไดนามิกปัจจุบันสำหรับส่วนขยาย ผู้โทรสามารถเลือกกรองรายการกฎที่ดึงข้อมูลมาได้โดยระบุ filter

พารามิเตอร์

ตัวกรอง

GetRulesFilter ไม่บังคับ

Chrome 111 ขึ้นไป browser.* ตั้งแต่ Chrome 148

ออบเจ็กต์สำหรับกรองรายการกฎที่ดึงมา

การคืนสินค้า

Promise<Rule[]>

Chrome 91 ขึ้นไป browser.* ตั้งแต่ Chrome 148

Promise ที่แก้ไขด้วยชุดกฎแบบไดนามิก ระบบอาจปฏิเสธ Promise ในกรณีที่เกิดข้อผิดพลาดภายในชั่วคราว

getEnabledRulesets()

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

แสดงรหัสสำหรับชุดกฎแบบคงที่ที่เปิดใช้ในปัจจุบัน

การคืนสินค้า

Promise<string[]>

Chrome 91 ขึ้นไป browser.* ตั้งแต่ Chrome 148

Promise ที่แก้ไขด้วยรายการรหัส โดยที่รหัสแต่ละรายการสอดคล้องกับ Ruleset แบบคงที่ที่เปิดใช้

getMatchedRules()

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

แสดงกฎทั้งหมดที่ตรงกับส่วนขยาย ผู้โทรสามารถเลือกกรองรายการกฎที่ตรงกันได้โดยระบุ filter วิธีนี้ใช้ได้กับส่วนขยายที่มีสิทธิ์ "declarativeNetRequestFeedback" หรือได้รับสิทธิ์ "activeTab" สำหรับ tabId ที่ระบุใน filter เท่านั้น หมายเหตุ: ระบบจะไม่แสดงกฎที่ไม่ได้เชื่อมโยงกับเอกสารที่ใช้งานอยู่ซึ่งมีการจับคู่มากกว่า 5 นาทีที่ผ่านมา

พารามิเตอร์

ตัวกรอง

MatchedRulesFilter ไม่บังคับ

ออบเจ็กต์สำหรับกรองรายการกฎที่ตรงกัน

การคืนสินค้า

Promise<RulesMatchedDetails>

Chrome 91 ขึ้นไป browser.* ตั้งแต่ Chrome 148

Promise ที่จะได้รับการแก้ไขเมื่อดึงข้อมูลรายการกฎที่ตรงกันแล้ว ในกรณีที่เกิดข้อผิดพลาด ระบบจะปฏิเสธ Promise ซึ่งอาจเกิดขึ้นได้จากหลายสาเหตุ เช่น สิทธิ์ไม่เพียงพอ หรือเกินโควต้า

getSessionRules()

Chrome 90 ขึ้นไป เบราว์เซอร์* ตั้งแต่ Chrome 148

browser.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
): Promise<Rule[]>

แสดงผลชุดกฎที่กำหนดขอบเขตเซสชันปัจจุบันสำหรับส่วนขยาย ผู้โทรสามารถเลือกกรองรายการกฎที่ดึงข้อมูลมาได้โดยระบุ filter

พารามิเตอร์

ตัวกรอง

GetRulesFilter ไม่บังคับ

Chrome 111 ขึ้นไป browser.* ตั้งแต่ Chrome 148

ออบเจ็กต์สำหรับกรองรายการกฎที่ดึงมา

การคืนสินค้า

Promise<Rule[]>

Chrome 91 ขึ้นไป browser.* ตั้งแต่ Chrome 148

Promise ที่แก้ไขด้วยชุดกฎที่กำหนดขอบเขตเซสชัน

isRegexSupported()

Chrome 87 ขึ้นไป browser.* ตั้งแต่ Chrome 148

browser.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
): Promise<IsRegexSupportedResult>

ตรวจสอบว่าระบบจะรองรับนิพจน์ทั่วไปที่ระบุเป็นเงื่อนไขของกฎ regexFilter หรือไม่

พารามิเตอร์

regexOptions

RegexOptions

นิพจน์ทั่วไปที่จะตรวจสอบ

การคืนสินค้า

Promise<IsRegexSupportedResult>

Chrome 91 ขึ้นไป browser.* ตั้งแต่ Chrome 148

Promise ที่แก้ไขด้วยรายละเอียดที่ประกอบด้วยข้อมูลว่าระบบรองรับนิพจน์ทั่วไปหรือไม่ และเหตุผลหากไม่รองรับ

setExtensionActionOptions()

Chrome 88 ขึ้นไป browser.* ตั้งแต่ Chrome 148

browser.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
): Promise<void>

กำหนดค่าว่าควรแสดงจำนวนการดำเนินการสำหรับแท็บเป็นข้อความป้ายของการดำเนินการของส่วนขยายหรือไม่ และระบุวิธีเพิ่มจำนวนการดำเนินการนั้น

พารามิเตอร์

ตัวเลือก

ExtensionActionOptions

การคืนสินค้า

Promise<void>

Chrome 91 ขึ้นไป browser.* ตั้งแต่ Chrome 148

testMatchOutcome()

Chrome 103 ขึ้นไป browser.* ตั้งแต่ Chrome 148

browser.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
): Promise<TestMatchOutcomeResult>

ตรวจสอบว่ากฎ declarativeNetRequest ของส่วนขยายตรงกับคำขอสมมติหรือไม่ หมายเหตุ: ใช้ได้กับส่วนขยายที่ไม่ได้แพ็กเท่านั้น เนื่องจากมีไว้เพื่อใช้ในระหว่างการพัฒนาส่วนขยายเท่านั้น

พารามิเตอร์

ส่งคำขอ

TestMatchRequestDetails

การคืนสินค้า

Promise<TestMatchOutcomeResult>

Promise ที่แก้ไขด้วยรายละเอียดของกฎที่ตรงกัน

updateDynamicRules()

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

แก้ไขชุดกฎแบบไดนามิกปัจจุบันสำหรับส่วนขยาย ระบบจะนำกฎที่มีรหัสที่ระบุไว้ใน options.removeRuleIds ออกก่อน จากนั้นจึงเพิ่มกฎที่ระบุไว้ใน options.addRules หมายเหตุ:

การอัปเดตนี้จะเกิดขึ้นเป็นการดำเนินการแบบอะตอมเดียว กล่าวคือ ระบบจะเพิ่มและนำกฎที่ระบุทั้งหมดออก หรือแสดงข้อผิดพลาด
กฎเหล่านี้จะคงอยู่ตลอดเซสชันของเบราว์เซอร์และตลอดการอัปเดตส่วนขยาย
กฎแบบคงที่ที่ระบุเป็นส่วนหนึ่งของแพ็กเกจส่วนขยายจะนำออกโดยใช้ฟังก์ชันนี้ไม่ได้
MAX_NUMBER_OF_DYNAMIC_RULES คือจำนวนกฎแบบไดนามิกสูงสุดที่ส่วนขยายสามารถเพิ่มได้ จำนวนกฎที่ไม่ปลอดภัยต้องไม่เกิน MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

พารามิเตอร์

ตัวเลือก

UpdateRuleOptions

Chrome 87 ขึ้นไป browser.* ตั้งแต่ Chrome 148

การคืนสินค้า

Promise<void>

Chrome 91 ขึ้นไป browser.* ตั้งแต่ Chrome 148

Promise ที่จะได้รับการแก้ไขเมื่อการอัปเดตเสร็จสมบูรณ์ ในกรณีที่เกิดข้อผิดพลาด ระบบจะปฏิเสธสัญญาและจะไม่มีการเปลี่ยนแปลงชุดกฎ ซึ่งอาจเกิดขึ้นได้จากหลายสาเหตุ เช่น รูปแบบกฎไม่ถูกต้อง รหัสกฎซ้ำ จำนวนกฎเกินขีดจำกัด ข้อผิดพลาดภายใน และอื่นๆ

updateEnabledRulesets()

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

อัปเดตชุดกฎแบบคงที่ที่เปิดใช้สำหรับส่วนขยาย ระบบจะนำชุดกฎที่มีรหัสที่ระบุไว้ใน options.disableRulesetIds ออกก่อน จากนั้นจึงเพิ่มชุดกฎที่ระบุไว้ใน options.enableRulesetIds โปรดทราบว่าชุดกฎแบบคงที่ที่เปิดใช้จะยังคงอยู่ตลอดเซสชัน แต่จะไม่คงอยู่ตลอดการอัปเดตส่วนขยาย กล่าวคือ คีย์ไฟล์ Manifest rule_resources จะกำหนดชุดกฎแบบคงที่ที่เปิดใช้ในการอัปเดตส่วนขยายแต่ละครั้ง

พารามิเตอร์

ตัวเลือก

UpdateRulesetOptions

Chrome 87 ขึ้นไป browser.* ตั้งแต่ Chrome 148

การคืนสินค้า

Promise<void>

Chrome 91 ขึ้นไป browser.* ตั้งแต่ Chrome 148

Promise ที่จะได้รับการแก้ไขเมื่อการอัปเดตเสร็จสมบูรณ์ ในกรณีที่เกิดข้อผิดพลาด ระบบจะปฏิเสธ Promise และจะไม่มีการเปลี่ยนแปลงชุดกฎที่เปิดใช้ ซึ่งอาจเกิดขึ้นได้จากหลายสาเหตุ เช่น รหัสชุดกฎไม่ถูกต้อง จำนวนกฎเกินขีดจำกัด หรือข้อผิดพลาดภายใน

updateSessionRules()

Chrome 90 ขึ้นไป เบราว์เซอร์* ตั้งแต่ Chrome 148

browser.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
): Promise<void>

แก้ไขชุดกฎที่กำหนดขอบเขตเซสชันปัจจุบันสำหรับส่วนขยาย ระบบจะนำกฎที่มีรหัสที่ระบุไว้ใน options.removeRuleIds ออกก่อน จากนั้นจึงเพิ่มกฎที่ระบุไว้ใน options.addRules หมายเหตุ:

การอัปเดตนี้จะเกิดขึ้นเป็นการดำเนินการแบบอะตอมเดียว กล่าวคือ ระบบจะเพิ่มและนำกฎที่ระบุทั้งหมดออก หรือแสดงข้อผิดพลาด
กฎเหล่านี้จะไม่คงอยู่ข้ามเซสชันและจะได้รับการสำรองข้อมูลไว้ในหน่วยความจำ
MAX_NUMBER_OF_SESSION_RULES คือจำนวนกฎเซสชันสูงสุดที่ส่วนขยายสามารถเพิ่มได้

พารามิเตอร์

ตัวเลือก

UpdateRuleOptions

การคืนสินค้า

Promise<void>

Chrome 91 ขึ้นไป browser.* ตั้งแต่ Chrome 148

Promise ที่จะได้รับการแก้ไขเมื่อการอัปเดตเสร็จสมบูรณ์ ในกรณีที่เกิดข้อผิดพลาด ระบบจะปฏิเสธสัญญาและจะไม่มีการเปลี่ยนแปลงชุดกฎ ซึ่งอาจเกิดขึ้นได้จากหลายสาเหตุ เช่น รูปแบบกฎไม่ถูกต้อง รหัสกฎซ้ำ จำนวนกฎเกินขีดจำกัด และอื่นๆ

updateStaticRules()

Chrome 111 ขึ้นไป browser.* ตั้งแต่ Chrome 148

browser.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
): Promise<void>

ปิดใช้และเปิดใช้กฎแบบคงที่แต่ละข้อใน Ruleset การเปลี่ยนแปลงกฎที่เป็นของ Ruleset ที่ปิดใช้อยู่จะมีผลในครั้งถัดไปที่เปิดใช้

พารามิเตอร์

ตัวเลือก

UpdateStaticRulesOptions

การคืนสินค้า

Promise<void>

Promise ที่จะได้รับการแก้ไขเมื่อการอัปเดตเสร็จสมบูรณ์ ในกรณีที่เกิดข้อผิดพลาด ระบบจะปฏิเสธ Promise และจะไม่มีการเปลี่ยนแปลงกฎแบบคงที่ที่เปิดใช้

กิจกรรม

onRuleMatchedDebug

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

เริ่มทำงานเมื่อกฎตรงกับคำขอ ใช้ได้กับส่วนขยายที่ไม่ได้แพ็กซึ่งมีสิทธิ์ "declarativeNetRequestFeedback" เท่านั้น เนื่องจากมีไว้เพื่อใช้สำหรับการแก้ไขข้อบกพร่องเท่านั้น

พารามิเตอร์

callback

ฟังก์ชัน

พารามิเตอร์ callback จะมีลักษณะดังนี้
```
(info: MatchedRuleInfoDebug) => void
```
- ข้อมูล
  
  MatchedRuleInfoDebug