תיאור
ה-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 כללים סטטיים שהושבתו.
כדי להפעיל או להשבית מערכי כללים סטטיים, קוראים לפונקציה 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"]
}
}
התאמה לכתובת URL
Declarative Net Request מספק את היכולת להתאים כתובות URL באמצעות כל אחד מהדפוסים. תחביר או ביטויים רגולריים תואמים.
תחביר של סינון כתובות URL
מפתח "condition"
של כלל מאפשר למפתח "urlFilter"
לפעול על כתובות URL בדומיין שצוין. אתם יוצרים דפוסים באמצעות אסימונים תואמים לתבניות. ריכזנו כאן כמה דוגמאות.
urlFilter |
משחקים | לא תואמת |
---|---|---|
"abc" |
https://abcd.com https://example.com/abcd |
https://ab.com |
"abc*d" |
https://abcd.com https://example.com/abcxyzd |
https://abc.com |
"||a.example.com" |
https://a.example.com/ https://b.a.example.com/xyz https://a.example.company |
https://example.com/ |
"|https*" |
https://example.com | http://example.com/ http://https.com |
"example*^123|" |
https://example.com/123 http://abc.com/example?123 |
https://example.com/1234 https://abc.com/example0123 |
ביטויים רגולריים
התנאים יכולים גם להשתמש בביטויים רגולריים. לצפייה
מקש "regexFilter"
. כדי ללמוד על
המגבלות שחלות על התנאים האלה:
כללים שמשתמשים בביטויים רגולריים.
כתיבת תנאים טובים לכתובות URL
חשוב להקפיד לכתוב כללים כך שתמיד יתאימו לדומיין שלם. אחרת, עשוי להתאים במצבים בלתי צפויים. לדוגמה, כשמשתמשים באופרטור תחביר התאמת דפוסים:
google.com
תואם בצורה שגויה ל-https://example.com/?param=google.com
||google.com
תואם בצורה שגויה ל-https://google.company
https://www.google.com
תואם בצורה שגויה ל-https://example.com/?param=https://www.google.com
כדאי להשתמש בצירופים הבאים:
||google.com/
, שתואם לכל הנתיבים ולכל תתי-הדומיינים.|https://www.google.com/
שתואם לכל הנתיבים ללא תת-דומיינים.
באופן דומה, צריך להשתמש בתווים ^
ו-/
כדי לעגן ביטוי רגולרי. עבור
לדוגמה, ^https:\/\/www\.google\.com\/
תואם לכל נתיב ב-
https://www.google.com.
הערכת כללים
כללי DNR חלים על ידי הדפדפן בשלבים שונים של מחזור החיים של בקשת הרשת.
לפני הבקשה
לפני שליחת בקשה, תוסף יכול לחסום או להפנות באופן אוטומטי (כולל שדרוג הסכמה מ-HTTP ל-HTTPS) באמצעות כלל תואם.
הדפדפן קובע רשימה של כללים תואמים לכל תוסף. כללים עם פעולת modifyHeaders
לא נכללים כאן, כי הם יטופלו מאוחר יותר. בנוסף, כללים עם תנאי responseHeaders
ייחשבו מאוחר יותר (כשיש כותרות תגובה זמינות) והם לא ייכללו.
לאחר מכן, עבור כל תוסף, Chrome בוחר מועמד אחד לכל היותר בכל בקשה. Chrome מוצא כלל תואם על ידי סידור כל הכללים התואמים לפי עדיפות. כללים עם אותה עדיפות מסודרים לפי פעולה (allow
או allowAllRequests
> block
> upgradeScheme
> redirect
).
אם המועמד הוא כלל allow
או allowAllRequests
, או אם המסגרת שבה מתבצעת הבקשה תואמת לכלל allowAllRequests
שהוגדר קודם לכן עם עדיפות גבוהה יותר או שווה מהתוסף הזה, הבקשה 'מותרת' והתוסף לא ישפיע על הבקשה.
אם יותר מתוסף אחד רוצה לחסום את הבקשה הזו או להפנות אותה לכתובת אחרת, נבחרת פעולה יחידה לביצוע. Chrome עושה זאת על ידי מיון הכללים לפי סדר block
> redirect
או upgradeScheme
> allow
או allowAllRequests
. אם שני כללים הם מאותו סוג, Chrome בוחר את הכלל מהתוסף האחרון שהותקן.
לפני שליחת הכותרות של הבקשות
לפני ש-Chrome שולח כותרות של בקשות לשרת, הכותרות מתעדכנות על סמך כללי modifyHeaders
תואמים.
בתוך תוסף אחד, Chrome יוצר רשימת שינויים לביצוע על ידי חיפוש כל הכללים התואמים של modifyHeaders
. בדומה למה הקודם, נכללים רק כללים עם עדיפות גבוהה יותר מכל הכללים התואמים מסוג allow
או allowAllRequests
.
הכללים האלה מוחלים על ידי Chrome לפי הסדר שבו כללים מתוסף שהותקן מאוחר יותר נבדקים תמיד לפני כללים מתוסף ישן. בנוסף, כללים שיש להם עדיפות גבוהה יותר מתוסף אחד יחולו תמיד לפני כללים עם עדיפות נמוכה יותר מאותו תוסף. חשוב לציין שגם כשמשתמשים בתוספים:
- אם כלל מצורף לכותרת, כללים עם עדיפות נמוכה יותר יוכלו לצרף אותם רק לכותרת הזו. פעולות הגדרה והסרה אינן מותרות.
- אם כלל מגדיר כותרת, רק כללים עם עדיפות נמוכה יותר מאותו תוסף יכולים לצרף לכותרת הזו. אסור לבצע שינויים אחרים.
- אם כלל מסיר כותרת, כללים בעדיפות נמוכה יותר לא יכולים לשנות את הכותרת עוד יותר.
ברגע שמתקבלת תשובה
אחרי שמתקבלות כותרות התגובה, Chrome מבצע הערכה של הכללים עם תנאי responseHeaders
.
לאחר מיון הכללים האלה לפי action
ו-priority
והחרגת כללים שהוחרגו על ידי כלל allow
או allowAllRequests
תואם (זה קורה באופן זהה לשלבים בקטע "לפני הבקשה"), Chrome עשוי לחסום או להפנות את הבקשה בשם תוסף.
שימו לב שאם בקשה הגיעה לשלב הזה, הבקשה כבר נשלחה לשרת והשרת קיבל נתונים כמו גוף הבקשה. כלל של חסימה או הפניה לכתובת אחרת עם תנאי של כותרות תגובה ימשיכו לפעול, אבל לא יוכל לחסום או להפנות את הבקשה בפועל.
במקרה של כלל חסימה, הפעולה הזו מטופלת על ידי הדף שבעקבותיו הבקשה קיבלה תגובה נחסמה ו-Chrome מסיים את הבקשה מוקדם. במקרה של כלל של הפניה אוטומטית, Chrome יוצר בקשה חדשה אל כתובת ה-URL שאליה מתבצעת ההפניה. חשוב לבדוק אם ההתנהגויות האלה עומדות בציפיות הפרטיות של התוסף.
אם הבקשה לא חסומה או מנותבת מחדש, Chrome יחיל את כל כללי modifyHeaders
. החלת שינויים על כותרות של תגובות מתבצעת באותו אופן כמו שמתואר בקטע 'לפני שליחת כותרות של בקשות'. החלת שינויים על כותרות של בקשות לא עושה דבר, כי הבקשה כבר בוצעה.
כללי בטיחות
כללים בטוחים מוגדרים ככללים עם הפעולה block
, allow
allowAllRequests
או upgradeScheme
. הכללים האלה כפופים
מכסה של כללים דינמיים.
מגבלות על כללים
יש תקורת ביצועים מבחינת טעינה והערכה של כללים בדפדפן, לכן חלות מגבלות מסוימות כאשר משתמשים ב-API. המגבלות תלויות בסוג שבו אתה משתמש.
כללים סטטיים
כללים סטטיים הם הכללים המוגדרים בקובצי כללים שהוצהרו בקובץ המניפסט. תוסף יכול לציין עד 100 מערכי כללים סטטיים כחלק ממפתח המניפסט "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
מחרוזת
המזהה שתואם ל-
Ruleset
הסטטי.
GetRulesFilter
מאפיינים
-
ruleIds
מספר[] אופציונלי
אם צוין, ייכללו רק כללים עם מזהים תואמים.
HeaderInfo
מאפיינים
-
excludedValues
string[] אופציונלי
אם צוין התנאי הזה, הוא לא מתקיים אם הכותרת קיימת אבל הערך שלו מכיל לפחות רכיב אחד ברשימה הזו. היא משתמשת באותו תחביר של דפוס התאמה כמו
values
. -
כותרת
מחרוזת
שם הכותרת. התנאי הזה תואם לשם רק אם לא צוינו
values
וגםexcludedValues
. -
ערכים
string[] אופציונלי
אם צוין התנאי הזה, התנאי הזה מתאים אם ערך הכותרת תואם לפחות לדפוס אחד ברשימה הזו. הוא תומך בהתאמה של ערכי כותרות לא תלויי-רישיות, וגם במבנים הבאים:
'*' : התאמה לכל מספר של תווים.
'?' : התאמה לאפס תווים או לתו אחד.
'*' ו-'?' יכול להיות בתו בריחה (escape) באמצעות לוכסן הפוך, לדוגמה '\*' וגם '\?'
HeaderOperation
תיאור זה מתאר את הפעולות האפשריות של "modifyHeaders" כלל.
Enum
"append"
הוספת רשומה חדשה לכותרת שצוינה. אי אפשר לבצע את הפעולה הזאת בכותרות של בקשות.
"set"
הגדרת ערך חדש לכותרת שצוינה, תוך הסרת הכותרות הקיימות עם אותו שם.
"remove"
הסרת כל הרשומות מהכותרת שצוינה.
IsRegexSupportedResult
מאפיינים
-
isSupported
בוליאני
-
סיבה
UnsupportedRegexReason אופציונלי
מציינת את הסיבה לכך שהביטוי הרגולרי לא נתמך. צוין רק אם הערך של
isSupported
הוא False.
MatchedRule
מאפיינים
-
ruleId
number
מזהה של כלל תואם.
-
rulesetId
מחרוזת
המזהה של
Ruleset
שהכלל הזה שייך לו. עבור כלל שמקורו בקבוצת כללים דינמיים, הערך יהיה שווה ל-DYNAMIC_RULESET_ID
.
MatchedRuleInfo
מאפיינים
-
כלל
-
tabId
number
ה-TabId של הכרטיסייה שממנה הגיעה הבקשה, אם הכרטיסייה עדיין פעילה. אחרת -1.
-
timeStamp
number
המועד שבו נמצאה התאמה לכלל. חותמות הזמן יתאימו למוסכמה של JavaScript עבור זמנים, כלומר מספר אלפיות השנייה מאז תחילת התקופה.
MatchedRuleInfoDebug
מאפיינים
-
בקשה
פרטים על הבקשה שעבורה נמצאה התאמה לכלל.
-
כלל
MatchedRulesFilter
מאפיינים
-
minTimeStamp
מספר אופציונלי
אם צוין, המערכת תתאים את הכללים רק אחרי חותמת הזמן הנתונה.
-
tabId
מספר אופציונלי
אם הוא מוגדר, הוא יתאים רק לכללים של הכרטיסייה הנתונה. תואם לכללים שלא משויכים לאף כרטיסייה פעילה, אם הערך שהוגדר הוא 1-.
ModifyHeaderInfo
מאפיינים
-
כותרת
מחרוזת
שם הכותרת שרוצים לשנות.
-
פעולה
הפעולה שצריך לבצע על כותרת.
-
ערך
מחרוזת אופציונלי
הערך החדש של הכותרת. יש לציין את הערך עבור פעולות
append
ו-set
.
QueryKeyValue
מאפיינים
-
מקש
מחרוזת
-
replaceOnly
ערך בוליאני אופציונלי
Chrome מגרסה 94 ואילךאם הערך הוא True, מפתח השאילתה יוחלף רק אם הוא כבר קיים. אחרת, המפתח יתווסף גם אם הוא חסר. ברירת המחדל היא False.
-
ערך
מחרוזת
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)
מחרוזת
ה-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
מחרוזת
שיטת HTTP סטנדרטית.
-
parentDocumentId
מחרוזת אופציונלי
Chrome 106+המזהה הייחודי של מסמך ההורה של המסגרת, אם הבקשה הזו היא למסגרת ויש לה הורה.
-
parentFrameId
number
מזהה המסגרת שעוטפת את המסגרת ששלחה את הבקשה. אם לא קיימת מסגרת הורה, יש להגדיר את הערך -1.
-
requestId
מחרוזת
מזהה הבקשה. מזהי הבקשות הם ייחודיים בכל סשן בדפדפן.
-
tabId
number
המזהה של הכרטיסייה שבה הבקשה נשלחת. יש להגדיר את הערך -1 אם הבקשה לא קשורה לכרטיסייה.
-
סוג
סוג המשאב של הבקשה.
-
כתובת אתר
מחרוזת
כתובת ה-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
"חסימה"
חסימת בקשת הרשת.
"redirect"
הפניה אוטומטית של בקשת הרשת.
"allow"
אישור בקשת הרשת. הבקשה לא תיירט אם קיים כלל הרשאה שתואם לה.
"upgradeScheme"
שדרוג הסכימה של כתובת ה-URL של בקשת הרשת ל-https אם הבקשה היא http או ftp.
"modifyHeaders"
שינוי הכותרות של הבקשה/תשובה מבקשת הרשת.
"allowAllRequests"
אישור כל הבקשות בהיררכיית פריימים, כולל בקשת המסגרת עצמה.
RuleCondition
מאפיינים
-
domainType
DomainType אופציונלי
מציין אם בקשת הרשת היא של צד ראשון או של צד שלישי לדומיין שממנו היא הגיעה. אם לא מציינים את הפרטים, כל הבקשות מאושרות.
-
דומיינים
string[] אופציונלי
הוצא משימוש החל מגרסה Chrome 101במקום זאת, אתם יכולים להשתמש ב-
initiatorDomains
הכלל יתאים רק לבקשות רשת שמגיעות מהרשימה
domains
. -
excludedDomains
string[] אופציונלי
הוצא משימוש החל מגרסה Chrome 101במקום זאת, אתם יכולים להשתמש ב-
excludedInitiatorDomains
הכלל לא יתאים לבקשות רשת שמגיעות מהרשימה
excludedDomains
. -
excludedInitiatorDomains
string[] אופציונלי
Chrome 101 ואילךהכלל לא יתאים לבקשות רשת שמגיעות מהרשימה
excludedInitiatorDomains
. אם הרשימה ריקה או לא מוצגת, אף דומיין לא יוחרג. ההגדרה הזו מקבלת עדיפות על פניinitiatorDomains
.הערות:
- תת-דומיינים כמו "a.example.com" מותרות גם הן.
- הערכים חייבים לכלול רק תווי ASCII.
- להשתמש בקידוד punycode לדומיינים בינלאומיים.
- הכתובת הזאת תואמת למיזם הבקשה ולא לכתובת ה-URL של הבקשה.
- גם תת-הדומיינים של הדומיינים שברשימה לא נכללים.
-
excludedRequestDomains
string[] אופציונלי
Chrome 101 ואילךהכלל לא יתאים לבקשות רשת כאשר הדומיינים תואמים לאחד מהרשימה
excludedRequestDomains
. אם הרשימה ריקה או לא מוצגת, אף דומיין לא יוחרג. ההגדרה הזו מקבלת עדיפות על פניrequestDomains
.הערות:
- תת-דומיינים כמו "a.example.com" מותרות גם הן.
- הערכים חייבים לכלול רק תווי ASCII.
- להשתמש בקידוד punycode לדומיינים בינלאומיים.
- גם תת-הדומיינים של הדומיינים שברשימה לא נכללים.
-
excludedRequestMethods
RequestMethod[] אופציונלי
Chrome מגרסה 91 ואילךרשימה של שיטות בקשה שהכלל לא יתאים. יש לציין רק אחד מהערכים
requestMethods
ו-excludedRequestMethods
. אם אף אחת מהאפשרויות האלה לא תצוין, המערכת תתאים לכל שיטות הבקשה. -
excludedResourceTypes
ResourceType[] אופציונלי
רשימה של סוגי משאבים שהכלל לא יתאים. יש לציין רק אחד מהערכים
resourceTypes
ו-excludedResourceTypes
. אם לא צוין אף אחד מהם, כל סוגי המשאבים מלבד "main_frame" חסומות. -
excludedResponseHeaders
HeaderInfo[] אופציונלי
Chrome 128 ואילךהכלל לא תואם אם הבקשה תואמת לאחד מהתנאים של כותרת התגובה ברשימה הזו (אם צוין). אם מציינים גם
excludedResponseHeaders
וגםresponseHeaders
, המאפייןexcludedResponseHeaders
מקבל קדימות. -
excludedTabIds
מספר[] אופציונלי
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
. -
responseHeaders
HeaderInfo[] אופציונלי
Chrome 128 ואילךהכלל תואם אם הבקשה תואמת לאחד מהתנאים של כותרת התגובה ברשימה הזו (אם צוין).
-
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
מאפיינים
-
פעיל
בוליאני
האם ערכת הכללים מופעלת כברירת מחדל.
-
id [מזהה]
מחרוזת
מחרוזת שאינה ריקה באופן ייחודי לזיהוי קבוצת הכללים. מזהים המתחילים ב-'_' שמורים לשימוש פנימי.
-
נתיב
מחרוזת
הנתיב של קבוצת הכללים של JSON ביחס לספריית התוספים.
RulesMatchedDetails
מאפיינים
-
rulesMatchedInfo
כללים שתואמים למסנן הנתון.
TabActionCountUpdate
מאפיינים
-
הוסף
number
הסכום שצריך להגדיל את מספר הפעולות בכרטיסייה. ערכים שליליים יקטינו את המספר.
-
tabId
number
הכרטיסייה שעבורה צריך לעדכן את ספירת הפעולות.
TestMatchOutcomeResult
מאפיינים
-
matchedRules
הכללים (אם יש) שתואמים לבקשה ההיפותטית.
TestMatchRequestDetails
מאפיינים
-
יוזם
מחרוזת אופציונלי
כתובת ה-URL של המאתחל (אם יש) של הבקשה ההיפותטית.
-
method
RequestMethod אופציונלי
שיטת HTTP סטנדרטית של הבקשה ההיפותטית. ברירת המחדל היא 'get'. לבקשות HTTP, והמערכת מתעלמת ממנו בבקשות שאינן HTTP.
-
responseHeaders
אובייקט אופציונלי
בהמתנההכותרות מספקות תגובה היפותטית אם הבקשה לא נחסמת או מופנית מחדש לפני שהיא נשלחת. מיוצג כאובייקט שממפה שם של כותרת לרשימה של ערכי מחרוזות. אם לא צוין אחרת, התגובה ההיפותטית תחזיר כותרות תגובה ריקות, שיכולות להתאים לכללים שאינם קיימים של כותרות. לדוגמה:
{"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}
-
tabId
מספר אופציונלי
המזהה של הכרטיסייה שבה הבקשה ההיפותטית. לא צריך להתאים למזהה כרטיסייה אמיתי. ברירת המחדל היא -1. כלומר, הבקשה לא קשורה לכרטיסייה.
-
סוג
סוג המשאב של הבקשה ההיפותטית.
-
כתובת אתר
מחרוזת
כתובת ה-URL של הבקשה ההיפותטית.
UnsupportedRegexReason
מתאר את הסיבה לכך שביטוי רגולרי נתון לא נתמך.
Enum
"syntaxError"
הביטוי הרגולרי שגוי מבחינה תחבירית, או שנעשה בו שימוש בתכונות שלא זמינות בתחביר RE2.
"memoryLimitExceeded"
הביטוי הרגולרי חורג ממגבלת הזיכרון.
UpdateRuleOptions
מאפיינים
-
addRules
כלל[] אופציונלי
כללים להוספה.
-
removeRuleIds
מספר[] אופציונלי
המזהים של הכללים להסרה. המערכת תתעלם ממזהים לא תקינים.
UpdateRulesetOptions
מאפיינים
UpdateStaticRulesOptions
מאפיינים
URLTransform
מאפיינים
-
מקטע (fragment)
מחרוזת אופציונלי
המקטע החדש של הבקשה. צריך להיות ריק. במקרה כזה, המקטע הקיים נמחק; או צריך להתחיל בתו '#'.
-
מארח
מחרוזת אופציונלי
המארח החדש של הבקשה.
-
סיסמה
מחרוזת אופציונלי
הסיסמה החדשה של הבקשה.
-
נתיב
מחרוזת אופציונלי
הנתיב החדש של הבקשה. אם השדה ריק, הנתיב הקיים נמחק.
-
יציאה
מחרוזת אופציונלי
הניוד החדש של הבקשה. אם השדה ריק, היציאה הקיימת נמחקת.
-
שאילתה
מחרוזת אופציונלי
השאילתה החדשה של הבקשה. השדה צריך להיות ריק, במקרה כזה השאילתה הקיימת נמחקת. או צריך להתחיל ב-'?'.
-
queryTransform
QueryTransform אופציונלי
הוספה, הסרה או החלפה של צמדי מפתח/ערך של שאילתה.
-
סכמה
מחרוזת אופציונלי
הסכימה החדשה של הבקשה. הערכים המותרים הם 'http', 'https', 'ftp' ו-'chrome-extension'.
-
שם משתמש
מחרוזת אופציונלי
שם המשתמש החדש של הבקשה.
מאפיינים
DYNAMIC_RULESET_ID
מזהה כללים לכללים הדינמיים שהתוסף מוסיף.
ערך
"_דינמי"
GETMATCHEDRULES_QUOTA_INTERVAL
מרווח הזמן שבו ניתן לבצע MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules
שיחות. הערך הזה מוגדר בדקות. קריאות נוספות ייכשלו באופן מיידי ויוגדרו runtime.lastError
. הערה: שיחות getMatchedRules
שמשויכות לפעולת משתמש לא פטורות מהמכסה.
ערך
10
GUARANTEED_MINIMUM_STATIC_RULES
המספר המינימלי של כללים סטטיים שמובטח לתוסף בכל קבוצות הכללים הסטטיות שהופעלו. כל כלל מעבר למגבלה הזו ייחשב כחלק מהמגבלה הגלובלית של כללים סטטיים.
ערך
30000
MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL
מספר הפעמים שניתן להתקשר אל getMatchedRules
בפרק זמן של GETMATCHEDRULES_QUOTA_INTERVAL
.
ערך
20
MAX_NUMBER_OF_DYNAMIC_RULES
המספר המקסימלי של כללים דינמיים שאפשר להוסיף לתוסף.
ערך
30000
MAX_NUMBER_OF_ENABLED_STATIC_RULESETS
המספר המקסימלי של Rulesets
סטטיים שתוסף יכול להפעיל בכל רגע נתון.
ערך
50
MAX_NUMBER_OF_REGEX_RULES
המספר המקסימלי של כללים של ביטויים רגולריים שאפשר להוסיף לתוסף. המגבלה הזו מוערכת בנפרד עבור קבוצת הכללים הדינמיים ואלה שצוינו בקובץ המשאבים של הכללים.
ערך
1000
MAX_NUMBER_OF_SESSION_RULES
המספר המקסימלי של כללים ברמת הסשן שתוסף יכול להוסיף.
ערך
5000
MAX_NUMBER_OF_STATIC_RULESETS
המספר המקסימלי של Rulesets
סטטיים שתוסף יכול לציין כחלק ממפתח המניפסט "rule_resources"
.
ערך
100
MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES
המספר המקסימלי של שגיאות 'לא בטוחות' כללים דינמיים שתוסף יכול להוסיף.
ערך
5000
MAX_NUMBER_OF_UNSAFE_SESSION_RULES
המספר המקסימלי של שגיאות 'לא בטוחות' כללים ברמת הסשן שתוסף יכול להוסיף.
ערך
5000
SESSION_RULESET_ID
מזהה כללים לכללים ברמת הסשן שהתוסף מוסיף.
ערך
"_session"
שיטות
getAvailableStaticRuleCount()
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
callback?: function,
)
הפונקציה מחזירה את מספר הכללים הסטטיים שתוסף יכול להפעיל לפני הגעה למגבלה הגלובלית של הכללים הסטטיים.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callback
נראה כך:(count: number) => void
-
count
number
-
החזרות
-
Promise<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[]
-
החזרות
-
Promise<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
החזרות
-
הבטחה<Empty>
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
החזרות
-
הבטחה<Empty>
Chrome מגרסה 91 ואילךהבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.
updateEnabledRulesets()
chrome.declarativeNetRequest.updateEnabledRulesets(
options: UpdateRulesetOptions,
callback?: function,
)
עדכון הקבוצה של קבוצות הכללים הסטטיות שהופעלו עבור התוסף. המערכת מסירה קודם את קבוצות הכללים עם המזהים שרשומים ב-options.disableRulesetIds
, ולאחר מכן את קבוצות הכללים שמופיעות ב-options.enableRulesetIds
.
חשוב לשים לב שהקבוצה של קבוצות הכללים הסטטיות שהופעלו נשמרת בכל הסשנים, אבל לא בכל עדכוני התוסף. כלומר, מפתח המניפסט rule_resources
יקבע את הקבוצה של קבוצות הכללים הסטטיות שהופעלו בכל עדכון של תוסף.
פרמטרים
-
אפשרויותChrome מגרסה 87 ואילך
-
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callback
נראה כך:() => void
החזרות
-
הבטחה<Empty>
Chrome מגרסה 91 ואילךהבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.
updateSessionRules()
chrome.declarativeNetRequest.updateSessionRules(
options: UpdateRuleOptions,
callback?: function,
)
שינוי הקבוצה הנוכחית של כללים ברמת הסשן עבור התוסף. קודם כל מסירים את הכללים עם המזהים שרשומים בשדה options.removeRuleIds
, ואז את הכללים שמופיעים בטבלה options.addRules
נוספים. הערות:
- העדכון הזה מתבצע כפעולה אטומית אחת: או שכל הכללים שצוינו מתווספים ומסירים, או מוחזרת שגיאה.
- הכללים האלה לא נשמרים בכל הסשנים ומגובים בזיכרון.
MAX_NUMBER_OF_SESSION_RULES
הוא המספר המקסימלי של כללי סשנים שתוסף יכול להוסיף.
פרמטרים
-
אפשרויות
-
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callback
נראה כך:() => void
החזרות
-
הבטחה<Empty>
Chrome מגרסה 91 ואילךהבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.
updateStaticRules()
chrome.declarativeNetRequest.updateStaticRules(
options: UpdateStaticRulesOptions,
callback?: function,
)
השבתה והפעלה של כללים סטטיים ספציפיים ב-Ruleset
. שינויים בכללים ששייכים למכשיר Ruleset
שהושבת ייכנסו לתוקף בפעם הבאה שהוא יופעל.
פרמטרים
-
אפשרויות
-
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callback
נראה כך:() => void
החזרות
-
הבטחה<Empty>
הבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.
אירועים
onRuleMatchedDebug
chrome.declarativeNetRequest.onRuleMatchedDebug.addListener(
callback: function,
)
מופעל כאשר כלל תואם לבקשה. האפשרות הזו זמינה רק לתוספים לא ארוזים עם ההרשאה "declarativeNetRequestFeedback"
, כי היא מיועדת לשימוש למטרות ניפוי באגים בלבד.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(info: MatchedRuleInfoDebug) => void
-
מידע
-