תוספי Manifest V2 הוסרו מחנות האינטרנט של Chrome ב-31 באוגוסט 2026. כדי שהתוסף יהיה זמין שוב למשתמשים, צריך להעביר אותו ל-Manifest V3.

‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

chrome.declarativeNetRequest

refresh date: 2026-09-25 robots: noindex

תיאור

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

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

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

כדי להפעיל או להשבית קבוצות כללים סטטיות, צריך להפעיל את 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

תעדוף כללים

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

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

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

תעדוף כללים בתוך תוסף

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

הכלל עם העדיפות הגבוהה ביותר שהוגדרה על ידי המפתח (כלומר, השדה "priority") מוחזר.
אם יש יותר מכלל אחד עם העדיפות הגבוהה ביותר שהוגדרה על ידי המפתח, הכללים מקבלים עדיפות באמצעות השדה "action", בסדר הבא:
1. allow
2. allowAllRequests
3. block
4. upgradeScheme
5. redirect
אם סוג הפעולה הוא לא block או redirect, המערכת בודקת את כללי modifyHeaders התואמים. חשוב לדעת שאם יש כללים עם עדיפות שהוגדרה על ידי המפתח והיא נמוכה מהעדיפות שצוינה ל-allow ול-allowAllRequests, המערכת מתעלמת מהכללים האלה.
אם כמה כללים משנים את אותה כותרת, השינוי נקבע לפי השדה "priority" שהמפתח הגדיר ולפי הפעולות שצוינו.
- אם כלל מוסיף לכותרת, כללים בעדיפות נמוכה יותר יכולים רק להוסיף לכותרת הזו. אי אפשר להגדיר ולהסיר פעולות.
- אם כלל מגדיר כותרת, כללים בעדיפות נמוכה יותר יכולים רק להוסיף לכותרת הזו. אסור לבצע שינויים אחרים.
- אם כלל מסיר כותרת, כללים בעדיפות נמוכה יותר לא יכולים לשנות את הכותרת.

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

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

הכללים מקבלים עדיפות לפי השדה "action", בסדר הבא:
1. block
2. redirect או upgradeScheme
3. allow או allowAllRequests
אם יש כמה כללים תואמים, התוסף שהותקן אחרון מקבל עדיפות.

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

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

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

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

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

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

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

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

מקורות מידע נגישים באינטרנט

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

דוגמאות

דוגמאות לקוד

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

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

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

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

‫TabActionCountUpdate אופציונלי

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

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

GetDisabledRuleIdsOptions

‫Chrome מגרסה 111 ואילך

מאפיינים

rulesetId

מחרוזת

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

GetRulesFilter

‫Chrome מגרסה 111 ואילך

מאפיינים

ruleIds

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

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

HeaderInfo

‫Chrome מגרסה 128 ואילך

מאפיינים

excludedValues

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

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

מחרוזת

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

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

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

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

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

אפשר להוסיף לוכסן הפוך לפני התווים "*" ו-"?", למשל "‎\*‎" ו-"‎\?‎"

HeaderOperation

‫Chrome מגרסה 86 ואילך

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

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

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

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

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

IsRegexSupportedResult

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

מאפיינים

isSupported

בוליאני
reason

‫UnsupportedRegexReason אופציונלי

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

MatchedRule

מאפיינים

ruleId

number

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

מחרוזת

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

MatchedRuleInfo

מאפיינים

כלל

MatchedRule
tabId

number

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

number

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

MatchedRuleInfoDebug

מאפיינים

בקשה

RequestDetails

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

MatchedRule

MatchedRulesFilter

מאפיינים

minTimeStamp

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

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

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

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

ModifyHeaderInfo

‫Chrome מגרסה 86 ואילך

מאפיינים

כותרת

מחרוזת

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

HeaderOperation

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

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

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

QueryKeyValue

מאפיינים

מקש

מחרוזת
replaceOnly

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

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

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

מחרוזת

QueryTransform

מאפיינים

addOrReplaceParams

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

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

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

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

Redirect

מאפיינים

extensionPath

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

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

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

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

URLTransform אופציונלי

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

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

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

RegexOptions

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

מאפיינים

isCaseSensitive

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

אם הערך שצוין ב-regex תלוי אותיות רישיות. ערך ברירת המחדל הוא true.
ביטוי רגולרי (regex)

מחרוזת

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

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

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

RequestDetails

מאפיינים

documentId

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

‫Chrome מגרסה 106 ואילך

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

DocumentLifecycle אופציונלי

‫Chrome מגרסה 106 ואילך

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

number

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

‫FrameType אופציונלי

‫Chrome מגרסה 106 ואילך

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

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

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

מחרוזת

שיטת HTTP רגילה.
parentDocumentId

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

‫Chrome מגרסה 106 ואילך

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

number

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

מחרוזת

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

number

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

ResourceType

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

מחרוזת

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

RequestMethod

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

השדה הזה מתאר את שיטת בקשת ה-HTTP של בקשה לאחזור מהרשת.

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

"connect"

"delete"

"get"

"head"

"options"

"patch"

"post"

"put"

"other"

ResourceType

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

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

"main_frame"

"sub_frame"

"stylesheet"

"script"

"image"

"font"

"object"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"webtransport"

"webbundle"

"other"

Rule

מאפיינים

פעולה

RuleAction

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

RuleCondition

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

number

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

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

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

RuleAction

מאפיינים

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

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

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

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

‫Chrome מגרסה 86 ואילך

כותרות הבקשה שצריך לשנות בבקשה. תקף רק אם RuleActionType הוא modifyHeaders.
responseHeaders

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

‫Chrome מגרסה 86 ואילך

כותרות התגובה שצריך לשנות בבקשה. תקף רק אם RuleActionType הוא modifyHeaders.
סוג

RuleActionType

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

RuleActionType

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

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

"block"
חסימת הבקשה לאחזור מהרשת.

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

"allow"
אישור הבקשה לאחזור מהרשת. הבקשה לא תופסק אם יש כלל "אישור" שתואם לה.

‫"upgradeScheme"
שדרוג הסכימה של כתובת ה-URL של הבקשה לאחזור מהרשת ל-https אם הבקשה היא http או ftp.

‫"modifyHeaders"
שינוי כותרות של בקשות או תגובות מהבקשה לאחזור מהרשת.

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

RuleCondition

מאפיינים

domainType

DomainType אופציונלי

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

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

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

במקום זאת, אתם צריכים להשתמש ב-initiatorDomains
הכלל יתאים רק לבקשות לאחזור מהרשת שמקורן ברשימה של domains.
excludedDomains

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

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

במקום זאת, אתם צריכים להשתמש ב-excludedInitiatorDomains
הכלל לא יתאים לבקשות לאחזור מהרשת שמקורן ברשימת excludedDomains.
excludedInitiatorDomains

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

‫Chrome מגרסה 101 ואילך

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

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

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

‫Chrome מגרסה 101 ואילך

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

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

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

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

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

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

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

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

‫Chrome מגרסה 128 ואילך

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

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

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

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

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

‫Chrome מגרסה 145 ואילך

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

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

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

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

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

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

‫Chrome מגרסה 128 ואילך

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

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

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

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

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

‫Chrome מגרסה 145 ואילך

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

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

RuleConditionKeys

‫Chrome מגרסה 145 ואילך

טיפוסים בני מנייה (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 אופציונלי

שיטת HTTP סטנדרטית של הבקשה ההיפותטית. אם לא מגדירים את הפרמטר, ברירת המחדל היא "get" לבקשות HTTP, והוא לא רלוונטי לבקשות שהן לא HTTP.
responseHeaders

object optional

‫Chrome מגרסה 129 ואילך

הכותרות שסופקו על ידי תגובה היפותטית אם הבקשה לא נחסמת או מופנית מחדש לפני שהיא נשלחת. מיוצג כאובייקט שממפה שם של כותרת לרשימה של ערכי מחרוזת. אם לא מציינים כותרות, התגובה ההיפותטית תחזיר כותרות תגובה ריקות, שיכולות להתאים לכללים שמתאימים למצב שבו אין כותרות. לדוגמה: {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}
tabId

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

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

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

‫Chrome מגרסה 145 ואילך

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

ResourceType

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

מחרוזת

כתובת ה-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 שמשויכות לתנועה של המשתמש פטורות מהמכסה.

ערך

GUARANTEED_MINIMUM_STATIC_RULES

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

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

ערך

30,000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

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

ערך

MAX_NUMBER_OF_DYNAMIC_RULES

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

ערך

30,000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

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

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

ערך

MAX_NUMBER_OF_REGEX_RULES

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

ערך

1,000

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

function optional

הפרמטר callback נראה כך:
```
(count: number) => void
```
- ספירה
  
  number

החזרות

Promise<number>

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

הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

getDisabledRuleIds()

Promise Chrome 111+‎

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

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

פרמטרים

אפשרויות

GetDisabledRuleIdsOptions

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

function optional

הפרמטר callback נראה כך:
```
(disabledRuleIds: number[]) => void
```
- disabledRuleIds
  
  number[]‎

החזרות

Promise<number[]>

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

הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

getDynamicRules()

Promise

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

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

פרמטרים

סינון

GetRulesFilter אופציונלי

‫Chrome מגרסה 111 ואילך

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

function optional

הפרמטר callback נראה כך:
```
(rules: Rule[]) => void
```
- כללים
  
  כלל[]

החזרות

Promise<Rule[]>

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

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

הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

getEnabledRulesets()

Promise

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

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

פרמטרים

callback

function optional

הפרמטר callback נראה כך:
```
(rulesetIds: string[]) => void
```
- rulesetIds
  
  string[]‎

החזרות

Promise<string[]>

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

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

הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

getMatchedRules()

Promise

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

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

פרמטרים

סינון

‫MatchedRulesFilter אופציונלי

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

function optional

הפרמטר callback נראה כך:
```
(details: RulesMatchedDetails) => void
```
- פרטים
  
  RulesMatchedDetails

החזרות

Promise<RulesMatchedDetails>

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

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

הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

getSessionRules()

Promise Chrome 90+‎

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

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

פרמטרים

סינון

GetRulesFilter אופציונלי

‫Chrome מגרסה 111 ואילך

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

function optional

הפרמטר callback נראה כך:
```
(rules: Rule[]) => void
```
- כללים
  
  כלל[]

החזרות

Promise<Rule[]>

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

הבטחה (Promise) שמתקיימת עם קבוצת הכללים ברמת הסשן.

הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

isRegexSupported()

Promise Chrome 87 ואילך

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

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

פרמטרים

regexOptions

RegexOptions

הביטוי הרגולרי שרוצים לבדוק.
callback

function optional

הפרמטר callback נראה כך:
```
(result: IsRegexSupportedResult) => void
```
- תוצאה
  
  IsRegexSupportedResult

החזרות

Promise<IsRegexSupportedResult>

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

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

הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

setExtensionActionOptions()

Promise Chrome 88 ואילך

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

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

פרמטרים

אפשרויות

ExtensionActionOptions
callback

function optional

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

הפרמטר callback נראה כך:
```
() => void
```

החזרות

Promise<void>

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

הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

testMatchOutcome()

Promise Chrome 103+‎

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

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

פרמטרים

בקשה

TestMatchRequestDetails
callback

function optional

הפרמטר callback נראה כך:
```
(result: TestMatchOutcomeResult) => void
```
- תוצאה
  
  TestMatchOutcomeResult

החזרות

Promise<TestMatchOutcomeResult>

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

הבטחות נתמכות רק ב-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.

פרמטרים

אפשרויות

UpdateRuleOptions

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

function optional

הפרמטר callback נראה כך:
```
() => void
```

החזרות

Promise<void>

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

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

הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

updateEnabledRulesets()

Promise

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

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

פרמטרים

אפשרויות

UpdateRulesetOptions

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

function optional

הפרמטר callback נראה כך:
```
() => void
```

החזרות

Promise<void>

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

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

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

פרמטרים

אפשרויות

UpdateRuleOptions
callback

function optional

הפרמטר callback נראה כך:
```
() => void
```

החזרות

Promise<void>

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

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

הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

updateStaticRules()

Promise Chrome 111+‎

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

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

פרמטרים

אפשרויות

UpdateStaticRulesOptions
callback

function optional

הפרמטר callback נראה כך:
```
() => void
```

החזרות

Promise<void>

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

הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

אירועים

onRuleMatchedDebug

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

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

פרמטרים

callback

פונקציה

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

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

תיאור

הרשאות

זמינות

מניפסט

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

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

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

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

יצירת כללים

תווים תואמים ב-urlFilter

תעדוף כללים

תעדוף כללים בתוך תוסף

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

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

כללים סטטיים

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

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

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

מקורות מידע נגישים באינטרנט

דוגמאות

דוגמאות לקוד

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

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

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

המפתח "priority"

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

כותרות

סוגים

DomainType

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

ExtensionActionOptions

מאפיינים

GetDisabledRuleIdsOptions

מאפיינים

GetRulesFilter

מאפיינים

HeaderInfo

מאפיינים

HeaderOperation

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

IsRegexSupportedResult

מאפיינים

MatchedRule

מאפיינים

MatchedRuleInfo

מאפיינים

MatchedRuleInfoDebug

מאפיינים

MatchedRulesFilter

מאפיינים

ModifyHeaderInfo

מאפיינים

QueryKeyValue

מאפיינים

QueryTransform

מאפיינים

Redirect

מאפיינים

RegexOptions

מאפיינים

RequestDetails

מאפיינים

RequestMethod

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

ResourceType

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

Rule

מאפיינים

RuleAction

מאפיינים

RuleActionType

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

RuleCondition

מאפיינים

RuleConditionKeys

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

Ruleset

מאפיינים

RulesMatchedDetails

chrome.declarativeNetRequest