chrome.declarativeNetRequest

תיאור

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

הרשאות

declarativeNetRequest
declarativeNetRequestWithHostAccess

declarativeNetRequestFeedback
host_permissions

זמינות

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

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

יצירת כללים

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

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

תווים תואמים של urlFilter

המפתח "condition" של כלל מאפשר מפתח "urlFilter" לפעולה על כתובות URL בדומיין שצוין. יוצרים תבניות באמצעות אסימונים להתאמת תבניות. בהמשך מופיעות כמה דוגמאות.

urlFilter התאמות לא מתאים
"abc" https://abcd.com
https://example.com/abcd		 https://ab.com
"abc*d" https://abcd.com
https://example.com/abcxyzd		 https://abc.com
"||a.example.com" https://a.example.com/
https://b.a.example.com/xyz		 https://example.com/
"|https*" https://example.com http://example.com/
http://https.com
"example*^123|" https://example.com/123
http://abc.com/example?123		 https://example.com/1234
https://abc.com/example0123

קביעת סדרי עדיפויות לכללים

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

  1. העדיפות נקבעת לכללים בתוך תוסף.
  2. אם יותר מהרחבה אחת יכולה להחיל כלל על בקשה, המערכת קובעת את העדיפות של כל ההרחבות שתואמות לבקשה מסוימת.

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

קביעת סדר עדיפויות לכללים בתוסף

בתוך תוסף יחיד, התהליך הבא קובע את סדר העדיפויות:

  1. הכלל עם העדיפות הגבוהה ביותר שהוגדרה על ידי המפתח (במילים אחרות, השדה "priority") מוחזר.

  2. אם יש יותר מכלל אחד עם העדיפות הכי גבוהה שהוגדרה על ידי המפתח, הכללים מקבלים עדיפות לפי השדה "action", בסדר הבא:

    1. allow
    2. allowAllRequests
    3. block
    4. upgradeScheme
    5. redirect

  3. אם סוג הפעולה הוא לא block או redirect, המערכת מעריכה את כל כללי modifyHeaders התואמים. חשוב לדעת שאם יש כללים עם עדיפות שהוגדרה על ידי מפתח ונמוכה מהעדיפות שצוינה עבור allow ו-allowAllRequests, המערכת מתעלמת מהכללים האלה.

  4. אם כמה כללים משנים את אותו כותר, השינוי נקבע לפי השדה "priority" שהוגדר על ידי המפתח ולפי הפעולות שצוינו.

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

הגדרת עדיפות לכללים בין תוספים

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

  1. הכללים מדורגים לפי סדר העדיפות הבא, שמוגדר בשדה "action":

    1. block
    2. redirect או upgradeScheme
    3. allow או allowAllRequests

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

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

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

כללים סטטיים

כללים סטטיים הם כללים שמוגדרים בקובצי כללים שהוצהרו בקובץ המניפסט. תוסף יכול לציין עד 50 ערכות כללים סטטיות כחלק ממפתח המניפסט "rule_resources", אבל אפשר להפעיל רק 10 מהן בכל פעם. האחרון נקרא MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. יחד, ערכות הכללים האלה מבטיחות לפחות 30,000 כללים. הפעולה הזו נקראת GUARANTEED_MINIMUM_STATIC_RULES.

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

כללים דינמיים וכללים בזמן פעילות באתר

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

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

אפשר להשתמש בביטויים רגולריים בכל סוגי הכללים, אבל המספר הכולל של כללים מסוג ביטוי רגולרי לא יכול לעלות על 1,000. המספר הזה נקרא MAX_NUMBER_OF_REGEX_RULES.

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

rules_1.json: Rule with id 1 specified a more complext 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" בקובץ המניפסט.

דוגמאות

דוגמאות לקוד

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

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

מאפיינים

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

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

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()

Promise Chrome 89 ואילך 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
): Promise<number>

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

פרמטרים

  • callback

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

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

    (count: number) => void

    • ספירה

      number

החזרות

  • Promise<number>

    ‫Chrome 91 ואילך

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

getDisabledRuleIds()

Promise Chrome 111+ 
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
  callback?: function,
): Promise<number[]>

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

פרמטרים

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

  • callback

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

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

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      number[]

החזרות

  • Promise<number[]>

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

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

getDynamicRules()

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

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

פרמטרים

  • סינון

    ‫GetRulesFilter optional

    ‫Chrome 111 ואילך

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

  • callback

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

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

    (rules: Rule[]) => void

החזרות

  • Promise<Rule[]>

    ‫Chrome 91 ואילך

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

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

getEnabledRulesets()

Promise 
chrome.declarativeNetRequest.getEnabledRulesets(
  callback?: function,
): Promise<string[]>

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

פרמטרים

  • callback

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

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

    (rulesetIds: string[]) => void

    • rulesetIds

      string[]

החזרות

  • Promise<string[]>

    ‫Chrome 91 ואילך

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

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

getMatchedRules()

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

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

פרמטרים

החזרות

  • ‫Chrome 91 ואילך

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

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

getSessionRules()

Promise Chrome 90+ 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
  callback?: function,
): Promise<Rule[]>

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

פרמטרים

  • סינון

    ‫GetRulesFilter optional

    ‫Chrome 111 ואילך

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

  • callback

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

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

    (rules: Rule[]) => void

החזרות

  • Promise<Rule[]>

    ‫Chrome 91 ואילך

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

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

isRegexSupported()

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

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

פרמטרים

החזרות

  • ‫Chrome 91 ואילך

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

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

setExtensionActionOptions()

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

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

פרמטרים

  • callback

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

    ‫Chrome 89 ואילך

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 91 ואילך

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

testMatchOutcome()

Promise Chrome 103+ 
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
): Promise<TestMatchOutcomeResult>

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

פרמטרים

החזרות

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

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

updateDynamicRules()

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

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

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

פרמטרים

  • ‫Chrome 87 ואילך
  • callback

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

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 91 ואילך

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

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

updateEnabledRulesets()

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

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

פרמטרים

  • ‫Chrome 87 ואילך
  • callback

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

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 91 ואילך

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

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

updateSessionRules()

Promise Chrome 90+ 
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
  callback?: function,
): Promise<void>

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

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

פרמטרים

  • callback

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

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 91 ואילך

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

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

updateStaticRules()

Promise Chrome 111+ 
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
  callback?: function,
): Promise<void>

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

פרמטרים

  • callback

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

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

    () => void

החזרות

  • Promise<void>

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

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

אירועים

onRuleMatchedDebug

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

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

פרמטרים