דף זה תורגם על ידי Cloud Translation API.

chrome.declarativeNetRequest

תיאור

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

הרשאות

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

יש שלושה סוגים של קבוצות כללים, והניהול שלהן מתבצע בצורה שונה.

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

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

יצירת כללים

לא משנה מה הסוג, כל כלל מתחיל עם ארבעה שדות, כמו שמוצג בהמשך. המקשים "id" ו-"priority" מקבלים מספר, אבל המקשים "action" ו-"condition" יכולים לספק כמה תנאים לחסימה ולהפניה. הכלל הבא חוסם את כל הבקשות לסקריפטים שמקורן ב-"foo.com" לכל כתובת URL עם "abc" כמחרוזת משנה.

{
  "id" : 1,
  "priority": 1,
  "action" : { "type" : "block" },
  "condition" : {
    "urlFilter" : "abc",
    "initiatorDomains" : ["foo.com"],
    "resourceTypes" : ["script"]
  }
}

התאמה לכתובת URL

ה-API ‏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.

לפני גרסה 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. הרשימה הלבנה הזו היא תלוית אותיות רישיות (באג 449152902).

כשמוסיפים כותרת לבקשה או לתשובה, הדפדפן ישתמש במפריד המתאים, אם אפשר.

דוגמאות

דוגמאות לקוד

עדכון כללים דינמיים

בדוגמה הבאה אפשר לראות איך מפעילים את 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 אופציונלי

‫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

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

number

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

MatchedRuleInfoDebug

מאפיינים

בקשה

RequestDetails

פרטים על הבקשה שהכלל התאים לה.
כלל

MatchedRule

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 שצוין תלוי אותיות רישיות (case-sensitive). ברירת המחדל היא True.
ביטוי רגולרי (regex)

מחרוזת

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

boolean אופציונלי

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

RequestDetails

מאפיינים

documentId

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

‫Chrome 106 ואילך

המזהה הייחודי של מסמך ה-iframe, אם הבקשה הזו היא עבור iframe.
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'

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

סוג הפעולה לביצוע.

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

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

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

בהמתנה

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

הערות:
- מותרים גם תת-דומיינים כמו 'a.example.com'.
- הערכים חייבים לכלול רק תווי ASCII.
- צריך להשתמש בקידוד Punycode לדומיינים בינלאומיים.
- גם תת-דומיינים של הדומיינים שמופיעים ברשימה מוחרגים.
- עבור בקשות ללא מסגרת משויכת ברמה העליונה (למשל בקשות שהופעלו על ידי ServiceWorker), נלקח בחשבון הדומיין של יוזם הבקשה.
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 תואם לבקשות שלא מגיעות מכרטיסייה. אסור להשתמש ברשימה ריקה. האפשרות הזו נתמכת רק בכללים בהיקף הסשן.
topDomains

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

בהמתנה

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

הערות:
- מותרים גם תת-דומיינים כמו 'a.example.com'.
- הערכים חייבים לכלול רק תווי ASCII.
- צריך להשתמש בקידוד Punycode לדומיינים בינלאומיים.
- המערכת תתאים גם תת-דומיינים של הדומיינים שמופיעים ברשימה.
- עבור בקשות ללא מסגרת משויכת ברמה העליונה (למשל בקשות שהופעלו על ידי ServiceWorker), נלקח בחשבון הדומיין של יוזם הבקשה.
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.

RuleConditionKeys

בהמתנה

Enum

‪"urlFilter"

‪"regexFilter"

‪"isUrlFilterCaseSensitive"

‪"initiatorDomains"

‫"excludedInitiatorDomains"

‫"requestDomains"

‫"excludedRequestDomains"

‫"topDomains"

‫‎"excludedTopDomains"

‫"domains"

‎"excludedDomains"

‎"resourceTypes"

‫"excludedResourceTypes"

‫"requestMethods"

‫"excludedRequestMethods"

‫"domainType"

"tabIds"

‫"excludedTabIds"

‪"responseHeaders"

‫"excludedResponseHeaders"

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, כלומר הבקשה לא קשורה לכרטיסייה.
topUrl

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

בהמתנה

כתובת ה-URL של המסגרת ברמה העליונה שמשויכת לבקשה (אם יש כזו).
סוג

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

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

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

ערך

‫5,000

MAX_NUMBER_OF_STATIC_RULESETS

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

ערך

‫100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

‫Chrome 120 ואילך

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

ערך

‫5,000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

‫Chrome 120 ואילך

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

ערך

‫5,000

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 הנתון שמושבתים כרגע.

פרמטרים

options

GetDisabledRuleIdsOptions

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

החזרות

Promise<number[]>

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

getDynamicRules()

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

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

פרמטרים

סינון

‫GetRulesFilter optional

‫Chrome 111 ואילך

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

החזרות

Promise<Rule[]>

‫Chrome 91 ואילך

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

getEnabledRulesets()

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

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

החזרות

Promise<string[]>

‫Chrome 91 ואילך

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

getMatchedRules()

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

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

פרמטרים

סינון

‫MatchedRulesFilter אופציונלי

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

החזרות

Promise<RulesMatchedDetails>

‫Chrome 91 ואילך

הבטחה שמושלמת אחרי שליפת רשימת הכללים התואמים. במקרה של שגיאה, ה-Promise יידחה. יכולות להיות לכך כמה סיבות, למשל: אין לכם הרשאות מספיקות או חרגתם מהמכסה.

getSessionRules()

‫Chrome 90 ואילך

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

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

פרמטרים

סינון

‫GetRulesFilter optional

‫Chrome 111 ואילך

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

החזרות

Promise<Rule[]>

‫Chrome 91 ואילך

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

isRegexSupported()

‫Chrome 87 ואילך

chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
): Promise<IsRegexSupportedResult>

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

פרמטרים

regexOptions

RegexOptions

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

החזרות

Promise<IsRegexSupportedResult>

‫Chrome 91 ואילך

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

setExtensionActionOptions()

‫Chrome 88 ואילך

chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
): Promise<void>

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

פרמטרים

options

ExtensionActionOptions

החזרות

Promise<void>

‫Chrome 91 ואילך

testMatchOutcome()

‫Chrome 103 ואילך

chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
): Promise<TestMatchOutcomeResult>

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

פרמטרים

בקשה

TestMatchRequestDetails

החזרות

Promise<TestMatchOutcomeResult>

הבטחה שמושלמת עם פרטי הכללים התואמים.

updateDynamicRules()

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

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

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

פרמטרים

options

UpdateRuleOptions

‫Chrome 87 ואילך

החזרות

Promise<void>

‫Chrome 91 ואילך

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

updateEnabledRulesets()

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

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

פרמטרים

options

UpdateRulesetOptions

‫Chrome 87 ואילך

החזרות

Promise<void>

‫Chrome 91 ואילך

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

updateSessionRules()

‫Chrome 90 ואילך

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

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

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

פרמטרים

options

UpdateRuleOptions

החזרות

Promise<void>

‫Chrome 91 ואילך

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

updateStaticRules()

‫Chrome 111 ואילך

chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
): Promise<void>

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

פרמטרים

options

UpdateStaticRulesOptions

החזרות

Promise<void>

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

אירועים

onRuleMatchedDebug

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

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

פרמטרים

callback

פונקציה

הפרמטר callback נראה כך:
```
(info: MatchedRuleInfoDebug) => void
```
- מידע
  
  MatchedRuleInfoDebug

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

תיאור

הרשאות

זמינות

מניפסט

כללים וקבוצות כללים

קבוצות כללים דינמיות וקבוצות כללים ברמת הסשן

קבוצות כללים סטטיות

בדיקה מהירה

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

יצירת כללים

התאמה לכתובת URL

תחביר של מסנן כתובות URL

ביטויים רגולריים

כתיבת תנאים טובים לכתובות URL

הערכת הכלל

לפני הבקשה

לפני שליחת כותרות הבקשות

אחרי שמקבלים תשובה

כללים בטוחים

מגבלות על כללים

כללים סטטיים

כללים של סשנים

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

כללים שמשתמשים בביטויים רגולריים

אינטראקציות עם Service Workers

משאבים שאפשר לגשת אליהם באינטרנט

שינוי הכותרת

דוגמאות

דוגמאות לקוד

עדכון כללים דינמיים

עדכון של קבוצות כללים סטטיות

דוגמאות לכללים

המפתח 'priority'

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

כותרות

סוגים

DomainType

Enum

ExtensionActionOptions

מאפיינים

GetDisabledRuleIdsOptions

מאפיינים

GetRulesFilter

מאפיינים

HeaderInfo

מאפיינים

HeaderOperation

Enum

IsRegexSupportedResult

מאפיינים

MatchedRule

מאפיינים

MatchedRuleInfo

מאפיינים

MatchedRuleInfoDebug

מאפיינים

MatchedRulesFilter

מאפיינים

ModifyHeaderInfo

מאפיינים

QueryKeyValue

מאפיינים

QueryTransform

מאפיינים

Redirect

מאפיינים

RegexOptions

מאפיינים

RequestDetails

מאפיינים

RequestMethod

Enum

ResourceType

Enum

Rule

מאפיינים

RuleAction

מאפיינים

RuleActionType

chrome.declarativeNetRequest