chrome.declarativeNetRequest

คำอธิบาย

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

สิทธิ์

declarativeNetRequest
declarativeNetRequestWithHostAccess

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

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

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

Chrome 84 ขึ้นไป

ไฟล์ Manifest

นอกเหนือจากสิทธิ์ที่อธิบายไว้ก่อนหน้านี้แล้ว ชุดกฎบางประเภท โดยเฉพาะชุดกฎแบบคงที่กำหนดให้ประกาศ"declarative_net_request"คีย์ไฟล์ Manifest ซึ่งควรเป็นพจนานุกรมที่มีคีย์เดียวชื่อ "rule_resources" คีย์นี้เป็นอาร์เรย์ที่มีพจนานุกรมประเภท 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"
    },
    ...
    ]
  }
  ...
}

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

การตรวจสอบอย่างรวดเร็ว

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

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

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

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

นอกจากนี้ ระบบยังจำกัดจำนวนกฎและชุดกฎที่อาจเปิดใช้ได้ในครั้งเดียวด้วยเหตุผลด้านประสิทธิภาพ โทรหา 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

คำขอเครือข่ายแบบประกาศช่วยให้สามารถจับคู่ 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:\/\/p.rizon.top:443\/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 ชุดเป็นส่วนหนึ่งของ"rule_resources"คีย์ไฟล์ Manifest แต่จะเปิดใช้ชุดกฎเหล่านี้ได้ครั้งละ 50 ชุดเท่านั้น ส่วนอย่างหลังเรียกว่า MAX_NUMBER_OF_ENABLED_STATIC_RULESETS โดยรวมแล้ว ชุดกฎเหล่านั้นมีการรับประกันว่าจะมีกฎอย่างน้อย 30,000 รายการ ซึ่งเรียกว่า GUARANTEED_MINIMUM_STATIC_RULES

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

กฎเซสชัน

ส่วนขยายมีกฎเซสชันได้สูงสุด 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

ตัวอย่าง

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

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

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

// 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
});

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

ตัวอย่างต่อไปนี้แสดงวิธีเปิดใช้และปิดใช้ชุดกฎขณะพิจารณาจำนวนชุดกฎแบบคงที่ที่พร้อมใช้งานและจำนวนสูงสุดของชุดกฎแบบคงที่ที่เปิดใช้ คุณจะทำเช่นนี้เมื่อจำนวนกฎแบบคงที่คุณต้องการเกินจำนวนที่อนุญาต หากต้องการให้การดำเนินการนี้ทำงานได้ คุณควรติดตั้งชุดกฎบางชุดโดยปิดใช้ชุดกฎบางชุด (ตั้งค่า "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 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);
}

ตัวอย่างกฎ

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

คีย์ "priority"

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

หากต้องการทราบลำดับความสำคัญของ URL ใด 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 ขึ้นไป

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

  • displayActionCountAsBadgeText

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

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

  • tabUpdate

    TabActionCountUpdate ไม่บังคับ

    Chrome 89 ขึ้นไป

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

GetDisabledRuleIdsOptions

Chrome 111 ขึ้นไป

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

  • rulesetId

    สตริง

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

GetRulesFilter

Chrome 111 ขึ้นไป

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

  • ruleIds

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

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

HeaderInfo

Chrome 128 ขึ้นไป

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

  • excludedValues

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

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

  • ส่วนหัว

    สตริง

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

  • values

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

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

    "*" : จับคู่กับอักขระกี่ตัวก็ได้

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

    คุณใช้เครื่องหมายแบ็กสแลชเป็นอักขระหลีกสำหรับ "*" และ "?" ได้ เช่น "\*" และ "\?"

HeaderOperation

Chrome 86 ขึ้นไป

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

ค่าแจกแจง

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

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

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

IsRegexSupportedResult

Chrome 87 ขึ้นไป

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

  • isSupported

    บูลีน

  • เหตุผล

    UnsupportedRegexReason ไม่บังคับ

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

MatchedRule

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

  • ruleId

    ตัวเลข

    รหัสของกฎที่ตรงกัน

  • rulesetId

    สตริง

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

MatchedRuleInfo

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

  • กฎ

    MatchedRule

  • tabId

    ตัวเลข

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

  • timeStamp

    ตัวเลข

    เวลาที่กฎตรงกัน การประทับเวลาจะสอดคล้องกับรูปแบบ JavaScript สำหรับเวลา ซึ่งก็คือจำนวนมิลลิวินาทีนับตั้งแต่ Epoch

MatchedRuleInfoDebug

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

  • ส่งคำขอ

    RequestDetails

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

  • กฎ

    MatchedRule

MatchedRulesFilter

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

  • minTimeStamp

    หมายเลข ไม่บังคับ

    หากระบุ ระบบจะจับคู่เฉพาะกฎหลังจากประทับเวลาที่ระบุ

  • tabId

    หมายเลข ไม่บังคับ

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

ModifyHeaderInfo

Chrome 86 ขึ้นไป

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

  • ส่วนหัว

    สตริง

    ชื่อของส่วนหัวที่จะแก้ไข

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

    HeaderOperation

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

  • value

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

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

QueryKeyValue

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

  • แป้น

    สตริง

  • replaceOnly

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

    Chrome 94 ขึ้นไป

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

  • 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 ขึ้นไป

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

  • isCaseSensitive

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

    regex ที่ระบุพิจารณาตัวพิมพ์เล็กและตัวพิมพ์ใหญ่หรือไม่ ค่าเริ่มต้นคือ True

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

    สตริง

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

  • requireCapturing

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

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

RequestDetails

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

  • documentId

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

    Chrome 106 ขึ้นไป

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

  • documentLifecycle

    DocumentLifecycle ไม่บังคับ

    Chrome 106 ขึ้นไป

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

  • frameId

    ตัวเลข

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

  • frameType

    FrameType ไม่บังคับ

    Chrome 106 ขึ้นไป

    ประเภทของเฟรม หากคำขอนี้เป็นคำขอสำหรับเฟรม

  • ผู้เริ่ม

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

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

  • method

    สตริง

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

  • parentDocumentId

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

    Chrome 106 ขึ้นไป

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

  • parentFrameId

    ตัวเลข

    รหัสของเฟรมที่ครอบเฟรมซึ่งส่งคำขอ ตั้งค่าเป็น -1 หากไม่มีเฟรมหลัก

  • requestId

    สตริง

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

  • tabId

    ตัวเลข

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

  • ประเภท

    ResourceType

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

  • URL

    สตริง

    URL ของคำขอ

RequestMethod

Chrome 91 ขึ้นไป

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

ค่าแจกแจง

"connect"

"ลบ"

"get"

"head"

"options"

"patch"

"post"

"put"

"อื่นๆ"

ResourceType

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

ค่าแจกแจง

"main_frame"

"sub_frame"

"stylesheet"

"script"

"image"

"font"

"object"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"webtransport"

"webbundle"

"อื่นๆ"

Rule

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

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

    RuleAction

    การดำเนินการที่จะทำหากตรงกับกฎนี้

  • เงื่อนไข

    RuleCondition

    เงื่อนไขที่ทำให้เกิดการเรียกใช้กฎนี้

  • id

    ตัวเลข

    รหัสที่ระบุกฎแบบไม่ซ้ำ ต้องระบุและควรมีค่ามากกว่าหรือเท่ากับ 1

  • ลำดับความสำคัญ

    หมายเลข ไม่บังคับ

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

RuleAction

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

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

    เปลี่ยนเส้นทาง ไม่บังคับ

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

  • requestHeaders

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

    Chrome 86 ขึ้นไป

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

  • responseHeaders

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

    Chrome 86 ขึ้นไป

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

  • ประเภท

    RuleActionType

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

RuleActionType

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

ค่าแจกแจง

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

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

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

"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 ขึ้นไป

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

    หมายเหตุ:

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

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

    Chrome 101 ขึ้นไป

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

    หมายเหตุ:

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

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

    Chrome 91 ขึ้นไป

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

  • excludedResourceTypes

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

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

  • excludedResponseHeaders

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

    Chrome 128 ขึ้นไป

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

  • excludedTabIds

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

    Chrome 92 ขึ้นไป

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

  • initiatorDomains

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

    Chrome 101 ขึ้นไป

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

    หมายเหตุ:

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

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

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

  • regexFilter

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

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

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

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

  • requestDomains

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

    Chrome 101 ขึ้นไป

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

    หมายเหตุ:

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

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

    Chrome 91 ขึ้นไป

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

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

  • resourceTypes

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

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

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

  • responseHeaders

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

    Chrome 128 ขึ้นไป

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

  • tabIds

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

    Chrome 92 ขึ้นไป

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

  • urlFilter

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

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

    "*" : ไวลด์การ์ด: จับคู่กับอักขระกี่ตัวก็ได้

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

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

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

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

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

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

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

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

Ruleset

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

  • เปิดใช้อยู่

    บูลีน

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

  • id

    สตริง

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

  • เส้นทาง

    สตริง

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

RulesMatchedDetails

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

  • rulesMatchedInfo

    MatchedRuleInfo[]

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

TabActionCountUpdate

Chrome 89 ขึ้นไป

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

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

    ตัวเลข

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

  • tabId

    ตัวเลข

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

TestMatchOutcomeResult

Chrome 103 ขึ้นไป

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

  • matchedRules

    MatchedRule[]

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

TestMatchRequestDetails

Chrome 103 ขึ้นไป

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

  • ผู้เริ่ม

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

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

  • method

    RequestMethod ไม่บังคับ

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

  • responseHeaders

    object ไม่บังคับ

    Chrome 129 ขึ้นไป

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

  • tabId

    หมายเลข ไม่บังคับ

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

  • ประเภท

    ResourceType

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

  • URL

    สตริง

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

UnsupportedRegexReason

Chrome 87 ขึ้นไป

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

ค่าแจกแจง

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

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

UpdateRuleOptions

Chrome 87 ขึ้นไป

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

  • addRules

    กฎ[] ไม่บังคับ

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

  • removeRuleIds

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

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

UpdateRulesetOptions

Chrome 87 ขึ้นไป

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

  • disableRulesetIds

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

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

  • enableRulesetIds

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

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

UpdateStaticRulesOptions

Chrome 111 ขึ้นไป

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

  • 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 การเรียกที่เชื่อมโยงกับการแตะของผู้ใช้จะได้รับการยกเว้นจากโควต้า

ค่า

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89 ขึ้นไป

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

ค่า

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

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

ค่า

20

MAX_NUMBER_OF_DYNAMIC_RULES

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

ค่า

30000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94 ขึ้นไป

จำนวน Rulesets แบบคงที่สูงสุดที่ส่วนขยายเปิดใช้ได้ในคราวเดียว

ค่า

50

MAX_NUMBER_OF_REGEX_RULES

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

ค่า

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120 ขึ้นไป

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

ค่า

5000

MAX_NUMBER_OF_STATIC_RULESETS

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

ค่า

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120 ขึ้นไป

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

ค่า

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120 ขึ้นไป

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

ค่า

5000

SESSION_RULESET_ID

Chrome 90 ขึ้นไป

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

ค่า

"_session"

เมธอด

getAvailableStaticRuleCount()

Chrome 89 ขึ้นไป 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(): Promise<number>

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

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

  • Promise<number>

    Chrome 91 ขึ้นไป

getDisabledRuleIds()

Chrome 111 ขึ้นไป 
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
): Promise<number[]>

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

พารามิเตอร์

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

  • Promise<number[]>

getDynamicRules()

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

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

พารามิเตอร์

  • ตัวกรอง

    GetRulesFilter ไม่บังคับ

    Chrome 111 ขึ้นไป

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

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

  • Promise<Rule[]>

    Chrome 91 ขึ้นไป

getEnabledRulesets()

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

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

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

  • Promise<string[]>

    Chrome 91 ขึ้นไป

getMatchedRules()

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

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

พารามิเตอร์

  • ตัวกรอง

    MatchedRulesFilter ไม่บังคับ

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

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

getSessionRules()

Chrome 90 ขึ้นไป 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
): Promise<Rule[]>

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

พารามิเตอร์

  • ตัวกรอง

    GetRulesFilter ไม่บังคับ

    Chrome 111 ขึ้นไป

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

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

  • Promise<Rule[]>

    Chrome 91 ขึ้นไป

isRegexSupported()

Chrome 87 ขึ้นไป 
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
): Promise<IsRegexSupportedResult>

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

พารามิเตอร์

  • regexOptions

    RegexOptions

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

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

setExtensionActionOptions()

Chrome 88 ขึ้นไป 
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
): Promise<void>

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

พารามิเตอร์

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

  • Promise<void>

    Chrome 91 ขึ้นไป

testMatchOutcome()

Chrome 103 ขึ้นไป 
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
): Promise<TestMatchOutcomeResult>

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

พารามิเตอร์

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

updateDynamicRules()

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

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

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

พารามิเตอร์

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

  • Promise<void>

    Chrome 91 ขึ้นไป

updateEnabledRulesets()

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

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

พารามิเตอร์

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

  • Promise<void>

    Chrome 91 ขึ้นไป

updateSessionRules()

Chrome 90 ขึ้นไป 
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
): Promise<void>

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

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

พารามิเตอร์

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

  • Promise<void>

    Chrome 91 ขึ้นไป

updateStaticRules()

Chrome 111 ขึ้นไป 
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
): Promise<void>

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

พารามิเตอร์

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

  • Promise<void>

กิจกรรม

onRuleMatchedDebug

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

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

พารามิเตอร์

  • callback

    ฟังก์ชัน

    พารามิเตอร์ callback มีลักษณะดังนี้ 

    (info: MatchedRuleInfoDebug) => void