คำอธิบาย
chrome.declarativeNetRequest
API ใช้เพื่อบล็อกหรือแก้ไขคำขอเครือข่ายด้วยการระบุกฎการประกาศ วิธีนี้ช่วยให้ส่วนขยายแก้ไขคำขอเครือข่ายได้โดยไม่ต้องสกัดกั้นและดูเนื้อหาของตน ดังนั้นจึงให้ความเป็นส่วนตัวมากขึ้น
สิทธิ์
declarativeNetRequest
declarativeNetRequestWithHostAccess
declarativeNetRequestFeedback
host_permissions
ความพร้อมใช้งาน
ไฟล์ 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
หากต้องการเปิดหรือปิดใช้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 รายการที่สามารถใช้กฎกับคำขอ ระบบจะกำหนดลำดับความสำคัญของส่วนขยายทั้งหมดที่ตรงกับคำขอหนึ่งๆ
ให้นึกถึงการจับคู่ในลักษณะนี้: กฎใดก็ตามที่ส่วนขยายหนึ่งๆ ให้ความสำคัญจะได้รับการจัดลำดับความสำคัญเทียบกับกฎจากส่วนขยายอื่นๆ
การจัดลำดับความสำคัญของกฎภายในส่วนขยาย
ภายในส่วนขยายเดียว การจัดลำดับความสำคัญจะดำเนินการโดยใช้กระบวนการต่อไปนี้
- ระบบจะแสดงผลกฎที่มีลำดับความสำคัญสูงสุดตามที่นักพัฒนาแอปกำหนด (กล่าวคือ ช่อง
"priority"
) หากมีกฎมากกว่า 1 กฎที่มีลำดับความสำคัญสูงสุดตามที่นักพัฒนาแอปกำหนด ระบบจะจัดลำดับความสำคัญของกฎโดยใช้ช่อง
"action"
ตามลำดับต่อไปนี้allow
allowAllRequests
block
upgradeScheme
redirect
หากประเภทการดำเนินการไม่ใช่
block
หรือredirect
ระบบจะประเมินกฎmodifyHeaders
ที่ตรงกัน โปรดทราบว่าหากมีกฎที่มีลำดับความสำคัญที่นักพัฒนาแอปกำหนดต่ำกว่าลำดับความสำคัญที่ระบุไว้สำหรับallow
และallowAllRequests
ระบบจะไม่สนใจกฎดังกล่าวหากมีกฎหลายข้อแก้ไขส่วนหัวเดียวกัน การแก้ไขจะกำหนดโดยช่อง
"priority"
ที่นักพัฒนาแอปกำหนดและการดำเนินการที่ระบุ- หากกฎเพิ่มต่อท้ายส่วนหัว กฎที่มีลำดับความสำคัญต่ำกว่าจะสามารถต่อท้ายส่วนหัวได้เท่านั้น ไม่อนุญาตให้ตั้งค่าและนำออก
- หากกฎกำหนดส่วนหัว กฎที่มีลำดับความสำคัญต่ำกว่าจะสามารถต่อท้ายส่วนหัวดังกล่าวได้เท่านั้น โดยไม่อนุญาตให้มีการแก้ไขอื่นๆ
- หากกฎนำส่วนหัวออก กฎที่มีลำดับความสำคัญต่ำกว่าจะแก้ไขส่วนหัวไม่ได้อีก
ลำดับความสำคัญของกฎระหว่างส่วนขยาย
หากมีส่วนขยายเพียงรายการเดียวที่มีกฎที่ตรงกับคำขอ ระบบจะใช้กฎนั้น แต่หากมีส่วนขยายมากกว่า 1 รายการที่ตรงกับคำขอ จะใช้กระบวนการต่อไปนี้
ระบบจะจัดลำดับความสำคัญของกฎโดยใช้ช่อง
"action"
ตามลำดับต่อไปนี้block
redirect
หรือupgradeScheme
allow
หรือallowAllRequests
หากมีกฎที่ตรงกันมากกว่า 1 ข้อ ส่วนขยายที่ติดตั้งล่าสุดจะมีลำดับความสำคัญสูงกว่า
ขีดจํากัดของกฎ
การโหลดและการประเมินกฎในเบราว์เซอร์จะมีโอเวอร์เฮดประสิทธิภาพ ทำให้มีขีดจำกัดบางอย่างเมื่อใช้ API โดยขีดจำกัดจะขึ้นอยู่กับประเภทของกฎที่คุณกำลังใช้
กฎแบบคงที่
กฎแบบคงที่คือกฎที่ระบุไว้ในไฟล์กฎที่ประกาศในไฟล์ Manifest ส่วนขยายสามารถระบุrulesetsแบบคงที่ได้สูงสุด 50 รายการเป็นส่วนหนึ่งของคีย์ไฟล์ Manifest "rule_resources"
แต่จะเปิดใช้ชุดกฎได้ครั้งละ 10 ชุดเท่านั้น แบบหลังจะเรียกว่า MAX_NUMBER_OF_ENABLED_STATIC_RULESETS
ชุดกฎเหล่านี้รวมกันแล้วมีการรับประกันอย่างน้อย 30,000 กฎ ซึ่งเรียกว่า GUARANTEED_MINIMUM_STATIC_RULES
จำนวนกฎที่ใช้ได้หลังจากนั้นจะขึ้นอยู่กับจำนวนกฎที่เปิดใช้งานโดยส่วนขยายทั้งหมดที่ติดตั้งในเบราว์เซอร์ของผู้ใช้ คุณดูหมายเลขนี้ระหว่างรันไทม์ได้โดยการโทรหา getAvailableStaticRuleCount()
ดูตัวอย่างนี้ได้ในส่วนตัวอย่างโค้ด
กฎแบบไดนามิกและกฎเซสชัน
ขีดจำกัดที่ใช้กับกฎแบบไดนามิกและกฎเซสชันจะง่ายกว่ากฎแบบคงที่ จำนวนรวมทั้งหมดต้องไม่เกิน 5,000 ซึ่งเรียกว่า MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES
กฎที่ใช้นิพจน์ทั่วไป
กฎทุกประเภทสามารถใช้นิพจน์ทั่วไปได้ แต่จำนวนกฎ regex ทั้งหมดของแต่ละประเภทต้องไม่เกิน 1000 ซึ่งเรียกว่า MAX_NUMBER_OF_REGEX_RULES
นอกจากนี้ กฎแต่ละข้อจะต้องมีขนาดไม่เกิน 2 KB เมื่อคอมไพล์แล้ว ซึ่งจะสัมพันธ์กับความซับซ้อนของกฎโดยคร่าวๆ หากพยายามโหลดกฎที่เกินขีดจำกัดนี้ คุณจะเห็นคำเตือนที่มีลักษณะเหมือนคำเตือนด้านล่าง และระบบจะไม่สนใจกฎนั้น
rules_1.json: Rule with id 1 specified a more complext regex than allowed
as part of the "regexFilter" key.
การโต้ตอบกับ Service Worker
declarativeNetRequest ใช้กับคำขอที่เข้าถึงสแต็กเครือข่ายเท่านั้น ซึ่งรวมถึงการตอบกลับจากแคช HTTP แต่อาจไม่รวมการตอบกลับที่ส่งผ่านเครื่องจัดการ onfetch
ของ Service Worker ด้วย declarativeNetRequest จะไม่ส่งผลต่อการตอบสนองที่โปรแกรมทำงานของบริการสร้างขึ้นหรือที่ดึงมาจาก CacheStorage
แต่จะส่งผลต่อการเรียกใช้ fetch()
ที่ดำเนินการใน Service Worker
แหล่งข้อมูลที่เข้าถึงได้บนเว็บ
กฎ 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"
ให้สังเกตการใช้ 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
พร็อพเพอร์ตี้
-
displayActionCountAsBadgeText
บูลีน ไม่บังคับ
เลือกว่าจะแสดงจำนวนการดำเนินการของหน้าเว็บเป็นข้อความป้ายของส่วนขยายโดยอัตโนมัติหรือไม่ ค่ากำหนดนี้จะคงอยู่ในเซสชันต่างๆ
-
tabUpdate
TabActionCountUpdate ไม่บังคับ
Chrome เวอร์ชัน 89 ขึ้นไปรายละเอียดเกี่ยวกับวิธีปรับจำนวนการดำเนินการของแท็บ
GetDisabledRuleIdsOptions
พร็อพเพอร์ตี้
-
rulesetId
string
รหัสที่ตรงกับ
Ruleset
แบบคงที่
GetRulesFilter
พร็อพเพอร์ตี้
-
ruleIds
number[] ไม่บังคับ
หากระบุไว้ ระบบจะรวมเฉพาะกฎที่มีรหัสตรงกัน
HeaderOperation
ซึ่งอธิบายการดำเนินการที่เป็นไปได้สำหรับกฎ "modifyHeaders"
ค่าแจกแจง
"append"
เพิ่มรายการใหม่สำหรับส่วนหัวที่ระบุ การดำเนินการนี้ไม่รองรับส่วนหัวของคำขอ
"set"
กำหนดค่าใหม่สำหรับส่วนหัวที่ระบุ โดยนำส่วนหัวที่มีอยู่ชื่อเดียวกันออก
"remove"
ลบรายการทั้งหมดสำหรับส่วนหัวที่ระบุ
IsRegexSupportedResult
พร็อพเพอร์ตี้
-
isSupported
boolean
-
สาเหตุ
UnsupportedRegexReason ไม่บังคับ
ระบุเหตุผลที่ไม่รองรับนิพจน์ทั่วไป ระบุเฉพาะในกรณีที่
isSupported
เป็นเท็จ
MatchedRule
พร็อพเพอร์ตี้
-
ruleId
ตัวเลข
รหัสของกฎที่ตรงกัน
-
rulesetId
string
รหัสของ
Ruleset
กฎนี้ สำหรับกฎที่เกิดจากชุดกฎแบบไดนามิก ค่านี้จะเท่ากับDYNAMIC_RULESET_ID
MatchedRuleInfo
พร็อพเพอร์ตี้
-
กฎ
-
tabId
ตัวเลข
TabId ของแท็บที่สร้างคำขอหากแท็บนั้นยังทำงานอยู่ อื่นๆ -1
-
timeStamp
ตัวเลข
เวลาที่ตรงกับกฎ การประทับเวลาจะสอดคล้องกับข้อตกลง JavaScript สำหรับเวลา ซึ่งก็คือจำนวนมิลลิวินาทีตั้งแต่ Epoch
MatchedRuleInfoDebug
พร็อพเพอร์ตี้
-
ส่งคำขอ
รายละเอียดเกี่ยวกับคำขอที่มีการจับคู่กฎ
-
กฎ
MatchedRulesFilter
พร็อพเพอร์ตี้
-
minTimeStamp
หมายเลข ไม่บังคับ
หากระบุ จะจับคู่กฎหลังจากการประทับเวลาที่ระบุเท่านั้น
-
tabId
หมายเลข ไม่บังคับ
หากระบุไว้ จะจับคู่เฉพาะกฎของแท็บที่ระบุ จับคู่กฎที่ไม่เชื่อมโยงกับแท็บที่ใช้งานอยู่ใดๆ หากตั้งค่าเป็น -1
ModifyHeaderInfo
พร็อพเพอร์ตี้
-
ส่วนหัว
string
ชื่อของส่วนหัวที่จะแก้ไข
-
การดำเนินการ
การดำเนินการที่จะดำเนินการในส่วนหัว
-
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
พร็อพเพอร์ตี้
-
isCaseSensitive
บูลีน ไม่บังคับ
regex
ที่ระบุคำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่หรือไม่ ค่าเริ่มต้นเป็น True -
นิพจน์ทั่วไป
string
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
string
เมธอด HTTP มาตรฐาน
-
parentDocumentId
string ไม่บังคับ
Chrome 106 ขึ้นไปตัวระบุที่ไม่ซ้ำกันสำหรับเอกสารระดับบนสุดของเฟรม หากเป็นคำขอนี้สำหรับเฟรมและมีระดับบนสุด
-
parentFrameId
ตัวเลข
รหัสเฟรมที่รวมเฟรมที่ส่งคำขอ หากไม่มีเฟรมหลัก ให้ตั้งค่าเป็น -1
-
requestId
string
รหัสของคำขอ รหัสคำขอจะไม่ซ้ำกันภายในเซสชันของเบราว์เซอร์หนึ่งๆ
-
tabId
ตัวเลข
รหัสของแท็บที่มีคำขอ ตั้งค่าเป็น -1 หากคำขอไม่เกี่ยวข้องกับแท็บ
-
ประเภท
ประเภททรัพยากรของคำขอ
-
url
string
URL ของคำขอ
RequestMethod
นโยบายนี้อธิบายวิธีคำขอ HTTP ของคำขอเครือข่าย
ค่าแจกแจง
"get"
"head"
"options"
"post"
"put"
ResourceType
ส่วนนี้อธิบายประเภททรัพยากรของคำขอเครือข่าย
ค่าแจกแจง
"main_frame"
"sub_frame"
"stylesheet"
"script"
"font"
"xmlhttprequest"
"ping"
"csp_report"
"websocket"
"webtransport"
"webbundle"
Rule
พร็อพเพอร์ตี้
-
การดำเนินการ
การดำเนินการที่ต้องทำหากมีการจับคู่กฎนี้แล้ว
-
เงื่อนไข
เงื่อนไขที่กฎนี้เรียกใช้
-
id
ตัวเลข
รหัสที่ระบุกฎโดยไม่ซ้ำกัน บังคับและควรมากกว่าหรือเท่ากับ 1
-
ลำดับความสำคัญ
หมายเลข ไม่บังคับ
ลำดับความสำคัญของกฎ ค่าเริ่มต้นคือ 1 เมื่อระบุ ค่าควรเป็น >= 1
RuleAction
พร็อพเพอร์ตี้
-
เปลี่ยนเส้นทาง
เปลี่ยนเส้นทาง ไม่บังคับ
อธิบายวิธีการเปลี่ยนเส้นทาง ใช้ได้กับกฎการเปลี่ยนเส้นทางเท่านั้น
-
requestHeaders
ModifyHeaderInfo[] ไม่บังคับ
Chrome เวอร์ชัน 86 ขึ้นไปส่วนหัวของคำขอที่จะแก้ไขสำหรับคำขอ ใช้ได้เฉพาะเมื่อ RuleActionType เป็น "modifyHeaders"
-
responseHeaders
ModifyHeaderInfo[] ไม่บังคับ
Chrome เวอร์ชัน 86 ขึ้นไปส่วนหัวการตอบกลับที่ต้องแก้ไขสำหรับคำขอ ใช้ได้เฉพาะเมื่อ RuleActionType เป็น "modifyHeaders"
-
ประเภท
ประเภทของการดำเนินการ
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" -
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
-
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
string
สตริงที่ไม่ว่างเปล่าซึ่งสามารถระบุชุดกฎโดยไม่ซ้ำกัน รหัสที่ขึ้นต้นด้วย "_" สงวนไว้สำหรับการใช้งานภายใน
-
เส้นทาง
string
เส้นทางของชุดกฎ JSON ที่สัมพันธ์กับไดเรกทอรีส่วนขยาย
RulesMatchedDetails
พร็อพเพอร์ตี้
-
rulesMatchedInfo
กฎที่ตรงกับตัวกรองที่ระบุ
TabActionCountUpdate
พร็อพเพอร์ตี้
-
การเพิ่มขึ้น
ตัวเลข
จำนวนที่จะเพิ่มจำนวนการทำงานของแท็บตาม ค่าติดลบจะลดจำนวนลง
-
tabId
ตัวเลข
แท็บที่จะอัปเดตจำนวนการดำเนินการ
TestMatchOutcomeResult
พร็อพเพอร์ตี้
-
matchedRules
กฎ (หากมี) ที่ตรงกับคำขอสมมติ
TestMatchRequestDetails
พร็อพเพอร์ตี้
-
ผู้เริ่ม
string ไม่บังคับ
URL ของตัวเริ่ม (หากมี) สำหรับคำขอสมมติ
-
method
RequestMethod ไม่บังคับ
เมธอด HTTP มาตรฐานของคำขอสมมติ ค่าเริ่มต้นจะเป็น "get" สำหรับคำขอ HTTP และละเว้นสำหรับคำขอที่ไม่ใช่ HTTP
-
tabId
หมายเลข ไม่บังคับ
รหัสของแท็บที่มีคำขอสมมติ ไม่จำเป็นต้องสอดคล้องกับรหัสแท็บจริง ค่าเริ่มต้นคือ -1 หมายความว่าคำขอไม่เกี่ยวข้องกับแท็บ
-
ประเภท
ประเภททรัพยากรของคำขอสมมติ
-
url
string
URL ของคำขอสมมติ
UnsupportedRegexReason
อธิบายเหตุผลที่ไม่รองรับนิพจน์ทั่วไปที่กำหนด
ค่าแจกแจง
"syntaxError"
นิพจน์ทั่วไปไม่ถูกต้องตามไวยากรณ์ หรือใช้ฟีเจอร์ที่ไม่มีในไวยากรณ์ RE2
"memoryLimitExceeded"
นิพจน์ทั่วไปเกินขีดจำกัดหน่วยความจำ
UpdateRuleOptions
พร็อพเพอร์ตี้
-
addRules
กฎ[] ไม่บังคับ
กฎที่ควรเพิ่ม
-
removeRuleIds
number[] ไม่บังคับ
รหัสของกฎที่จะนำออก ระบบจะไม่สนใจรหัสที่ไม่ถูกต้อง
UpdateRulesetOptions
พร็อพเพอร์ตี้
UpdateStaticRulesOptions
พร็อพเพอร์ตี้
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
จำนวนกฎแบบคงที่ขั้นต่ำที่รับประกันไปยังส่วนขยายในชุดกฎแบบคงที่ที่เปิดใช้ กฎใดๆ ก็ตามที่มีขีดจำกัดนี้จะนับรวมในขีดจำกัดกฎแบบคงที่โดยรวม
ค่า
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
จำนวนสูงสุดของ Rulesets
แบบคงที่ที่ส่วนขยายเปิดใช้ได้ต่อครั้ง
ค่า
50
MAX_NUMBER_OF_REGEX_RULES
จำนวนกฎนิพจน์ทั่วไปสูงสุดที่ส่วนขยายเพิ่มได้ ระบบจะประเมินขีดจำกัดนี้แยกกันสำหรับชุดกฎแบบไดนามิกและขีดจำกัดที่ระบุไว้ในไฟล์ทรัพยากรกฎ
ค่า
1,000
MAX_NUMBER_OF_SESSION_RULES
จำนวนกฎที่มีขอบเขตเซสชันสูงสุดที่ส่วนขยายเพิ่มได้
ค่า
5,000
MAX_NUMBER_OF_STATIC_RULESETS
จำนวนสูงสุดของ Rulesets
แบบคงที่ที่ส่วนขยายระบุให้เป็นส่วนหนึ่งของคีย์ไฟล์ Manifest ของ "rule_resources"
ได้
ค่า
100
MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES
จำนวนกฎแบบไดนามิกที่ "ไม่ปลอดภัย" สูงสุดที่ส่วนขยายเพิ่มได้
ค่า
5,000
MAX_NUMBER_OF_UNSAFE_SESSION_RULES
จำนวนกฎที่มีขอบเขตเซสชัน "ไม่ปลอดภัย" สูงสุดที่ส่วนขยายเพิ่มได้
ค่า
5,000
SESSION_RULESET_ID
รหัสชุดกฎสำหรับกฎที่มีขอบเขตระดับเซสชันที่เพิ่มโดยส่วนขยาย
ค่า
วิธีการ
getAvailableStaticRuleCount()
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
callback?: function,
)
แสดงผลจำนวนกฎแบบคงที่ที่ส่วนขยายเปิดใช้ได้ก่อนที่จะถึงขีดจำกัดกฎแบบคงที่โดยรวม
พารามิเตอร์
-
Callback
ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้(count: number) => void
-
จำนวน
ตัวเลข
-
การคืนสินค้า
-
คำมั่นสัญญา<จำนวน>
Chrome 91 ขึ้นไปPromise รองรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้ Callback
getDisabledRuleIds()
chrome.declarativeNetRequest.getDisabledRuleIds(
options: GetDisabledRuleIdsOptions,
callback?: function,
)
แสดงรายการกฎแบบคงที่ใน Ruleset
ที่ปิดใช้อยู่
พารามิเตอร์
-
ตัวเลือก
ระบุชุดกฎที่จะค้นหา
-
Callback
ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้(disabledRuleIds: number[]) => void
-
disabledRuleIds
ตัวเลข[]
-
การคืนสินค้า
-
คำสัญญา<จำนวน[]>
Promise รองรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้ Callback
getDynamicRules()
chrome.declarativeNetRequest.getDynamicRules(
filter?: GetRulesFilter,
callback?: function,
)
แสดงผลกฎแบบไดนามิกชุดปัจจุบันสำหรับส่วนขยาย ผู้โทรจะกรองรายการกฎที่ดึงข้อมูลได้โดยการระบุ filter
พารามิเตอร์
-
ฟิลเตอร์
GetRulesFilter ไม่บังคับ
Chrome 111 ขึ้นไปออบเจ็กต์สำหรับกรองรายการกฎที่ดึงข้อมูล
-
Callback
ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้(rules: Rule[]) => void
-
กฎ
กฎ[]
-
การคืนสินค้า
-
คำสัญญา<กฎ[]>
Chrome 91 ขึ้นไปPromise รองรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้ Callback
getEnabledRulesets()
chrome.declarativeNetRequest.getEnabledRulesets(
callback?: function,
)
แสดงผลรหัสสำหรับชุดกฎแบบคงที่ที่เปิดใช้ในปัจจุบัน
พารามิเตอร์
-
Callback
ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้(rulesetIds: string[]) => void
-
rulesetIds
สตริง[]
-
การคืนสินค้า
-
คำสัญญา<สตริง[]>
Chrome 91 ขึ้นไปPromise รองรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้ Callback
getMatchedRules()
chrome.declarativeNetRequest.getMatchedRules(
filter?: MatchedRulesFilter,
callback?: function,
)
แสดงกฎทั้งหมดที่ตรงกันสำหรับส่วนขยาย ผู้โทรอาจเลือกกรองรายการกฎที่ตรงกันโดยระบุ filter
ก็ได้ วิธีนี้ใช้ได้เฉพาะกับส่วนขยายที่มีสิทธิ์ "declarativeNetRequestFeedback"
หรือมีสิทธิ์ "activeTab"
สำหรับ tabId
ที่ระบุใน filter
หมายเหตุ: กฎที่ไม่ได้เชื่อมโยงกับเอกสารที่ใช้งานอยู่ซึ่งมีการจับคู่เกิน 5 นาทีแล้วจะไม่ถูกส่งคืน
พารามิเตอร์
-
ฟิลเตอร์
MatchedRulesFilter ไม่บังคับ
ออบเจ็กต์เพื่อกรองรายการกฎที่ตรงกัน
-
Callback
ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้(details: RulesMatchedDetails) => void
-
รายละเอียด
-
การคืนสินค้า
-
Promise<RulesMatchedDetails>
Chrome 91 ขึ้นไปPromise รองรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้ Callback
getSessionRules()
chrome.declarativeNetRequest.getSessionRules(
filter?: GetRulesFilter,
callback?: function,
)
จะแสดงผลชุดกฎที่กำหนดขอบเขตระดับเซสชันปัจจุบันสำหรับส่วนขยาย ผู้โทรจะกรองรายการกฎที่ดึงข้อมูลได้โดยการระบุ filter
พารามิเตอร์
-
ฟิลเตอร์
GetRulesFilter ไม่บังคับ
Chrome 111 ขึ้นไปออบเจ็กต์สำหรับกรองรายการกฎที่ดึงข้อมูล
-
Callback
ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้(rules: Rule[]) => void
-
กฎ
กฎ[]
-
การคืนสินค้า
-
คำสัญญา<กฎ[]>
Chrome 91 ขึ้นไปPromise รองรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้ Callback
isRegexSupported()
chrome.declarativeNetRequest.isRegexSupported(
regexOptions: RegexOptions,
callback?: function,
)
ตรวจสอบว่าระบบจะรองรับนิพจน์ทั่วไปที่ระบุเป็นเงื่อนไขของกฎ regexFilter
หรือไม่
พารามิเตอร์
-
regexOptions
นิพจน์ทั่วไปที่จะตรวจสอบ
-
Callback
ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้(result: IsRegexSupportedResult) => void
-
ผลลัพธ์
-
การคืนสินค้า
-
Promise<IsRegexSupportedResult>
Chrome 91 ขึ้นไปPromise รองรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้ Callback
setExtensionActionOptions()
chrome.declarativeNetRequest.setExtensionActionOptions(
options: ExtensionActionOptions,
callback?: function,
)
กำหนดค่าว่าจำนวนการดำเนินการของแท็บควรแสดงเป็นข้อความป้ายของการดำเนินการของส่วนขยายหรือไม่ และระบุวิธีเพิ่มจำนวนการดำเนินการดังกล่าว
พารามิเตอร์
-
ตัวเลือก
-
Callback
ไม่บังคับ
Chrome เวอร์ชัน 89 ขึ้นไปพารามิเตอร์
callback
มีลักษณะดังนี้() => void
การคืนสินค้า
-
Promise<void>
Chrome 91 ขึ้นไปPromise รองรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้ Callback
testMatchOutcome()
chrome.declarativeNetRequest.testMatchOutcome(
request: TestMatchRequestDetails,
callback?: function,
)
ตรวจสอบว่ากฎ declarativeNetRequest ของส่วนขยายใดตรงกับคำขอสมมติหรือไม่ หมายเหตุ: ใช้ได้กับส่วนขยายที่คลายการแพคแล้วเท่านั้นเนื่องจากใช้ระหว่างการพัฒนาส่วนขยายเท่านั้น
พารามิเตอร์
-
ส่งคำขอ
-
Callback
ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้(result: TestMatchOutcomeResult) => void
-
ผลลัพธ์
-
การคืนสินค้า
-
Promise<TestMatchOutcomeResult>
Promise รองรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้ Callback
updateDynamicRules()
chrome.declarativeNetRequest.updateDynamicRules(
options: UpdateRuleOptions,
callback?: function,
)
แก้ไขชุดกฎแบบไดนามิกปัจจุบันสำหรับส่วนขยาย ระบบจะนำกฎที่มีรหัสที่แสดงใน options.removeRuleIds
ออกก่อน จากนั้นจึงจะเพิ่มกฎที่ระบุไว้ใน options.addRules
หมายเหตุ:
- การอัปเดตนี้จะเกิดขึ้นเป็นการทำงานแบบอะตอมเดียว นั่นคือมีการเพิ่มและนำกฎที่ระบุทั้งหมดออก หรือมีข้อผิดพลาดเกิดขึ้น
- กฎเหล่านี้จะคงอยู่ในเซสชันของเบราว์เซอร์และในการอัปเดตส่วนขยาย
- ไม่สามารถนำกฎแบบคงที่ที่ระบุไว้เป็นส่วนหนึ่งของแพ็กเกจส่วนขยายออกโดยใช้ฟังก์ชันนี้
MAX_NUMBER_OF_DYNAMIC_RULES
คือจำนวนกฎแบบไดนามิกสูงสุดที่ส่วนขยายจะเพิ่มได้ จำนวนของกฎที่ไม่ปลอดภัยต้องไม่เกินMAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES
พารามิเตอร์
-
ตัวเลือกChrome เวอร์ชัน 87 ขึ้นไป
-
Callback
ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้() => void
การคืนสินค้า
-
Promise<void>
Chrome 91 ขึ้นไปPromise รองรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้ Callback
updateEnabledRulesets()
chrome.declarativeNetRequest.updateEnabledRulesets(
options: UpdateRulesetOptions,
callback?: function,
)
อัปเดตชุดกฎแบบคงที่ที่เปิดใช้สำหรับส่วนขยาย ระบบจะนำชุดกฎที่มีรหัสที่แสดงใน options.disableRulesetIds
ออกก่อน จากนั้นจึงเพิ่มชุดกฎที่แสดงใน options.enableRulesetIds
โปรดทราบว่าชุดกฎกฎแบบคงที่ที่เปิดใช้จะยังคงอยู่ในเซสชันต่างๆ แต่ไม่คงอยู่ในการอัปเดตส่วนขยาย กล่าวคือ คีย์ไฟล์ Manifest rule_resources
จะกำหนดชุดกฎแบบคงที่ที่เปิดใช้ในการอัปเดตส่วนขยายแต่ละรายการ
พารามิเตอร์
-
ตัวเลือกChrome เวอร์ชัน 87 ขึ้นไป
-
Callback
ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้() => void
การคืนสินค้า
-
Promise<void>
Chrome 91 ขึ้นไปPromise รองรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้ Callback
updateSessionRules()
chrome.declarativeNetRequest.updateSessionRules(
options: UpdateRuleOptions,
callback?: function,
)
แก้ไขชุดกฎขอบเขตเซสชันปัจจุบันสำหรับส่วนขยาย ระบบจะนำกฎที่มีรหัสที่แสดงใน options.removeRuleIds
ออกก่อน จากนั้นจึงจะเพิ่มกฎที่ระบุไว้ใน options.addRules
หมายเหตุ:
- การอัปเดตนี้จะเกิดขึ้นเป็นการทำงานแบบอะตอมเดียว นั่นคือมีการเพิ่มและนำกฎที่ระบุทั้งหมดออก หรือมีข้อผิดพลาดเกิดขึ้น
- กฎเหล่านี้จะไม่คงอยู่ในเซสชันต่างๆ และจะสำรองไว้ในหน่วยความจำ
MAX_NUMBER_OF_SESSION_RULES
คือจำนวนกฎเซสชันสูงสุดที่ส่วนขยายจะเพิ่มได้
พารามิเตอร์
-
ตัวเลือก
-
Callback
ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้() => void
การคืนสินค้า
-
Promise<void>
Chrome 91 ขึ้นไปPromise รองรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้ Callback
updateStaticRules()
chrome.declarativeNetRequest.updateStaticRules(
options: UpdateStaticRulesOptions,
callback?: function,
)
ปิดใช้และเปิดใช้กฎแบบคงที่แต่ละรายการใน Ruleset
การเปลี่ยนแปลงกฎที่เป็นของ Ruleset
ที่ปิดใช้จะมีผลในครั้งถัดไปที่เปิดใช้งาน
พารามิเตอร์
-
ตัวเลือก
-
Callback
ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้() => void
การคืนสินค้า
-
Promise<void>
Promise รองรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้ Callback
กิจกรรม
onRuleMatchedDebug
chrome.declarativeNetRequest.onRuleMatchedDebug.addListener(
callback: function,
)
เริ่มทำงานเมื่อกฎตรงกับคำขอ ใช้ได้เฉพาะกับส่วนขยายที่คลายการแพคแล้วซึ่งมีสิทธิ์ "declarativeNetRequestFeedback"
เนื่องจากมีไว้เพื่อใช้การแก้ไขข้อบกพร่องเท่านั้น
พารามิเตอร์
-
Callback
ฟังก์ชัน
พารามิเตอร์
callback
มีลักษณะดังนี้(info: MatchedRuleInfoDebug) => void
-
ข้อมูล
-