chrome.webRequest

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

תיאור

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

הרשאות

webRequest

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

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

webRequestBlocking

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

webRequestAuthProvider

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

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

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

ה-Web request 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. לא בטוח שהרשימה הזו תהיה מלאה או יציבה.

• הרשאה
• פקד המטמון
• חיבור
• Content-Length
• Host
• אם השתנה מאז
• אם-ללא-התאמה
• אם-טווח
• נתונים חלקיים
• פרגמה
• הרשאת proxy
• חיבור proxy
• קידוד העברה

החל מ-Chrome 79, שינויים בכותרות של בקשות משפיעים על הבדיקות של שיתוף משאבים בין מקורות (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:

• מקור

הערה: יכול להיות ששינוי כותרת הבקשה Origin לא יפעל כמצופה ועלול לגרום לשגיאות לא צפויות בבדיקות CORS של התגובה. הסיבה לכך היא שתוספים יכולים לשנות רק את כותרת הבקשה Origin, אבל הם לא יכולים לשנות את request origin או את היוזם, שהם קונספט שמוגדר במפרט האחזור על מנת לייצג את מי שמתחיל את הבקשה. בתרחיש כזה, השרת עשוי לאפשר ל-CORS גישה לבקשה ששונתה, ולהכניס את ה-Origin של הכותרת לכותרת Access-Control-Allow-Origin בתגובה. אבל הוא לא יתאים לערך בשדה request origin שלא ניתן לשינוי ויגרום לכשל ב-CORS.

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

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

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

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

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

הערה: לציון 'extraHeaders' ב-opt_extraInfoSpec עלולה להיות השפעה שלילית על הביצועים, ולכן יש להשתמש בו רק כשצריך להשתמש בו בלבד.

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

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

• הודעות נפרדות שנשלחות דרך חיבור WebSocket קיים.
• החיבור של WebSocket נסגר.

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

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

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

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

מזהי בקשות

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

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

כדי לרשום פונקציות 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' (מותר רק לאירועים ספציפיים), פונקציית הקריאה החוזרת מטופלת באופן סינכרוני. המשמעות היא שהבקשה חסומה עד שפונקציית הקריאה החוזרת (callback) תוחזר. במקרה כזה, הקריאה החוזרת יכולה להחזיר webRequest.BlockingResponse שקובע את מחזור החיים הנוסף של הבקשה. בהתאם להקשר, התגובה הזו מאפשרת לבטל בקשה או להפנות אותה לכתובת אחרת (onBeforeRequest), לבטל בקשה או לשנות כותרות (onBeforeSendHeaders, onHeadersReceived) ולבטל בקשה או לספק פרטי כניסה (onAuthRequired).

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

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

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

יישוב סכסוכים

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

שמירה במטמון

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

חותמות זמן

המאפיין 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

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

תכונות

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

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

ArrayBuffer

מחרוזת

HttpHeaders

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

סוג

אובייקט[]

תכונות

• binaryValue

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

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

• name

  מחרוזת

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

• value

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

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

IgnoredActionType

Chrome 70 ומעלה

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

"request_headers"

"response_headers"

OnAuthRequiredOptions

Chrome 44 ואילך

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

"ResponseHeaders"
מציין שכותרות התגובות צריכות להיות כלולות באירוע.

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

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

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

OnBeforeRedirectOptions

Chrome 44 ואילך

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

"ResponseHeaders"
מציין שכותרות התגובות צריכות להיות כלולות באירוע.

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

OnBeforeRequestOptions

Chrome 44 ואילך

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

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

"requestBody"
מציין שגוף הבקשה צריך להיכלל באירוע.

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

OnBeforeSendHeadersOptions

Chrome 44 ואילך

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

"requestHeaders"
מציין שכותרת הבקשה צריכה להיכלל באירוע.

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

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

OnCompletedOptions

Chrome 44 ואילך

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

"ResponseHeaders"
מציין שכותרות התגובות צריכות להיות כלולות באירוע.

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

OnErrorOccurredOptions

Chrome 79 ומעלה

Value

"extraHeaders"

OnHeadersReceivedOptions

Chrome 44 ואילך

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

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

"ResponseHeaders"
מציין שכותרות התגובות צריכות להיות כלולות באירוע.

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

OnResponseStartedOptions

Chrome 44 ואילך

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

"ResponseHeaders"
מציין שכותרות התגובות צריכות להיות כלולות באירוע.

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

OnSendHeadersOptions

Chrome 44 ואילך

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

"requestHeaders"
מציין שכותרת הבקשה צריכה להיכלל באירוע.

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

RequestFilter

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

תכונות

• tabId

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

• סוגים

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

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

• urls

  מחרוזת[]

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

• windowId

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

ResourceType

Chrome 44 ואילך

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

"main_frame"
מגדיר את המשאב בתור המסגרת הראשית.

"sub_frame"
מציין את המשאב כמסגרת משנה.

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

"script"
מגדיר את המשאב כסקריפט.

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

"font"
הגדרת המשאב כגופן.

"object"
מגדיר את המשאב כאובייקט.

"xmlhttprequest"
מגדיר את המשאב כ-XMLHttpRequest.

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

'csp_report'
ההגדרה קובעת את המשאב כדוח 'מדיניות אבטחת תוכן' (CSP).

"media"
מגדיר את המשאב כאובייקט מדיה.

"websocket"
מציין את המשאב כ-WebSocket.

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

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

UploadData

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

תכונות

• בייטים

  כל אופציונלי

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

• קובץ

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

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

תכונות

MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES

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

Value

20

שיטות

handlerBehaviorChanged()

הבטחה

chrome.webRequest.handlerBehaviorChanged(
  callback?: function,
)

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

פרמטרים

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

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

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

  ()=>void

החזרות

• Promise<void>

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

פרמטרים

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

  פונקציה

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

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

  • פרטים

    אובייקט

    • מתמודד

      אובייקט

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

      • מארח

        מחרוזת

      • יציאה

        מספר

    • documentId

      מחרוזת

      Chrome 106 ומעלה

      ה-UUID של המסמך שממנו נשלחה הבקשה.

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 ומעלה

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

    • frameId

      מספר

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

    • frameType

      extensionTypes.FrameType

      Chrome 106 ומעלה

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

    • יוזם

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

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

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

    • isProxy

      boolean

      True עבור Proxy-Authenticate, FALSE ל-WWW-Authenticate.

    • method

      מחרוזת

      שיטת HTTP רגילה.

    • parentDocumentId

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

      Chrome 106 ומעלה

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

    • parentFrameId

      מספר

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

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

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

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

    • requestId

      מחרוזת

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

    • responseHeaders

      HttpHeaders אופציונלי

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

    • סכמה

      מחרוזת

      סכימת האימות, למשל Basic או Digest.

    • statusCode

      מספר

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

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

    • statusLine

      מחרוזת

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

    • tabId

      מספר

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

    • timeStamp

      מספר

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

    • סוג

      ResourceType

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

    • כתובת אתר

      מחרוזת

  • asyncCallback

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

    Chrome בגרסה 58 ומעלה

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

    (response: BlockingResponse)=>void

    • תשובה

      BlockingResponse

  • החזרות

    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 של המסמך שממנו נשלחה הבקשה.

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 ומעלה

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

    • frameId

      מספר

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

    • frameType

      extensionTypes.FrameType

      Chrome 106 ומעלה

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

    • fromCache

      boolean

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

    • יוזם

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

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

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

    • ip

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

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

    • method

      מחרוזת

      שיטת HTTP רגילה.

    • parentDocumentId

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

      Chrome 106 ומעלה

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

    • parentFrameId

      מספר

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

    • redirectUrl

      מחרוזת

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

    • requestId

      מחרוזת

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

    • responseHeaders

      HttpHeaders אופציונלי

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

    • statusCode

      מספר

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

    • statusLine

      מחרוזת

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

    • tabId

      מספר

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

    • timeStamp

      מספר

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

    • סוג

      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 אופציונלי

      Chrome 106 ומעלה

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

    • frameId

      מספר

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

    • frameType

      extensionTypes.FrameType אופציונלי

      Chrome 106 ומעלה

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

    • יוזם

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

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

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

    • method

      מחרוזת

      שיטת HTTP רגילה.

    • parentDocumentId

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

      Chrome 106 ומעלה

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

    • parentFrameId

      מספר

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

    • requestBody

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

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

      • error

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

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

      • formData

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

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

      • גולמי

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

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

    • requestId

      מחרוזת

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

    • tabId

      מספר

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

    • timeStamp

      מספר

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

    • סוג

      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 של המסמך שממנו נשלחה הבקשה.

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 ומעלה

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

    • frameId

      מספר

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

    • frameType

      extensionTypes.FrameType

      Chrome 106 ומעלה

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

    • יוזם

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

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

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

    • method

      מחרוזת

      שיטת HTTP רגילה.

    • parentDocumentId

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

      Chrome 106 ומעלה

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

    • parentFrameId

      מספר

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

    • requestHeaders

      HttpHeaders אופציונלי

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

    • requestId

      מחרוזת

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

    • tabId

      מספר

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

    • timeStamp

      מספר

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

    • סוג

      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 של המסמך שממנו נשלחה הבקשה.

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 ומעלה

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

    • frameId

      מספר

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

    • frameType

      extensionTypes.FrameType

      Chrome 106 ומעלה

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

    • fromCache

      boolean

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

    • יוזם

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

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

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

    • ip

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

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

    • method

      מחרוזת

      שיטת HTTP רגילה.

    • parentDocumentId

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

      Chrome 106 ומעלה

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

    • parentFrameId

      מספר

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

    • requestId

      מחרוזת

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

    • responseHeaders

      HttpHeaders אופציונלי

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

    • statusCode

      מספר

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

    • statusLine

      מחרוזת

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

    • tabId

      מספר

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

    • timeStamp

      מספר

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

    • סוג

      ResourceType

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

    • כתובת אתר

      מחרוזת

• סינון

  RequestFilter

• extraInfoSpec

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

onErrorOccurred

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

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

פרמטרים

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

  פונקציה

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

  (details: object)=>void

  • פרטים

    אובייקט

    • documentId

      מחרוזת

      Chrome 106 ומעלה

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

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 ומעלה

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

    • error

      מחרוזת

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

    • frameId

      מספר

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

    • frameType

      extensionTypes.FrameType

      Chrome 106 ומעלה

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

    • fromCache

      boolean

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

    • יוזם

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

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

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

    • ip

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

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

    • method

      מחרוזת

      שיטת HTTP רגילה.

    • parentDocumentId

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

      Chrome 106 ומעלה

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

    • parentFrameId

      מספר

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

    • requestId

      מחרוזת

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

    • tabId

      מספר

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

    • timeStamp

      מספר

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

    • סוג

      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 של המסמך שממנו נשלחה הבקשה.

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 ומעלה

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

    • frameId

      מספר

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

    • frameType

      extensionTypes.FrameType

      Chrome 106 ומעלה

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

    • יוזם

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

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

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

    • method

      מחרוזת

      שיטת HTTP רגילה.

    • parentDocumentId

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

      Chrome 106 ומעלה

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

    • parentFrameId

      מספר

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

    • requestId

      מחרוזת

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

    • responseHeaders

      HttpHeaders אופציונלי

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

    • statusCode

      מספר

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

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

    • statusLine

      מחרוזת

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

    • tabId

      מספר

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

    • timeStamp

      מספר

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

    • סוג

      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 של המסמך שממנו נשלחה הבקשה.

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 ומעלה

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

    • frameId

      מספר

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

    • frameType

      extensionTypes.FrameType

      Chrome 106 ומעלה

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

    • fromCache

      boolean

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

    • יוזם

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

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

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

    • ip

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

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

    • method

      מחרוזת

      שיטת HTTP רגילה.

    • parentDocumentId

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

      Chrome 106 ומעלה

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

    • parentFrameId

      מספר

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

    • requestId

      מחרוזת

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

    • responseHeaders

      HttpHeaders אופציונלי

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

    • statusCode

      מספר

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

    • statusLine

      מחרוזת

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

    • tabId

      מספר

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

    • timeStamp

      מספר

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

    • סוג

      ResourceType

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

    • כתובת אתר

      מחרוזת

• סינון

  RequestFilter

• extraInfoSpec

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

onSendHeaders

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

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

פרמטרים

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

  פונקציה

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

  (details: object)=>void

  • פרטים

    אובייקט

    • documentId

      מחרוזת

      Chrome 106 ומעלה

      ה-UUID של המסמך שממנו נשלחה הבקשה.

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 ומעלה

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

    • frameId

      מספר

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

    • frameType

      extensionTypes.FrameType

      Chrome 106 ומעלה

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

    • יוזם

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

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

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

    • method

      מחרוזת

      שיטת HTTP רגילה.

    • parentDocumentId

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

      Chrome 106 ומעלה

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

    • parentFrameId

      מספר

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

    • requestHeaders

      HttpHeaders אופציונלי

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

    • requestId

      מחרוזת

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

    • tabId

      מספר

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

    • timeStamp

      מספר

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

    • סוג

      ResourceType

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

    • כתובת אתר

      מחרוזת

• סינון

  RequestFilter

• extraInfoSpec

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