chrome.webRequest

תיאור

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

הרשאות

webRequest

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

{
  "name": "My extension",
  ...
  "permissions": [
    "webRequest"
  ],
  "host_permissions": [
    "*://*.google.com/*"
  ],
  ...
}

webRequestBlocking

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

webRequestAuthProvider

נדרש כדי להשתמש בשיטה onAuthRequired. צפייה טיפול באימות.

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

מחזור החיים של בקשות

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

מחזור החיים של אירוע של בקשות שהושלמו מודגם כאן, ולאחר מכן הגדרות האירוע:

מחזור החיים של בקשת אינטרנט מנקודת המבט של Webrequest API

onBeforeRequest (אופציונלי)
מופעל כשבקשה עומדת להתרחש. האירוע הזה נשלח לפני שנוצר חיבור TCP, ויכול משמש לביטול או להפניה אוטומטית של בקשות.
onBeforeSendHeaders (אופציונלי)
מופעלות כשבקשה עומדת להתרחש והכותרות הראשוניות מוכנות. האירוע שמטרתו לאפשר לתוספים להוסיף, לשנות ולמחוק כותרות של בקשות (*). האירוע onBeforeSendHeaders מועבר לכל המנויים, לכן מנויים שונים עשויים לנסות לשנות את הבקשה; בקטע פרטי ההטמעה מוסבר איך אנחנו מטפלים בכך. האירוע הזה יכול לשמש לביטול הבקשה.
onSendHeaders
מופעלות אחרי שכל התוספים קיבלו הזדמנות לשנות את כותרות הבקשות, ומציגות את התמונה הסופית הגרסה (*). האירוע מופעל לפני שהכותרות נשלחות לרשת. האירוע הזה אינפורמטיביים ומטופלים באופן אסינכרוני. אסור לשנות או לבטל את הבקשה.
onHeadersReceived (אופציונלי)
מופעלת בכל פעם שמתקבלת כותרת תגובה של HTTP(S). בגלל הפניות אוטומטיות ואימות הבקשות יכולות להתרחש כמה פעמים בכל בקשה. האירוע הזה נועד לאפשר לתוספים: להוסיף, לשנות ולמחוק כותרות תגובה, כמו כותרות Content-Type נכנסות. השמירה במטמון ההוראות מעובדות לפני שהאירוע הזה מופעל, לכן שינוי כותרות כמו Cache-Control אין השפעה על המטמון של הדפדפן. הוא גם מאפשר לבטל את הבקשה או להפנות אותה לכתובת אחרת.
onAuthRequired (אופציונלי)
מופעל כאשר בקשה מחייבת אימות של המשתמש. אפשר לטפל באירוע הזה באופן סינכרוני כדי מספק פרטי כניסה לאימות. לתשומת ליבכם: יכול להיות שתוספים יספקו פרטי כניסה לא חוקיים. להתראות ולא להיכנס ללולאה אינסופית באמצעות מתן פרטי כניסה לא חוקיים שוב ושוב. אפשר להשתמש במודל הזה גם לבטל את הבקשה.
onBeforeRedirect
מופעל כאשר הפניה מחדש עומדת להתבצע. תגובת HTTP יכולה להפעיל הפניה אוטומטית או באמצעות תוסף. האירוע הזה הוא אינפורמטיבי ומטופל באופן אסינכרוני. אסור כדי לשנות או לבטל את הבקשה.
onResponseStarted
מופעל כאשר מתקבל הבייט הראשון של גוף התגובה. בבקשות HTTP, המשמעות היא אפשר להשתמש בכותרות סטטוס וכותרות תגובה. האירוע הזה הוא למטרות מידע בלבד ומטופל באופן אסינכרוני. אסור לשנות או לבטל את הבקשה.
onCompleted
נפתחת לאחר שבקשה עובדה בהצלחה.
onErrorOccurred
מופעל כאשר לא ניתן לעבד בקשה בהצלחה.

ה-API של בקשת האינטרנט מבטיח שלכל בקשה, הערך של onCompleted או של onErrorOccurred הוא מופעלת כאירוע הסופי, למעט חריג אחד: אם הבקשה מופנית לכתובת URL של data://, onBeforeRedirect הוא האירוע האחרון שדווח.

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

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

  • אישור
  • סמל המטמון
  • חיבור
  • אורך התוכן
  • מארח
  • 'אם השתנה מאז'
  • אם אין התאמה
  • אם-טווח
  • נתונים חלקיים
  • פראגמה
  • הרשאת שרת proxy
  • חיבור לשרת proxy
  • Transfer-Encoding

החל מגרסה 79 של Chrome, שינויים בכותרת הבקשה ישפיעו על שיתוף משאבים בין מקורות (CORS) בדיקות. אם כותרות שהשתנו בבקשות ממקורות שונים לא עומדות בקריטריונים, שולחת קדם-הפעלה של CORS כדי לשאול את השרת אם אפשר לקבל כותרות כאלה. אם ממש צריך תשנה את הכותרות באופן שמפר את פרוטוקול CORS, עליך לציין את 'extraHeaders' בפורמט opt_extraInfoSpec. לעומת זאת, שינויים בכותרות תגובה לא מאפשרים לרמות CORS בדיקות. אם צריך לרמות את פרוטוקול CORS, צריך לציין גם 'extraHeaders' בשביל שינויים בתגובות.

החל מגרסה 79 של Chrome, ה-webRequest API לא מיירט בקשות קדם-הפעלה של CORS כברירת מחדל. קדם-הפעלה של CORS לכתובת URL של בקשה גלויה לתוסף אם יש אוזן ה-'extraHeaders' שצוין ב-opt_extraInfoSpec לכתובת ה-URL של הבקשה. לonBeforeRequest יש גם אפשרות להוריד את 'extraHeaders' מ-Chrome 79.

החל מגרסה 79 של Chrome, כותרת הבקשה הבאה לא סופקה ולא ניתן לשנות אותה או הוסר בלי לציין 'extraHeaders' ב-opt_extraInfoSpec:

  • מקור

החל מגרסה 72 של Chrome, אם צריך לשנות את התשובות לפני חסימת קריאה ממקורות שונים (CORB) יכול לחסום את התשובה. צריך לציין 'extraHeaders' ב-opt_extraInfoSpec.

החל מגרסה 72 של Chrome, כותרות הבקשות הבאות לא סופקו ואי אפשר לשנות אותן או הוסרו בלי לציין 'extraHeaders' ב-opt_extraInfoSpec:

  • אישור השפה
  • Accept-Encoding
  • אתר מפנה
  • קובץ Cookie

החל מגרסה 72 של Chrome, כותרת התגובה Set-Cookie לא סופקה ואי אפשר לשנות אותה או הוסרו בלי לציין 'extraHeaders' ב-opt_extraInfoSpec.

החל מגרסה 89 של Chrome, אי אפשר לשנות ביעילות את כותרת התגובה X-Frame-Options או הוסרו בלי לציין 'extraHeaders' ב-opt_extraInfoSpec.

ה-webRequest API חושף רק בקשות שלתוסף יש הרשאה לראות, בהינתן המארח שלו הרשאות. בנוסף, אפשר לגשת רק לסכימות הבאות: http://, https://, ftp://, file://, ws:// (החל מ-Chrome 58), wss:// (החל מ-Chrome 58), urn: (החל מ-Chrome 91) או chrome-extension://. בנוסף, גם בקשות מסוימות עם כתובות URL שמשתמשות באחת מהסכימות שלמעלה מוסתרות. למשל chrome-extension://other_extension_id כאשר other_extension_id אינו מזהה התוסף לטיפול בבקשה, https://www.google.com/chrome ופרטים רגישים אחרים חיוני לפונקציונליות של הדפדפן. בנוסף, בקשות XMLHttpRequest מסונכרנות מהתוסף שלך מוסתרת מחסימה של גורמים מטפלים באירועים, כדי למנוע מבוי סתום. שימו לב שבחלק מהמקרים של הסכמות הנתמכות, ייתכן שקבוצת האירועים הזמינים תהיה מוגבלת בגלל אופי של פרוטוקול מתאים. לדוגמה, לקובץ: scheme, רק onBeforeRequest, ייתכן שהחבילה onResponseStarted, onCompleted וגם onErrorOccurred יישלחו.

החל מגרסה 58 של Chrome, webRequest API תומך ביירוט בקשת לחיצת היד של WebSocket. מאחר שלחיצת היד מתבצעת באמצעות בקשת שדרוג HTTP, הזרימה שלו מתאימה ל-HTTP מודל webRequest. שימו לב שה-API לא מיירט:

  • הודעות בודדות שנשלחו באמצעות חיבור WebSocket קיים.
  • חיבור נסגר באמצעות WebSocket.

הפניות אוטומטיות לא נתמכות בבקשות WebSocket.

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

החל מגרסה 96 של Chrome, webRequest API תומך ביירוט של WebTransport באמצעות HTTP/3 לבקשת לחיצת יד. מכיוון שלחיצת היד מתבצעת באמצעות בקשת HTTP CONNECT, הזרימה הזאת למודל webRequest שמכוון ל-HTTP. הערה:

  • אחרי שיוצרים את הסשן, התוספים לא יכולים לצפות בסשן או להתערב בו דרך webRequest API.
  • המערכת מתעלמת משינוי הכותרות של בקשת HTTP ב-onBeforeSendHeaders.
  • אין תמיכה בהפניות אוטומטיות ובשיטות אימות ב-WebTransport ב-HTTP/3.

מזהי הבקשות

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

רישום פונקציות event listener

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

שלושת הארגומנטים ב-addListener() של ה-API של בקשת האינטרנט כוללים את ההגדרות הבאות:

var callback = function(details) {...};
var filter = {...};
var opt_extraInfoSpec = [...];

הנה דוגמה להאזנה לאירוע onBeforeRequest:

chrome.webRequest.onBeforeRequest.addListener(
    callback, filter, opt_extraInfoSpec);

כל קריאה ל-addListener() משתמשת בפונקציית קריאה חוזרת שהיא חובה בתור הפרמטר הראשון. הקריאה החוזרת (callback) הזו הפונקציה מועברת מילון שמכיל מידע על בקשת כתובת ה-URL הנוכחית. המידע במילון הזה תלוי בסוג האירוע הספציפי ובתוכן opt_extraInfoSpec

אם המערך האופציונלי opt_extraInfoSpec מכיל את המחרוזת 'blocking' (מותר רק עבור אירועים ספציפיים), פונקציית הקריאה החוזרת מטופלת באופן סינכרוני. המשמעות היא שהבקשה ייחסם עד שפונקציית הקריאה החוזרת תחזור במקרה כזה, הקריאה החוזרת יכולה להחזיר webRequest.BlockingResponse שקובע את מחזור החיים הנוסף של הבקשה. בהתאם בהקשר, התשובה הזו מאפשרת לבטל או להפנות בקשה מחדש (onBeforeRequest), ביטול בקשה או שינוי כותרות (onBeforeSendHeaders, onHeadersReceived), וגם ביטול בקשה או מסירת פרטי כניסה לאימות (onAuthRequired).

אם המערך האופציונלי opt_extraInfoSpec מכיל במקום זאת את המחרוזת 'asyncBlocking' (רק מותרת עבור onAuthRequired), התוסף יכול ליצור את הwebRequest.BlockingResponse באופן אסינכרוני.

filter של webRequest.RequestFilter מאפשר להגביל את הבקשות של אירועים מופעלות במאפיינים שונים:

כתובות URL
תבניות URL כמו *://www.google.com/foo*bar.
סוגים
סוגי בקשות כמו main_frame (מסמך שנטען למסגרת ברמה עליונה), sub_frame שנטען עבור מסגרת מוטמעת) ו-image (תמונה באתר אינטרנט). צפייה webRequest.RequestFilter
מזהה הכרטיסייה
המזהה של כרטיסייה אחת.
מזהה חלון
המזהה של חלון.

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

טיפול באימות

כדי לטפל בבקשות לאימות HTTP, צריך להוסיף את "webRequestAuthProvider" הרשאה לקובץ המניפסט:

{
  "permissions": [
    "webRequest",
    "webRequestAuthProvider"
  ]
}

חשוב לשים לב שההרשאה הזו לא נדרשת לתוסף שמותקן במדיניות עם ההרשאה "webRequestBlocking".

כדי לספק פרטי כניסה באופן סינכרוני:

chrome.webRequest.onAuthRequired.addListener((details) => {
    return {
      authCredentials: {
        username: 'guest',
        password: 'guest'
      }
    };
  },
  { urls: ['https://httpbin.org/basic-auth/guest/guest'] },
  ['blocking']
);

כדי לספק פרטי כניסה באופן אסינכרוני:

chrome.webRequest.onAuthRequired.addListener((details, callback) => {
    callback({
      authCredentials: {
        username: 'guest',
        password: 'guest'
      }
    });
  },
  { urls: ['https://httpbin.org/basic-auth/guest/guest'] },
  ['asyncBlocking']
);

פרטי ההטמעה

חשוב להבין כמה פרטים על ההטמעה כשמפתחים תוסף שמשתמש ממשק ה-API של בקשת האינטרנט:

web_accessible_resources

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

יישוב מחלוקות

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

שמירה במטמון

Chrome משתמש בשני מטמון – מטמון בדיסק ומטמון מהיר מאוד בזיכרון. משך החיים של המטמון בזיכרון מצורף לכל משך החיים של תהליך העיבוד, בדומה לכרטיסייה. בקשות שנענות ממטמון הזיכרון לא גלויות ל-API של בקשת האינטרנט. אם ה-handler של הבקשות משנה את ההתנהגות שלו (לדוגמה, ההתנהגות שבה הבקשות נחסם), יכול להיות שרענון פשוט של הדף לא יכבד את ההתנהגות הזו שהשתנתה. כדי לוודא שההתנהגות כאשר מתבצע שינוי, יש לקרוא ל-handlerBehaviorChanged() כדי לנקות את המטמון שבזיכרון. אבל לא לעשות את זה לעיתים קרובות; ניקוי המטמון הוא פעולה יקרה מאוד. אין צורך להתקשר handlerBehaviorChanged() אחרי רישום או ביטול הרישום של האזנה לאירועים.

חותמות זמן

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

טיפול בשגיאות

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

דוגמאות

הדוגמה הבאה ממחישה איך לחסום את כל הבקשות אל www.evil.com:

chrome.webRequest.onBeforeRequest.addListener(
  function(details) {
    return {cancel: details.url.indexOf("://www.evil.com/") != -1};
  },
  {urls: ["<all_urls>"]},
  ["blocking"]
);

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

בדוגמה הבאה משיגים את אותו יעד בדרך יעילה יותר, כי בקשות שלא אין צורך להעביר את הטירגוט ל-www.evil.com לתוסף:

chrome.webRequest.onBeforeRequest.addListener(
  function(details) { return {cancel: true}; },
  {urls: ["*://www.evil.com/*"]},
  ["blocking"]
);

הדוגמה הבאה ממחישה איך מוחקים את הכותרת של סוכן המשתמש מכל הבקשות:

chrome.webRequest.onBeforeSendHeaders.addListener(
  function(details) {
    for (var i = 0; i < details.requestHeaders.length; ++i) {
      if (details.requestHeaders[i].name === 'User-Agent') {
        details.requestHeaders.splice(i, 1);
        break;
      }
    }
    return {requestHeaders: details.requestHeaders};
  },
  {urls: ["<all_urls>"]},
  ["blocking", "requestHeaders"]
);

כדי לנסות את ה-API של chrome.webRequest, להתקין את דוגמה WebRequest מ-chrome-extension-samples של מאגר הנתונים.

סוגים

BlockingResponse

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

מאפיינים

  • authCredentials

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

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

    • סיסמה

      מחרוזת

    • שם משתמש

      מחרוזת

  • ביטול

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

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

  • redirectUrl

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

    משמש רק כתגובה לאירועי onBeforeRequest ו-onHeadersReceived. אם המדיניות מוגדרת, המערכת מונעת שליחה/השלמה של הבקשה המקורית, ובמקום זאת היא מפנה לכתובת ה-URL הנתונה. מותר להשתמש בהפניות מחדש לסכימות שאינן HTTP כמו data:. הפניות אוטומטיות שיזמו פעולת הפניה אוטומטית משתמשות בשיטת הבקשה המקורית להפניה אוטומטית, פרט למקרה חריג אחד: אם ההפניה האוטומטית מופעלת בשלב onHeadersReceived, ההפניה האוטומטית תונפק באמצעות שיטת GET. המערכת תתעלם מהפניות אוטומטיות מכתובות URL עם סכמות ws:// ו-wss://.

  • requestHeaders

    HttpHeaders אופציונלי

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

  • responseHeaders

    HttpHeaders אופציונלי

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

FormDataItem

Chrome 66 ואילך

מכיל נתונים שהועברו בתוך נתוני הטופס. בפורמט עם כתובת URL מקודדת הוא מאוחסן כמחרוזת אם הנתונים הם מחרוזת utf-8, ואם לא – הוא מאוחסן כ-ArrayBuffer. לנתוני טופס הוא ArrayBuffer. אם הפרמטר form-data מייצג העלאה של קובץ, הוא צריך להיות מחרוזת עם שם הקובץ, אם ציינתם את שם הקובץ.

Enum

ArrayBuffer

מחרוזת

HttpHeaders

מערך של כותרות HTTP. כל כותרת מיוצגת כמילון שמכיל את המפתחות name וגם value או binaryValue.

סוג

object[]

מאפיינים

  • binaryValue

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

    ערך של כותרת ה-HTTP אם לא ניתן לייצג אותה על ידי UTF-8, מאוחסן כערכי בייטים נפרדים (0..255).

  • שם

    מחרוזת

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

  • ערך

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

    הערך של כותרת ה-HTTP, אם אפשר לייצג אותה על ידי UTF-8.

IgnoredActionType

Chrome 70+

Enum

"redirect"

"request_headers"

&quot;response_headers&quot;

&quot;auth_credentials&quot;

OnAuthRequiredOptions

Chrome 44 ואילך

Enum

&quot;responseHeaders&quot;
ההגדרה קובעת שצריך לכלול את כותרות התגובות באירוע.

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

&quot;asyncBlocking&quot;
מציין שפונקציית הקריאה החוזרת מטופלת באופן אסינכרוני.

"extraHeaders"
מציין שכותרות יכולות להפר את שיתוף המשאבים בין מקורות (CORS).

OnBeforeRedirectOptions

Chrome 44 ואילך

Enum

&quot;responseHeaders&quot;
ההגדרה קובעת שצריך לכלול את כותרות התגובות באירוע.

"extraHeaders"
מציין שכותרות יכולות להפר את שיתוף המשאבים בין מקורות (CORS).

OnBeforeRequestOptions

Chrome 44 ואילך

Enum

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

&quot;requestBody&quot;
מציין שיש לכלול את גוף הבקשה באירוע.

"extraHeaders"
מציין שכותרות יכולות להפר את שיתוף המשאבים בין מקורות (CORS).

OnBeforeSendHeadersOptions

Chrome 44 ואילך

Enum

&quot;requestHeaders&quot;
מציין שצריך לכלול באירוע את כותרת הבקשה.

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

"extraHeaders"
מציין שכותרות יכולות להפר את שיתוף המשאבים בין מקורות (CORS).

OnCompletedOptions

Chrome 44 ואילך

Enum

&quot;responseHeaders&quot;
ההגדרה קובעת שצריך לכלול את כותרות התגובות באירוע.

"extraHeaders"
מציין שכותרות יכולות להפר את שיתוף המשאבים בין מקורות (CORS).

OnErrorOccurredOptions

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

ערך

"extraHeaders"

OnHeadersReceivedOptions

Chrome 44 ואילך

Enum

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

&quot;responseHeaders&quot;
ההגדרה קובעת שצריך לכלול את כותרות התגובות באירוע.

"extraHeaders"
מציין שכותרות יכולות להפר את שיתוף המשאבים בין מקורות (CORS).

OnResponseStartedOptions

Chrome 44 ואילך

Enum

&quot;responseHeaders&quot;
ההגדרה קובעת שצריך לכלול את כותרות התגובות באירוע.

"extraHeaders"
מציין שכותרות יכולות להפר את שיתוף המשאבים בין מקורות (CORS).

OnSendHeadersOptions

Chrome 44 ואילך

Enum

&quot;requestHeaders&quot;
מציין שצריך לכלול באירוע את כותרת הבקשה.

"extraHeaders"
מציין שכותרות יכולות להפר את שיתוף המשאבים בין מקורות (CORS).

RequestFilter

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

מאפיינים

  • tabId

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

  • סוגים

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

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

  • כתובות אתרים

    String[]

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

  • windowId

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

ResourceType

Chrome 44 ואילך

Enum

"main_frame"
הפרמטר הזה מציין את המשאב בתור המסגרת הראשית.

"sub_frame"
ההגדרה הזו מציינת את המשאב בתור מסגרת משנה.

"stylesheet"
מציין את המשאב כגיליון סגנונות.

&quot;script&quot;
מציין את המשאב כסקריפט.

"image"
מציין את המשאב כתמונה.

"font"
מציין את המשאב כגופן.

"object"
מציין את המשאב כאובייקט.

&quot;xmlhttprequest&quot;
מציין את המשאב בתור XMLHttpRequest.

"ping"
מציין את המשאב כפינג.

&quot;csp_report&quot;
המציין את המשאב בתור דוח Content Security Policy (CSP).

"media"
מציינים את המשאב כאובייקט מדיה.

"websocket"
הגדרת המשאב בתור WebSocket.

"webbundle"
מציין את המשאב כ-WebBundle.

"אחר"
מציין את המשאב כסוג שלא נכלל בסוגים הרשומים.

UploadData

מכיל נתונים שהועלו בבקשה לכתובת URL.

מאפיינים

  • בייטים

    כל אופציונלי

    ArrayBuffer עם עותק של הנתונים.

  • קובץ

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

    מחרוזת עם הנתיב והשם של הקובץ.

מאפיינים

MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES

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

ערך

20

שיטות

handlerBehaviorChanged()

הבטחה 
chrome.webRequest.handlerBehaviorChanged(
  callback?: function,
)

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

פרמטרים

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome 116 ואילך

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

אירועים

onActionIgnored

Chrome 70+ 
chrome.webRequest.onActionIgnored.addListener(
  callback: function,
)

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

פרמטרים

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

    פונקציה

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

    (details: object) => void

    • פרטים

      אובייקט

      • פעולה

        IgnoredActionType

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

      • requestId

        מחרוזת

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

onAuthRequired

chrome.webRequest.onAuthRequired.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnAuthRequiredOptions[],
)

מופעל כשמתקבלת כשל באימות. ל-listener יש שלוש אפשרויות: הוא יכול לספק פרטי כניסה לאימות, לבטל את הבקשה ולהציג את דף השגיאה, או לא לבצע שום פעולה באתגר. אם תספקו פרטי כניסה שגויים של המשתמש, ייתכן שהמערכת תקרא לכך כמה פעמים עבור אותה בקשה. הערה, צריך לציין רק אחד מהמצבים 'blocking' או 'asyncBlocking' בפרמטר extraInfoSpec.

פרמטרים

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

    פונקציה

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

    (details: object, asyncCallback?: function) => BlockingResponse | undefined

    • פרטים

      אובייקט

      • מתמודד

        אובייקט

        השרת שמבקש אימות.

        • מארח

          מחרוזת

        • יציאה

          number

      • documentId

        מחרוזת

        Chrome 106+

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

      • Chrome 106+

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

      • frameId

        number

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

      • Chrome 106+

        סוג המסגרת שבה התרחשה הבקשה.

      • יוזם

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

        Chrome 63+

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

      • isProxy

        בוליאני

        הערך הוא True לצורך אימות proxy ו-FALSE עבור WWW-Authenticate.

      • method

        מחרוזת

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

      • parentDocumentId

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

        Chrome 106+

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

      • parentFrameId

        number

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

      • מקבץ שרתי משחק (Realm)

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

        תחום האימות שסופק על ידי השרת, אם קיים.

      • requestId

        מחרוזת

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

      • responseHeaders

        HttpHeaders אופציונלי

        כותרות תגובת ה-HTTP שהתקבלו יחד עם התשובה הזו.

      • סכמה

        מחרוזת

        סכימת האימות, למשל 'בסיסי' או 'תקציר'.

      • statusCode

        number

        Chrome 43 ואילך

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

      • statusLine

        מחרוזת

        שורת הסטטוס של HTTP בתשובה או 'HTTP/0.9 200 OK' מחרוזת לתגובות HTTP/0.9 (כלומר תגובות שאין בהן שורת סטטוס) או מחרוזת ריקה אם אין כותרות.

      • tabId

        number

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

      • timeStamp

        number

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

      • סוג

        ResourceType

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

      • כתובת אתר

        מחרוזת

    • asyncCallback

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

      Chrome 58 ואילך

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

      (response: BlockingResponse) => void

    • החזרות

      BlockingResponse | לא מוגדר

      אם "חוסמים" מצוין ב-'extraInfoSpec' פרמטר, ה-event listener צריך להחזיר אובייקט מהסוג הזה.

  • סינון

    RequestFilter

  • extraInfoSpec

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

onBeforeRedirect

chrome.webRequest.onBeforeRedirect.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnBeforeRedirectOptions[],
)

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

פרמטרים

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

    פונקציה

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

    (details: object) => void

    • פרטים

      אובייקט

      • documentId

        מחרוזת

        Chrome 106+

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

      • Chrome 106+

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

      • frameId

        number

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

      • Chrome 106+

        סוג המסגרת שבה התרחשה הבקשה.

      • fromCache

        בוליאני

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

      • יוזם

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

        Chrome 63+

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

      • ip

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

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

      • method

        מחרוזת

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

      • parentDocumentId

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

        Chrome 106+

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

      • parentFrameId

        number

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

      • redirectUrl

        מחרוזת

        כתובת ה-URL החדשה.

      • requestId

        מחרוזת

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

      • responseHeaders

        HttpHeaders אופציונלי

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

      • statusCode

        number

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

      • statusLine

        מחרוזת

        שורת הסטטוס של HTTP בתשובה או 'HTTP/0.9 200 OK' מחרוזת לתגובות HTTP/0.9 (כלומר תגובות שאין בהן שורת סטטוס) או מחרוזת ריקה אם אין כותרות.

      • tabId

        number

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

      • timeStamp

        number

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

      • סוג

        ResourceType

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

      • כתובת אתר

        מחרוזת

  • סינון

    RequestFilter

  • extraInfoSpec

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

onBeforeRequest

chrome.webRequest.onBeforeRequest.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnBeforeRequestOptions[],
)

מופעל כשבקשה עומדת להתרחש.

פרמטרים

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

    פונקציה

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

    (details: object) => BlockingResponse | undefined

    • פרטים

      אובייקט

      • documentId

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

        Chrome 106+

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

      • documentLifecycle

        extensionTypes.DocumentLifecycle optional

        Chrome 106+

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

      • frameId

        number

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

      • frameType

        extensionTypes.FrameType optional

        Chrome 106+

        סוג המסגרת שבה התרחשה הבקשה.

      • יוזם

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

        Chrome 63+

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

      • method

        מחרוזת

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

      • parentDocumentId

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

        Chrome 106+

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

      • parentFrameId

        number

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

      • requestBody

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

        מכיל את הנתונים בגוף בקשת ה-HTTP. סופק רק אם extraInfoSpec מכיל 'requestBody'.

        • error

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

          שגיאות בהשגת הנתונים של גוף הבקשה.

        • formData

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

          אם שיטת הבקשה היא POST והגוף הוא רצף של צמדי מפתח/ערך שמקודדים ב-UTF8 ומקודדים כ-multipart/form-data או כ-app/x-www-form-urlencoded, המילון הזה קיים ולכל מפתח מכיל את רשימת כל הערכים של המפתח הזה. אם הנתונים הם מסוג מדיה אחר או אם הם שגויים, המילון לא קיים. ערך לדוגמה של המילון הזה הוא {'key': ['value1', 'value2']}.

        • גולמי

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

          אם שיטת הבקשה היא PUT או POST, והגוף לא מנות כבר ב-formData, רכיבי גוף הבקשה שלא נותחו נכללים במערך הזה.

      • requestId

        מחרוזת

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

      • tabId

        number

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

      • timeStamp

        number

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

      • סוג

        ResourceType

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

      • כתובת אתר

        מחרוזת

    • החזרות

      BlockingResponse | לא מוגדר

      אם "חוסמים" מצוין ב-'extraInfoSpec' פרמטר, ה-event listener צריך להחזיר אובייקט מהסוג הזה.

  • סינון

    RequestFilter

  • extraInfoSpec

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

onBeforeSendHeaders

chrome.webRequest.onBeforeSendHeaders.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnBeforeSendHeadersOptions[],
)

מופעל לפני שליחה של בקשת HTTP, ברגע שכותרות הבקשות זמינות. מצב זה עשוי להתרחש לאחר יצירת חיבור TCP לשרת, אבל לפני שליחה של נתוני HTTP.

פרמטרים

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

    פונקציה

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

    (details: object) => BlockingResponse | undefined

    • פרטים

      אובייקט

      • documentId

        מחרוזת

        Chrome 106+

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

      • Chrome 106+

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

      • frameId

        number

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

      • Chrome 106+

        סוג המסגרת שבה התרחשה הבקשה.

      • יוזם

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

        Chrome 63+

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

      • method

        מחרוזת

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

      • parentDocumentId

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

        Chrome 106+

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

      • parentFrameId

        number

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

      • requestHeaders

        HttpHeaders אופציונלי

        הכותרות של בקשת ה-HTTP שיישלחו עם הבקשה הזו.

      • requestId

        מחרוזת

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

      • tabId

        number

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

      • timeStamp

        number

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

      • סוג

        ResourceType

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

      • כתובת אתר

        מחרוזת

    • החזרות

      BlockingResponse | לא מוגדר

      אם "חוסמים" מצוין ב-'extraInfoSpec' פרמטר, ה-event listener צריך להחזיר אובייקט מהסוג הזה.

  • סינון

    RequestFilter

  • extraInfoSpec

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

onCompleted

chrome.webRequest.onCompleted.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnCompletedOptions[],
)

מופעל כשמתבצעת בקשה להשלמת בקשה.

פרמטרים

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

    פונקציה

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

    (details: object) => void

    • פרטים

      אובייקט

      • documentId

        מחרוזת

        Chrome 106+

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

      • Chrome 106+

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

      • frameId

        number

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

      • Chrome 106+

        סוג המסגרת שבה התרחשה הבקשה.

      • fromCache

        בוליאני

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

      • יוזם

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

        Chrome 63+

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

      • ip

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

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

      • method

        מחרוזת

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

      • parentDocumentId

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

        Chrome 106+

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

      • parentFrameId

        number

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

      • requestId

        מחרוזת

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

      • responseHeaders

        HttpHeaders אופציונלי

        כותרות תגובת ה-HTTP שהתקבלו יחד עם התשובה הזו.

      • statusCode

        number

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

      • statusLine

        מחרוזת

        שורת הסטטוס של HTTP בתשובה או 'HTTP/0.9 200 OK' מחרוזת לתגובות HTTP/0.9 (כלומר תגובות שאין בהן שורת סטטוס) או מחרוזת ריקה אם אין כותרות.

      • tabId

        number

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

      • timeStamp

        number

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

      • סוג

        ResourceType

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

      • כתובת אתר

        מחרוזת

  • סינון

    RequestFilter

  • extraInfoSpec

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

onErrorOccurred

chrome.webRequest.onErrorOccurred.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnErrorOccurredOptions[],
)

מופעל כשמתרחשת שגיאה.

פרמטרים

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

    פונקציה

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

    (details: object) => void

    • פרטים

      אובייקט

      • documentId

        מחרוזת

        Chrome 106+

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

      • Chrome 106+

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

      • error

        מחרוזת

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

      • frameId

        number

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

      • Chrome 106+

        סוג המסגרת שבה התרחשה הבקשה.

      • fromCache

        בוליאני

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

      • יוזם

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

        Chrome 63+

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

      • ip

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

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

      • method

        מחרוזת

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

      • parentDocumentId

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

        Chrome 106+

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

      • parentFrameId

        number

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

      • requestId

        מחרוזת

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

      • tabId

        number

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

      • timeStamp

        number

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

      • סוג

        ResourceType

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

      • כתובת אתר

        מחרוזת

  • סינון

    RequestFilter

  • extraInfoSpec

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

onHeadersReceived

chrome.webRequest.onHeadersReceived.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnHeadersReceivedOptions[],
)

מופעל כשמקבלים כותרות תגובת HTTP של בקשה.

פרמטרים

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

    פונקציה

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

    (details: object) => BlockingResponse | undefined

    • פרטים

      אובייקט

      • documentId

        מחרוזת

        Chrome 106+

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

      • Chrome 106+

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

      • frameId

        number

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

      • Chrome 106+

        סוג המסגרת שבה התרחשה הבקשה.

      • יוזם

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

        Chrome 63+

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

      • method

        מחרוזת

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

      • parentDocumentId

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

        Chrome 106+

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

      • parentFrameId

        number

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

      • requestId

        מחרוזת

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

      • responseHeaders

        HttpHeaders אופציונלי

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

      • statusCode

        number

        Chrome 43 ואילך

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

      • statusLine

        מחרוזת

        שורת הסטטוס של HTTP בתשובה או 'HTTP/0.9 200 OK' מחרוזת עבור תגובות HTTP/0.9 (כלומר תגובות ללא שורת סטטוס).

      • tabId

        number

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

      • timeStamp

        number

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

      • סוג

        ResourceType

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

      • כתובת אתר

        מחרוזת

    • החזרות

      BlockingResponse | לא מוגדר

      אם "חוסמים" מצוין ב-'extraInfoSpec' פרמטר, ה-event listener צריך להחזיר אובייקט מהסוג הזה.

  • סינון

    RequestFilter

  • extraInfoSpec

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

onResponseStarted

chrome.webRequest.onResponseStarted.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnResponseStartedOptions[],
)

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

פרמטרים

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

    פונקציה

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

    (details: object) => void

    • פרטים

      אובייקט

      • documentId

        מחרוזת

        Chrome 106+

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

      • Chrome 106+

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

      • frameId

        number

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

      • Chrome 106+

        סוג המסגרת שבה התרחשה הבקשה.

      • fromCache

        בוליאני

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

      • יוזם

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

        Chrome 63+

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

      • ip

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

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

      • method

        מחרוזת

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

      • parentDocumentId

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

        Chrome 106+

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

      • parentFrameId

        number

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

      • requestId

        מחרוזת

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

      • responseHeaders

        HttpHeaders אופציונלי

        כותרות תגובת ה-HTTP שהתקבלו יחד עם התשובה הזו.

      • statusCode

        number

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

      • statusLine

        מחרוזת

        שורת הסטטוס של HTTP בתשובה או 'HTTP/0.9 200 OK' מחרוזת לתגובות HTTP/0.9 (כלומר תגובות שאין בהן שורת סטטוס) או מחרוזת ריקה אם אין כותרות.

      • tabId

        number

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

      • timeStamp

        number

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

      • סוג

        ResourceType

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

      • כתובת אתר

        מחרוזת

  • סינון

    RequestFilter

  • extraInfoSpec

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

onSendHeaders

chrome.webRequest.onSendHeaders.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnSendHeadersOptions[],
)

מופעלת ממש לפני שהבקשה תישלח לשרת (שינויים בקריאות החוזרות הקודמות של onBeforeSendHeaders יהיו גלויים לפני ההפעלה של onSendHeaders).

פרמטרים

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

    פונקציה

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

    (details: object) => void

    • פרטים

      אובייקט

      • documentId

        מחרוזת

        Chrome 106+

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

      • Chrome 106+

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

      • frameId

        number

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

      • Chrome 106+

        סוג המסגרת שבה התרחשה הבקשה.

      • יוזם

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

        Chrome 63+

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

      • method

        מחרוזת

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

      • parentDocumentId

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

        Chrome 106+

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

      • parentFrameId

        number

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

      • requestHeaders

        HttpHeaders אופציונלי

        הכותרות של בקשת ה-HTTP שנשלחו עם הבקשה הזו.

      • requestId

        מחרוזת

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

      • tabId

        number

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

      • timeStamp

        number

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

      • סוג

        ResourceType

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

      • כתובת אתר

        מחרוזת

  • סינון

    RequestFilter

  • extraInfoSpec

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