chrome.declarativeNetRequest

คำอธิบาย

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

สิทธิ์

declarativeNetRequest
declarativeNetRequestWithHostAccess

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

"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 ขณะใช้งานส่วนขยาย

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

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

หากต้องการเปิดหรือปิดใช้rulesetsแบบคงที่ ให้เรียกใช้ 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"]
  }
}

อักขระที่ตรงกัน urlFilter

คีย์ "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://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

การจัดลำดับความสำคัญของกฎ

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

1. ระบบจะพิจารณาลำดับความสำคัญสำหรับกฎภายในส่วนขยาย
2. หากมีส่วนขยายมากกว่า 1 รายการที่สามารถใช้กฎกับคำขอได้ ระบบจะจัดลำดับความสำคัญของส่วนขยายทั้งหมดที่ตรงกับคำขอนั้นๆ

เมื่อนึกถึงการจับคู่ในลักษณะนี้: กฎใดๆ ที่ส่วนขยายหนึ่งๆ ให้ความสำคัญจะได้รับการจัดลำดับความสำคัญมากกว่ากฎจากส่วนขยายอื่นๆ

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

การจัดลำดับความสำคัญของกฎภายในส่วนขยาย

การจัดลําดับความสําคัญภายในส่วนขยายเดียวจะทํางานโดยใช้กระบวนการต่อไปนี้

1. ระบบจะแสดงผลกฎที่มีลำดับความสำคัญสูงสุดที่นักพัฒนาแอปกำหนด (กล่าวคือ ช่อง "priority")

2. หากมีกฎมากกว่า 1 กฎที่มีลำดับความสำคัญสูงสุดที่กำหนดโดยนักพัฒนาซอฟต์แวร์ ระบบจะจัดลำดับความสำคัญให้กับกฎโดยใช้ช่อง "action" ในลำดับต่อไปนี้

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

3. หากประเภทการดำเนินการไม่ใช่ block หรือ redirect ระบบจะประเมินกฎ modifyHeaders ทั้งหมดที่ตรงกัน โปรดทราบว่าหากมีกฎที่มีลำดับความสำคัญที่นักพัฒนาแอปกำหนดต่ำกว่าลำดับความสำคัญที่ระบุไว้สำหรับ allow และ allowAllRequests ระบบจะไม่สนใจกฎดังกล่าว

4. หากกฎหลายข้อแก้ไขส่วนหัวเดียวกัน การแก้ไขจะกำหนดโดยช่อง "priority" ที่นักพัฒนาแอปกำหนดและโดยการดำเนินการที่ระบุ

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

การจัดลำดับความสำคัญของกฎระหว่างส่วนขยาย

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

1. ระบบจะจัดลําดับความสําคัญของกฎโดยใช้ช่อง "action" ในลําดับต่อไปนี้

   1. block
   2. redirect หรือ upgradeScheme
   3. allow หรือ allowAllRequests

2. หากมีกฎที่ตรงกันมากกว่า 1 ข้อ ส่วนขยายที่ติดตั้งล่าสุดจะมีลำดับความสำคัญสูงกว่า

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

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

กฎแบบคงที่

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

หมายเหตุ: ก่อนที่จะมี Chrome 120 ส่วนขยายจะจํากัดไว้ที่ชุดกฎแบบคงที่ทั้งหมด 50 ชุด และเปิดใช้งานพร้อมกันได้เพียง 10 ชุดเท่านั้น ใช้ช่องไฟล์ Manifest minimum_chrome_version เพื่อจำกัดเวอร์ชันของ Chrome ที่ติดตั้งส่วนขยายได้

จำนวนกฎที่ใช้ได้หลังจากนั้นจะขึ้นอยู่กับจำนวนกฎที่เปิดใช้งานโดยส่วนขยายทั้งหมดที่ติดตั้งในเบราว์เซอร์ของผู้ใช้ คุณจะหาหมายเลขนี้ได้ขณะรันไทม์โดยโทรไปที่ 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 กฎที่ปลอดภัยหมายถึงกฎที่มีการดำเนินการ block, allow, allowAllRequests หรือ upgradeScheme กฎที่ไม่ปลอดภัยซึ่งเพิ่มภายในช่วงขีดจำกัด 5,000 รายการจะนับรวมอยู่ในขีดจำกัดนี้ด้วย

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

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

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

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

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 จะไม่ส่งผลต่อการตอบกลับที่โปรแกรมทำงานของบริการสร้างขึ้นหรือที่ดึงมาจาก CacheStorage แต่จะส่งผลต่อการเรียกใช้ fetch() ที่เกิดขึ้นในโปรแกรมทำงานของบริการ

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

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

ตัวอย่าง

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

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

ตัวอย่างต่อไปนี้แสดงวิธีเรียกใช้ 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" ให้สังเกตวิธีการซ่อนจุด และกลุ่มการบันทึกจะเลือก "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

  string

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

GetRulesFilter

Chrome 111 ขึ้นไป

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

• ruleIds

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

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

HeaderOperation

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

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

ค่าแจกแจง

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

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

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

IsRegexSupportedResult

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

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

• isSupported

  boolean

• สาเหตุ

  UnsupportedRegexReason ไม่บังคับ

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

MatchedRule

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

• ruleId

  ตัวเลข

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

• rulesetId

  string

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

MatchedRuleInfo

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

• กฎ

  MatchedRule

• tabId

  ตัวเลข

  รหัสแท็บของแท็บที่เป็นแหล่งที่มาของคำขอในกรณีที่แท็บนั้นยังทำงานอยู่ อื่นๆ -1

• timeStamp

  ตัวเลข

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

MatchedRuleInfoDebug

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

• ส่งคำขอ

  RequestDetails

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

• กฎ

  MatchedRule

MatchedRulesFilter

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

• minTimeStamp

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

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

• tabId

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

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

ModifyHeaderInfo

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

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

• ส่วนหัว

  string

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

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

  HeaderOperation

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

• value

  string ไม่บังคับ

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

QueryKeyValue

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

• แป้น

  string

• replaceOnly

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

  Chrome 94 ขึ้นไป

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

• value

  string

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 ที่ระบุคำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่หรือไม่ ค่าเริ่มต้นคือ จริง

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

  string

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

• 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

  string

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

• parentDocumentId

  string ไม่บังคับ

  Chrome 106 ขึ้นไป

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

• parentFrameId

  ตัวเลข

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

• requestId

  string

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

• tabId

  ตัวเลข

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

• ประเภท

  ResourceType

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

• url

  string

  URL ของคำขอ

RequestMethod

Chrome 91 ขึ้นไป

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

ค่าแจกแจง

ResourceType

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

ค่าแจกแจง

"script"

"xmlhttprequest"

"ping"

"csp_report"

"webtransport"

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

• excludedResourceTypes

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

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

• 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 ได้เพียง 1 รายการเท่านั้น

  หมายเหตุ: 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

• tabIds

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

  Chrome 92 ขึ้นไป

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

• urlFilter

  string ไม่บังคับ

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

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

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

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

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

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

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

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

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

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

Ruleset

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

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

  boolean

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

• id

  string

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

• เส้นทาง

  string

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

RulesMatchedDetails

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

• rulesMatchedInfo

  MatchedRuleInfo[]

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

TabActionCountUpdate

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

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

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

  ตัวเลข

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

• tabId

  ตัวเลข

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

TestMatchOutcomeResult

Chrome 103 ขึ้นไป

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

• matchedRules

  MatchedRule[]

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

TestMatchRequestDetails

Chrome 103 ขึ้นไป

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

• ผู้เริ่ม

  string ไม่บังคับ

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

• method

  RequestMethod ไม่บังคับ

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

• tabId

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

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

• ประเภท

  ResourceType

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

• url

  string

  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

  string

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

URLTransform

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

• Fragment

  string ไม่บังคับ

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

• ผู้จัด

  string ไม่บังคับ

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

• รหัสผ่าน

  string ไม่บังคับ

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

• เส้นทาง

  string ไม่บังคับ

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

• พอร์ต

  string ไม่บังคับ

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

• query

  string ไม่บังคับ

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

• queryTransform

  QueryTransform ไม่บังคับ

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

• สคีม

  string ไม่บังคับ

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

• ชื่อผู้ใช้

  string ไม่บังคับ

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

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

DYNAMIC_RULESET_ID

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

ค่า

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

ค่า

20

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

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

ค่า

"_session"

วิธีการ

getAvailableStaticRuleCount()

คำมั่นสัญญา Chrome เวอร์ชัน 89 ขึ้นไป

chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
)

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

พารามิเตอร์

• Callback

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

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

  (count: number)=>void

  • จำนวน

    ตัวเลข

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

• คำมั่นสัญญา<number>

  Chrome 91 ขึ้นไป

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

getDisabledRuleIds()

คำมั่นสัญญา Chrome 111 ขึ้นไป

chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
  callback?: function,
)

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

พารามิเตอร์

• ตัวเลือก

  GetDisabledRuleIdsOptions

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

• Callback

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

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

  (disabledRuleIds: number[])=>void

  • disabledRuleIds

    ตัวเลข[]

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

• คำสัญญา<number[]>

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

getDynamicRules()

สัญญา

chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
  callback?: function,
)

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

พารามิเตอร์

• ฟิลเตอร์

  GetRulesFilter ไม่บังคับ

  Chrome 111 ขึ้นไป

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

• Callback

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

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

  (rules: Rule[])=>void

  • กฎ

    กฎ[]

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

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

  Chrome 91 ขึ้นไป

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

getEnabledRulesets()

สัญญา

chrome.declarativeNetRequest.getEnabledRulesets(
  callback?: function,
)

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

พารามิเตอร์

• Callback

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

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

  (rulesetIds: string[])=>void

  • rulesetIds

    สตริง[]

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

• คำสัญญา<string[]>

  Chrome 91 ขึ้นไป

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

getMatchedRules()

สัญญา

chrome.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
  callback?: function,
)

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

พารามิเตอร์

• ฟิลเตอร์

  MatchedRulesFilter ไม่บังคับ

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

• Callback

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

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

  (details: RulesMatchedDetails)=>void

  • รายละเอียด

    RulesMatchedDetails

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

• Promise<RulesMatchedDetails>

  Chrome 91 ขึ้นไป

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

getSessionRules()

คำมั่นสัญญา Chrome 90 ขึ้นไป

chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
  callback?: function,
)

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

พารามิเตอร์

• ฟิลเตอร์

  GetRulesFilter ไม่บังคับ

  Chrome 111 ขึ้นไป

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

• Callback

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

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

  (rules: Rule[])=>void

  • กฎ

    กฎ[]

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

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

  Chrome 91 ขึ้นไป

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

isRegexSupported()

คำมั่นสัญญา Chrome เวอร์ชัน 87 ขึ้นไป

chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
  callback?: function,
)

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

พารามิเตอร์

• regexOptions

  RegexOptions

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

• Callback

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

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

  (result: IsRegexSupportedResult)=>void

  • ผลลัพธ์

    IsRegexSupportedResult

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

• Promise<IsRegexSupportedResult>

  Chrome 91 ขึ้นไป

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

setExtensionActionOptions()

คำมั่นสัญญา Chrome เวอร์ชัน 88 ขึ้นไป

chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
  callback?: function,
)

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

พารามิเตอร์

• ตัวเลือก

  ExtensionActionOptions

• Callback

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

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

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

  ()=>void

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

• Promise<void>

  Chrome 91 ขึ้นไป

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

testMatchOutcome()

คำมั่นสัญญา Chrome 103 ขึ้นไป

chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
)

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

พารามิเตอร์

• ส่งคำขอ

  TestMatchRequestDetails

• Callback

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

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

  (result: TestMatchOutcomeResult)=>void

  • ผลลัพธ์

    TestMatchOutcomeResult

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

• Promise<TestMatchOutcomeResult>

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

updateDynamicRules()

สัญญา

chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
  callback?: function,
)

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

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

พารามิเตอร์

• ตัวเลือก

  UpdateRuleOptions

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

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

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

  ()=>void

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

• Promise<void>

  Chrome 91 ขึ้นไป

  Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 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 V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

updateSessionRules()

คำมั่นสัญญา Chrome 90 ขึ้นไป

chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
  callback?: function,
)

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

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

พารามิเตอร์

• ตัวเลือก

  UpdateRuleOptions

• Callback

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

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

  ()=>void

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

• Promise<void>

  Chrome 91 ขึ้นไป

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

updateStaticRules()

คำมั่นสัญญา Chrome 111 ขึ้นไป

chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
  callback?: function,
)

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

พารามิเตอร์

• ตัวเลือก

  UpdateStaticRulesOptions

• Callback

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

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

  ()=>void

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

• Promise<void>

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

กิจกรรม

onRuleMatchedDebug

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

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

พารามิเตอร์

• Callback

  ฟังก์ชัน

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

  (info: MatchedRuleInfoDebug)=>void

  • ข้อมูล

    MatchedRuleInfoDebug