chrome.declarativeWebRequest

תיאור

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

הרשאות

declarativeWebRequest

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

{
  "name": "My extension",
  ...
  "permissions": [
    "declarativeWebRequest",
    "*://*/*"
  ],
  ...
}

זמינות

ערוץ בטא ≤ MV2

מניפסט

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

  • CancelRequest
  • IgnoreRules
  • RedirectToEmptyDocument
  • RedirectToTransparentImage

לפעולה SendMessageToExtension() נדרשות הרשאות מארח לכל המארחים שבקשות הרשת שלהם שרוצים להפעיל בו הודעה.

לכל שאר הפעולות נדרשות הרשאות מארח לכל כתובות ה-URL.

לדוגמה, אם "https://*.google.com/*" הוא הרשאת המארח היחידה שיש לתוסף, אז למשל התוסף יכול להגדיר כלל:

  • לבטל בקשה שנשלחה אל https://www.google.com או אל https://anything.else.com.
  • שליחת הודעה במהלך הניווט אל https://www.google.com אבל לא אל https://something.else.com.

התוסף לא יכול להגדיר כלל להפניה מחדש של https://www.google.com אל https://mail.google.com.

כללים

ה-Delarative Web Request API מבוסס על המושגים של Declarative API. אפשר להירשם לאובייקט האירוע chrome.declarativeWebRequest.onRequest.

ה-declarative Web Request API תומך בסוג יחיד של קריטריוני התאמה, RequestMatcher. RequestMatcher תואם לבקשות רשת רק אם הוא עומד בכל הקריטריונים שצוינו. הבאים RequestMatcher יתאים לבקשת רשת כשהמשתמש יזין את https://www.example.com ב תיבת דואר נכנס:

var matcher = new chrome.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com', schemes: ['http'] },
  resourceType: ['main_frame']
});

בקשות אל https://www.example.com יידחו על ידי RequestMatcher בהתאם לסכימה. כמו כן, כל הבקשות ל-iframe מוטמע יידחו מהסיבה הבאה: resourceType.

כדי לבטל את כל הבקשות אל example.com, אפשר להגדיר כלל באופן הבא:

var rule = {
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'example.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]
};

כדי לבטל את כל הבקשות אל example.com ואל foobar.com, אפשר להוסיף תנאי שני, כל תנאי מספיק כדי להפעיל את כל הפעולות שצוינו:

var rule2 = {
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'example.com' } }),
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'foobar.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]
};

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

chrome.declarativeWebRequest.onRequest.addRules([rule2]);

הערכת תנאים ופעולות

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

שלבי הבקשה שבמהלכם אפשר לעבד את מאפייני התנאי.
מאפיין תנאי onBeforeRequest onBeforeSendHeaders onHeadersReceived onAuthRequired
url ✓ ✓ ✓ ✓
resourceType ✓ ✓ ✓ ✓
contentType ✓
excludeContentType ✓
responseHeaders ✓
excludeResponseHeaders ✓
requestHeaders ✓
excludeRequestHeaders ✓
thirdPartyForCookies ✓ ✓ ✓ ✓
שלבי הבקשה שבמהלכם אפשר לבצע פעולות.
אירוע onBeforeRequest onBeforeSendHeaders onHeadersReceived onAuthRequired
AddRequestCookie ✓
AddResponseCookie ✓
AddResponseHeader ✓
CancelRequest ✓ ✓ ✓ ✓
EditRequestCookie ✓
EditResponseCookie ✓
IgnoreRules ✓ ✓ ✓ ✓
RedirectByRegEx ✓ ✓
RedirectRequest ✓ ✓
RedirectToEmptyDocument ✓ ✓
RedirectToTransparentImage ✓ ✓
RemoveRequestCookie ✓
RemoveRequestHeader ✓
RemoveResponseCookie ✓
RemoveResponseHeader ✓
SendMessageToExtension ✓ ✓ ✓ ✓
SetRequestHeader ✓

שימוש בעדיפויות כדי לשנות כללים

אפשר לשייך כללים לעדיפויות כפי שמתואר ב-Event API. המנגנון הזה משמש לציון חריגים. בדוגמה הבאה חסמת את כל הבקשות לתמונות בשם evil.jpg מלבד בשרת "myserver.com".

var rule1 = {
  priority: 100,
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
        url: { pathEquals: 'evil.jpg' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]
};
var rule2 = {
  priority: 1000,
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: '.myserver.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.IgnoreRules({
      lowerPriorityThan: 1000 })
  ]
};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

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

סוגים

AddRequestCookie

הוספת קובץ cookie לבקשה או ביטול קובץ ה-cookie, במקרה שכבר קיים קובץ cookie אחר באותו שם. הערה: עדיף להשתמש ב-Cookie API כי החישוב הזה זול יותר.

מאפיינים

AddResponseCookie

מוסיפה קובץ cookie לתשובה או מבטלת קובץ cookie, במקרה שכבר קיים קובץ cookie אחר באותו שם. הערה: עדיף להשתמש ב-Cookie API כי החישוב הזה זול יותר.

מאפיינים

AddResponseHeader

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

מאפיינים

  • constructor

    ריק

    הפונקציה constructor נראית כך: 

    (arg: AddResponseHeader) => {...}

  • שם

    מחרוזת

    שם כותרת תגובת HTTP.

  • ערך

    מחרוזת

    ערך כותרת של תגובת HTTP.

CancelRequest

פעולה הצהרתית שמבטלת בקשת רשת.

מאפיינים

EditRequestCookie

עורך קובץ cookie אחד או יותר של הבקשה. הערה: עדיף להשתמש ב-Cookie API כי החישוב הזה זול יותר.

מאפיינים

  • constructor

    ריק

    הפונקציה constructor נראית כך: 

    (arg: EditRequestCookie) => {...}

  • סינון

    RequestCookie

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

  • שינוי

    RequestCookie

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

EditResponseCookie

עורך קובץ cookie אחד או יותר של התגובה. הערה: עדיף להשתמש ב-Cookie API כי החישוב הזה זול יותר.

מאפיינים

  • constructor

    ריק

    הפונקציה constructor נראית כך: 

    (arg: EditResponseCookie) => {...}

  • סינון קובצי Cookie שישתנו. המערכת תתעלם מכל הערכים הריקים.

  • שינוי

    ResponseCookie

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

FilterResponseCookie

מסנן של קובץ cookie בתשובות HTTP.

מאפיינים

  • ageLowerBound

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

    גבול תחתון כוללני של משך החיים של קובץ ה-cookie (מצוין בשניות אחרי השעה הנוכחית). רק קובצי cookie שמועד התפוגה שלהם מוגדר כ-'עכשיו + AgeLowerBound' או להשלים את הקריטריון הזה מאוחר יותר. קובצי cookie של סשן לא עומדים בקריטריונים של מסנן זה. משך החיים של קובץ ה-cookie מחושב לפי 'max-age' או 'יפוג' במאפיינים של קובצי Cookie. אם מציינים את שתי האפשרויות, 'max-age' משמש לחישוב משך החיים של קובץ ה-cookie.

  • ageUpperBound

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

    גבול עליון כוללני של משך החיים של קובץ ה-cookie (מצוין בשניות אחרי השעה הנוכחית). רק קובצי cookie שתאריך התפוגה שלהם נמצא במרווח הזמן הזה [עכשיו, עכשיו + גילUpperBound] עומדים בקריטריון הזה. קובצי cookie של סשן וקובצי cookie שתאריך התפוגה שלהם כבר עבר, לא עומדים בקריטריונים של מסנן זה. משך החיים של קובץ ה-cookie מחושב לפי 'max-age' או 'יפוג' במאפיינים של קובצי Cookie. אם מציינים את שתי האפשרויות, 'max-age' משמש לחישוב משך החיים של קובץ ה-cookie.

  • דומיין

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

    הערך של מאפיין קובץ ה-cookie של הדומיין.

  • בתוקף עד

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

    הערך של מאפיין קובץ ה-cookie שתוקפו פג.

  • httpOnly

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

    קיום של מאפיין קובץ ה-cookie HttpOnly.

  • maxAge

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

    הערך של מאפיין קובץ ה-cookie 'גיל מקסימלי'

  • שם

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

    שם של קובץ Cookie.

  • נתיב

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

    ערך המאפיין של קובץ ה-cookie של הנתיב.

  • מאובטח

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

    קיום של מאפיין קובץ ה-cookie המאובטח.

  • sessionCookie

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

    מסנן קובצי cookie של הפעלה. לקובצי cookie של סשן לא צוין משך חיים באף אחד מה-'max-age' או 'יפוג' .

  • ערך

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

    את הערך של קובץ cookie ניתן להוסיף במירכאות כפולות.

HeaderFilter

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

מאפיינים

  • nameContains

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

    תואם אם שם הכותרת מכיל את כל המחרוזות שצוינו.

  • nameEquals

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

    תואם אם שם הכותרת שווה למחרוזת שצוינה.

  • namePrefix

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

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

  • nameSuffix

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

    תואם אם שם הכותרת מסתיים במחרוזת שצוינה.

  • valueContains

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

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

  • valueEquals

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

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

  • valuePrefix

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

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

  • valueSuffix

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

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

IgnoreRules

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

מאפיינים

  • constructor

    ריק

    הפונקציה constructor נראית כך: 

    (arg: IgnoreRules) => {...}

  • hasTag

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

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

  • lowerPriorityThan

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

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

RedirectByRegEx

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

מאפיינים

  • constructor

    ריק

    הפונקציה constructor נראית כך: 

    (arg: RedirectByRegEx) => {...}

  • החל מ-

    מחרוזת

    דפוס התאמה שעשוי להכיל קבוצות לחילוץ. ההפניה לקבוצות חילוץ מתבצעת בתחביר Perl ($1, $2, ...) במקום בתחביר RE2 (\1, \2, ...) כדי להיות קרובים יותר לביטויים רגולריים של JavaScript.

  • עד

    מחרוזת

    דפוס יעד.

RedirectRequest

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

מאפיינים

RedirectToEmptyDocument

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

מאפיינים

RedirectToTransparentImage

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

מאפיינים

RemoveRequestCookie

הסרה של קובץ Cookie אחד או יותר של הבקשה. הערה: עדיף להשתמש ב-Cookie API כי החישוב הזה זול יותר.

מאפיינים

RemoveRequestHeader

הסרת כותרת הבקשה של השם שצוין. אין להשתמש ב-SetRequestHeader וב-RemoveRequestHeader עם אותו שם כותרת באותה בקשה. כל שם של כותרת בקשה מופיע פעם אחת בלבד בכל בקשה.

מאפיינים

RemoveResponseCookie

הפעולה הזו מסירה קובץ Cookie אחד או יותר של התגובה. הערה: עדיף להשתמש ב-Cookie API כי החישוב הזה זול יותר.

מאפיינים

RemoveResponseHeader

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

מאפיינים

  • constructor

    ריק

    הפונקציה constructor נראית כך: 

    (arg: RemoveResponseHeader) => {...}

  • שם

    מחרוזת

    שם הכותרת של בקשת ה-HTTP (לא תלוי-רישיות).

  • ערך

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

    ערך כותרת בקשת HTTP (לא תלוי-רישיות).

RequestCookie

מסנן או מפרט של קובץ cookie בבקשות HTTP.

מאפיינים

  • שם

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

    שם של קובץ Cookie.

  • ערך

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

    את הערך של קובץ cookie ניתן להוסיף במירכאות כפולות.

RequestMatcher

מתאימה אירועי רשת לפי קריטריונים שונים.

מאפיינים

  • constructor

    ריק

    הפונקציה constructor נראית כך: 

    (arg: RequestMatcher) => {...}

  • contentType

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

    תואם אם סוג המדיה MIME של התשובה (מהכותרת Content-Type של HTTP) כלול ברשימה.

  • excludeContentType

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

    תואם אם סוג המדיה MIME של תגובה (מהכותרת Content-Type ב-HTTP) לא כלולה ברשימה.

  • excludeRequestHeaders

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

    תואם אם אף אחת מכותרות הבקשה לא תואמת לאף אחד מ-HeaderFilters.

  • excludeResponseHeaders

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

    תואם אם אף אחת מכותרות התגובה לא תואמת לאף אחד מ-HeaderFilters.

  • firstPartyForCookiesUrl

    UrlFilter אופציונלי

    הוצא משימוש

    המערכת התעלמה מגרסה 82.

    תואם אם מתקיימים התנאים של UrlFilter עבור 'צד ראשון' כתובת ה-URL של הבקשה. 'הצד הראשון' כתובת ה-URL של בקשה, אם יש כזו, יכולה להיות שונה מכתובת היעד של הבקשה, ומתארת מה נחשב כ'צד ראשון'. למטרות בדיקות של קובצי cookie על ידי צד שלישי.

  • requestHeaders

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

    תואם אם חלק מכותרות הבקשה תואמות לאחד מ-HeaderFilters.

  • resourceType

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

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

  • responseHeaders

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

    תואם אם חלק מכותרות התגובה תואמות לאחד מ-HeaderFilters.

  • שלבים

    שלב[] אופציונלי

    מכילה רשימת מחרוזות שמתארות שלבים. הערכים המותרים הם:onBeforeRequest, 'onBeforeSendHeaders', 'onHeadersReceived', 'onAuthrequired'. אם המאפיין הזה קיים, הוא מגביל את השלבים הרלוונטיים לאלה שמפורטים ברשימה. שימו לב שהתנאי כולו חל רק בשלבים שתואמים לכל המאפיינים.

  • thirdPartyForCookies

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

    הוצא משימוש

    המערכת התעלמה מגרסה 87.

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

  • כתובת אתר

    UrlFilter אופציונלי

    תואם אם מתקיימים התנאים של UrlFilter בכתובת ה-URL של הבקשה.

ResponseCookie

מפרט של קובץ cookie בתשובות HTTP.

מאפיינים

  • דומיין

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

    הערך של מאפיין קובץ ה-cookie של הדומיין.

  • בתוקף עד

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

    הערך של מאפיין קובץ ה-cookie שתוקפו פג.

  • httpOnly

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

    קיום של מאפיין קובץ ה-cookie HttpOnly.

  • maxAge

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

    הערך של מאפיין קובץ ה-cookie 'גיל מקסימלי'

  • שם

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

    שם של קובץ Cookie.

  • נתיב

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

    ערך המאפיין של קובץ ה-cookie של הנתיב.

  • מאובטח

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

    קיום של מאפיין קובץ ה-cookie המאובטח.

  • ערך

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

    את הערך של קובץ cookie ניתן להוסיף במירכאות כפולות.

SendMessageToExtension

הפעלת האירוע declarativeWebRequest.onMessage.

מאפיינים

SetRequestHeader

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

מאפיינים

  • constructor

    ריק

    הפונקציה constructor נראית כך: 

    (arg: SetRequestHeader) => {...}

  • שם

    מחרוזת

    שם הכותרת של בקשת ה-HTTP.

  • ערך

    מחרוזת

    ערך הכותרת של בקשת ה-HTTP.

Stage

Enum

"onBeforeRequest"

"onBeforeSendHeaders"

"onHeadersReceived"

"onAuthrequired"

אירועים

onMessage

chrome.declarativeWebRequest.onMessage.addListener(
  callback: function,
)

מופעל כשהודעה נשלחת דרך declarativeWebRequest.SendMessageToExtension מפעולה של ה-API לבקשות אינטרנט הצהרתיות.

פרמטרים

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

    פונקציה

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

    (details: object) => void

    • פרטים

      אובייקט

      • documentId

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

        מזהה ייחודי אוניברסלי (UUID) של המסמך שממנו נשלחה הבקשה.

      • מחזור החיים של המסמך.

      • frameId

        number

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

      • סוג המסגרת שבה התרחש הניווט.

      • הודעה

        מחרוזת

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

      • method

        מחרוזת

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

      • parentDocumentId

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

        מזהה ייחודי אוניברסלי (UUID) של מסמך ההורה שהוא הבעלים של המסגרת הזו. הערך לא מוגדר אם אין הורה.

      • parentFrameId

        number

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

      • requestId

        מחרוזת

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

      • לאחסן נתונים במחסן ביניים (Stage)

        שלב

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

      • tabId

        number

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

      • timeStamp

        number

        הזמן שבו האות הזה מופעל, באלפיות השנייה מאז תחילת התקופה.

      • איך ייעשה שימוש במשאב המבוקש.

      • כתובת אתר

        מחרוזת

onRequest

מספקת את Declarative Event API שמכיל addRules, removeRules ו-getRules.

תנאים

RequestMatcher

פעולות

AddRequestCookie

AddResponseCookie

AddResponseHeader

CancelRequest

EditRequestCookie

EditResponseCookie

RedirectRequest

RedirectToTransparentImage

RedirectToEmptyDocument

RedirectByRegEx

RemoveRequestCookie

RemoveResponseCookie

RemoveRequestHeader

RemoveResponseHeader

SetRequestHeader

SendMessageToExtension

IgnoreRules