chrome.declarativeNetRequest

คำอธิบาย

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

สิทธิ์

declarativeNetRequest
declarativeNetRequestWithHostAccess

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

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

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

Chrome เวอร์ชัน 84 ขึ้นไป

ไฟล์ Manifest

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

{
  "name": "My extension",
  ...

  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    }, {
      "id": "ruleset_2",
      "enabled": false,
      "path": "rules_2.json"
    }]
  },
  "permissions": [
    "declarativeNetRequest",
    "declarativeNetRequestFeedback",
  ],
  "host_permissions": [
    "http://www.blogger.com/*",
    "http://*.google.com/*"
  ],
  ...
}

กฎและชุดกฎ

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

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

ชุดกฎมี 3 ประเภท ซึ่งจัดการในรูปแบบที่แตกต่างกันเล็กน้อย

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

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

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

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

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

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

กฎทุกประเภทสามารถใช้นิพจน์ทั่วไปได้ แต่จำนวนทั้งหมดของกฎนิพจน์ทั่วไปแต่ละประเภทต้องไม่เกิน 1000 ซึ่งเรียกว่า 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() ที่ดำเนินการในโปรแกรมทำงานของบริการ

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

กฎ 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, x-forwarded-for, user-agent, x-forwarded-forviawant-digest

ตัวอย่าง

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

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

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

"ลำดับความสำคัญ" แป้น

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

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

การนำทางไปยัง https://google.com
กฎ 2 ข้อที่ครอบคลุม URL นี้ ได้แก่ กฎที่มีรหัส 1 และ 4 กฎที่มีรหัส 1 จะมีผลเนื่องจากการดำเนินการ "block" รายการมีลำดับความสำคัญสูงกว่าการดำเนินการ "redirect" รายการ กฎที่เหลือจะไม่มีผลเพราะมีไว้สำหรับ URL ที่ยาวกว่า
การนำทางไปที่ https://google.com/1234
เนื่องจาก URL ที่ยาวกว่า กฎที่มีรหัส 2 จะจับคู่กับกฎที่มีรหัส 1 และ 4 เพิ่มเติมจากกฎ กฎที่มีรหัส 2 จะมีผลเนื่องจาก "allow" มีลำดับความสำคัญสูงกว่า "block" และ "redirect"
การนำทางไปที่ https://google.com/12345
กฎทั้ง 4 ข้อตรงกับ URL นี้ กฎที่มีรหัส 3 จะมีผลเนื่องจากลำดับความสำคัญที่นักพัฒนาแอปกำหนดเป็นกฎสูงสุดของกลุ่ม
[
  {
    "id": 1,
    "priority": 1,
    "action": { "type": "block" },
    "condition": {"urlFilter": "||google.com/", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 2,
    "priority": 1,
    "action": { "type": "allow" },
    "condition": { "urlFilter": "||google.com/123", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 3,
    "priority": 2,
    "action": { "type": "block" },
    "condition": { "urlFilter": "||google.com/12345", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 4,
    "priority": 1,
    "action": { "type": "redirect", "redirect": { "url": "https://example.com" } },
    "condition": { "urlFilter": "||google.com/", "resourceTypes": ["main_frame"] }
  },
]

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

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

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

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

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

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

ตัวอย่างต่อไปนี้ใช้นิพจน์ทั่วไปเพื่อเปลี่ยนเส้นทางจาก https://www.abc.xyz.com/path ไปยัง https://abc.xyz.com/path ในคีย์ "regexFilter" ให้สังเกตการใช้ Escape กับจุด และให้กลุ่มการบันทึกเลือก "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) เดียวกันกับเฟรมที่สร้างคำขอนั้น

ค่าแจกแจง

"บุคคลที่หนึ่ง"
คำขอเครือข่ายเป็นบุคคลที่หนึ่งในเฟรมที่กำเนิด

"บุคคลที่สาม"
คำขอเครือข่ายเป็นบุคคลที่สามในเฟรมที่กำเนิด

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

  • ค่า

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

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

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

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

    "*" และ "?" สามารถใช้อักขระหลีกด้วยแบ็กสแลชได้ เช่น "\*" และ "\?"

HeaderOperation

Chrome เวอร์ชัน 86 ขึ้นไป

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

ค่าแจกแจง

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

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

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

IsRegexSupportedResult

Chrome เวอร์ชัน 87 ขึ้นไป

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

  • isSupported

    boolean

  • สาเหตุ

    UnsupportedRegexReason ไม่บังคับ

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

MatchedRule

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

  • ruleId

    ตัวเลข

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

  • rulesetId

    สตริง

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

MatchedRuleInfo

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

  • กฎ

    MatchedRule

  • tabId

    ตัวเลข

    TabId ของแท็บที่สร้างคำขอหากแท็บนั้นยังทำงานอยู่ อื่นๆ -1

  • timeStamp

    ตัวเลข

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

MatchedRuleInfoDebug

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

  • ส่งคำขอ

    RequestDetails

    รายละเอียดเกี่ยวกับคำขอที่มีการจับคู่กฎ

  • กฎ

    MatchedRule

MatchedRulesFilter

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

  • minTimeStamp

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

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

  • tabId

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

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

ModifyHeaderInfo

Chrome เวอร์ชัน 86 ขึ้นไป

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

  • ส่วนหัว

    สตริง

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

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

    HeaderOperation

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

  • value

    string ไม่บังคับ

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

QueryKeyValue

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

  • แป้น

    สตริง

  • replaceOnly

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

    Chrome 94 ขึ้นไป

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

  • value

    สตริง

QueryTransform

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

  • addOrReplaceParams

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

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

  • removeParams

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

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

Redirect

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

  • extensionPath

    string ไม่บังคับ

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

  • regexSubstitution

    string ไม่บังคับ

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

  • การเปลี่ยนรูปแบบ

    URLTransform ไม่บังคับ

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

  • URL

    string ไม่บังคับ

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

RegexOptions

Chrome เวอร์ชัน 87 ขึ้นไป

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

  • isCaseSensitive

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

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

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

    สตริง

    Expresson ปกติที่ต้องตรวจสอบ

  • requireCapturing

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

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

RequestDetails

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

  • documentId

    string ไม่บังคับ

    Chrome 106 ขึ้นไป

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

  • documentLifecycle

    DocumentLifecycle ไม่บังคับ

    Chrome 106 ขึ้นไป

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

  • frameId

    ตัวเลข

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

  • frameType

    FrameType ไม่บังคับ

    Chrome 106 ขึ้นไป

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

  • ผู้เริ่ม

    string ไม่บังคับ

    ต้นทางที่เริ่มต้นคำขอ โดยจะไม่เปลี่ยนแปลงผ่านการเปลี่ยนเส้นทาง หากเป็นต้นทางที่ไม่ชัดเจน สตริง "Null" จะถูกนำมาใช้

  • method

    สตริง

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

  • parentDocumentId

    string ไม่บังคับ

    Chrome 106 ขึ้นไป

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

  • parentFrameId

    ตัวเลข

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

  • requestId

    สตริง

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

  • tabId

    ตัวเลข

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

  • ประเภท

    ResourceType

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

  • URL

    สตริง

    URL ของคำขอ

RequestMethod

Chrome 91 ขึ้นไป

นโยบายนี้อธิบายวิธีคำขอ HTTP ของคำขอเครือข่าย

ค่าแจกแจง

"เชื่อมต่อ"

"ลบ"

"get"

"head"

"options"

"แพตช์"

"post"

"put"

"อื่นๆ"

ResourceType

ส่วนนี้อธิบายประเภททรัพยากรของคำขอเครือข่าย

ค่าแจกแจง

"main_frame"

"sub_frame"

"stylesheet"

"script"

"รูปภาพ"

"font"

"ออบเจ็กต์"

"xmlhttprequest"

"ping"

"csp_report"

"สื่อ"

"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 หนึ่งๆ

ค่าแจกแจง

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

  • excludedResourceTypes

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

    รายการประเภททรัพยากรที่กฎจะไม่ตรง ควรระบุ resourceTypes และ excludedResourceTypes เพียง 1 รายการเท่านั้น หากไม่ได้ระบุ 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

    string ไม่บังคับ

    นิพจน์ทั่วไปที่จะจับคู่กับ 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

    string ไม่บังคับ

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

    '*' : ไวลด์การ์ด: ตรงกับอักขระกี่ตัวก็ได้

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

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

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

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

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

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

    หมายเหตุ: สามารถระบุ urlFilter หรือ regexFilter ได้เพียงรายการเดียวเท่านั้น

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

Ruleset

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

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

    boolean

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

  • id

    สตริง

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

  • เส้นทาง

    สตริง

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

RulesMatchedDetails

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

  • rulesMatchedInfo

    MatchedRuleInfo[]

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

TabActionCountUpdate

Chrome เวอร์ชัน 89 ขึ้นไป

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

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

    ตัวเลข

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

  • tabId

    ตัวเลข

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

TestMatchOutcomeResult

Chrome 103 ขึ้นไป

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

  • matchedRules

    MatchedRule[]

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

TestMatchRequestDetails

Chrome 103 ขึ้นไป

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

  • ผู้เริ่ม

    string ไม่บังคับ

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

  • method

    RequestMethod ไม่บังคับ

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

  • responseHeaders

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

    รอดำเนินการ

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

    string ไม่บังคับ

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

  • ผู้จัด

    string ไม่บังคับ

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

  • รหัสผ่าน

    string ไม่บังคับ

    รหัสผ่านใหม่สำหรับคำขอ

  • เส้นทาง

    string ไม่บังคับ

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

  • พอร์ต

    string ไม่บังคับ

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

  • query

    string ไม่บังคับ

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

  • queryTransform

    QueryTransform ไม่บังคับ

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

  • สคีม

    string ไม่บังคับ

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

  • ชื่อผู้ใช้

    string ไม่บังคับ

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

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

DYNAMIC_RULESET_ID

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

ค่า

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

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

ค่า

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome เวอร์ชัน 89 ขึ้นไป

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

ค่า

30,000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

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

ค่า

24

MAX_NUMBER_OF_DYNAMIC_RULES

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

ค่า

30,000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94 ขึ้นไป

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

ค่า

50

MAX_NUMBER_OF_REGEX_RULES

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

ค่า

1,000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120 ขึ้นไป

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

ค่า

5,000

MAX_NUMBER_OF_STATIC_RULESETS

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

ค่า

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120 ขึ้นไป

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

ค่า

5,000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120 ขึ้นไป

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

ค่า

5,000

SESSION_RULESET_ID

Chrome 90 ขึ้นไป

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

ค่า

"_เซสชัน"

เมธอด

getAvailableStaticRuleCount()

สัญญา Chrome 89 ขึ้นไป 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
)

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

พารามิเตอร์

  • Callback

    ไม่บังคับ

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

    (count: number) => void

    • จำนวน

      ตัวเลข

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

  • Promise<number>

    Chrome 91 ขึ้นไป

    รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback

getDisabledRuleIds()

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

แสดงรายการกฎแบบคงที่ใน Ruleset ที่ปิดใช้อยู่

พารามิเตอร์

  • ตัวเลือก

    GetDisabledRuleIdsOptions

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

  • Callback

    ไม่บังคับ

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

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      ตัวเลข[]

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

  • คำสัญญา<จำนวน[]>

    รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback

getDynamicRules()

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

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

พารามิเตอร์

  • ตัวกรอง

    GetRulesFilter ไม่บังคับ

    Chrome 111 ขึ้นไป

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

  • Callback

    ไม่บังคับ

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

    (rules: Rule[]) => void

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

  • คำสัญญา<กฎ[]>

    Chrome 91 ขึ้นไป

    รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback

getEnabledRulesets()

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

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

พารามิเตอร์

  • Callback

    ไม่บังคับ

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

    (rulesetIds: string[]) => void

    • rulesetIds

      สตริง[]

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

  • Promise&lt;string[]&gt;

    Chrome 91 ขึ้นไป

    รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback

getMatchedRules()

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

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

พารามิเตอร์

  • ตัวกรอง

    MatchedRulesFilter ไม่บังคับ

    ออบเจ็กต์เพื่อกรองรายการกฎที่ตรงกัน

  • Callback

    ไม่บังคับ

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

    (details: RulesMatchedDetails) => void

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

  • Promise&lt;RulesMatchedDetails&gt;

    Chrome 91 ขึ้นไป

    รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback

getSessionRules()

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

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

พารามิเตอร์

  • ตัวกรอง

    GetRulesFilter ไม่บังคับ

    Chrome 111 ขึ้นไป

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

  • Callback

    ไม่บังคับ

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

    (rules: Rule[]) => void

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

  • คำสัญญา<กฎ[]>

    Chrome 91 ขึ้นไป

    รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback

isRegexSupported()

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

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

พารามิเตอร์

  • regexOptions

    RegexOptions

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

  • Callback

    ไม่บังคับ

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

    (result: IsRegexSupportedResult) => void

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

  • Promise&lt;IsRegexSupportedResult&gt;

    Chrome 91 ขึ้นไป

    รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback

setExtensionActionOptions()

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

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

พารามิเตอร์

  • ตัวเลือก

    ExtensionActionOptions

  • Callback

    ไม่บังคับ

    Chrome เวอร์ชัน 89 ขึ้นไป

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

    () => void

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

  • คำมั่นสัญญา<โมฆะ>

    Chrome 91 ขึ้นไป

    รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback

testMatchOutcome()

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

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

พารามิเตอร์

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

  • Promise&lt;TestMatchOutcomeResult&gt;

    รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback

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

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

  • คำมั่นสัญญา<โมฆะ>

    Chrome 91 ขึ้นไป

    รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback

updateEnabledRulesets()

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

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

พารามิเตอร์

  • ตัวเลือก

    UpdateRulesetOptions

    Chrome เวอร์ชัน 87 ขึ้นไป
  • Callback

    ไม่บังคับ

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

    () => void

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

  • คำมั่นสัญญา<โมฆะ>

    Chrome 91 ขึ้นไป

    รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback

updateSessionRules()

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

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

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

พารามิเตอร์

  • ตัวเลือก

    UpdateRuleOptions

  • Callback

    ไม่บังคับ

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

    () => void

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

  • คำมั่นสัญญา<โมฆะ>

    Chrome 91 ขึ้นไป

    รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback

updateStaticRules()

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

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

พารามิเตอร์

  • ตัวเลือก

    UpdateStaticRulesOptions

  • Callback

    ไม่บังคับ

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

    () => void

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

  • คำมั่นสัญญา<โมฆะ>

    รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback

กิจกรรม

onRuleMatchedDebug

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

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

พารามิเตอร์

  • Callback

    ฟังก์ชัน

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

    (info: MatchedRuleInfoDebug) => void