chrome.declarativeNetRequest

תיאור

ה-API של chrome.declarativeNetRequest משמש לחסימה או לשינוי של בקשות רשת על ידי ציון כללים מוצהריים. כך התוספים יכולים לשנות בקשות רשת בלי ליירט אותן ולראות את התוכן שלהן, וכך לשפר את הפרטיות.

הרשאות

declarativeNetRequest
declarativeNetRequestWithHostAccess

ההרשאות declarativeNetRequest ו-declarativeNetRequestWithHostAccess מספקות את אותן יכולות. ההבדל בין שתי האפשרויות הוא מתי מבקשים את ההרשאות ומתי הן ניתנות.

"declarativeNetRequest"
מפעילה אזהרה לגבי הרשאות בזמן ההתקנה, אבל מספקת גישה משתמעת לכללים allow,‏ allowAllRequests ו-block. מומלץ להשתמש באפשרות הזו כשהיא זמינה כדי שלא תצטרכו לבקש גישה מלאה מהמארחים.
"declarativeNetRequestFeedback"
הפעלת תכונות לניפוי באגים בתוספים לא מוצקים, במיוחד ב-getMatchedRules() וב-onRuleMatchedDebug.
"declarativeNetRequestWithHostAccess"
לא מוצגת אזהרה לגבי הרשאות בזמן ההתקנה, אבל צריך לבקש הרשאות מהמארח כדי לבצע פעולה כלשהי במארח. האפשרות הזו מתאימה כשרוצים להשתמש בכללים דמוקרטיים לבקשות רשת בתוסף שכבר יש לו הרשאות מארח, בלי ליצור אזהרות נוספות.

זמינות

Chrome מגרסה 84 ואילך

מניפסט

בנוסף להרשאות שתוארו למעלה, סוגים מסוימים של כללי מדיניות, במיוחד כללי מדיניות סטטיים, דורשים הצהרה על מפתח המניפסט "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"
    },
    ...
    ]
  }
  ...
}

כדי לבדוק את קובצי הכללים, צריך לטעון את התוסף ללא אריזה. שגיאות ואזהרות לגבי כללים סטטיים לא תקינים מוצגות רק לגבי תוספי CSS שלא פורקו. המערכת מתעלמת מכללים סטטיים לא חוקיים בתוספים ארוזים.

בדיקה מהירה

יכול להיות ששינויים בכללי סט של כללים סטטיים יעמדו בדרישות לבדיקה מהירה. בדיקה מהירה של שינויים שעומדים בדרישות

הפעלה והשבתה של כללים סטטיים וקבוצות כללים

אפשר להפעיל או להשבית כללים סטטיים בודדים וגם קבוצות של כללים סטטיים מלאות במהלך זמן הריצה.

קבוצת הכללים הסטטיים וקבוצות הכללים המופעלות נשארת קבועה בסשנים שונים בדפדפן. אף אחד מהם לא נשמר לאחר עדכוני התוספים, כלומר רק הכללים שבחרתם להשאיר בקובצי הכללים יהיו זמינים אחרי העדכון.

מטעמי ביצועים, יש גם מגבלות על מספר הכללים ועל מספר קבוצות הכללים שאפשר להפעיל בו-זמנית. אפשר להתקשר למספר getAvailableStaticRuleCount() כדי לבדוק את מספר הכללים הנוספים שאפשר להפעיל. מידע על מגבלות של כללים זמין במאמר מגבלות של כללים.

כדי להפעיל או להשבית כללים סטטיים, קוראים לפונקציה updateStaticRules(). השיטה מקבלת אובייקט UpdateStaticRulesOptions שמכיל מערכי מזהי כללים להפעלה או להשבתה. המזהים מוגדרים באמצעות המפתח "id" במילון Ruleset. המגבלה המקסימלית היא 5,000 כללים סטטיים מושבתים.

כדי להפעיל או להשבית קבוצות כללים סטטיות, קוראים ל-updateEnabledRulesets(). ה-method הזה מקבל אובייקט UpdateRulesetOptions שמכיל מערכי מזהי של כללי כללים שרוצים להפעיל או להשבית. המזהים מוגדרים באמצעות המפתח "id" במילון Ruleset.

יצירת כללים

ללא קשר לסוג, כל כלל מתחיל בארבעה שדות, כפי שמתואר בהמשך. המפתחות "id" ו-"priority" מקבלים מספר, אבל המפתחות "action" ו-"condition" יכולים לספק כמה תנאים לחסימה ולהפניה אוטומטית. הכלל הבא חוסם את כל הבקשות ל-script שמגיעות מ-"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.

החל מ-Chrome 121, יש מגבלה גדולה יותר של 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.

אינטראקציות עם שירותי עבודה

ה-declarativeNetRequest חל רק על בקשות שמגיעות ל-stack הרשת. התגובה הזו כוללת תגובות מהמטמון של HTTP, אבל יכול להיות שהיא לא תכלול תגובות שעוברות דרך הטיפול של 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, ‏ 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 מקצה עדיפות לכללים בתוסף. כשבודקים אותם, כדאי לפתוח את כללי העדיפות בחלון נפרד.

המפתח priority

הדוגמאות האלה מחייבות הרשאת מארח ל-*://*.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. הקוד משתמש בציון (anchor) של שם דומיין ("||") כדי ליירט בקשות עם כל סכימה מ-example.com. המפתח "scheme" ב-"transform" מציין שבהפניות אוטומטיות לתת-הדומיין תמיד נעשה שימוש ב-"https".

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

בדוגמה הבאה נעשה שימוש בביטויים רגולריים כדי להפנות אוטומטית מ-https://www.abc.xyz.com/path אל https://abc.xyz.com/path. במפתח "regexFilter", שימו לב לאופן שבו נשמרים בריחה של נקודות, ולכך שקבוצת התיעוד בוחרת את 'abc' או את 'def'. המפתח "regexSubstitution" מציין את ההתאמה הראשונה שהוחזרה של הביטוי הרגולרי באמצעות \1. במקרה כזה, המערכת מתעדת את הערך 'abc' מכתובת ה-URL שהופנתה ומציבה אותו במקום החלפה.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": {
      "regexSubstitution": "https://\\1.xyz.com/"
    }
  },
  "condition": {
    "regexFilter": "^https://www\\.(abc|def)\\.xyz\\.com/",
    "resourceTypes": [
      "main_frame"
    ]
  }
}

כותרות

בדוגמה הבאה, כל קובצי ה-cookie יוסרו גם מהמסגרת הראשית וגם מכל המסגרות המשניות.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "modifyHeaders",
    "requestHeaders": [{ "header": "cookie", "operation": "remove" }]
  },
  "condition": { "resourceTypes": ["main_frame", "sub_frame"] }
}

סוגים

DomainType

השדה הזה מתאר אם הבקשה היא מצד ראשון או מצד שלישי ביחס למסגרת שבה היא נוצרה. בקשה נחשבת לצד ראשון אם יש לה את אותו דומיין (eTLD+1) כמו המסגרת שממנה הבקשה נשלחה.

Enum

"firstParty"
בקשת הרשת היא צד ראשון ביחס למסגרת שבה היא נוצרה.

"thirdParty"
בקשת הרשת היא צד שלישי ביחס למסגרת שבה היא נוצרה.

ExtensionActionOptions

גרסה 88 ואילך של Chrome

מאפיינים

  • displayActionCountAsBadgeText

    בוליאני אופציונלי

    האם להציג באופן אוטומטי את מספר הפעולות בדף כטקסט התג של התוסף. ההעדפה הזו נשמרת בין סשנים.

  • tabUpdate

    TabActionCountUpdate אופציונלי

    Chrome מגרסה 89 ואילך

    פרטים על האופן שבו צריך לשנות את מספר הפעולות בכרטיסייה.

GetDisabledRuleIdsOptions

גרסה 111 ואילך של Chrome

מאפיינים

  • rulesetId

    מחרוזת

    המזהה התואם ל-Ruleset סטטי.

GetRulesFilter

גרסה 111 ואילך של Chrome

מאפיינים

  • ruleIds

    number[] אופציונלי

    אם יצוין מזהה, ייכללו רק כללים עם מזהי התאמה.

HeaderInfo

Chrome מגרסה 128 ואילך

מאפיינים

  • excludedValues

    string[] אופציונלי

    אם צוין, התנאי הזה לא יתאים אם הכותרת קיימת אבל הערך שלה מכיל לפחות רכיב אחד מהרשימה הזו. נעשה כאן שימוש באותו תחביר של תבנית ההתאמה כמו ב-values.

  • header

    מחרוזת

    שם הכותרת. התנאי הזה תואם לשם רק אם לא צוינו גם values וגם excludedValues.

  • ערכים

    string[] אופציונלי

    אם צוין, התנאי הזה מתקיים אם הערך של הכותרת תואם לתבנית אחת לפחות ברשימה הזו. התכונה הזו תומכת בהתאמה של ערכי כותרות ללא קשר לאותיות רישיות, וגם במבנים הבאים:

    '*' : תואם לכל מספר תווים.

    '?' : תואם לאפס תווים או לתו אחד.

    אפשר לסמן את התווים '*' ו-'?' בתו בריחה (escape) של קו נטוי לאחור, למשל '\*' ו-'\?'

HeaderOperation

Chrome מגרסה 86 ואילך

כאן מתוארות הפעולות האפשריות של כלל 'modifyHeaders'.

Enum

append
הוספת רשומה חדשה לכותרת שצוינה. הפעולה הזו לא נתמכת בכותרות של בקשות.

‎"set"
הגדרת ערך חדש לכותרת שצוינה, והסרה של כותרות קיימות עם אותו שם.

‎"remove"
הסרת כל הרשומות של הכותרת שצוינה.

IsRegexSupportedResult

Chrome מגרסה 87 ואילך

מאפיינים

  • isSupported

    בוליאני

  • סיבה

    UnsupportedRegexReason אופציונלי

    הסיבה לכך שאין תמיכה בביטוי הרגולרי. האפשרות הזו מוצגת רק אם הערך של isSupported הוא false.

MatchedRule

מאפיינים

  • ruleId

    number

    מזהה של כלל תואם.

  • rulesetId

    מחרוזת

    המזהה של Ruleset שהכלל הזה שייך אליו. לכלל שמקורו בקבוצת הכללים הדינמיים, הערך יהיה DYNAMIC_RULESET_ID.

MatchedRuleInfo

מאפיינים

  • כלל

    MatchedRule

  • tabId

    number

    מזהה הכרטיסייה (tabId) שממנה נשלחה הבקשה, אם הכרטיסייה עדיין פעילה. אחרת, -1.

  • timeStamp

    number

    המועד שבו הכלל התאים. חותמות הזמן יתאימו למוסכמה של JavaScript לזמנים, כלומר מספר אלפיות השנייה מאז תחילת התקופה של זמן מערכת.

MatchedRuleInfoDebug

מאפיינים

MatchedRulesFilter

מאפיינים

  • minTimeStamp

    מספר אופציונלי

    אם מצוין, המערכת תתאים רק לכללים אחרי חותמת הזמן שצוינה.

  • tabId

    מספר אופציונלי

    אם מצוין, המערכת תתאים רק כללים מהכרטיסייה הזו. אם הערך מוגדר כ--1, המערכת תתאים כללים שלא משויכים לכרטיסייה פעילה כלשהי.

ModifyHeaderInfo

Chrome מגרסה 86 ואילך

מאפיינים

  • header

    מחרוזת

    שם הכותרת שרוצים לשנות.

  • פעולה

    HeaderOperation

    הפעולה שתתבצע בכותרת.

  • ערך

    מחרוזת אופציונלי

    הערך החדש של הכותרת. צריך לציין אותו בפעולות append ו-set.

QueryKeyValue

מאפיינים

  • מקש

    מחרוזת

  • replaceOnly

    בוליאני אופציונלי

    גרסה 94 ואילך של Chrome

    אם הערך הוא True, מפתח השאילתה יוחלף רק אם הוא כבר קיים. אחרת, המפתח יתווסף גם אם הוא חסר. ברירת המחדל היא false.

  • ערך

    מחרוזת

QueryTransform

מאפיינים

  • addOrReplaceParams

    QueryKeyValue[] אופציונלי

    רשימת צמדי המפתח/ערך של השאילתה שרוצים להוסיף או להחליף.

  • removeParams

    string[] אופציונלי

    רשימת מפתחות השאילתות שרוצים להסיר.

Redirect

מאפיינים

  • extensionPath

    מחרוזת אופציונלי

    נתיב ביחס לספריית ההרחבה. צריך להתחיל ב-'/'.

  • regexSubstitution

    מחרוזת אופציונלי

    דפוס החלפה לכללים שצוין בהם regexFilter. ההתאמה הראשונה של regexFilter בכתובת ה-URL תוחלף בתבנית הזו. בתוך regexSubstitution, אפשר להשתמש בספרות עם בריחה (backslash) (\1 עד \9) כדי להוסיף את קבוצות התיעוד התואמות. \0 מתייחס לכל הטקסט התואם.

  • ונבצע טרנספורמציה

    URLTransform אופציונלי

    טרנספורמציות של כתובות URL לביצוע.

  • כתובת אתר

    מחרוזת אופציונלי

    כתובת ה-URL להפניה אוטומטית. אסור להשתמש בהפניות אוטומטיות לכתובות URL של JavaScript.

RegexOptions

גרסה 87 ואילך של Chrome

מאפיינים

  • isCaseSensitive

    בוליאני אופציונלי

    אם הערך שצוין בשדה regex תלוי אותיות רישיות. ברירת המחדל היא true.

  • ביטוי רגולרי (regex)

    מחרוזת

    הביטוי הרגולרי לבדיקה.

  • requireCapturing

    בוליאני אופציונלי

    האם צריך לתעד את regex שצוין. התיעוד נדרש רק לכללי הפניה אוטומטית שצוינה בהם פעולה מסוג regexSubstition. ברירת המחדל היא false.

RequestDetails

מאפיינים

  • documentId

    מחרוזת אופציונלי

    Chrome מגרסה 106 ואילך

    המזהה הייחודי של מסמך המסגרת, אם הבקשה היא למסגרת.

  • documentLifecycle

    DocumentLifecycle אופציונלי

    גרסה 106 ואילך של Chrome

    מחזור החיים של מסמך המסגרת, אם הבקשה היא למסגרת.

  • frameId

    number

    הערך 0 מציין שהבקשה מתרחשת בפריים הראשי. ערך חיובי מציין את המזהה של פריים משנה שבו מתרחשת הבקשה. אם המסמך של מסגרת (משנית) נטען (type הוא main_frame או sub_frame), הערך של frameId מציין את המזהה של המסגרת הזו, ולא את המזהה של המסגרת החיצונית. מזהי המסגרות הם ייחודיים בכרטיסייה.

  • frameType

    FrameType אופציונלי

    גרסה 106 ואילך של Chrome

    סוג המסגרת, אם הבקשה היא למסגרת.

  • מפעיל

    מחרוזת אופציונלי

    המקור שבו הבקשה הופעל. המצב הזה לא משתנה דרך הפניות אוטומטיות. אם מדובר במקור אטום, המערכת תשתמש במחרוזת 'null'.

  • method

    מחרוזת

    שיטת HTTP רגילה.

  • parentDocumentId

    מחרוזת אופציונלי

    Chrome מגרסה 106 ואילך

    המזהה הייחודי של מסמך ההורה של המסגרת, אם הבקשה היא למסגרת שיש לה הורה.

  • parentFrameId

    number

    המזהה של המסגרת שמקיפה את המסגרת ששלחה את הבקשה. הערך מוגדר ל-1 אם לא קיים מסגרת הורה.

  • requestId

    מחרוזת

    מזהה הבקשה. מזהי הבקשות הם ייחודיים בסשן הדפדפן.

  • tabId

    number

    המזהה של הכרטיסייה שבה מתבצעת הבקשה. מגדירים את הערך כ--1 אם הבקשה לא קשורה לכרטיסייה.

  • סוג

    ResourceType

    סוג המשאב של הבקשה.

  • כתובת אתר

    מחרוזת

    כתובת ה-URL של הבקשה.

RequestMethod

Chrome מגרסה 91 ואילך

כאן מתוארת שיטת הבקשה של ה-HTTP לבקשת רשת.

Enum

"connect"

"delete"

"get"

"head"

"options"

"patch"

"post"

"put"

"other"

ResourceType

כאן מתואר סוג המשאב של בקשת הרשת.

Enum

"main_frame"

"sub_frame"

"stylesheet"

"script"

"image"

"font"

"object"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"webtransport"

"webbundle"

"other"

Rule

מאפיינים

  • פעולה

    RuleAction

    הפעולה שתתבצע אם הכלל הזה יתאים.

  • תנאי

    RuleCondition

    התנאי שבו הכלל הזה מופעל.

  • id [מזהה]

    number

    מזהה שמזהה באופן ייחודי כלל. חובה, והערך צריך להיות גדול או שווה ל-1.

  • הקמפיין

    מספר אופציונלי

    עדיפות הכלל. ברירת המחדל היא 1. אם מצוין ערך, הוא צריך להיות גדול או שווה ל-1.

RuleAction

מאפיינים

  • הפניה לכתובת אתר אחרת

    הפניה אוטומטית אופציונלי

    תיאור האופן שבו צריך לבצע את ההפניה האוטומטית. תקף רק לכללי הפניה אוטומטית.

  • 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[] אופציונלי

    הוצאה משימוש החל מ-Chrome 101

    במקום זאת, צריך להשתמש ב-initiatorDomains

    הכלל יתאים רק לבקשות רשת שמקורן ברשימת domains.

  • excludedDomains

    string[] אופציונלי

    הוצאה משימוש החל מ-Chrome 101

    במקום זאת, צריך להשתמש ב-excludedInitiatorDomains

    הכלל לא יתאים לבקשות רשת שמקורן ברשימת excludedDomains.

  • excludedInitiatorDomains

    string[] אופציונלי

    גרסה 101 ואילך של Chrome

    הכלל לא יתאים לבקשות רשת שמקורן ברשימת excludedInitiatorDomains. אם הרשימה ריקה או לא מוגדרת, לא ייכללו דומיינים. האפשרות הזו מקבלת עדיפות על פני initiatorDomains.

    הערות:

    • מותר גם להשתמש בתתי-דומיינים כמו 'a.example.com'.
    • הרשומות חייבות להכיל רק תווים מסוג ASCII.
    • שימוש בקידוד punycode לדומיינים בינלאומיים.
    • ההתאמה מתבצעת ליזם הבקשה ולא לכתובת ה-URL של הבקשה.
    • גם תת-דומיינים של הדומיינים המפורטים נכללים בהחרגה.
  • excludedRequestDomains

    string[] אופציונלי

    גרסה 101 ואילך של Chrome

    הכלל לא יתאים לבקשות רשת כשהדומיינים יהיו תואמים לאחד מהדומיינים ברשימה 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

    number[] אופציונלי

    Chrome מגרסה 92 ואילך

    רשימה של tabs.Tab.id שהכלל לא צריך להתאים אליהם. מזהה tabs.TAB_ID_NONE לא כולל בקשות שלא מגיעות מכרטיסייה. התכונה נתמכת רק בכללים ברמת הסשן.

  • initiatorDomains

    string[] אופציונלי

    גרסה 101 ואילך של Chrome

    הכלל יתאים רק לבקשות רשת שמקורן ברשימת 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[] אופציונלי

    גרסה 101 ואילך של Chrome

    הכלל יתאים לבקשות רשת רק אם הדומיין תואם לאחד מהדומיינים ברשימה 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

    number[] אופציונלי

    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

    MatchedRuleInfo[]

    כללים שתואמים למסנן הנתון.

TabActionCountUpdate

Chrome מגרסה 89 ואילך

מאפיינים

  • הוסף

    number

    הסכום שבו צריך להגדיל את מספר הפעולות בכרטיסייה. ערכים שליליים יגרמו לירידה במספר.

  • tabId

    number

    הכרטיסייה שעבורה רוצים לעדכן את מספר הפעולות.

TestMatchOutcomeResult

גרסה 103 ואילך של Chrome

מאפיינים

  • matchedRules

    MatchedRule[]

    הכללים (אם יש כאלה) שתואמים לבקשה היפותטית.

TestMatchRequestDetails

גרסה 103 ואילך של Chrome

מאפיינים

  • מפעיל

    מחרוזת אופציונלי

    כתובת ה-URL של המאתחל (אם יש כזו) של הבקשה ההיפותטית.

  • method

    RequestMethod אופציונלי

    שיטת ה-HTTP הרגילה של הבקשה ההיפותטית. ערך ברירת המחדל הוא 'get' לבקשות HTTP, והוא מתעלם מבקשות שאינן בקשות HTTP.

  • responseHeaders

    אובייקט אופציונלי

    גרסה 129 ואילך של Chrome

    הכותרות שסופקו בתגובה היפותטית, אם הבקשה לא נחסמה או הועברה לכתובת אחרת לפני שהיא נשלחה. מיוצג כאובייקט שממפה שם כותרת לרשימה של ערכי מחרוזות. אם לא מציינים את הערך, התגובה ההיפותטית תחזיר כותרות תגובה ריקות, שיכולות להתאים לכללים שמתאימים לתנאי של אי-קיומ כותרות. לדוגמה: {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}

  • tabId

    מספר אופציונלי

    המזהה של הכרטיסייה שבה מתבצעת הבקשה היפותטית. לא חייב להתאים למזהה כרטיסייה אמיתי. ברירת המחדל היא -1, כלומר הבקשה לא קשורה לכרטיסייה.

  • סוג

    ResourceType

    סוג המשאב של הבקשה היפותטית.

  • כתובת אתר

    מחרוזת

    כתובת ה-URL של הבקשה ההיפותטית.

UnsupportedRegexReason

Chrome מגרסה 87 ואילך

תיאור הסיבה לכך שביטוי רגולרי נתון לא נתמך.

Enum

‎"syntaxError"
הביטוי הרגולרי שגוי מבחינה תחבירית או שהוא כולל תכונות שלא זמינות בתחביר של RE2.

‎"memoryLimitExceeded"
הביטוי הרגולרי חורג ממגבלת הזיכרון.

UpdateRuleOptions

Chrome מגרסה 87 ואילך

מאפיינים

  • addRules

    Rule[] אופציונלי

    הכללים שרוצים להוסיף.

  • removeRuleIds

    number[] אופציונלי

    המזהים של הכללים שרוצים להסיר. המערכת תתעלם ממזהים לא חוקיים.

UpdateRulesetOptions

Chrome מגרסה 87 ואילך

מאפיינים

  • disableRulesetIds

    string[] אופציונלי

    קבוצת המזהים התואמת ל-Ruleset סטטי שצריך להשבית.

  • enableRulesetIds

    string[] אופציונלי

    קבוצת המזהים התואמת ל-Ruleset סטטי שצריך להפעיל.

UpdateStaticRulesOptions

גרסה 111 ואילך של Chrome

מאפיינים

  • disableRuleIds

    number[] אופציונלי

    קבוצת מזהים שתואמים לכללים ב-Ruleset שרוצים להשבית.

  • enableRuleIds

    number[] אופציונלי

    קבוצת מזהי כללים שרוצים להפעיל ב-Ruleset.

  • rulesetId

    מחרוזת

    המזהה התואם ל-Ruleset סטטי.

URLTransform

מאפיינים

  • מקטע (fragment)

    מחרוזת אופציונלי

    החלק החדש של הבקשה. השדה צריך להיות ריק, ובמקרה כזה החלק הקיים יימחק. לחלופין, השדה צריך להתחיל ב-'#'.

  • מארח

    מחרוזת אופציונלי

    המארח החדש של הבקשה.

  • סיסמה

    מחרוזת אופציונלי

    הסיסמה החדשה לבקשה.

  • נתיב

    מחרוזת אופציונלי

    הנתיב החדש של הבקשה. אם השדה ריק, הנתיב הקיים יימחק.

  • יציאה

    מחרוזת אופציונלי

    היציאה החדשה לבקשה. אם השדה ריק, היציאה הקיימת תימחק.

  • שאילתה

    מחרוזת אופציונלי

    השאילתה החדשה של הבקשה. השדה צריך להיות ריק, ובמקרה כזה השאילתה הקיימת תימחק. לחלופין, השדה צריך להתחיל ב-'?'.

  • queryTransform

    QueryTransform אופציונלי

    הוספה, הסרה או החלפה של צמד מפתח/ערך של שאילתה.

  • סכמה

    מחרוזת אופציונלי

    הסכימה החדשה של הבקשה. הערכים המותרים הם http,‏ https,‏ ftp ו-chrome-extension.

  • שם משתמש

    מחרוזת אופציונלי

    שם המשתמש החדש של הבקשה.

מאפיינים

DYNAMIC_RULESET_ID

מזהה קבוצת הכללים של הכללים הדינמיים שנוספו על ידי התוסף.

ערך

‎"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

מרווח הזמן שבו אפשר לבצע שיחות MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules, שמצוין בדקות. שיחות נוספות ייכשלו באופן מיידי ויגדירו את הערך runtime.lastError. הערה: קריאות getMatchedRules שמשויכות לתנועת משתמש פטורות מהמכסה.

ערך

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome מגרסה 89 ואילך

המספר המינימלי של כללי סטטיקה שמובטח לתוסף בכל קבוצות הכללים הסטטיות שהופעלו. כללים מעבר למגבלה הזו ייכללו במגבלה הגלובלית של כללים סטטיים.

ערך

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

מספר הפעמים שניתן להפעיל את getMatchedRules בתקופה של GETMATCHEDRULES_QUOTA_INTERVAL.

ערך

20

MAX_NUMBER_OF_DYNAMIC_RULES

המספר המקסימלי של כללים דינמיים שאפשר להוסיף באמצעות תוסף.

ערך

30000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

גרסה 94 ואילך של Chrome

המספר המקסימלי של Rulesets סטטיים שאפשר להפעיל בכל פעם בתוסף.

ערך

50

MAX_NUMBER_OF_REGEX_RULES

המספר המקסימלי של כללי ביטויים רגולריים שאפשר להוסיף באמצעות תוסף. המגבלה הזו נבדקת בנפרד לגבי קבוצת הכללים הדינמיים וכללים שצוינו בקובץ המשאבים של הכללים.

ערך

1,000

MAX_NUMBER_OF_SESSION_RULES

Chrome מגרסה 120 ואילך

המספר המקסימלי של כללים ברמת הסשן שאפשר להוסיף באמצעות תוסף.

ערך

5000

MAX_NUMBER_OF_STATIC_RULESETS

המספר המקסימלי של Rulesets סטטיים שאפשר לציין בתוסף כחלק ממפתח המניפסט "rule_resources".

ערך

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome מגרסה 120 ואילך

המספר המקסימלי של כללים דינמיים 'לא בטוחים' שאפשר להוסיף לתוסף.

ערך

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome מגרסה 120 ואילך

המספר המקסימלי של כללים 'לא בטוחים' ברמת הסשן שאפשר להוסיף באמצעות תוסף.

ערך

5000

SESSION_RULESET_ID

גרסה 90 ואילך של Chrome

מזהה קבוצת הכללים של הכללים ברמת הסשן שנוספו על ידי התוסף.

ערך

‎"_session"

Methods

getAvailableStaticRuleCount()

Promise Chrome מגרסה 89 ואילך 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
)

הפונקציה מחזירה את מספר הכללים הסטטיים שאפשר להפעיל בתוסף לפני שמגיעים למגבלה הגלובלית של כללים סטטיים.

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (count: number) => void

    • count

      number

החזרות

  • Promise<number>

    Chrome מגרסה 91 ואילך

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

getDisabledRuleIds()

Promise Chrome מגרסה 111 ואילך 
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
  callback?: function,
)

הפונקציה מחזירה את רשימת הכללים הסטטיים ב-Ruleset שמושבתים כרגע.

פרמטרים

  • אפשרויות

    GetDisabledRuleIdsOptions

    מציין את קבוצת הכללים שעבורה רוצים לשלוח שאילתה.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      number[]

החזרות

  • Promise<number[]>

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

getDynamicRules()

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

הפונקציה מחזירה את קבוצת הכללים הדינמיים הנוכחית של התוסף. קריאה יכולה לסנן את רשימת הכללים שאוחזרו על ידי ציון filter.

פרמטרים

  • סינון

    GetRulesFilter אופציונלי

    גרסה 111 ואילך של Chrome

    אובייקט לסינון רשימת הכללים שאוחזרו.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (rules: Rule[]) => void

החזרות

  • Promise<Rule[]>

    Chrome מגרסה 91 ואילך

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

getEnabledRulesets()

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

הפונקציה מחזירה את המזהים של הקבוצה הנוכחית של כללי קבוצות סטטיות מופעלות.

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (rulesetIds: string[]) => void

    • rulesetIds

      string[]

החזרות

  • Promise<string[]>

    Chrome מגרסה 91 ואילך

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

getMatchedRules()

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

הפונקציה מחזירה את כל הכללים שתואמים לתוסף. מבצעי הקריאה החוזרת יכולים לסנן את רשימת הכללים שתואמים על ידי ציון filter. השיטה הזו זמינה רק לתוספים עם ההרשאה "declarativeNetRequestFeedback" או עם ההרשאה "activeTab" שניתנה ל-tabId שצוין ב-filter. הערה: כללים שלא משויכים למסמך פעיל ותואמים לפני יותר מחמש דקות לא יוחזרו.

פרמטרים

  • סינון

    MatchedRulesFilter אופציונלי

    אובייקט לסינון רשימת הכללים התואמים.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (details: RulesMatchedDetails) => void

החזרות

  • Chrome מגרסה 91 ואילך

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

getSessionRules()

Promise Chrome מגרסה 90 ואילך 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
  callback?: function,
)

הפונקציה מחזירה את הקבוצה הנוכחית של כללים ברמת הסשן של התוסף. קריאה יכולה לסנן את רשימת הכללים שאוחזרו על ידי ציון filter.

פרמטרים

  • סינון

    GetRulesFilter אופציונלי

    גרסה 111 ואילך של Chrome

    אובייקט לסינון רשימת הכללים שאוחזרו.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (rules: Rule[]) => void

החזרות

  • Promise<Rule[]>

    Chrome מגרסה 91 ואילך

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

isRegexSupported()

Promise Chrome מגרסה 87 ואילך 
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
  callback?: function,
)

הפונקציה בודקת אם המערכת תומכת בביטוי הרגולרי הנתון כתנאי לכלל regexFilter.

פרמטרים

החזרות

  • Chrome מגרסה 91 ואילך

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

setExtensionActionOptions()

Promise Chrome מגרסה 88 ואילך 
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
  callback?: function,
)

ההגדרה קובעת אם מספר הפעולות בכרטיסיות יוצג כטקסט התג של פעולת התוסף, ומספקת דרך להגדלת מספר הפעולות.

פרמטרים

  • אפשרויות

    ExtensionActionOptions

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    Chrome מגרסה 89 ואילך

    הפרמטר callback נראה כך: 

    () => void

החזרות

  • Promise<void>

    Chrome מגרסה 91 ואילך

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

testMatchOutcome()

Promise Chrome מגרסה 103 ואילך 
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
)

הפונקציה בודקת אם אחד מהכללים של declarativeNetRequest בתוסף יתאים לבקשה היפותטית. הערה: האפשרות הזו זמינה רק לתוספים לא מוצקים, כי היא מיועדת לשימוש רק במהלך פיתוח התוסף.

פרמטרים

החזרות

  • יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

updateDynamicRules()

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

שינוי של קבוצת הכללים הדינמיים הנוכחית של התוסף. קודם מסירים את הכללים עם המזהים שמפורטים ב-options.removeRuleIds, ואז מוסיפים את הכללים שמפורטים ב-options.addRules. הערות:

  • העדכון מתבצע כפעולה אטומית אחת: כל הכללים שצוינו מתווספים ומוסרים, או שמוחזרת שגיאה.
  • הכללים האלה נשארים בתוקף בכל סשנים בדפדפן ובכל עדכוני התוספים.
  • אי אפשר להסיר כללים סטטיים שצוינו כחלק מחבילת התוסף באמצעות הפונקציה הזו.
  • MAX_NUMBER_OF_DYNAMIC_RULES הוא המספר המקסימלי של כללים דינמיים שאפשר להוסיף באמצעות תוסף. מספר כללי האבטחה הלא בטוחים לא יכול לחרוג מ-MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES.

פרמטרים

  • אפשרויות

    UpdateRuleOptions

    Chrome מגרסה 87 ואילך
  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    () => void

החזרות

  • Promise<void>

    Chrome מגרסה 91 ואילך

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

updateEnabledRulesets()

Promise 
chrome.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
  callback?: function,
)

עדכון של קבוצת כללי ה-ruleset הסטטיים המופעלים בתוסף. קודם מסירים את כללי המדיניות עם המזהים שמפורטים ב-options.disableRulesetIds, ואז מוסיפים את כללי המדיניות שמפורטים ב-options.enableRulesetIds. חשוב לזכור שקבוצת כללי המדיניות הסטטיים המופעלים נשמרת בין סשנים, אבל לא בין עדכוני התוספים. כלומר, מפתח המניפסט rule_resources יקבע את קבוצת כללי המדיניות הסטטיים המופעלים בכל עדכון של התוסף.

פרמטרים

  • אפשרויות

    UpdateRulesetOptions

    Chrome מגרסה 87 ואילך
  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    () => void

החזרות

  • Promise<void>

    Chrome מגרסה 91 ואילך

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

updateSessionRules()

Promise Chrome מגרסה 90 ואילך 
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
  callback?: function,
)

שינוי של קבוצת הכללים הנוכחית ברמת הסשן של התוסף. קודם מסירים את הכללים עם המזהים שמפורטים ב-options.removeRuleIds, ואז מוסיפים את הכללים שמפורטים ב-options.addRules. הערות:

  • העדכון מתבצע כפעולה אטומית אחת: כל הכללים שצוינו מתווספים ומוסרים, או שמוחזרת שגיאה.
  • הכללים האלה לא נשמרים בין סשנים, והם נשמרים בזיכרון.
  • MAX_NUMBER_OF_SESSION_RULES הוא המספר המקסימלי של כללי סשן שאפשר להוסיף באמצעות תוסף.

פרמטרים

  • אפשרויות

    UpdateRuleOptions

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    () => void

החזרות

  • Promise<void>

    Chrome מגרסה 91 ואילך

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

updateStaticRules()

Promise Chrome מגרסה 111 ואילך 
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
  callback?: function,
)

השבתה והפעלה של כללים סטטיים ספציפיים ב-Ruleset. שינויים בכללים ששייכים ל-Ruleset מושבת ייכנסו לתוקף בפעם הבאה שהוא יופעל.

פרמטרים

  • אפשרויות

    UpdateStaticRulesOptions

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    () => void

החזרות

  • Promise<void>

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

אירועים

onRuleMatchedDebug

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

האירוע מופעל כשמתבצע התאמה בין כלל לבקשה. האפשרות הזו זמינה רק לתוספים מסוג unpacked עם ההרשאה "declarativeNetRequestFeedback", כי היא מיועדת לשימוש למטרות ניפוי באגים בלבד.

פרמטרים