chrome.declarativeNetRequest

תיאור

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

הרשאות

declarativeNetRequest
declarativeNetRequestWithHostAccess

ההרשאות 'declarativeNetRequest' ו-'declarativeNetRequestWithHostAccess' מאפשרות לבצע את אותן פעולות. ההבדל ביניהן הוא מתי נדרשות או ניתנות הרשאות.

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

זמינות

‫Chrome 84 ואילך

מניפסט

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

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

בדיקה מהירה

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

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

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

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

מסיבות שקשורות לביצועים, יש גם מגבלות על מספר הכללים וקבוצות הכללים שאפשר להפעיל בו-זמנית. מתקשרים למספר 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

ה-API של בקשות רשת דקלרטיביות מאפשר להתאים כתובות 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.

לפני Chrome 120, הייתה מגבלה של 5,000 כללים דינמיים וכללים של סשנים ביחד.

כללים דינמיים

לתוסף יכולים להיות לפחות 5,000 כללים דינמיים. הוא נחשף כMAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES.

החל מ-Chrome 121, יש מגבלה גדולה יותר של 30,000 כללים שזמינים לכללים דינמיים בטוחים, שמוצגים כ-MAX_NUMBER_OF_DYNAMIC_RULES. כל כלל לא בטוח שנוסף במסגרת המגבלה של 5,000 ייכלל גם הוא במגבלה הזו.

לפני גרסה Chrome 120, הייתה מגבלה של 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 Workers

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

‫Chrome 88 ואילך

מאפיינים

  • displayActionCountAsBadgeText

    ‫boolean אופציונלי

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

  • tabUpdate

    ‫TabActionCountUpdate optional

    ‫Chrome 89 ואילך

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

GetDisabledRuleIdsOptions

‫Chrome 111 ואילך

מאפיינים

  • rulesetId

    מחרוזת

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

GetRulesFilter

‫Chrome 111 ואילך

מאפיינים

  • ruleIds

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

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

HeaderInfo

‫Chrome 128 ואילך

מאפיינים

  • excludedValues

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

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

  • כותרת

    מחרוזת

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

  • values

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

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

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

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

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

HeaderOperation

‫Chrome 86 ואילך

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

Enum

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

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

‫"remove"
מסיר את כל הערכים של הכותרת שצוינה.

IsRegexSupportedResult

‫Chrome 87 ואילך

מאפיינים

  • isSupported

    בוליאני

  • reason

    ‫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 ואילך

מאפיינים

  • כותרת

    מחרוזת

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

  • פעולה

    HeaderOperation

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

  • ערך

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

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

QueryKeyValue

מאפיינים

  • מקש

    מחרוזת

  • replaceOnly

    ‫boolean אופציונלי

    Chrome 94+

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

  • ערך

    מחרוזת

QueryTransform

מאפיינים

  • addOrReplaceParams

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

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

  • removeParams

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

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

Redirect

מאפיינים

  • extensionPath

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

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

  • regexSubstitution

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

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

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

    ‫URLTransform אופציונלי

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

  • כתובת אתר

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

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

RegexOptions

‫Chrome 87 ואילך

מאפיינים

  • isCaseSensitive

    ‫boolean אופציונלי

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

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

    מחרוזת

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

  • requireCapturing

    ‫boolean אופציונלי

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

RequestDetails

מאפיינים

  • documentId

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

    ‫Chrome 106 ואילך

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

  • documentLifecycle

    ‫DocumentLifecycle אופציונלי

    ‫Chrome 106 ואילך

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

  • frameId

    number

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

  • frameType

    ‫FrameType אופציונלי

    ‫Chrome 106 ואילך

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

  • מפעיל

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

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

  • method

    מחרוזת

    שיטת HTTP רגילה.

  • parentDocumentId

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

    ‫Chrome 106 ואילך

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

  • parentFrameId

    number

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

  • requestId

    מחרוזת

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

  • tabId

    number

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

  • סוג

    ResourceType

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

  • כתובת אתר

    מחרוזת

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

RequestMethod

‫Chrome 91 ואילך

המאפיין הזה מתאר את שיטת בקשת ה-HTTP של בקשה לרשת.

Enum

‫"connect"

'מחיקה'

‎"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

מתאר את סוג הפעולה שיש לבצע אם יש התאמה ל-RuleCondition מסוים.

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

    ‫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[] optional

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

  • excludedResponseHeaders

    ‫HeaderInfo[] optional

    ‫Chrome 128 ואילך

    הכלל לא תואם אם הבקשה תואמת לאף תנאי של כותרת תגובה ברשימה הזו (אם צוין). אם מציינים גם את excludedResponseHeaders וגם את responseHeaders, המאפיין excludedResponseHeaders מקבל עדיפות.

  • excludedTabIds

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

    ‫Chrome 92 ואילך

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

  • initiatorDomains

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

    ‫Chrome 101 ואילך

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

    הערות:

    • מותרים גם תתי-דומיינים כמו a.example.com.
    • הערכים חייבים לכלול רק תווי ASCII.
    • צריך להשתמש בקידוד Punycode לדומיינים בינלאומיים.
    • ההתאמה מתבצעת מול מי שיזם את הבקשה ולא מול כתובת ה-URL של הבקשה.
    • המערכת תתאים גם תת-דומיינים של הדומיינים שמופיעים ברשימה.
  • isUrlFilterCaseSensitive

    ‫boolean אופציונלי

    האם urlFilter או regexFilter (הערך שצוין) תלוי אותיות רישיות. ברירת המחדל היא False.

  • regexFilter

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

    ביטוי רגולרי שיושווה לכתובת ה-URL של בקשת הרשת. התחביר הזה מבוסס על תחביר RE2.

    הערה: אפשר לציין רק אחד מהערכים urlFilter או regexFilter.

    הערה: התג regexFilter חייב לכלול רק תווים מסוג ASCII. ההתאמה מתבצעת מול כתובת URL שבה המארח מקודד בפורמט punycode (במקרה של דומיינים בינלאומיים), וכל שאר התווים שאינם ASCII מקודדים בכתובת ה-URL בפורמט UTF-8.

  • requestDomains

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

    ‫Chrome 101 ואילך

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

    הערות:

    • מותרים גם תתי-דומיינים כמו a.example.com.
    • הערכים חייבים לכלול רק תווי ASCII.
    • צריך להשתמש בקידוד Punycode לדומיינים בינלאומיים.
    • המערכת תתאים גם תת-דומיינים של הדומיינים שמופיעים ברשימה.
  • requestMethods

    ‫RequestMethod[] אופציונלי

    ‫Chrome 91 ואילך

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

    הערה: אם מציינים תנאי כלל requestMethods, גם בקשות שאינן HTTP(s) ייכללו, אבל אם מציינים excludedRequestMethods, הן לא ייכללו.

  • resourceTypes

    ‫ResourceType[] optional

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

    הערה: חובה לציין את המאפיין הזה בכללי allowAllRequests, והוא יכול לכלול רק את סוגי המשאבים sub_frame ו-main_frame.

  • responseHeaders

    ‫HeaderInfo[] optional

    ‫Chrome 128 ואילך

    הכלל תואם אם הבקשה תואמת לתנאי כלשהו של כותרת תגובה ברשימה הזו (אם צוין).

  • tabIds

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

    ‫Chrome 92 ואילך

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

  • urlFilter

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

    התבנית שמושוות לכתובת ה-URL של בקשת הרשת. מבנים נתמכים:

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

    ‫'|' : עוגן שמאלי/ימני: אם משתמשים בו באחד מקצוות התבנית, הוא מציין את ההתחלה או הסוף של כתובת ה-URL, בהתאמה.

    ‫'||' : עוגן של שם דומיין: אם משתמשים בו בתחילת התבנית, הוא מציין את ההתחלה של (תת-)דומיין של כתובת ה-URL.

    ‫'^' : תו מפריד: התו הזה תואם לכל דבר חוץ מאות, ספרה או אחד מהתווים הבאים: _, -, . או %. ההתאמה תהיה גם לסוף כתובת ה-URL.

    לכן, urlFilter מורכב מהחלקים הבאים: (עוגן אופציונלי בצד ימין/שם הדומיין) + תבנית + (עוגן אופציונלי בצד שמאל).

    אם לא מציינים כתובת URL, כל כתובות ה-URL תואמות. אסור להשתמש במחרוזת ריקה.

    אסור להשתמש בתבנית שמתחילה ב-||*. במקום זאת, אתם צריכים להשתמש ב-*.

    הערה: אפשר לציין רק אחד מהערכים urlFilter או regexFilter.

    הערה: התג urlFilter חייב לכלול רק תווים מסוג ASCII. ההתאמה מתבצעת מול כתובת URL שבה המארח מקודד בפורמט punycode (במקרה של דומיינים בינלאומיים), וכל שאר התווים שאינם ASCII מקודדים בכתובת ה-URL בפורמט 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

‫Chrome 103 ואילך

מאפיינים

  • matchedRules

    MatchedRule[]

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

TestMatchRequestDetails

‫Chrome 103 ואילך

מאפיינים

  • מפעיל

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

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

  • method

    ‫RequestMethod אופציונלי

    ה-method הסטנדרטית של ה-HTTP של הבקשה ההיפותטית. ברירת המחדל היא get לבקשות HTTP, והיא מתעלמת מבקשות שאינן HTTP.

  • responseHeaders

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

    ‫Chrome 129 ואילך

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

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

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

  • removeRuleIds

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

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

UpdateRulesetOptions

‫Chrome 87 ואילך

מאפיינים

  • disableRulesetIds

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

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

  • enableRulesetIds

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

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

UpdateStaticRulesOptions

‫Chrome 111 ואילך

מאפיינים

  • 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

Chrome 94+

המספר המקסימלי של תוספים סטטיים (Rulesets) שתוסף יכול להפעיל בכל רגע נתון.

ערך

‫50

MAX_NUMBER_OF_REGEX_RULES

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

ערך

1000

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

‫Chrome 90 ואילך

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

ערך

‎"_session"

Methods

getAvailableStaticRuleCount()

‫Chrome 89 ואילך 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(): Promise<number>

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

החזרות

  • Promise<number>

    ‫Chrome 91 ואילך

getDisabledRuleIds()

‫Chrome 111 ואילך 
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
): Promise<number[]>

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

פרמטרים

החזרות

  • Promise<number[]>

getDynamicRules()

chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
): Promise<Rule[]>

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

פרמטרים

  • סינון

    ‫GetRulesFilter אופציונלי

    ‫Chrome 111 ואילך

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

החזרות

  • Promise<Rule[]>

    ‫Chrome 91 ואילך

getEnabledRulesets()

chrome.declarativeNetRequest.getEnabledRulesets(): Promise<string[]>

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

החזרות

  • Promise<string[]>

    ‫Chrome 91 ואילך

getMatchedRules()

chrome.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
): Promise<RulesMatchedDetails>

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

פרמטרים

  • סינון

    ‫MatchedRulesFilter אופציונלי

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

החזרות

getSessionRules()

‫Chrome 90 ואילך 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
): Promise<Rule[]>

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

פרמטרים

  • סינון

    ‫GetRulesFilter אופציונלי

    ‫Chrome 111 ואילך

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

החזרות

  • Promise<Rule[]>

    ‫Chrome 91 ואילך

isRegexSupported()

‫Chrome 87 ואילך 
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
): Promise<IsRegexSupportedResult>

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

פרמטרים

  • regexOptions

    RegexOptions

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

החזרות

setExtensionActionOptions()

‫Chrome 88 ואילך 
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
): Promise<void>

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

פרמטרים

החזרות

  • Promise<void>

    ‫Chrome 91 ואילך

testMatchOutcome()

‫Chrome 103 ואילך 
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
): Promise<TestMatchOutcomeResult>

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

פרמטרים

החזרות

updateDynamicRules()

chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
): Promise<void>

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

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

פרמטרים

החזרות

  • Promise<void>

    ‫Chrome 91 ואילך

updateEnabledRulesets()

chrome.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
): Promise<void>

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

פרמטרים

החזרות

  • Promise<void>

    ‫Chrome 91 ואילך

updateSessionRules()

‫Chrome 90 ואילך 
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
): Promise<void>

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

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

פרמטרים

החזרות

  • Promise<void>

    ‫Chrome 91 ואילך

updateStaticRules()

‫Chrome 111 ואילך 
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
): Promise<void>

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

פרמטרים

החזרות

  • Promise<void>

אירועים

onRuleMatchedDebug

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

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

פרמטרים