תיאור
ה-API chrome.declarativeNetRequest
משמש לחסימה או לשינוי של בקשות רשת על ידי ציון כללים הצהרתיים. כך התוספים יכולים לשנות את בקשות הרשת בלי ליירט אותן ולצפות בתוכן שלהם, וכך לשפר את הפרטיות.
הרשאות
declarativeNetRequest
declarativeNetRequestWithHostAccess
ההרשאות 'declarativeNetRequest
' ו-'declarativeNetRequestWithHostAccess
' מספקות את אותן היכולות. ההבדלים ביניהם הם המועד שבו מבקשים או מקבלים הרשאות.
"declarativeNetRequest"
- מפעילה אזהרה לגבי הרשאה בזמן ההתקנה, אבל מספקת גישה מרומזת לכללים
allow
,allowAllRequests
ו-block
. כדאי להשתמש באפשרות הזו כשאפשר, כדי שלא יהיה צורך לבקש גישה מלאה למארחים. "declarativeNetRequestFeedback"
- הפעלת תכונות לניפוי באגים בתוספים לא ארוזים, באופן ספציפי
getMatchedRules()
ו-onRuleMatchedDebug
. "declarativeNetRequestWithHostAccess"
- לא מוצגת אזהרה לגבי הרשאות בזמן ההתקנה, אבל חייבים לבקש הרשאות מארח לפני שאפשר לבצע פעולה כלשהי במארח. האפשרות הזו מתאימה כשרוצים להשתמש בכללים הצהרתיים לבקשות נטו בתוסף שכבר יש לו הרשאות מארח, בלי ליצור אזהרות נוספות.
זמינות
מניפסט
בנוסף להרשאות שתוארו קודם לכן, בסוגים מסוימים של מערכי כללים, ובמיוחד ערכות כללים סטטיות, נדרשת הצהרה על מפתח המניפסט "declarative_net_request"
, שאמור להיות מילון עם מפתח יחיד שנקרא "rule_resources"
. המפתח הזה הוא מערך שמכיל מילונים מסוג Ruleset
, כפי שמוצג בהמשך. (שימו לב שהשם 'Ruleset' לא מופיע ב-JSON של המניפסט כי הוא בסך הכול מערך). ערכות כללים סטטיות מוסברות בהמשך מסמך זה.
{
"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 הזה, צריך לציין קבוצת כללים אחת או יותר. קבוצת כללים מכילה מערך של כללים. כלל יחיד מבצע אחת מהפעולות הבאות:
- חסימה של בקשת רשת.
- שדרוג הסכימה (http ל-https).
- כדי למנוע חסימה של בקשה, מבטלים את כל הכללים החסומים התואמים.
- הפניה אוטומטית של בקשת רשת.
- משנים את הכותרות של הבקשה או התגובה.
יש שלושה סוגים של ערכות כללים, שמנוהלות בדרכים מעט שונות.
- דינמית
- עובדים באופן קבוע בכל סשנים של דפדפן ושדרוגי תוספים ומנוהלים באמצעות JavaScript כל עוד התוסף נמצא בשימוש.
- סשן
- מוגדרת כשהדפדפן נכבה וכשמתקינים גרסה חדשה של התוסף. כללי סשנים מנוהלים באמצעות JavaScript כשתוסף נמצא בשימוש.
- סטטית
- ארוזים, מותקנים ומעודכנים כאשר תוסף מותקן או משודרג. הכללים הסטטיים מאוחסנים בקובצי כללים בפורמט JSON ומופיעים בקובץ המניפסט.
בקטעים הבאים נסביר בפירוט על סוגים של קבוצות כללים.
קבוצות כללים דינמיות וברמת הסשן
מערכי כללים דינמיים וסשנים מנוהלים באמצעות JavaScript בזמן השימוש בתוסף.
- הכללים הדינמיים נשארים עקביים בכל הסשנים בדפדפן ושדרוגי התוספים.
- כללי הסשן נמחקים כשהדפדפן נסגר וכשמתקינים גרסה חדשה של התוסף.
יש רק אחד מהסוגים האלה של קבוצות כללים. לתוסף יש הרשאה להוסיף או להסיר כללים באופן דינמי באמצעות קריאה ל-updateDynamicRules()
ול-updateSessionRules()
, בתנאי שלא תחרגו מהמגבלות של הכללים. למידע נוסף על המגבלות על הכללים, אפשר לעיין במאמר מגבלות כללים. תוכלו לראות דוגמה לכך בקטע דוגמאות קוד.
מערכי כללים סטטיים
בניגוד לכללים דינמיים ולכללי סשן, הכללים הסטטיים נארזים, מותקנים ומתעדכנים כשתוספים מותקנים או משודרגים. הם מאוחסנים בקובצי כללים בפורמט JSON שמצוין בהם לתוסף באמצעות המפתחות "declarative_net_request"
ו-"rule_resources"
כפי שמתואר למעלה, וגם מילון אחד או יותר של Ruleset
. מילון Ruleset
מכיל נתיב לקובץ הכלל, מזהה של קבוצת הכללים בקובץ, והאם קבוצת הכללים מופעלת או מושבתת. שתי האפשרויות האחרונות חשובות כאשר מפעילים או משביתים קבוצת כללים באופן פרוגרמטי.
{
...
"declarative_net_request" : {
"rule_resources" : [{
"id": "ruleset_1",
"enabled": true,
"path": "rules_1.json"
},
...
]
}
...
}
כדי לבדוק קבצים של כללים, צריך לטעון את התוסף unpacked. שגיאות ואזהרות לגבי כללים סטטיים לא חוקיים מוצגות רק עבור תוספים שאינם ארוזים. המערכת מתעלמת מכללים סטטיים לא חוקיים בתוספים ארוזים.
בדיקה מזורזת
יכול להיות ששינויים בקבוצות הכללים הסטטיים יעמדו בדרישות לבדיקה מזורזת. ראו בדיקה מהירה יותר של שינויים שעומדים בדרישות.
הפעלה והשבתה של כללים סטטיים וקבוצות כללים
ניתן להפעיל או להשבית גם כללים סטטיים בודדים וגם מערכי כללים סטטיים מלאים בזמן הריצה.
הקבוצה של ערכות הכללים והכללים הסטטיים שהופעלו נשמרת בכל הסשנים בדפדפן. אף אחת מהאפשרויות האלה לא מופיעה בעדכוני תוספים, כלומר רק כללים שבחרתם להשאיר בקובצי הכללים יהיו זמינים אחרי עדכון.
מטעמי ביצועים, חלות גם מגבלות על מספר הכללים וקבוצות הכללים שניתן להפעיל בבת אחת. אפשר להתקשר אל getAvailableStaticRuleCount()
כדי לבדוק את מספר הכללים הנוספים שניתן להפעיל. למידע נוסף על המגבלות על הכללים, אפשר לעיין במאמר מגבלות כללים.
כדי להפעיל או להשבית כללים סטטיים, קוראים לפונקציה updateStaticRules()
. השיטה הזו משתמשת באובייקט UpdateStaticRulesOptions
, שמכיל מערכים של מזהים של כללים להפעלה או להשבתה. המזהים מוגדרים באמצעות המפתח "id"
של מילון Ruleset
. יש מגבלה של עד 5,000 כללים סטטיים שהושבתו.
כדי להפעיל או להשבית rulesets סטטיים, קוראים לפונקציה updateEnabledRulesets()
. השיטה הזו משתמשת באובייקט UpdateRulesetOptions
, שמכיל מערכים של מזהים של קבוצות כללים כדי להפעיל או להשבית אותם. המזהים מוגדרים באמצעות המפתח "id"
של מילון Ruleset
.
יצירת כללים
ללא קשר לסוג, כל כלל מתחיל בארבעה שדות כפי שמוצג בדוגמה הבאה. המקשים "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 |
תעדוף של כללים
הכללים מופעלים על ידי בקשות שנשלחות מדפי אינטרנט. אם מספר כללים תואמים לבקשה מסוימת, יש לתת עדיפות לכללים. בקטע הזה נסביר איך נקבעות סדר העדיפויות שלהן. קביעת סדר העדיפויות מתבצעת בשני שלבים.
- העדיפות נקבעת עבור כללים שנכללים בתוסף.
- אם יותר מתוסף אחד יכול להחיל כלל על בקשה, נקבעת עדיפות לכל התוספים שתואמים לבקשה מסוימת.
חושבים על התאמה כזו: כל כלל מסוים שייקבע על ידי תוסף מסוים יקבל עדיפות על פני כללים מתוספים אחרים.
תעדוף של כללים בתוך תוסף
במסגרת תוסף אחד, קביעת סדר העדיפויות מתבצעת באמצעות התהליך הבא:
- מוחזר הכלל עם העדיפות הגבוהה ביותר בהגדרת המפתח (במילים אחרות, השדה
"priority"
). אם יש יותר מכלל אחד עם העדיפות הגבוהה ביותר בהגדרת המפתח, הכללים יקבלו עדיפות באמצעות השדה
"action"
, בסדר הבא:allow
allowAllRequests
block
upgradeScheme
redirect
אם סוג הפעולה הוא לא
block
אוredirect
, תתבצע הערכה של כל כלליmodifyHeaders
שתואמים. חשוב לזכור שאם יש כללים שהעדיפות שהוגדרה על ידי המפתח נמוכה מהעדיפות שהוגדרה עבורallow
ו-allowAllRequests
, המערכת תתעלם מכללים כאלה.אם מספר כללים משנים את אותה הכותרת, השינוי נקבע על ידי השדה
"priority"
שהוגדר על ידי המפתח ועל ידי הפעולות שצוינו.- אם כלל מצורף לכותרת, כללים עם עדיפות נמוכה יותר יכולים לצרף אותם רק לכותרת הזו. פעולות הגדרה והסרה אינן מותרות.
- אם כלל מגדיר כותרת, כללים עם עדיפות נמוכה יותר יכולים לצרף אותם רק לכותרת הזו. אסור לבצע שינויים אחרים.
- אם כלל מסיר כותרת, כללים בעדיפות נמוכה יותר לא יכולים לשנות את הכותרת עוד יותר.
תעדוף של כללים בין תוספים
אם רק לתוסף אחד יש כלל שתואם לבקשה מסוימת, הכלל הזה יוחל. אבל אם יותר מתוסף אחד תואם לבקשה, נעשה שימוש בתהליך הבא:
הכללים מקבלים עדיפות באמצעות השדה
"action"
, בסדר הבא:block
-
redirect
אוupgradeScheme
-
allow
אוallowAllRequests
אם יותר מכלל אחד תואם, התוסף האחרון שהותקן מקבל עדיפות.
כללי בטיחות
כללים בטוחים מוגדרים ככללים עם פעולה block
, allow
, allowAllRequests
או upgradeScheme
. הכללים האלה כפופים למכסה גדולה יותר של כללים דינמיים.
מגבלות על כללים
יש תקורת הביצועים של טעינה והערכה של כללים בדפדפן, ולכן חלק מהמגבלות חלות כשמשתמשים ב-API. המגבלות תלויות בסוג הכלל שבו משתמשים.
כללים סטטיים
כללים סטטיים הם הכללים המוגדרים בקובצי כללים שהוצהרו בקובץ המניפסט. תוסף יכול לציין עד 100 rulesets סטטיים כחלק ממפתח המניפסט "rule_resources"
, אבל ניתן להפעיל רק 50 מקבוצות הכללים האלה בכל פעם. האפשרות השנייה נקראת MAX_NUMBER_OF_ENABLED_STATIC_RULESETS
. יחד, בקבוצות הכללים האלה מובטחים לפחות 30,000 כללים. סוג החשבון הזה נקרא GUARANTEED_MINIMUM_STATIC_RULES
.
מספר הכללים הזמינים לאחר מכן תלוי במספר הכללים שהופעלו על ידי כל התוספים שמותקנים בדפדפן של המשתמש. כדי למצוא את המספר הזה בזמן הריצה, צריך להתקשר למספר getAvailableStaticRuleCount()
. תוכלו לראות דוגמה לכך בקטע דוגמאות קוד.
כללי סשנים
תוסף יכול לכלול עד 5,000 כללי סשנים. הוא נחשף בתור MAX_NUMBER_OF_SESSION_RULES
.
עד גרסה 120 של Chrome, הייתה מגבלה של 5,000 כללים משולבים של דינמיות ושל סשנים.
כללים דינמיים
תוסף יכול לכלול לפחות 5,000 כללים דינמיים. הוא נחשף בתור MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES
.
החל מגרסה 121 של Chrome, קיימת מגבלה גדולה יותר של 30,000 כללים לכללים דינמיים בטוחים שגלויים כMAX_NUMBER_OF_DYNAMIC_RULES
. גם כללים לא בטוחים שיתווספו במגבלה של עד 5,000 יחידות ייכללו במגבלה הזו.
עד גרסה 120 של Chrome, הייתה מגבלה של 5,000 כללי פעילות דינמית וכללי סשנים.
כללים שמשתמשים בביטויים רגולריים
כל סוגי הכללים יכולים להשתמש בביטויים רגולריים. עם זאת, המספר הכולל של כללי ביטויים רגולריים מכל סוג לא יכול לעלות על 1,000. המספר הזה נקרא 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, אבל לא בטוח שיהיו תשובות דרך handler onfetch
של קובץ שירות (service worker). declarativeNetRequest לא ישפיע על תגובות שנוצרו על ידי Service Worker או אוחזרו מ-CacheStorage
, אבל הן ישפיעו על קריאות ל-fetch()
שמתבצעות דרך Service Worker.
משאבים נגישים מהאינטרנט
כלל declarativeNetRequest לא יכול להפנות מבקשה של משאב ציבורי למשאב שאינו נגיש מהאינטרנט. פעולה זו תגרום לשגיאה. הדבר נכון גם אם המשאב הנגיש מהאינטרנט שצוין נמצא בבעלות התוסף שמפנה מחדש. כדי להצהיר על משאבים בשביל declarativeNetRequest, צריך להשתמש במערך "web_accessible_resources"
של המניפסט.
שינוי בכותרת
פעולת ההוספה נתמכת רק עבור הכותרות הבאות: accept
, accept-encoding
, accept-language
, access-control-request-headers
, cache-control
, connection
, content-language
, cookie
, forwarded
, if-match
, if-none-match
, keep-alive
, range
, te
, trailer
, transfer-encoding
, upgrade
, user-agent
, via
, via
, via
, via
want-digest
x-forwarded-for
דוגמאות
דוגמאות לקוד
עדכון כללים דינמיים
הדוגמה הבאה מראה איך להתקשר ל-updateDynamicRules()
. ההליך לגבי updateSessionRules()
זהה.
// Get arrays containing new and old rules
const newRules = await getNewRules();
const oldRules = await chrome.declarativeNetRequest.getDynamicRules();
const oldRuleIds = oldRules.map(rule => rule.id);
// Use the arrays to update the dynamic rules
await chrome.declarativeNetRequest.updateDynamicRules({
removeRuleIds: oldRuleIds,
addRules: newRules
});
עדכון קבוצות כללים סטטיות
הדוגמה הבאה ממחישה איך להפעיל ולהשבית ערכות כללים תוך התייחסות למספר של קבוצות הכללים הסטטיות הזמינות ולמספר המקסימלי של קבוצות כללים סטטיות. צריך לעשות זאת כשמספר הכללים הסטטיים הדרושים לכם חורג מהמספר המותר. כדי שזה יעבוד, צריך להתקין חלק מקבוצות הכללים כשחלק מקבוצות הכללים מושבתות (הגדרה של "Enabled"
בתור false
בקובץ המניפסט).
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
- שני כללים חלים על כתובת ה-URL הזו: הכללים עם המזהים 1 ו-4. הכלל עם מזהה 1 חל כי לפעולות
"block"
יש עדיפות גבוהה יותר מפעולות של"redirect"
. שאר הכללים לא חלים כי הם מיועדים לכתובות URL ארוכות יותר. - ניווט אל https://google.com/1234
- בגלל כתובת ה-URL הארוכה יותר, הכלל עם מזהה 2 תואם עכשיו בנוסף לכללים עם מזהים 1 ו-4. הכלל עם מזהה 2 חל כי העדיפות של
"allow"
גבוהה יותר מהעדיפות של"block"
ושל"redirect"
. - ניווט אל https://google.com/12345
- כל ארבעת הכללים תואמים לכתובת ה-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
הוא המזהה של התוסף. כדי שההגנה הזו תפעל, המניפסט צריך להצהיר על /a.jpg
כמשאב נגיש לאינטרנט.
{
"id": 1,
"priority": 1,
"action": { "type": "redirect", "redirect": { "extensionPath": "/a.jpg" } },
"condition": {
"urlFilter": "https://www.example.com",
"resourceTypes": ["main_frame"]
}
}
הקוד הבא משתמש במפתח "transform"
כדי להפנות לתת-דומיין של example.com. הוא משתמש בעוגן של שם דומיין ('||') כדי ליירט בקשות עם כל סכימה מ-example.com. המפתח "scheme"
ב-"transform"
מציין שההפניות לתת-הדומיין תמיד ישתמשו ב-'https'.
{
"id": 1,
"priority": 1,
"action": {
"type": "redirect",
"redirect": {
"transform": { "scheme": "https", "host": "new.example.com" }
}
},
"condition": {
"urlFilter": "||example.com",
"resourceTypes": ["main_frame"]
}
}
הדוגמה הבאה משתמשת בביטויים רגולריים כדי להפנות מ-https://www.abc.xyz.com/path
אל https://abc.xyz.com/path
. במפתח "regexFilter"
, שימו לב איך נקודות מסומנות בתו בריחה (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"
]
}
}
כותרות
בדוגמה הבאה מסירים את כל קובצי ה-Cookie ממסגרת ראשית וממסגרות משנה כלשהן.
{
"id": 1,
"priority": 1,
"action": {
"type": "modifyHeaders",
"requestHeaders": [{ "header": "cookie", "operation": "remove" }]
},
"condition": { "resourceTypes": ["main_frame", "sub_frame"] }
}
סוגים
DomainType
המאפיין הזה מציין אם הבקשה היא צד ראשון או צד שלישי במסגרת שבה היא הגיעה. בקשה נחשבת כצד ראשון אם היא בעלת אותו דומיין (eTLD+1) כמו המסגרת שממנה הגיעה הבקשה.
טיפוסים בני מנייה (enum)
"firstParty"
בקשת הרשת היא צד ראשון במסגרת שבה היא הגיעה.
"צד שלישי"
בקשת הרשת היא צד שלישי במסגרת שבה היא הגיעה.
ExtensionActionOptions
תכונות
-
displayActionCountAsBadgeText
ערך בוליאני אופציונלי
הגדרה שקובעת אם להציג באופן אוטומטי את ספירת הפעולות בדף בתור טקסט התג של התוסף. ההעדפה הזו מופיעה בכל הסשנים.
-
tabUpdate
TabActionCountUpdate אופציונלי
Chrome מגרסה 89 ואילךפרטים לגבי השינויים במספר הפעולות של הכרטיסייה.
GetDisabledRuleIdsOptions
תכונות
-
rulesetId
string
המזהה שתואם ל-
Ruleset
הסטטי.
GetRulesFilter
תכונות
-
ruleIds
מספר[] אופציונלי
אם צוין, ייכללו רק כללים עם מזהים תואמים.
HeaderOperation
תיאור זה מתאר את הפעולות האפשריות לכלל "modifyHeaders".
טיפוסים בני מנייה (enum)
"append"
הוספת רשומה חדשה לכותרת שצוינה. אי אפשר לבצע את הפעולה הזאת בכותרות של בקשות.
"set"
הגדרת ערך חדש לכותרת שצוינה, תוך הסרת הכותרות הקיימות עם אותו שם.
"remove"
הסרת כל הרשומות מהכותרת שצוינה.
IsRegexSupportedResult
תכונות
-
isSupported
boolean
-
סיבה
UnsupportedRegexReason אופציונלי
מציינת את הסיבה לכך שהביטוי הרגולרי לא נתמך. צוין רק אם הערך של
isSupported
הוא False.
MatchedRule
תכונות
-
ruleId
number
מזהה של כלל תואם.
-
rulesetId
string
המזהה של
Ruleset
שהכלל הזה שייך לו. עבור כלל שמקורו בקבוצת כללים דינמיים, הערך יהיה שווה ל-DYNAMIC_RULESET_ID
.
MatchedRuleInfo
תכונות
-
כלל
-
tabId
number
ה-TabId של הכרטיסייה שממנה הגיעה הבקשה, אם הכרטיסייה עדיין פעילה. אחרת -1.
-
timeStamp
number
המועד שבו נמצאה התאמה לכלל. חותמות הזמן יתאימו למוסכמה של JavaScript עבור זמנים, כלומר מספר אלפיות השנייה מאז תחילת התקופה.
MatchedRuleInfoDebug
תכונות
-
בקשה
פרטים על הבקשה שעבורה נמצאה התאמה לכלל.
-
כלל
MatchedRulesFilter
תכונות
-
minTimeStamp
מספר אופציונלי
אם צוין, המערכת תתאים את הכללים רק אחרי חותמת הזמן הנתונה.
-
tabId
מספר אופציונלי
אם הוא מוגדר, הוא יתאים רק לכללים של הכרטיסייה הנתונה. תואם לכללים שלא משויכים לאף כרטיסייה פעילה, אם הערך שהוגדר הוא 1-.
ModifyHeaderInfo
תכונות
-
כותרת
string
שם הכותרת שרוצים לשנות.
-
פעולה
הפעולה שצריך לבצע על כותרת.
-
value
מחרוזת אופציונלי
הערך החדש של הכותרת. יש לציין את הערך עבור פעולות
append
ו-set
.
QueryKeyValue
תכונות
-
key
string
-
replaceOnly
ערך בוליאני אופציונלי
Chrome מגרסה 94 ואילךאם הערך הוא True, מפתח השאילתה יוחלף רק אם הוא כבר קיים. אחרת, המפתח יתווסף גם אם הוא חסר. ברירת המחדל היא False.
-
value
string
QueryTransform
תכונות
-
addOrReplaceParams
QueryKeyValue[] אופציונלי
רשימת צמדי מפתח/ערך של שאילתה להוספה או להחלפה.
-
removeParams
string[] אופציונלי
רשימת המפתחות של השאילתות להסרה.
Redirect
תכונות
-
extensionPath
מחרוזת אופציונלי
נתיב יחסי לספריית התוספים. צריך להתחיל ב-'/'.
-
regexSubstitution
מחרוזת אופציונלי
החלפה של דפוס לכללים המציינים
regexFilter
. ההתאמה הראשונה שלregexFilter
בכתובת ה-URL תוחלף בדפוס הזה. בתוךregexSubstitution
אפשר להשתמש בספרות עם תווי בריחה (escape) (\1 עד \9) כדי להוסיף את הקבוצות המתאימות לחילוץ. \0 מתייחס לכל הטקסט התואם. -
ונבצע טרנספורמציה
URLTransform אופציונלי
טרנספורמציות של כתובות URL לביצוע.
-
כתובת אתר
מחרוזת אופציונלי
כתובת ה-URL להפניה אוטומטית. הפניות אוטומטיות לכתובות URL של JavaScript אסורות.
RegexOptions
תכונות
-
isCaseSensitive
ערך בוליאני אופציונלי
אם השדה
regex
שצוין הוא תלוי אותיות רישיות. ברירת המחדל היא True. -
ביטוי רגולרי (regex)
string
ה-Expresson הרגיל שצריך לבדוק.
-
requireCapturing
ערך בוליאני אופציונלי
האם נדרשת הקלטה ב
regex
שצוינה. הלכידה נדרשת רק עבור כללים של הפניה אוטומטית המציינים פעולתregexSubstition
. ערך ברירת המחדל הוא False.
RequestDetails
תכונות
-
documentId
מחרוזת אופציונלי
Chrome 106 ואילךהמזהה הייחודי של המסמך של המסגרת, אם הבקשה הזו היא למסגרת.
-
documentLifecycle
DocumentLifecycle אופציונלי
Chrome 106 ואילךמחזור החיים של המסמך של המסגרת, אם הבקשה הזו היא למסגרת.
-
frameId
number
הערך 0 מציין שהבקשה מתרחשת בפריים הראשי. ערך חיובי מציין את המזהה של תת-מסגרת שבה הבקשה מתרחשת. אם המסמך של מסגרת (sub-) נטען (
type
הואmain_frame
אוsub_frame
),frameId
מציין את המזהה של המסגרת הזו ולא את המזהה של המסגרת החיצונית. מזהי פריימים הם ייחודיים בכרטיסייה. -
frameType
FrameType אופציונלי
Chrome 106 ואילךסוג המסגרת, אם הבקשה היא למסגרת.
-
יוזם
מחרוזת אופציונלי
המקור שבו נשלחה הבקשה. השינוי לא מופיע בהפניות אוטומטיות. אם זהו מקור אטום, ייעשה שימוש במחרוזת 'null'.
-
method
string
שיטת HTTP סטנדרטית.
-
parentDocumentId
מחרוזת אופציונלי
Chrome 106 ואילךהמזהה הייחודי של מסמך ההורה של המסגרת, אם הבקשה הזו היא למסגרת ויש לה הורה.
-
parentFrameId
number
מזהה המסגרת שעוטפת את המסגרת ששלחה את הבקשה. אם לא קיימת מסגרת הורה, יש להגדיר את הערך -1.
-
requestId
string
מזהה הבקשה. מזהי הבקשות הם ייחודיים בכל סשן בדפדפן.
-
tabId
number
המזהה של הכרטיסייה שבה הבקשה נשלחת. יש להגדיר את הערך -1 אם הבקשה לא קשורה לכרטיסייה.
-
סוג
סוג המשאב של הבקשה.
-
כתובת אתר
string
כתובת ה-URL של הבקשה.
RequestMethod
בשדה הזה מתוארת ה-method של בקשת ה-HTTP של בקשת הרשת.
טיפוסים בני מנייה (enum)
"connect"
"get"
"head"
"options"
"patch"
"post"
"put"
ResourceType
כאן מתואר סוג המשאב של בקשת הרשת.
טיפוסים בני מנייה (enum)
"main_frame"
"sub_frame"
"stylesheet"
"script"
"image"
"font"
"xmlhttprequest"
"csp_report"
"media"
"websocket"
"webtransport"
"webbundle"
Rule
תכונות
-
פעולה
הפעולה שתתבצע אם הכלל הזה תואם.
-
מצב
התנאי שלפיו הכלל הזה מופעל.
-
id
number
מזהה שמזהה כלל באופן ייחודי. חובה, והערך צריך להיות >= 1.
-
הקמפיין
מספר אופציונלי
עדיפות הכלל. ברירת המחדל היא 1. אם מציינים את הפרמטר, הוא צריך להיות >= 1.
RuleAction
תכונות
-
הפניה לכתובת אתר אחרת
הפניה לכתובת URL אחרת אופציונלי
מתאר איך לבצע את ההפניה האוטומטית. תקף רק לכללים של הפניות אוטומטיות.
-
requestHeaders
ModifyHeaderInfo[] אופציונלי
Chrome 86 ואילךכותרות הבקשה שצריך לשנות עבור הבקשה. חוקי רק אם RuleActionType הוא "modifyHeaders".
-
responseHeaders
ModifyHeaderInfo[] אופציונלי
Chrome 86 ואילךכותרות התגובה שצריך לשנות עבור הבקשה. חוקי רק אם RuleActionType הוא "modifyHeaders".
-
סוג
סוג הפעולה לביצוע.
RuleActionType
מתאר את סוג הפעולה לביצוע אם כלל תנאי נתון תואם.
טיפוסים בני מנייה (enum)
"block"
חסימת בקשת הרשת.
"redirect"
הפניה אוטומטית של בקשת הרשת.
"allow"
אישור בקשת הרשת. הבקשה לא תיירט אם קיים כלל הרשאה שתואם לה.
"upgradeScheme"
שדרוג הסכימה של כתובת ה-URL של בקשת הרשת ל-https אם הבקשה היא http או ftp.
"modifyHeaders"
שינוי הכותרות של הבקשה/תשובה מבקשת הרשת.
"allowAllRequests"
אישור כל הבקשות בהיררכיית פריימים, כולל בקשת המסגרת עצמה.
RuleCondition
תכונות
-
domainType
DomainType אופציונלי
מציין אם בקשת הרשת היא של צד ראשון או של צד שלישי לדומיין שממנו היא הגיעה. אם לא מציינים את הפרטים, כל הבקשות מאושרות.
-
דומיינים
string[] אופציונלי
הוצא משימוש החל מגרסה 101 של Chromeבמקום זאת, אתם יכולים להשתמש ב-
initiatorDomains
הכלל יתאים רק לבקשות רשת שמגיעות מהרשימה
domains
. -
excludedDomains
string[] אופציונלי
הוצא משימוש החל מגרסה 101 של Chromeבמקום זאת, אתם יכולים להשתמש ב-
excludedInitiatorDomains
הכלל לא יתאים לבקשות רשת שמגיעות מהרשימה
excludedDomains
. -
excludedInitiatorDomains
string[] אופציונלי
Chrome 101 ואילךהכלל לא יתאים לבקשות רשת שמגיעות מהרשימה
excludedInitiatorDomains
. אם הרשימה ריקה או לא מוצגת, אף דומיין לא יוחרג. ההגדרה הזו מקבלת עדיפות על פניinitiatorDomains
.הערות:
- מותר להשתמש גם בתת-דומיינים כמו a.example.com.
- הערכים חייבים לכלול רק תווי ASCII.
- להשתמש בקידוד punycode לדומיינים בינלאומיים.
- הכתובת הזאת תואמת למיזם הבקשה ולא לכתובת ה-URL של הבקשה.
- גם תת-הדומיינים של הדומיינים שברשימה לא נכללים.
-
excludedRequestDomains
string[] אופציונלי
Chrome 101 ואילךהכלל לא יתאים לבקשות רשת כאשר הדומיינים תואמים לאחד מהרשימה
excludedRequestDomains
. אם הרשימה ריקה או לא מוצגת, אף דומיין לא יוחרג. ההגדרה הזו מקבלת עדיפות על פניrequestDomains
.הערות:
- מותר להשתמש גם בתת-דומיינים כמו a.example.com.
- הערכים חייבים לכלול רק תווי ASCII.
- להשתמש בקידוד punycode לדומיינים בינלאומיים.
- גם תת-הדומיינים של הדומיינים שברשימה לא נכללים.
-
excludedRequestMethods
RequestMethod[] אופציונלי
Chrome מגרסה 91 ואילךרשימה של שיטות בקשה שהכלל לא יתאים. יש לציין רק אחד מהערכים
requestMethods
ו-excludedRequestMethods
. אם אף אחת מהאפשרויות האלה לא תצוין, המערכת תתאים לכל שיטות הבקשה. -
excludedResourceTypes
ResourceType[] אופציונלי
רשימה של סוגי משאבים שהכלל לא יתאים. יש לציין רק אחד מהערכים
resourceTypes
ו-excludedResourceTypes
. אם לא תציינו אף אחד מהם, כל סוגי המשאבים מלבד 'main_frame' ייחסמו. -
excludedTabIds
מספר[] אופציונלי
Chrome מגרסה 92 ואילךרשימה של
tabs.Tab.id
שהכלל לא צריך להתאים. מזהה שלtabs.TAB_ID_NONE
לא כולל בקשות שלא מגיעות מכרטיסייה. נתמך רק בכללים ברמת הסשן. -
initiatorDomains
string[] אופציונלי
Chrome 101 ואילךהכלל יתאים רק לבקשות רשת שמגיעות מהרשימה
initiatorDomains
. אם לא מציינים את הרשימה, הכלל יחול על בקשות מכל הדומיינים. רשימה ריקה אינה מותרת.הערות:
- מותר להשתמש גם בתת-דומיינים כמו a.example.com.
- הערכים חייבים לכלול רק תווי ASCII.
- להשתמש בקידוד punycode לדומיינים בינלאומיים.
- הכתובת הזאת תואמת למיזם הבקשה ולא לכתובת ה-URL של הבקשה.
- נמצאה התאמה גם בין תת-הדומיינים של הדומיינים שברשימה.
-
isUrlFilterCaseSensitive
ערך בוליאני אופציונלי
אם הערך
urlFilter
אוregexFilter
(בהתאם לערך שצוין) הוא תלוי אותיות רישיות. ברירת המחדל היא False. -
regexFilter
מחרוזת אופציונלי
ביטוי רגולרי שיתאים לכתובת ה-URL של בקשת הרשת. לפי התחביר של RE2.
הערה: אפשר לציין רק את אחד מהערכים
urlFilter
אוregexFilter
.הערה:
regexFilter
חייב להכיל תווי ASCII בלבד. מתבצעת התאמה לכתובת URL שבה המארח מקודד בפורמט Punycode (במקרה של דומיינים בינלאומיים) וכל תווים אחרים שאינם ASCII מקודדים ב-utf-8. -
requestDomains
string[] אופציונלי
Chrome 101 ואילךהכלל יתאים לבקשות רשת רק כאשר הדומיין תואם לאחד מהרשימה
requestDomains
. אם לא מציינים את הרשימה, הכלל יחול על בקשות מכל הדומיינים. רשימה ריקה אינה מותרת.הערות:
- מותר להשתמש גם בתת-דומיינים כמו a.example.com.
- הערכים חייבים לכלול רק תווי ASCII.
- להשתמש בקידוד punycode לדומיינים בינלאומיים.
- נמצאה התאמה גם בין תת-הדומיינים של הדומיינים שברשימה.
-
requestMethods
RequestMethod[] אופציונלי
Chrome מגרסה 91 ואילךרשימה של שיטות בקשת HTTP שהכלל יכול להתאים. רשימה ריקה אינה מותרת.
הערה: ציון תנאי של כלל
requestMethods
יגרום גם להחרגה של בקשות שאינן HTTP(s), וציוןexcludedRequestMethods
לא יגרום לכך. -
resourceTypes
ResourceType[] אופציונלי
רשימה של סוגי משאבים שהכלל יכול להתאים להם. רשימה ריקה אינה מותרת.
הערה: צריך לציין את השדה הזה עבור הכללים
allowAllRequests
, והוא יכול לכלול רק את סוגי המשאביםsub_frame
ו-main_frame
. -
tabIds
מספר[] אופציונלי
Chrome מגרסה 92 ואילךרשימה של
tabs.Tab.id
שהכלל צריך להתאים להם. מזהה שלtabs.TAB_ID_NONE
תואם לבקשות שלא מגיעות מכרטיסייה. רשימה ריקה אינה מותרת. נתמך רק בכללים ברמת הסשן. -
urlFilter
מחרוזת אופציונלי
הדפוס שתואם לכתובת ה-URL של בקשת הרשת. מבנים נתמכים:
'*' : תו כללי לחיפוש: תואם לכל מספר של תווים.
'|' : עוגן שמאלי/ימני: אם משתמשים באחד מקצוות התבנית, מציינים את ההתחלה/הסוף של כתובת ה-URL בהתאמה.
'||' : עוגן של שם דומיין: אם משתמשים בו בתחילת הדפוס, מציינים את ההתחלה של דומיין (תת-) של כתובת ה-URL.
'^' : תו מפריד: מתאים לכל דבר מלבד אות, ספרה או אחת מהאפשרויות הבאות:
_
,-
,.
או%
. הטקסט הזה מתאים גם לסוף של כתובת ה-URL.לכן,
urlFilter
מורכב מהחלקים הבאים: (עוגן שמאלי/שם דומיין אופציונלי) + תבנית + (עוגן ימני אופציונלי).אם לא מציינים את הפרמטר הזה, כל כתובות ה-URL יהיו תואמות. אסור להזין מחרוזת ריקה.
לא ניתן להשתמש בתבנית שמתחילה ב-
||*
. במקומה צריך להשתמש במדיניות*
.הערה: אפשר לציין רק את אחד מהערכים
urlFilter
אוregexFilter
.הערה:
urlFilter
חייב להכיל תווי ASCII בלבד. מתבצעת התאמה לכתובת URL שבה המארח מקודד בפורמט Punycode (במקרה של דומיינים בינלאומיים) וכל תווים אחרים שאינם ASCII מקודדים ב-utf-8. לדוגמה, כשכתובת ה-URL של הבקשה היא http://abc.рН?q=ф, תהיה התאמה ביןurlFilter
לכתובת ה-URL http://abc.xn--p1ai/?q=%D1%84.
Ruleset
תכונות
-
פעיל
boolean
האם ערכת הכללים מופעלת כברירת מחדל.
-
id
string
מחרוזת שאינה ריקה באופן ייחודי לזיהוי קבוצת הכללים. מזהים עם התחילית '_' שמורים לשימוש פנימי.
-
נתיב
string
הנתיב של קבוצת הכללים של JSON ביחס לספריית התוספים.
RulesMatchedDetails
תכונות
-
rulesMatchedInfo
כללים שתואמים למסנן הנתון.
TabActionCountUpdate
תכונות
-
הוסף
number
הסכום שצריך להגדיל את מספר הפעולות בכרטיסייה. ערכים שליליים יקטינו את המספר.
-
tabId
number
הכרטיסייה שעבורה צריך לעדכן את ספירת הפעולות.
TestMatchOutcomeResult
תכונות
-
matchedRules
הכללים (אם יש) שתואמים לבקשה ההיפותטית.
TestMatchRequestDetails
תכונות
-
יוזם
מחרוזת אופציונלי
כתובת ה-URL של המאתחל (אם יש) של הבקשה ההיפותטית.
-
method
RequestMethod אופציונלי
שיטת HTTP סטנדרטית של הבקשה ההיפותטית. ברירת המחדל היא 'get' בבקשות HTTP ומתעלמת מבקשות שאינן HTTP.
-
tabId
מספר אופציונלי
המזהה של הכרטיסייה שבה הבקשה ההיפותטית. לא צריך להתאים למזהה כרטיסייה אמיתי. ברירת המחדל היא -1. כלומר, הבקשה לא קשורה לכרטיסייה.
-
סוג
סוג המשאב של הבקשה ההיפותטית.
-
כתובת אתר
string
כתובת ה-URL של הבקשה ההיפותטית.
UnsupportedRegexReason
מתאר את הסיבה לכך שביטוי רגולרי נתון לא נתמך.
טיפוסים בני מנייה (enum)
"syntaxError"
הביטוי הרגולרי שגוי מבחינה תחבירית, או שנעשה בו שימוש בתכונות שלא זמינות בתחביר RE2.
"memoryLimitExceeded"
הביטוי הרגולרי חורג ממגבלת הזיכרון.
UpdateRuleOptions
תכונות
-
addRules
כלל[] אופציונלי
כללים להוספה.
-
removeRuleIds
מספר[] אופציונלי
המזהים של הכללים להסרה. המערכת תתעלם ממזהים לא תקינים.
UpdateRulesetOptions
תכונות
UpdateStaticRulesOptions
תכונות
URLTransform
תכונות
-
מקטע (fragment)
מחרוזת אופציונלי
המקטע החדש של הבקשה. השדה צריך להיות ריק. במקרה כזה, המקטע הקיים הוסר או צריך להתחיל בתו '#'.
-
מארח
מחרוזת אופציונלי
המארח החדש של הבקשה.
-
סיסמה
מחרוזת אופציונלי
הסיסמה החדשה של הבקשה.
-
נתיב
מחרוזת אופציונלי
הנתיב החדש של הבקשה. אם השדה ריק, הנתיב הקיים נמחק.
-
יציאה
מחרוזת אופציונלי
הניוד החדש של הבקשה. אם השדה ריק, היציאה הקיימת נמחקת.
-
שאילתה
מחרוזת אופציונלי
השאילתה החדשה של הבקשה. השדה צריך להיות ריק. במקרה כזה, השאילתה הקיימת נמחקה או שהיא צריכה להתחיל ב-'?'.
-
queryTransform
QueryTransform אופציונלי
הוספה, הסרה או החלפה של צמדי מפתח/ערך של שאילתה.
-
סכמה
מחרוזת אופציונלי
הסכימה החדשה של הבקשה. הערכים המותרים הם 'http', 'https', 'ftp' ו-'chrome-extension'.
-
שם משתמש
מחרוזת אופציונלי
שם המשתמש החדש של הבקשה.
תכונות
DYNAMIC_RULESET_ID
מזהה כללים לכללים הדינמיים שהתוסף מוסיף.
ערך של Gpa education
GETMATCHEDRULES_QUOTA_INTERVAL
מרווח הזמן שבו ניתן לבצע MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules
שיחות. הערך הזה מוגדר בדקות. קריאות נוספות ייכשלו באופן מיידי ויוגדרו runtime.lastError
. הערה: שיחות getMatchedRules
שמשויכות לפעולת משתמש לא פטורות מהמכסה.
ערך של Gpa education
10
GUARANTEED_MINIMUM_STATIC_RULES
המספר המינימלי של כללים סטטיים שמובטח לתוסף בכל קבוצות הכללים הסטטיות שהופעלו. כל כלל מעבר למגבלה הזו ייחשב כחלק מהמגבלה הגלובלית של כללים סטטיים.
ערך של Gpa education
30000
MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL
מספר הפעמים שניתן להתקשר אל getMatchedRules
בפרק זמן של GETMATCHEDRULES_QUOTA_INTERVAL
.
ערך של Gpa education
20
MAX_NUMBER_OF_DYNAMIC_RULES
המספר המקסימלי של כללים דינמיים שאפשר להוסיף לתוסף.
ערך של Gpa education
30000
MAX_NUMBER_OF_ENABLED_STATIC_RULESETS
המספר המקסימלי של Rulesets
סטטיים שתוסף יכול להפעיל בכל רגע נתון.
ערך של Gpa education
50
MAX_NUMBER_OF_REGEX_RULES
המספר המקסימלי של כללים של ביטויים רגולריים שאפשר להוסיף לתוסף. המגבלה הזו מוערכת בנפרד עבור קבוצת הכללים הדינמיים ואלה שצוינו בקובץ המשאבים של הכללים.
ערך של Gpa education
1000
MAX_NUMBER_OF_SESSION_RULES
המספר המקסימלי של כללים ברמת הסשן שתוסף יכול להוסיף.
ערך של Gpa education
5000
MAX_NUMBER_OF_STATIC_RULESETS
המספר המקסימלי של Rulesets
סטטיים שתוסף יכול לציין כחלק ממפתח המניפסט "rule_resources"
.
ערך של Gpa education
100
MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES
המספר המקסימלי של כללים דינמיים 'לא בטוחים' שתוסף יכול להוסיף.
ערך של Gpa education
5000
MAX_NUMBER_OF_UNSAFE_SESSION_RULES
המספר המקסימלי של כללים ברמת הסשן 'לא בטוח' שתוסף יכול להוסיף.
ערך של Gpa education
5000
SESSION_RULESET_ID
מזהה כללים לכללים ברמת הסשן שהתוסף מוסיף.
ערך של Gpa education
"_session"
שיטות
getAvailableStaticRuleCount()
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
callback?: function,
)
הפונקציה מחזירה את מספר הכללים הסטטיים שתוסף יכול להפעיל לפני הגעה למגבלה הגלובלית של הכללים הסטטיים.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callback
נראה כך:(count: number) => void
-
ספירה
number
-
החזרות
-
התחייבות<number>
Chrome מגרסה 91 ואילךהבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל יש גם קריאות חוזרות (callback) לצורך תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה ניתנת לפתרון באותו הסוג שמועבר לקריאה החוזרת.
getDisabledRuleIds()
chrome.declarativeNetRequest.getDisabledRuleIds(
options: GetDisabledRuleIdsOptions,
callback?: function,
)
מחזירה את רשימת הכללים הסטטיים ב-Ruleset
הנתון המושבת כרגע.
פרמטרים
-
אפשרויות
ציון קבוצת הכללים שיש להריץ על השאילתה.
-
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callback
נראה כך:(disabledRuleIds: number[]) => void
-
disabledRuleIds
מספר[]
-
החזרות
-
התחייבות<number[]>
הבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל יש גם קריאות חוזרות (callback) לצורך תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה ניתנת לפתרון באותו הסוג שמועבר לקריאה החוזרת.
getDynamicRules()
chrome.declarativeNetRequest.getDynamicRules(
filter?: GetRulesFilter,
callback?: function,
)
מחזירה את הקבוצה הנוכחית של כללים דינמיים עבור התוסף. מתקשרים יכולים לסנן את רשימת הכללים שאוחזרו על ידי ציון filter
.
פרמטרים
-
סינון
GetRulesFilter אופציונלי
Chrome 111 ואילךאובייקט לסינון רשימת הכללים שאוחזרו.
-
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callback
נראה כך:(rules: Rule[]) => void
-
כללים
הכלל[]
-
החזרות
-
הבטחה<כלל[]>
Chrome מגרסה 91 ואילךהבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל יש גם קריאות חוזרות (callback) לצורך תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה ניתנת לפתרון באותו הסוג שמועבר לקריאה החוזרת.
getEnabledRulesets()
chrome.declarativeNetRequest.getEnabledRulesets(
callback?: function,
)
מחזירה את המזהים של הקבוצה הנוכחית של קבוצות הכללים הסטטיות שהופעלו.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callback
נראה כך:(rulesetIds: string[]) => void
-
rulesetIds
String[]
-
החזרות
-
התחייבות<string[]>
Chrome מגרסה 91 ואילךהבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל יש גם קריאות חוזרות (callback) לצורך תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה ניתנת לפתרון באותו הסוג שמועבר לקריאה החוזרת.
getMatchedRules()
chrome.declarativeNetRequest.getMatchedRules(
filter?: MatchedRulesFilter,
callback?: function,
)
מחזירה את כל הכללים התואמים את התוסף. המתקשרים יכולים לסנן את רשימת הכללים התואמים על ידי ציון filter
. השיטה הזו זמינה רק לתוספים עם ההרשאה "declarativeNetRequestFeedback"
או עם ההרשאה "activeTab"
שהוענקה בשביל הtabId
שצוין בfilter
. הערה: לא יוחזרו כללים שלא משויכים למסמך פעיל שנמצאה להם התאמה לפני יותר מחמש דקות.
פרמטרים
-
סינון
MatchedRulesFilter אופציונלי
אובייקט לסינון רשימת הכללים התואמים.
-
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callback
נראה כך:(details: RulesMatchedDetails) => void
-
פרטים
-
החזרות
-
Promise<RulesMatchedDetails>
Chrome מגרסה 91 ואילךהבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל יש גם קריאות חוזרות (callback) לצורך תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה ניתנת לפתרון באותו הסוג שמועבר לקריאה החוזרת.
getSessionRules()
chrome.declarativeNetRequest.getSessionRules(
filter?: GetRulesFilter,
callback?: function,
)
הפונקציה מחזירה את הקבוצה הנוכחית של כללים ברמת הסשן עבור התוסף. מתקשרים יכולים לסנן את רשימת הכללים שאוחזרו על ידי ציון filter
.
פרמטרים
-
סינון
GetRulesFilter אופציונלי
Chrome 111 ואילךאובייקט לסינון רשימת הכללים שאוחזרו.
-
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callback
נראה כך:(rules: Rule[]) => void
-
כללים
הכלל[]
-
החזרות
-
הבטחה<כלל[]>
Chrome מגרסה 91 ואילךהבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל יש גם קריאות חוזרות (callback) לצורך תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה ניתנת לפתרון באותו הסוג שמועבר לקריאה החוזרת.
isRegexSupported()
chrome.declarativeNetRequest.isRegexSupported(
regexOptions: RegexOptions,
callback?: function,
)
הפונקציה בודקת אם הביטוי הרגולרי הנתון נתמך כתנאי של כלל regexFilter
.
פרמטרים
-
regexOptions
הביטוי הרגולרי שצריך לבדוק.
-
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callback
נראה כך:(result: IsRegexSupportedResult) => void
-
תוצאה אחת
-
החזרות
-
Promise<IsRegexSupportedResult>
Chrome מגרסה 91 ואילךהבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל יש גם קריאות חוזרות (callback) לצורך תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה ניתנת לפתרון באותו הסוג שמועבר לקריאה החוזרת.
setExtensionActionOptions()
chrome.declarativeNetRequest.setExtensionActionOptions(
options: ExtensionActionOptions,
callback?: function,
)
המדיניות הזו מגדירה אם ספירת הפעולות עבור כרטיסיות צריכה להיות מוצגת כטקסט התג של פעולת התוסף, ומאפשרת להגדיל את ספירת הפעולות.
פרמטרים
-
אפשרויות
-
קריאה חוזרת (callback)
פונקציה אופציונלית
Chrome מגרסה 89 ואילךהפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome מגרסה 91 ואילךהבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל יש גם קריאות חוזרות (callback) לצורך תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה ניתנת לפתרון באותו הסוג שמועבר לקריאה החוזרת.
testMatchOutcome()
chrome.declarativeNetRequest.testMatchOutcome(
request: TestMatchRequestDetails,
callback?: function,
)
הפונקציה בודקת אם אחד מכללי declarativeNetRequest של התוסף מתאים לבקשה היפותטית. הערה: האפשרות הזו זמינה רק עבור תוספים לא ארוזים, כי האפשרות הזו מיועדת לשימוש רק במהלך פיתוח התוספים.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callback
נראה כך:(result: TestMatchOutcomeResult) => void
-
תוצאה אחת
-
החזרות
-
Promise<TestMatchOutcomeResult>
הבטחות נתמכות במניפסט מגרסה 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 ואילךהבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל יש גם קריאות חוזרות (callback) לצורך תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה ניתנת לפתרון באותו הסוג שמועבר לקריאה החוזרת.
updateEnabledRulesets()
chrome.declarativeNetRequest.updateEnabledRulesets(
options: UpdateRulesetOptions,
callback?: function,
)
עדכון הקבוצה של קבוצות הכללים הסטטיות שהופעלו עבור התוסף. המערכת מסירה קודם את קבוצות הכללים עם המזהים שרשומים ב-options.disableRulesetIds
, ולאחר מכן את קבוצות הכללים שמופיעות ב-options.enableRulesetIds
.
חשוב לשים לב שהקבוצה של קבוצות הכללים הסטטיות שהופעלו נשמרת בכל הסשנים, אבל לא בכל עדכוני התוסף. כלומר, מפתח המניפסט rule_resources
יקבע את הקבוצה של קבוצות הכללים הסטטיות שהופעלו בכל עדכון של תוסף.
פרמטרים
-
אפשרויותChrome מגרסה 87 ואילך
-
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome מגרסה 91 ואילךהבטחות נתמכות במניפסט מגרסה 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 ואילךהבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל יש גם קריאות חוזרות (callback) לצורך תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה ניתנת לפתרון באותו הסוג שמועבר לקריאה החוזרת.
updateStaticRules()
chrome.declarativeNetRequest.updateStaticRules(
options: UpdateStaticRulesOptions,
callback?: function,
)
השבתה והפעלה של כללים סטטיים ספציפיים ב-Ruleset
. שינויים בכללים ששייכים למכשיר Ruleset
שהושבת ייכנסו לתוקף בפעם הבאה שהוא יופעל.
פרמטרים
-
אפשרויות
-
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
הבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל יש גם קריאות חוזרות (callback) לצורך תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה ניתנת לפתרון באותו הסוג שמועבר לקריאה החוזרת.
אירועים
onRuleMatchedDebug
chrome.declarativeNetRequest.onRuleMatchedDebug.addListener(
callback: function,
)
מופעל כאשר כלל תואם לבקשה. האפשרות הזו זמינה רק לתוספים לא ארוזים עם ההרשאה "declarativeNetRequestFeedback"
, כי היא מיועדת לשימוש למטרות ניפוי באגים בלבד.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(info: MatchedRuleInfoDebug) => void
-
מידע
-