chrome.declarativeNetRequest

תיאור

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

הרשאות

declarativeNetRequest
declarativeNetRequestWithHostAccess

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

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

זמינות

Chrome 84 ומעלה

מניפסט

בנוסף להרשאות שתוארו קודם לכן, סוגים מסוימים של קבוצות כללים (כללים סטטיים) מחייבים הצהרה על מפתח המניפסט "declarative_net_request", שעליו להיות מילון עם מפתח יחיד שנקרא "rule_resources". המפתח הזה הוא מערך שמכיל מילונים מסוג Ruleset, כמוצג בהמשך. (שימו לב שהשם ' Ruleset' לא מופיע ב-JSON של המניפסט כי הוא רק מערך). ערכות כללים סטטיות מוסברות בהמשך מסמך זה.

{
  "name": "My extension",
  ...

  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    }, {
      "id": "ruleset_2",
      "enabled": false,
      "path": "rules_2.json"
    }]
  },
  "permissions": [
    "declarativeNetRequest",
    "declarativeNetRequestFeedback",
  ],
  "host_permissions": [
    "http://www.blogger.com/*",
    "http://*.google.com/*"
  ],
  ...
}

מושגים ושימוש

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

  • חסימה של בקשת רשת.
  • מומלץ לשדרג את הסכימה (מ-http ל-https).
  • כדי למנוע חסימת בקשה, אפשר לשלול כללים חסומים תואמים.
  • הפניה אוטומטית של בקשת רשת.
  • לשנות את הכותרות של הבקשה או התשובות.

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

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

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

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

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

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

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

מערכי כללים סטטיים

בשונה מכללים דינמיים וכללים סטטיים, הכללים הסטטיים נארזים, מותקנים ומתעדכנים במהלך ההתקנה או השדרוג של התוסף. הם מאוחסנים בקובצי כללים בפורמט JSON, שמצוינים לתוסף באמצעות המפתחות "declarative_net_request" ו-"rule_resources" כפי שמתואר למעלה, וכן במילון Ruleset אחד או יותר. מילון Ruleset מכיל נתיב לקובץ הכללים, מזהה עבור קבוצת הכללים שכלולה בקובץ, ואם קבוצת הכללים מופעלת או מושבתת. שני הערכים האחרונים חשובים בעת הפעלה או השבתה של מערכת כללים באופן פרוגרמטי.

{
  ...
  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    },
    ...
    ]
  }
  ...
}

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

הפעלה והשבתה של כללים סטטיים ומערכי כללים

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

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

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

כללים סטטיים

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

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

כללי סשנים

תוסף יכול לכלול עד 5,000 כללי פעילות באתר. הוא חשוף בתור MAX_NUMBER_OF_SESSION_RULES.

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

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

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

החל מגרסה 121 של Chrome, יש מגבלה גדולה יותר של 30,000 כללים הזמינים לכללים דינמיים בטוחים, נחשפים בתור MAX_NUMBER_OF_DYNAMIC_RULES. כללים בטוחים מוגדרים ככללים עם פעולה של block, allow, allowAllRequests או upgradeScheme. גם כללים לא בטוחים שנוספו למגבלה של 5,000 ערכים ייספרו כחלק מהמגבלה.

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

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

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

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

rules_1.json: Rule with id 1 specified a more complex regex than allowed
as part of the "regexFilter" key.

אינטראקציות עם קובצי שירות (service worker)

declarativeNetRequest חל רק על בקשות שמגיעות לערימת הרשת. המדיניות הזו כוללת תגובות ממטמון HTTP, אבל לא יכולה לכלול תגובות שעוברות דרך handler של onfetch של קובץ שירות (service worker). declarativeNetRequest לא תשפיע על תגובות שנוצרות על ידי קובץ השירות (service worker) או אוחזרו מ-CacheStorage, אבל היא תשפיע על קריאות ל-fetch() שמתבצעות ב-Service Worker.

משאבים נגישים באינטרנט

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

דוגמאות

דוגמאות לקוד

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

הדוגמה הבאה מציגה איך להתקשר אל updateDynamicRules(). התהליך עבור updateSessionRules() זהה.

// Get arrays containing new and old rules
const newRules = await getNewRules();
const oldRules = await chrome.declarativeNetRequest.getDynamicRules();
const oldRuleIds = oldRules.map(rule => rule.id);

// Use the arrays to update the dynamic rules
await chrome.declarativeNetRequest.updateDynamicRules({
  removeRuleIds: oldRuleIds,
  addRules: newRules
});

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

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

async function updateStaticRules(enableRulesetIds, disableCandidateIds) {
  // Create the options structure for the call to updateEnabledRulesets()
  let options = { enableRulesetIds: enableRulesetIds }
  // Get the number of enabled static rules
  const enabledStaticCount = await chrome.declarativeNetRequest.getEnabledRulesets();
  // Compare rule counts to determine if anything needs to be disabled so that
  // new rules can be enabled
  const proposedCount = enableRulesetIds.length;
  if (enabledStaticCount + proposedCount > chrome.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS) {
    options.disableRulesetIds = disableCandidateIds
  }
  // Update the enabled static rules
  await chrome.declarativeNetRequest.updateEnabledRulesets(options);
}

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

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

מקש ה'עדיפות'

בדוגמאות האלה נדרשת הרשאת מארח כדי לבצע את *://*.example.com/*.

כדי לבדוק מה העדיפות של כתובת URL מסוימת, בודקים את המפתח "priority" (בהגדרת המפתח), את המפתח "action" ואת המפתח "urlFilter". הדוגמאות האלה מתייחסות לקובץ הכללים לדוגמה שמוצג מתחת שלהן.

ניווט אל https://google.com
שני כללים חלים על כתובת ה-URL הזו: הכללים עם המזהה 1 ו-4. הכלל עם המזהה 1 חל כי פעולות מסוג "block" מקבלות עדיפות גבוהה יותר מ-"redirect" פעולות. הכללים הנותרים לא חלים כי הם מיועדים לכתובות URL ארוכות יותר.
ניווט אל https://google.com/1234
בגלל כתובת ה-URL הארוכה יותר, הכלל עם מזהה 2 תואם עכשיו בנוסף לכללים עם המזהים 1 ו-4. הכלל עם המזהה 2 חל כי "allow" בעדיפות גבוהה יותר מ-"block" ומ-"redirect".
ניווט אל https://google.com/12345
כל ארבעת הכללים תואמים לכתובת ה-URL הזו. הכלל עם המזהה 3 חל כי העדיפות שלו שהוגדרה על ידי המפתח היא הגבוהה ביותר מהקבוצה.
[
  {
    "id": 1,
    "priority": 1,
    "action": { "type": "block" },
    "condition": {"urlFilter": "google.com", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 2,
    "priority": 1,
    "action": { "type": "allow" },
    "condition": { "urlFilter": "google.com/123", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 3,
    "priority": 2,
    "action": { "type": "block" },
    "condition": { "urlFilter": "google.com/12345", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 4,
    "priority": 1,
    "action": { "type": "redirect", "redirect": { "url": "https://example.com" } },
    "condition": { "urlFilter": "google.com", "resourceTypes": ["main_frame"] }
  },
]

כתובות אתרים להפניה מחדש

בדוגמה הבאה נדרשת הרשאת מארח עבור *://*.example.com/*.

הדוגמה הבאה מראה איך להפנות בקשה מ-example.com לדף בתוך התוסף עצמו. נתיב התוסף /a.jpg מוביל אל chrome-extension://EXTENSION_ID/a.jpg, כאשר EXTENSION_ID הוא מזהה התוסף. כדי שהמשאב הזה יפעל, המניפסט צריך להצהיר על /a.jpg בתור משאב נגיש באינטרנט.

{
  "id": 1,
  "priority": 1,
  "action": { "type": "redirect", "redirect": { "extensionPath": "/a.jpg" } },
  "condition": {
    "urlFilter": "https://www.example.com",
    "resourceTypes": ["main_frame"]
  }
}

הקוד הבא משתמש במפתח "transform" כדי להפנות לתת-דומיין של example.com. הוא משתמש בעוגן של שם הדומיין ("||") כדי ליירט בקשות באמצעות כל סכימה מ-example.com. המפתח "scheme" ב-"transform" מציין שמפנה לתת-הדומיין תמיד ישתמש ב-"https".

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

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

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

כותרות

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

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

סוגים

DomainType

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

טיפוסים בני מנייה (enum)

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

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

ExtensionActionOptions

Chrome 88 ומעלה

תכונות

  • displayActionCountAsBadgeText

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

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

  • tabUpdate

    TabActionCountUpdate אופציונלי

    Chrome 89 ומעלה

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

GetDisabledRuleIdsOptions

Chrome 111 ומעלה

תכונות

  • rulesetId

    מחרוזת

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

GetRulesFilter

Chrome 111 ומעלה

תכונות

  • ruleIds

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

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

HeaderOperation

Chrome 86 ומעלה

תיאור זה מתאר את הפעולות האפשריות לכלל "modifyHeaders".

טיפוסים בני מנייה (enum)

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

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

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

IsRegexSupportedResult

Chrome 87 ומעלה

תכונות

  • isSupported

    boolean

  • סיבה

    UnsupportedRegexReason אופציונלי

    מציין את הסיבה לכך שהביטוי הרגולרי לא נתמך. הערך מצוין רק אם הערך של isSupported מוגדר כ-False.

MatchedRule

תכונות

  • ruleId

    מספר

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

  • rulesetId

    מחרוזת

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

MatchedRuleInfo

תכונות

  • כלל

    MatchedRule

  • tabId

    מספר

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

  • timeStamp

    מספר

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

MatchedRuleInfoDebug

תכונות

MatchedRulesFilter

תכונות

  • minTimeStamp

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

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

  • tabId

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

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

ModifyHeaderInfo

Chrome 86 ומעלה

תכונות

  • כותרת

    מחרוזת

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

  • פעולה

    HeaderOperation

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

  • value

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

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

QueryKeyValue

תכונות

  • key

    מחרוזת

  • replaceOnly

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

    Chrome 94 ומעלה

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

  • value

    מחרוזת

QueryTransform

תכונות

  • addOrReplaceParams

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

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

  • removeParams

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

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

Redirect

תכונות

  • extensionPath

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

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

  • regexSubstitution

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

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

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

    URLTransform אופציונלי

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

  • כתובת אתר

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

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

RegexOptions

Chrome 87 ומעלה

תכונות

  • isCaseSensitive

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

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

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

    מחרוזת

    חשבון ה-expresson הרגיל שצריך לבדוק.

  • requireCapturing

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

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

RequestDetails

תכונות

  • documentId

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

    Chrome 106 ומעלה

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

  • documentLifecycle

    DocumentLifecycle אופציונלי

    Chrome 106 ומעלה

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

  • frameId

    מספר

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

  • frameType

    FrameType אופציונלי

    Chrome 106 ומעלה

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

  • יוזם

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

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

  • method

    מחרוזת

    שיטת HTTP רגילה.

  • parentDocumentId

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

    Chrome 106 ומעלה

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

  • parentFrameId

    מספר

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

  • requestId

    מחרוזת

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

  • tabId

    מספר

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

  • סוג

    ResourceType

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

  • כתובת אתר

    מחרוזת

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

RequestMethod

Chrome 91 ומעלה

מתארת את השיטה של בקשת HTTP של בקשת רשת.

טיפוסים בני מנייה (enum)

"get"

"put"

ResourceType

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

טיפוסים בני מנייה (enum)

"main_frame"

"sub_frame"

"stylesheet"

"script"

"xmlhttprequest"

"csp_report"

"websocket"

Rule

תכונות

  • פעולה

    RuleAction

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

  • מצב

    RuleCondition

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

  • id

    מספר

    מזהה שמזהה כלל באופן ייחודי. חובה ועליו להיות >= 1.

  • הקמפיין

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

    עדיפות הכלל. ברירת המחדל היא 1. כשמציינים אותו, הערך צריך להיות >= 1.

RuleAction

תכונות

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

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

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

  • requestHeaders

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

    Chrome 86 ומעלה

    כותרות הבקשה שצריך לשנות עבור הבקשה. חוקי רק אם התכונה ruleActionType היא "modifyHeaders".

  • responseHeaders

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

    Chrome 86 ומעלה

    כותרות התגובות שצריך לשנות עבור הבקשה. חוקי רק אם התכונה ruleActionType היא "modifyHeaders".

  • סוג הפעולה שצריך לבצע.

RuleActionType

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

טיפוסים בני מנייה (enum)

"block"
חסימת בקשת הרשת.

"redirect"
הפניה מחדש של בקשת הרשת.

"allow"
אישור בקשת הרשת. הבקשה לא תיווצר אם קיים כלל הרשאה שתואם לו.

'שדרוגScheme'
צריך לשדרג את סכמת כתובת ה-URL של בקשת הרשת ל-https אם הבקשה היא http או ftp.

"modifyHeaders"
שינוי כותרות של בקשה/תגובה מבקשת הרשת.

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

RuleCondition

תכונות

  • domainType

    DomainType אופציונלי

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

  • דומיינים

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

    הוצא משימוש מאז Chrome 101

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

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

  • excludedDomains

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

    הוצא משימוש מאז Chrome 101

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

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

  • excludedInitiatorDomains

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

    Chrome 101 ומעלה

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

    הערות:

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

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

    Chrome 101 ומעלה

    הכלל לא יתאים לבקשות רשת כאשר הדומיינים תואמים לבקשה מהרשימה excludedRequestDomains. אם הרשימה ריקה או לא מופיעה, המערכת לא תחריג דומיינים. המדיניות הזו מקבלת עדיפות על פני המדיניות requestDomains.

    הערות:

    • מותר להשתמש גם בתת-דומיינים כמו "a.example.com".
    • הערכים חייבים להכיל תווי ASCII בלבד.
    • מומלץ להשתמש בקידוד Punycode לדומיינים בינלאומיים.
    • גם תת-דומיינים של הדומיינים הרשומים אינם נכללים.
  • excludedRequestMethods

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

    Chrome 91 ומעלה

    רשימת שיטות הבקשה שהכלל לא יתאים להן. יש לציין רק אחד מהערכים requestMethods ו-excludedRequestMethods. אם אף אחת מהן לא מוגדרת, המערכת תתאים לכל שיטות הבקשה.

  • excludedResourceTypes

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

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

  • excludedTabIds

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

    Chrome 92 ומעלה

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

  • initiatorDomains

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

    Chrome 101 ומעלה

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

    הערות:

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

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

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

  • regexFilter

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

    ביטוי רגולרי שיש להתאים אל כתובת ה-URL של בקשת הרשת. בהתאם לתחביר של RE2.

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

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

  • requestDomains

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

    Chrome 101 ומעלה

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

    הערות:

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

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

    Chrome 91 ומעלה

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

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

  • resourceTypes

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

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

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

  • tabIds

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

    Chrome 92 ומעלה

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

  • urlFilter

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

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

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

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

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

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

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

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

    אין להשתמש בתבנית שמתחילה ב-||*. במקומה צריך להשתמש במדיניות *.

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

    הערה: השדה urlFilter חייב לכלול תווי ASCII בלבד. הערך הזה תואם לכתובת URL שבה המארח מקודד בפורמט Punycode (במקרה של דומיינים בינלאומיים), וכל התווים האחרים שאינם מסוג ASCII מקודדים כתובת URL ב-utf-8. לדוגמה, כשכתובת ה-URL של הבקשה היא http://abc.рф?q=ф, תתבצע התאמה של urlFilter לכתובת ה-URL http://abc.xn--p1ai/?q=%D1%84.

Ruleset

תכונות

  • פעיל

    boolean

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

  • id

    מחרוזת

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

  • נתיב

    מחרוזת

    הנתיב של קבוצת הכללים של JSON ביחס לספריית התוספים.

RulesMatchedDetails

תכונות

  • rulesMatchedInfo

    MatchedRuleInfo[]

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

TabActionCountUpdate

Chrome 89 ומעלה

תכונות

  • הוסף

    מספר

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

  • tabId

    מספר

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

TestMatchOutcomeResult

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

תכונות

  • matchedRules

    MatchedRule[]

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

TestMatchRequestDetails

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

תכונות

  • יוזם

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

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

  • method

    RequestMethod אופציונלי

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

  • tabId

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

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

  • סוג

    ResourceType

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

  • כתובת אתר

    מחרוזת

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

UnsupportedRegexReason

Chrome 87 ומעלה

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

טיפוסים בני מנייה (enum)

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

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

UpdateRuleOptions

Chrome 87 ומעלה

תכונות

  • addRules

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

    כללים להוספה.

  • removeRuleIds

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

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

UpdateRulesetOptions

Chrome 87 ומעלה

תכונות

  • disableRulesetIds

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

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

  • enableRulesetIds

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

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

UpdateStaticRulesOptions

Chrome 111 ומעלה

תכונות

  • disableRuleIds

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

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

  • enableRuleIds

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

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

  • rulesetId

    מחרוזת

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

URLTransform

תכונות

  • מקטע (fragment)

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

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

  • מארח

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

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

  • סיסמה

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

    הסיסמה החדשה עבור הבקשה.

  • נתיב

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

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

  • יציאה

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

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

  • שאילתה

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

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

  • queryTransform

    QueryTransform אופציונלי

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

  • סכמה

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

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

  • שם משתמש

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

    שם המשתמש החדש עבור הבקשה.

תכונות

DYNAMIC_RULESET_ID

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

Value

GETMATCHEDRULES_QUOTA_INTERVAL

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

Value

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89 ומעלה

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

Value

30,000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

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

Value

20

MAX_NUMBER_OF_DYNAMIC_RULES

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

Value

30,000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94 ומעלה

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

Value

50

MAX_NUMBER_OF_REGEX_RULES

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

Value

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120 ומעלה

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

Value

5,000

MAX_NUMBER_OF_STATIC_RULESETS

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

Value

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120 ומעלה

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

Value

5,000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120 ומעלה

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

Value

5,000

SESSION_RULESET_ID

Chrome 90 ומעלה

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

Value

שיטות

getAvailableStaticRuleCount()

Promise Chrome 89 ומעלה 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
)

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

פרמטרים

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

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

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

    (count: number)=>void

    • ספירה

      מספר

החזרות

  • הבטחה<number>

    Chrome 91 ומעלה

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

getDisabledRuleIds()

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

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

פרמטרים

  • אפשרויות

    GetDisabledRuleIdsOptions

    מציין את מערכת הכללים לשאילתה.

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

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

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

    (disabledRuleIds: number[])=>void

    • disabledRuleIds

      מספר[]

החזרות

  • הבטחה<מספר[]>

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

getDynamicRules()

הבטחה 
chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
  callback?: function,
)

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

פרמטרים

  • סינון

    GetRulesFilter אופציונלי

    Chrome 111 ומעלה

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

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

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

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

    (rules: Rule[])=>void

החזרות

  • הבטחה<כלל[]>

    Chrome 91 ומעלה

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

getEnabledRulesets()

הבטחה 
chrome.declarativeNetRequest.getEnabledRulesets(
  callback?: function,
)

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

פרמטרים

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

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

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

    (rulesetIds: string[])=>void

    • rulesetIds

      מחרוזת[]

החזרות

  • הבטחה<string[]>

    Chrome 91 ומעלה

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

getMatchedRules()

הבטחה 
chrome.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
  callback?: function,
)

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

פרמטרים

  • סינון

    MatchedRulesFilter אופציונלי

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

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

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

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

    (details: RulesMatchedDetails)=>void

החזרות

  • Chrome 91 ומעלה

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

getSessionRules()

Promise Chrome 90+ 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
  callback?: function,
)

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

פרמטרים

  • סינון

    GetRulesFilter אופציונלי

    Chrome 111 ומעלה

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

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

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

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

    (rules: Rule[])=>void

החזרות

  • הבטחה<כלל[]>

    Chrome 91 ומעלה

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

isRegexSupported()

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

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

פרמטרים

החזרות

  • Chrome 91 ומעלה

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

setExtensionActionOptions()

Promise Chrome 88 ומעלה 
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
  callback?: function,
)

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

פרמטרים

  • אפשרויות

    ExtensionActionOptions

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

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

    Chrome 89 ומעלה

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

    ()=>void

החזרות

  • Promise<void>

    Chrome 91 ומעלה

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

testMatchOutcome()

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

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

פרמטרים

החזרות

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

updateDynamicRules()

הבטחה 
chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
  callback?: function,
)

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

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

פרמטרים

  • אפשרויות

    UpdateRuleOptions

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

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

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

    ()=>void

החזרות

  • Promise<void>

    Chrome 91 ומעלה

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

updateEnabledRulesets()

הבטחה 
chrome.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
  callback?: function,
)

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

פרמטרים

  • אפשרויות

    UpdateRulesetOptions

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

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

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

    ()=>void

החזרות

  • Promise<void>

    Chrome 91 ומעלה

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

updateSessionRules()

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

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

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

פרמטרים

  • אפשרויות

    UpdateRuleOptions

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

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

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

    ()=>void

החזרות

  • Promise<void>

    Chrome 91 ומעלה

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

updateStaticRules()

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

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

פרמטרים

  • אפשרויות

    UpdateStaticRulesOptions

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

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

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

    ()=>void

החזרות

  • Promise<void>

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

אירועים

onRuleMatchedDebug

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

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

פרמטרים