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"
    },
    ...
    ]
  }
  ...
}

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

בדיקה מזורזת

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

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

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

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

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

כללי בטיחות

כללים בטוחים מוגדרים ככללים עם פעולה block, allow, allowAllRequests או upgradeScheme. הכללים האלה כפופים למכסה גדולה יותר של כללים דינמיים.

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

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

    string

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

GetRulesFilter

Chrome 111 ואילך

תכונות

  • ruleIds

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

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

HeaderOperation

Chrome 86 ואילך

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

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

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

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

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

IsRegexSupportedResult

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

תכונות

  • isSupported

    boolean

  • סיבה

    UnsupportedRegexReason אופציונלי

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

MatchedRule

תכונות

  • ruleId

    number

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

  • rulesetId

    string

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

MatchedRuleInfo

תכונות

  • כלל

    MatchedRule

  • tabId

    number

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

  • timeStamp

    number

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

MatchedRuleInfoDebug

תכונות

MatchedRulesFilter

תכונות

  • minTimeStamp

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

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

  • tabId

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

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

ModifyHeaderInfo

Chrome 86 ואילך

תכונות

  • כותרת

    string

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

  • פעולה

    HeaderOperation

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

  • value

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

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

QueryKeyValue

תכונות

  • key

    string

  • replaceOnly

    ערך בוליאני אופציונלי

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

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

  • value

    string

QueryTransform

תכונות

  • addOrReplaceParams

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

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

  • removeParams

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

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

Redirect

תכונות

  • extensionPath

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

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

  • regexSubstitution

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

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

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

    URLTransform אופציונלי

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

  • כתובת אתר

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

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

RegexOptions

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

תכונות

  • isCaseSensitive

    ערך בוליאני אופציונלי

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

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

    string

    ה-Expresson הרגיל שצריך לבדוק.

  • requireCapturing

    ערך בוליאני אופציונלי

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

RequestDetails

תכונות

  • documentId

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

    Chrome 106 ואילך

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

  • documentLifecycle

    DocumentLifecycle אופציונלי

    Chrome 106 ואילך

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

  • frameId

    number

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

  • frameType

    FrameType אופציונלי

    Chrome 106 ואילך

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

  • יוזם

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

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

  • method

    string

    שיטת HTTP סטנדרטית.

  • parentDocumentId

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

    Chrome 106 ואילך

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

  • parentFrameId

    number

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

  • requestId

    string

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

  • tabId

    number

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

  • סוג

    ResourceType

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

  • כתובת אתר

    string

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

RequestMethod

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

בשדה הזה מתוארת ה-method של בקשת ה-HTTP של בקשת הרשת.

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

"connect"

"get"

"head"

"options"

"patch"

"post"

"put"

ResourceType

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

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

"main_frame"

"sub_frame"

"stylesheet"

"script"

"image"

"font"

"xmlhttprequest"

"csp_report"

"media"

"websocket"

"webtransport"

"webbundle"

Rule

תכונות

  • פעולה

    RuleAction

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

  • מצב

    RuleCondition

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

  • id

    number

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

  • הקמפיין

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

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

RuleAction

תכונות

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

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

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

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

    הוצא משימוש החל מגרסה 101 של Chrome

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

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

  • excludedDomains

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

    הוצא משימוש החל מגרסה 101 של Chrome

    במקום זאת, אתם יכולים להשתמש ב-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

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

    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 מקודדים ב-utf-8.

  • requestDomains

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

    Chrome 101 ואילך

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

    הערות:

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

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

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

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

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

  • resourceTypes

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

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

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

  • tabIds

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

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

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

  • urlFilter

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

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

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

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

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

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

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

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

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

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

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

Ruleset

תכונות

  • פעיל

    boolean

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

  • id

    string

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

  • נתיב

    string

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

RulesMatchedDetails

תכונות

  • rulesMatchedInfo

    MatchedRuleInfo[]

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

TabActionCountUpdate

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

תכונות

  • הוסף

    number

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

  • tabId

    number

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

TestMatchOutcomeResult

Chrome 103 ואילך

תכונות

  • matchedRules

    MatchedRule[]

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

TestMatchRequestDetails

Chrome 103 ואילך

תכונות

  • יוזם

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

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

  • method

    RequestMethod אופציונלי

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

  • tabId

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

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

  • סוג

    ResourceType

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

  • כתובת אתר

    string

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

UnsupportedRegexReason

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

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

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

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

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

UpdateRuleOptions

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

תכונות

  • addRules

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

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

  • removeRuleIds

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

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

UpdateRulesetOptions

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

תכונות

  • disableRulesetIds

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

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

  • enableRulesetIds

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

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

UpdateStaticRulesOptions

Chrome 111 ואילך

תכונות

  • disableRuleIds

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

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

  • enableRuleIds

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

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

  • rulesetId

    string

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

URLTransform

תכונות

  • מקטע (fragment)

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

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

  • מארח

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

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

  • סיסמה

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

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

  • נתיב

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

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

  • יציאה

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

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

  • שאילתה

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

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

  • queryTransform

    QueryTransform אופציונלי

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

  • סכמה

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

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

  • שם משתמש

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

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

תכונות

DYNAMIC_RULESET_ID

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

ערך

GETMATCHEDRULES_QUOTA_INTERVAL

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

ערך

10

GUARANTEED_MINIMUM_STATIC_RULES

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

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

ערך

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

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

ערך

20

MAX_NUMBER_OF_DYNAMIC_RULES

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

ערך

30000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

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

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

ערך

50

MAX_NUMBER_OF_REGEX_RULES

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

ערך

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120 ואילך

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

ערך

5000

MAX_NUMBER_OF_STATIC_RULESETS

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

ערך

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120 ואילך

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

ערך

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120 ואילך

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

ערך

5000

SESSION_RULESET_ID

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

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

ערך

"_session"

שיטות

getAvailableStaticRuleCount()

Promise Chrome 89+ 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
)

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

פרמטרים

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

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

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

    (count: number) => void

    • ספירה

      number

החזרות

  • התחייבות<number>

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

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

getDisabledRuleIds()

Promise Chrome 111+ 
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
  callback?: function,
)

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

פרמטרים

  • אפשרויות

    GetDisabledRuleIdsOptions

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

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

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

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

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      מספר[]

החזרות

  • התחייבות<number[]>

    הבטחות נתמכות במניפסט מגרסה 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[]

החזרות

  • התחייבות<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()

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

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

פרמטרים

  • סינון

    GetRulesFilter אופציונלי

    Chrome 111 ואילך

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

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

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

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

    (rules: Rule[]) => void

החזרות

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

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

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

isRegexSupported()

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

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

פרמטרים

החזרות

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

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

setExtensionActionOptions()

מבטיח 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,
)

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

פרמטרים

החזרות

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

updateDynamicRules()

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

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

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

פרמטרים

  • אפשרויות

    UpdateRuleOptions

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

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

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

    () => void

החזרות

  • Promise<void>

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

    הבטחות נתמכות במניפסט מגרסה 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()

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

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

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

פרמטרים

  • אפשרויות

    UpdateRuleOptions

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

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

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

    () => void

החזרות

  • Promise<void>

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

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

פרמטרים