chrome.declarativeWebRequest

תיאור

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

הרשאות

declarativeWebRequest

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

{
  "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.

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

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 פועל בהתאם למודל מחזור החיים של בקשות אינטרנט של Web Request 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

הגדרת עדיפויות כדי לבטל כללים

אפשר לשייך כללים לסדרי עדיפויות כפי שמתואר ב-Events 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

    void

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

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

  • name

    מחרוזת

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

  • value

    מחרוזת

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

CancelRequest

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

תכונות

EditRequestCookie

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

תכונות

  • Constructor

    void

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

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

  • סינון

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

  • שינוי

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

EditResponseCookie

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

תכונות

  • Constructor

    void

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

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

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

  • שינוי

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

FilterResponseCookie

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

תכונות

  • ageLowerBound

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

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

  • ageUpperBound

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

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

  • דומיין

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

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

  • בתוקף עד

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

    ערך המאפיין 'קובצי Cookie בתוקף'.

  • httpOnly

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

    קיים מאפיין קובץ Cookie HttpOnly.

  • maxAge

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

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

  • name

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

    שם של קובץ cookie.

  • נתיב

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

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

  • מאובטח

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

    קיים מאפיין cookie מאובטח.

  • sessionCookie

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

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

  • value

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

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

HeaderFilter

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

תכונות

  • nameContains

    string|string[] optional

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

  • nameEquals

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

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

  • namePrefix

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

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

  • nameSuffix

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

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

  • valueContains

    string|string[] optional

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

  • valueEquals

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

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

  • valuePrefix

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

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

  • valueSuffix

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

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

IgnoreRules

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

תכונות

  • Constructor

    void

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

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

  • hasTag

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

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

  • lowerPriorityThan

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

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

RedirectByRegEx

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

תכונות

  • Constructor

    void

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

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

  • החל מ-

    מחרוזת

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

  • עד

    מחרוזת

    דפוס יעד.

RedirectRequest

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

תכונות

RedirectToEmptyDocument

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

תכונות

RedirectToTransparentImage

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

תכונות

RemoveRequestCookie

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

תכונות

RemoveRequestHeader

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

תכונות

RemoveResponseCookie

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

תכונות

RemoveResponseHeader

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

תכונות

  • Constructor

    void

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

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

  • name

    מחרוזת

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

  • value

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

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

RequestCookie

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

תכונות

  • name

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

    שם של קובץ cookie.

  • value

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

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

RequestMatcher

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

תכונות

  • Constructor

    void

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

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

  • contentType

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

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

  • excludeContentType

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

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

  • excludeRequestHeaders

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

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

  • excludeResponseHeaders

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

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

  • firstPartyForCookiesUrl

    UrlFilter אופציונלי

    הוצא משימוש

    המערכת מתעלמת ממנו מאז גרסה 82.

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

  • requestHeaders

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

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

  • resourceType

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

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

  • responseHeaders

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

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

  • שלבים

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

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

  • thirdPartyForCookies

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

    הוצא משימוש

    המערכת מתעלמת ממנו מאז גרסה 87.

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

  • כתובת אתר

    UrlFilter אופציונלי

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

ResponseCookie

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

תכונות

  • דומיין

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

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

  • בתוקף עד

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

    ערך המאפיין 'קובצי Cookie בתוקף'.

  • httpOnly

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

    קיים מאפיין קובץ Cookie HttpOnly.

  • maxAge

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

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

  • name

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

    שם של קובץ cookie.

  • נתיב

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

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

  • מאובטח

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

    קיים מאפיין cookie מאובטח.

  • value

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

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

SendMessageToExtension

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

תכונות

SetRequestHeader

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

תכונות

  • Constructor

    void

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

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

  • name

    מחרוזת

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

  • value

    מחרוזת

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

Stage

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

"onBeforeRequest"

"onBeforeSendHeaders"

"onHeadersReceived"

אירועים

onMessage

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

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

פרמטרים

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

    פונקציה

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

    (details: object)=>void

    • פרטים

      אובייקט

      • documentId

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

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

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

      • frameId

        מספר

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

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

      • הודעה

        מחרוזת

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

      • method

        מחרוזת

        שיטת HTTP רגילה.

      • parentDocumentId

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

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

      • parentFrameId

        מספר

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

      • requestId

        מחרוזת

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

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

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

      • tabId

        מספר

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

      • timeStamp

        מספר

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

      • אופן השימוש במשאב המבוקש.

      • כתובת אתר

        מחרוזת

onRequest

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

תנאים