chrome.declarativeNetRequest

คำอธิบาย

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

สิทธิ์

declarativeNetRequest
declarativeNetRequestWithHostAccess

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

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

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

Chrome 84 ขึ้นไป

ไฟล์ Manifest

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

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

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

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

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

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

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

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

กฎเซสชัน

ส่วนขยายมีกฎเซสชันได้สูงสุด 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 หนึ่งๆ ให้ดูที่คีย์ "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 โดยใช้แอตทริบิวต์แองเคอร์ชื่อโดเมน ("||") เพื่อสกัดกั้นคําขอที่มีรูปแบบใดก็ได้จาก 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 ของแท็บที่ส่งคำขอ หากแท็บยังทำงานอยู่ ไม่เช่นนั้น -1

  • timeStamp

    ตัวเลข

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

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"

"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

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

    ตัวเลข ไม่บังคับ

    ลําดับความสําคัญของกฎ ค่าเริ่มต้นคือ 1 หากระบุ ควรมีค่ามากกว่าหรือเท่ากับ 1

RuleAction

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

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

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

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

  • requestHeaders

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

    Chrome 86 ขึ้นไป

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

  • responseHeaders

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

    Chrome 86 ขึ้นไป

    ส่วนหัวของคำตอบที่จะแก้ไขสำหรับคำขอ ใช้ได้ก็ต่อเมื่อ 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 ขึ้นไป

    กฎจะไม่จับคู่กับคําขอเครือข่ายที่มาจากรายการ 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 อย่างใดอย่างหนึ่งเท่านั้น หากไม่ได้ระบุค่าใดเลย ระบบจะจับคู่วิธีการส่งคําขอทั้งหมด

  • excludedResourceTypes

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

    รายการประเภททรัพยากรที่กฎจะไม่จับคู่ ต้องระบุ resourceTypes หรือ excludedResourceTypes อย่างใดอย่างหนึ่งเท่านั้น หากไม่ได้ระบุรายการใดเลย ระบบจะบล็อกทรัพยากรทุกประเภทยกเว้น "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 (ในกรณีที่เป็นโดเมนที่แปลเป็นภาษาท้องถิ่น) และอักขระอื่นๆ ที่ไม่ใช่ ASCII เข้ารหัสเป็น URL ในรูปแบบ UTF-8

  • requestDomains

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

    Chrome 101 ขึ้นไป

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

    หมายเหตุ:

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

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

    Chrome 91 ขึ้นไป

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

    หมายเหตุ: การระบุเงื่อนไขกฎ requestMethods จะยกเว้นคำขอที่ไม่ใช่ HTTP ด้วย ขณะที่การระบุ 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 คำขอเครือข่าย โครงสร้างที่รองรับ

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

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

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

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

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

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

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

    หมายเหตุ: คุณระบุได้เพียง urlFilter หรือ regexFilter รายการเดียว

    หมายเหตุ: urlFilter ต้องประกอบด้วยอักขระ ASCII เท่านั้น รายการนี้จับคู่กับ URL ที่โฮสต์เข้ารหัสในรูปแบบ punycode (ในกรณีที่เป็นโดเมนที่แปลเป็นภาษาท้องถิ่น) และอักขระอื่นๆ ที่ไม่ใช่ ASCII เข้ารหัสเป็น URL ในรูปแบบ 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

    ออบเจ็กต์ ไม่บังคับ

    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

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

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

  • removeRuleIds

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

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

UpdateRulesetOptions

Chrome 87 ขึ้นไป

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

  • disableRulesetIds

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

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

  • enableRulesetIds

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

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

UpdateStaticRulesOptions

Chrome 111 ขึ้นไป

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

  • disableRuleIds

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

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

  • enableRuleIds

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

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

  • rulesetId

    สตริง

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

URLTransform

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

  • 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 แบบคงที่สูงสุดที่ส่วนขยายระบุได้เป็นส่วนหนึ่งของคีย์ไฟล์ Manifest "rule_resources"

ค่า

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(
  callback?: function,
)

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

พารามิเตอร์

  • Callback

    ฟังก์ชัน ไม่บังคับ

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

    (count: number) => void

    • จำนวน

      ตัวเลข

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

  • Promise<number>

    Chrome 91 ขึ้นไป

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

getDisabledRuleIds()

Promise Chrome 111 ขึ้นไป 
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
  callback?: function,
)

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

พารามิเตอร์

  • ตัวเลือก

    GetDisabledRuleIdsOptions

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

  • Callback

    ฟังก์ชัน ไม่บังคับ

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

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      number[]

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

  • Promise<number[]>

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

getDynamicRules()

สัญญา 
chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
  callback?: function,
)

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

พารามิเตอร์

  • ตัวกรอง

    GetRulesFilter ไม่บังคับ

    Chrome 111 ขึ้นไป

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

  • Callback

    ฟังก์ชัน ไม่บังคับ

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

    (rules: Rule[]) => void

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

  • Promise<Rule[]>

    Chrome 91 ขึ้นไป

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

getEnabledRulesets()

สัญญา 
chrome.declarativeNetRequest.getEnabledRulesets(
  callback?: function,
)

แสดงผลรหัสของชุดกฎแบบคงที่ที่เปิดใช้อยู่ในปัจจุบัน

พารามิเตอร์

  • Callback

    ฟังก์ชัน ไม่บังคับ

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

    (rulesetIds: string[]) => void

    • rulesetIds

      string[]

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

  • Promise<string[]>

    Chrome 91 ขึ้นไป

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

getMatchedRules()

สัญญา 
chrome.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
  callback?: function,
)

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

พารามิเตอร์

  • ตัวกรอง

    MatchedRulesFilter ไม่บังคับ

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

  • Callback

    ฟังก์ชัน ไม่บังคับ

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

    (details: RulesMatchedDetails) => void

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

  • Chrome 91 ขึ้นไป

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

getSessionRules()

สัญญา Chrome 90 ขึ้นไป 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
  callback?: function,
)

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

พารามิเตอร์

  • ตัวกรอง

    GetRulesFilter ไม่บังคับ

    Chrome 111 ขึ้นไป

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

  • Callback

    ฟังก์ชัน ไม่บังคับ

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

    (rules: Rule[]) => void

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

  • Promise<Rule[]>

    Chrome 91 ขึ้นไป

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

isRegexSupported()

สัญญา Chrome 87 ขึ้นไป 
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
  callback?: function,
)

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

พารามิเตอร์

  • regexOptions

    RegexOptions

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

  • Callback

    ฟังก์ชัน ไม่บังคับ

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

    (result: IsRegexSupportedResult) => void

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

  • Chrome 91 ขึ้นไป

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

setExtensionActionOptions()

สัญญา Chrome 88 ขึ้นไป 
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
  callback?: function,
)

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

พารามิเตอร์

  • ตัวเลือก

    ExtensionActionOptions

  • Callback

    ฟังก์ชัน ไม่บังคับ

    Chrome 89 ขึ้นไป

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

    () => void

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

  • Promise<void>

    Chrome 91 ขึ้นไป

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

testMatchOutcome()

สัญญา Chrome 103 ขึ้นไป 
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
)

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

พารามิเตอร์

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

  • ไฟล์ Manifest เวอร์ชัน 3 ขึ้นไปรองรับ Promise แต่ก็มีคอลแบ็กไว้เพื่อให้ใช้กับเวอร์ชันก่อนหน้าได้ คุณใช้ทั้ง 2 รูปแบบในการเรียกใช้ฟังก์ชันเดียวกันไม่ได้ พรอมต์จะได้รับการแก้ไขด้วยประเภทเดียวกันกับที่ส่งไปยังการเรียกกลับ

updateDynamicRules()

สัญญา 
chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
  callback?: function,
)

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

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

พารามิเตอร์

  • ตัวเลือก

    UpdateRuleOptions

    Chrome 87 ขึ้นไป
  • Callback

    ฟังก์ชัน ไม่บังคับ

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

    () => void

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

  • Promise<void>

    Chrome 91 ขึ้นไป

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

updateEnabledRulesets()

สัญญา 
chrome.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
  callback?: function,
)

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

พารามิเตอร์

  • ตัวเลือก

    UpdateRulesetOptions

    Chrome 87 ขึ้นไป
  • Callback

    ฟังก์ชัน ไม่บังคับ

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

    () => void

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

  • Promise<void>

    Chrome 91 ขึ้นไป

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

updateSessionRules()

สัญญา Chrome 90 ขึ้นไป 
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
  callback?: function,
)

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

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

พารามิเตอร์

  • ตัวเลือก

    UpdateRuleOptions

  • Callback

    ฟังก์ชัน ไม่บังคับ

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

    () => void

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

  • Promise<void>

    Chrome 91 ขึ้นไป

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

updateStaticRules()

Promise Chrome 111 ขึ้นไป 
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
  callback?: function,
)

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

พารามิเตอร์

  • ตัวเลือก

    UpdateStaticRulesOptions

  • Callback

    ฟังก์ชัน ไม่บังคับ

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

    () => void

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

  • Promise<void>

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

กิจกรรม

onRuleMatchedDebug

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

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

พารามิเตอร์

  • Callback

    ฟังก์ชัน

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

    (info: MatchedRuleInfoDebug) => void