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. יש מגבלה של עד 5,000 כללים סטטיים שהושבתו.

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

יצירת כללים

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

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

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

Declarative Net Request מספק את היכולת להתאים כתובות URL באמצעות כל אחד מהדפוסים. תחביר או ביטויים רגולריים תואמים.

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

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

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

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

התנאים יכולים גם להשתמש בביטויים רגולריים. לצפייה מקש "regexFilter". כדי ללמוד על המגבלות שחלות על התנאים האלה: כללים שמשתמשים בביטויים רגולריים.

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

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

  • google.com תואם בצורה שגויה ל-https://example.com/?param=google.com
  • ||google.com תואם בצורה שגויה ל-https://google.company
  • https://www.google.com תואם בצורה שגויה ל-https://example.com/?param=https://www.google.com

כדאי להשתמש בצירופים הבאים:

  • ||google.com/, שתואם לכל הנתיבים ולכל תתי-הדומיינים.
  • |https://www.google.com/ שתואם לכל הנתיבים ללא תת-דומיינים.

באופן דומה, צריך להשתמש בתווים ^ ו-/ כדי לעגן ביטוי רגולרי. עבור לדוגמה, ^https:\/\/www\.google\.com\/ תואם לכל נתיב ב- https://www.google.com.

הערכת כללים

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

לפני הבקשה

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

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

לאחר מכן, עבור כל תוסף, Chrome בוחר מועמד אחד לכל היותר בכל בקשה. Chrome מוצא כלל תואם על ידי סידור כל הכללים התואמים לפי עדיפות. כללים עם אותה עדיפות מסודרים לפי פעולה (allow או allowAllRequests > block > upgradeScheme > redirect).

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

אם יותר מתוסף אחד רוצה לחסום את הבקשה הזו או להפנות אותה לכתובת אחרת, נבחרת פעולה יחידה לביצוע. Chrome עושה זאת על ידי מיון הכללים לפי סדר block > redirect או upgradeScheme > allow או allowAllRequests. אם שני כללים הם מאותו סוג, Chrome בוחר את הכלל מהתוסף האחרון שהותקן.

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

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

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

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

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

ברגע שמתקבלת תשובה

אחרי שמתקבלות כותרות התגובה, Chrome מבצע הערכה של הכללים עם תנאי responseHeaders.

לאחר מיון הכללים האלה לפי action ו-priority והחרגת כללים שהוחרגו על ידי כלל allow או allowAllRequests תואם (זה קורה באופן זהה לשלבים בקטע "לפני הבקשה"), Chrome עשוי לחסום או להפנות את הבקשה בשם תוסף.

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

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

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

כללי בטיחות

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

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

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

כללים סטטיים

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

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

כללי סשנים

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

עד גרסה 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" של המניפסט.

שינוי בכותרת

פעולת ההוספה נתמכת רק עבור הכותרות הבאות: accept, accept-encoding, accept-language, access-control-request-headers, cache-control, connection, content-language, cookie, forwarded, if-match, if-none-match, keep-alive, range, te, trailer, transfer-encoding, upgrade, user-agent, via, via, via, viawant-digestx-forwarded-for

דוגמאות

דוגמאות לקוד

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

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

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

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

HeaderInfo

Chrome 128 ואילך

מאפיינים

  • excludedValues

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

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

  • כותרת

    מחרוזת

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

  • ערכים

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

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

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

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

    '*' ו-'?' יכול להיות בתו בריחה (escape) באמצעות לוכסן הפוך, לדוגמה '\*' וגם '\?'

HeaderOperation

Chrome 86 ואילך

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

Enum

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

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

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

IsRegexSupportedResult

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

מאפיינים

  • isSupported

    בוליאני

  • סיבה

    UnsupportedRegexReason אופציונלי

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

MatchedRule

מאפיינים

  • ruleId

    number

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

  • rulesetId

    מחרוזת

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

MatchedRuleInfo

מאפיינים

  • כלל

    MatchedRule

  • tabId

    number

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

  • timeStamp

    number

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

MatchedRuleInfoDebug

מאפיינים

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 אפשר להשתמש בספרות עם תווי בריחה (escape) (\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

    number

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

  • frameType

    FrameType אופציונלי

    Chrome 106+

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

  • יוזם

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

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

  • method

    מחרוזת

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

  • parentDocumentId

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

    Chrome 106+

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

  • parentFrameId

    number

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

  • requestId

    מחרוזת

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

  • tabId

    number

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

  • סוג

    ResourceType

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

  • כתובת אתר

    מחרוזת

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

RequestMethod

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

בשדה הזה מתוארת ה-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

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

"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

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

    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.

  • responseHeaders

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

    Chrome 128 ואילך

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

  • 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

מאפיינים

  • פעיל

    בוליאני

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

  • 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

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

    בהמתנה

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

  • tabId

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

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

  • סוג

    ResourceType

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

  • כתובת אתר

    מחרוזת

    כתובת ה-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

    מחרוזת

    המזהה שתואם ל-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()

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

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

פרמטרים

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

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

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

    (count: number) => void

    • count

      number

החזרות

  • Promise<number>

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

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

getDisabledRuleIds()

הבטחה 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[]

החזרות

  • Promise&lt;string[]&gt;

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

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

getMatchedRules()

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

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

פרמטרים

  • סינון

    MatchedRulesFilter אופציונלי

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

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

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

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

    (details: RulesMatchedDetails) => void

החזרות

  • Promise&lt;RulesMatchedDetails&gt;

    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.

פרמטרים

החזרות

  • Promise&lt;IsRegexSupportedResult&gt;

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

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

setExtensionActionOptions()

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

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

פרמטרים

  • אפשרויות

    ExtensionActionOptions

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

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

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

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

testMatchOutcome()

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

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

פרמטרים

החזרות

  • Promise&lt;TestMatchOutcomeResult&gt;

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

החזרות

  • הבטחה<Empty>

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

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

updateEnabledRulesets()

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

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

פרמטרים

  • אפשרויות

    UpdateRulesetOptions

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

    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

החזרות

  • הבטחה<Empty>

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

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

updateStaticRules()

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

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

פרמטרים

  • אפשרויות

    UpdateStaticRulesOptions

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

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

אירועים

onRuleMatchedDebug

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

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

פרמטרים