chrome.webRequest

refresh date: 2026-09-25 robots: noindex

شرح

از chrome.webRequest API برای مشاهده و تجزیه‌وتحلیل ترافیک و رهگیری، مسدود کردن، یا اصلاح درخواست‌های درحال پردازش استفاده کنید.

اجازه‌ها

webRequest

مانیفست

برای استفاده از میانای برنامه‌سازی کاربردی درخواست وب، باید اجازه "webRequest" را در مانیفست افزونه به‌همراه اجازه‌های میزبان لازم اعلام کنید. برای رهگیری درخواست زیرمنبع، افزونه باید هم به نشانی وب درخواست‌شده و هم به آغازگر آن دسترسی داشته باشد. برای مثال:

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

از Chrome 108، اگر از اجازه‌های "webRequest" و "webRequestAuthProvider" استفاده کنید، می‌توانید به‌صورت ناهمگام اعتبارنامه‌هایی برای رویدادهای onAuthRequired ارائه دهید.

چرخه زندگی درخواست‌ها

میانای برنامه‌سازی کاربردی درخواست وب مجموعه‌ای از رویدادها را تعریف می‌کند که چرخه زندگی درخواست وب را دنبال می‌کنند. می‌توانید از این رویدادها برای مشاهده و تحلیل ترافیک استفاده کنید. برخی‌از رویدادهای همگام به شما امکان می‌دهند درخواست را رهگیری، مسدود، یا اصلاح کنید.

چرخه عمر رویداد برای درخواست‌های موفق در اینجا نشان داده شده است و پس‌از آن تعاریف رویداد آمده است:

چرخه زندگی درخواست وب از دیدگاه میانای برنامه‌سازی کاربردی webrequest

onBeforeRequest (اختیاری همگام)
وقتی درخواستی درحال وقوع باشد، فعال می‌شود. این رویداد قبل‌از برقراری هرگونه اتصال TCP ارسال می‌شود و می‌توان از آن برای لغو یا تغییر مسیر درخواست‌ها استفاده کرد.
onBeforeSendHeaders (اختیاری همگام)
وقتی فعال می‌شود که درخواستی درحال وقوع باشد و سرصفحه‌های اولیه آماده شده باشند. هدف این رویداد این است که به افزونه‌ها اجازه دهد سرایندهای درخواست را اضافه، اصلاح، و حذف کنند (*). رویداد onBeforeSendHeaders به همه مشترکین ارسال می‌شود، بنابراین مشترکین مختلف ممکن است تلاش کنند درخواست را اصلاح کنند؛ برای نحوه مدیریت این موضوع، به بخش جزئیات پیاده‌سازی مراجعه کنید. از این رویداد می‌توان برای لغو درخواست استفاده کرد.
onSendHeaders
پس‌از اینکه همه افزونه‌ها فرصت اصلاح سرایندهای درخواست را پیدا کردند، فعال می‌شود و نسخه نهایی (*) را ارائه می‌دهد. این رویداد قبل‌از ارسال سرصفحه‌ها به شبکه راه‌اندازی می‌شود. این رویداد اطلاعاتی است و به‌صورت ناهمگام مدیریت می‌شود. این کار اجازه اصلاح یا لغو درخواست را نمی‌دهد.
onHeadersReceived (اختیاری همگام)
هر بار که سرایند پاسخ HTTP(S) دریافت می‌شود، فعال می‌شود. به‌دلیل درخواست‌های اصالت‌سنجی و تغییر مسیر، این اتفاق ممکن است چندین بار برای هر درخواست رخ دهد. این رویداد برای این است که به افزونه‌ها اجازه دهد سرایندهای پاسخ را اضافه، اصلاح، و حذف کنند، مثل سرایندهای Content-Type ورودی. دستورالعمل‌های ذخیره‌سازی در حافظه نهان قبل‌از راه‌اندازی این رویداد پردازش می‌شوند، بنابراین اصلاح سرایندهایی مانند Cache-Control تأثیری بر حافظه نهان مرورگر ندارد. همچنین به شما امکان می‌دهد درخواست را لغو یا هدایت کنید.
onAuthRequired (اختیاری همگام)
وقتی فعال می‌شود که درخواستی به اصالت‌سنجی کاربر نیاز داشته باشد. این رویداد را می‌توان به‌صورت هم‌زمان برای ارائه اعتبارنامه‌های اصالت‌سنجی مدیریت کرد. توجه داشته باشید که افزونه‌ها ممکن است اطلاعات اعتباری نامعتبر ارائه دهند. مراقب باشید با ارائه مکرر اعتبارنامه نامعتبر، وارد حلقه بی‌نهایت نشوید. از این دکمه همچنین می‌توان برای لغو درخواست استفاده کرد.
onBeforeRedirect
وقتی هدایت مجدد درحال اجرا باشد فعال می‌شود. بازهدایت می‌تواند توسط کد پاسخ HTTP یا توسط افزونه راه‌اندازی شود. این رویداد اطلاعاتی است و به‌صورت ناهمگام مدیریت می‌شود. این گزینه به شما اجازه نمی‌دهد درخواست را اصلاح یا لغو کنید.
onResponseStarted
وقتی اولین بایت بدنه پاسخ دریافت می‌شود، فعال می‌شود. برای درخواست‌های HTTP، این یعنی خط وضعیت و سرایندهای پاسخ دردسترس هستند. این رویداد اطلاعاتی است و به‌صورت ناهمگام رسیدگی می‌شود. این کار اجازه اصلاح یا لغو درخواست را نمی‌دهد.
onCompleted
وقتی درخواستی با موفقیت پردازش می‌شود، فعال می‌شود.
onErrorOccurred
وقتی درخواست با موفقیت پردازش نشود، فعال می‌شود.

‫web request API تضمین می‌کند که برای هر درخواست، یا onCompleted یا onErrorOccurred به‌عنوان رویداد نهایی اجرا می‌شود، به‌جز یک استثنا: اگر درخواستی به نشانی وب data:// هدایت شود، onBeforeRedirect آخرین رویداد گزارش‌شده است.

* توجه داشته باشید که API درخواست وب، انتزاعی از پشته شبکه را به افزونه ارائه می‌دهد. در داخل، یک درخواست نشانی وب می‌تواند به چند درخواست اچ‌تی‌تی‌پی تقسیم شود (برای مثال، برای واکشی کردن محدوده‌های بایت جداگانه از یک فایل بزرگ) یا می‌تواند توسط پشته شبکه بدون ارتباط با شبکه مدیریت شود. به همین دلیل، میانای برنامه‌سازی کاربردی سرایندهای HTTP نهایی را که به شبکه ارسال می‌شود ارائه نمی‌دهد. برای مثال، همه سرصفحه‌های مربوط به ذخیره‌سازی موقت برای افزونه نامرئی هستند.

درحال‌حاضر، سرصفحه‌های زیر برای رویداد onBeforeSendHeaders ارائه نشده است. تضمینی نیست که این فهرست کامل یا ثابت باشد.

  • صدور مجوز
  • کنترل حافظه نهان
  • اتصال
  • Content-Length
  • میزبان
  • If-Modified-Since
  • If-None-Match
  • If-Range
  • Partial-Data
  • Pragma
  • Proxy-Authorization
  • Proxy-Connection
  • کدبندی انتقال

از Chrome 79، اصلاحات سرایند درخواست بر بررسی‌های «هم‌رسانی منبع میان‌مبدئی» (CORS) تأثیر می‌گذارد. اگر سرصفحه‌های اصلاح‌شده برای درخواست‌های میان‌مبدئی با معیارها مطابقت نداشته باشند، یک پیش‌پرواز CORS ارسال می‌شود تا از سرور بپرسد آیا چنین سرصفحه‌هایی قابل‌پذیرش هستند یا نه. اگر واقعاً لازم است سرصفحه‌ها را به‌گونه‌ای اصلاح کنید که پروتکل CORS نقض شود، باید 'extraHeaders' را در opt_extraInfoSpec مشخص کنید. ازسوی دیگر، اصلاحات سرایند پاسخ برای فریب دادن بررسی‌های CORS کار نمی‌کند. اگر لازم است پروتکل CORS را فریب دهید، باید 'extraHeaders' را نیز برای اصلاحات پاسخ مشخص کنید.

از Chrome نسخه ۷۹ به بعد، webRequest API به‌طور پیش‌فرض درخواست‌ها و پاسخ‌های پیش‌پرواز CORS را رهگیری نمی‌کند. اگر شنونده‌ای با 'extraHeaders' مشخص‌شده در opt_extraInfoSpec برای نشانی وب درخواست وجود داشته باشد، پیش‌پرواز CORS برای نشانی وب درخواست برای افزونه قابل‌مشاهده است. onBeforeRequest همچنین می‌تواند 'extraHeaders' را از Chrome 79 بگیرد.

از Chrome نسخه ۷۹ به بعد، سرایند درخواست زیر ارائه نمی‌شود و بدون مشخص کردن 'extraHeaders' در opt_extraInfoSpec نمی‌توان آن را اصلاح یا حذف کرد:

  • مبدأ

از Chrome 72، اگر لازم است پاسخ‌ها را قبل‌از اینکه مسدود کردن خواندن میان‌مبدئی (CORB) بتواند پاسخ را مسدود کند اصلاح کنید، باید 'extraHeaders' را در opt_extraInfoSpec مشخص کنید.

از Chrome نسخه ۷۲ به بعد، سرایندهای درخواست زیر ارائه نمی‌شوند و بدون مشخص کردن 'extraHeaders' در opt_extraInfoSpec نمی‌توان آن‌ها را اصلاح یا حذف کرد:

  • Accept-Language
  • Accept-Encoding
  • ارجاع‌دهنده
  • کوکی

از Chrome نسخه ۷۲ به بعد، سرایند پاسخ Set-Cookie ارائه نمی‌شود و بدون مشخص کردن 'extraHeaders' در opt_extraInfoSpec نمی‌توان آن را اصلاح یا حذف کرد.

از Chrome نسخه ۸۹ به بعد، سرایند پاسخ X-Frame-Options را نمی‌توان به‌طور مؤثر اصلاح یا حذف کرد مگر اینکه 'extraHeaders' در opt_extraInfoSpec مشخص شده باشد.

میانای برنامه‌سازی کاربردی webRequest فقط درخواست‌هایی را نشان می‌دهد که افزونه بااستفاده از اجازه‌های میزبان خود اجازه دیدن آن‌ها را دارد. علاوه‌براین، فقط طرح‌های زیر دردسترس هستند: http://، https://، ftp://، file://، ws:// (از Chrome 58)، wss:// (از Chrome 58)، urn: (از Chrome 91)، یا chrome-extension://. علاوه‌براین، حتی برخی‌از درخواست‌های دارای نشانی وب که از یکی از طرح‌های بالا استفاده می‌کنند پنهان می‌شوند. این موارد شامل chrome-extension://other_extension_id است که در آن other_extension_id شناسه افزونه برای رسیدگی به درخواست نیست، https://www.google.com/chrome، و دیگر درخواست‌های حساس که برای عملکرد مرورگر ضروری هستند. همچنین XMLHttpRequests همگام از افزونه شما از مسدود کردن گرداننده‌های رویداد پنهان می‌شود تا از بن‌بست جلوگیری شود. توجه داشته باشید که برای برخی‌از طرح‌های پشتیبانی‌شده، مجموعه رویدادهای دردسترس ممکن است به‌دلیل ماهیت پروتکل مربوطه محدود باشد. برای مثال، برای طرح فایل، فقط onBeforeRequest، onResponseStarted، onCompleted، و onErrorOccurred ممکن است ارسال شود.

از Chrome 58،‏ webRequest API از رهگیری درخواست دست‌دهی WebSocket پشتیبانی می‌کند. ازآنجایی‌که دست‌دهی ازطریق درخواست ارتقای HTTP انجام می‌شود، جریان آن در مدل webRequest مبتنی بر HTTP قرار می‌گیرد. توجه داشته باشید که API موارد زیر را رهگیری نمی‌کند:

  • پیام‌های جداگانه ارسال‌شده ازطریق اتصال WebSocket برقرارشده.
  • ‫WebSocket درحال بستن اتصال است.

بازهدایت‌ها برای درخواست‌های WebSocket پشتیبانی نمی‌شوند.

از Chrome 72 به بعد، افزونه فقط درصورتی می‌تواند درخواست را رهگیری کند که برای نشانی وب درخواست‌شده و آغازگر درخواست، اجازه میزبان داشته باشد.

از Chrome 96،‏ webRequest API از رهگیری درخواست دست‌دهی WebTransport ازطریق HTTP/3 پشتیبانی می‌کند. ازآنجایی‌که دست‌دهی ازطریق درخواست HTTP CONNECT انجام می‌شود، جریان آن در مدل webRequest مبتنی بر HTTP قرار می‌گیرد. توجه داشته باشید:

  • پس‌از برقراری جلسه، افزونه‌ها نمی‌توانند ازطریق webRequest API جلسه را مشاهده کنند یا در آن مداخله کنند.
  • اصلاح سرصفحه‌های درخواست HTTP در onBeforeSendHeaders نادیده گرفته می‌شود.
  • بازهدایت‌ها و اصالت‌سنجی‌ها در WebTransport ازطریق HTTP/3 پشتیبانی نمی‌شوند.

مفاهیم

همان‌طور که در بخش‌های زیر توضیح داده شده است، رویدادها در میانای برنامه‌سازی کاربردی درخواست وب از شناسه‌های درخواست استفاده می‌کنند و شما می‌توانید هنگام ثبت شنوندگان رویداد، به‌طور اختیاری فیلترها و اطلاعات اضافی را مشخص کنید.

شناسه‌های درخواست

هر درخواست با شناسه درخواست شناسایی می‌شود. این شناسه در یک جلسه مرورگر و زمینه افزونه منحصربه‌فرد است. این شناسه درطول چرخه عمر درخواست ثابت می‌ماند و می‌توان از آن برای مطابقت دادن رویدادها برای همان درخواست استفاده کرد. توجه داشته باشید که درصورت تغییر مسیر HTTP یا اصالت‌سنجی HTTP، چندین درخواست HTTP به یک درخواست وب نگاشت می‌شود.

درحال ثبت شنوندگان رویداد

برای ثبت شنونده رویداد برای درخواست وب، از نوعی تابعaddListener() معمول استفاده می‌کنید. علاوه‌بر مشخص کردن تابع بازخوانی، باید متغیر مستقل فیلتر را مشخص کنید و می‌توانید متغیر مستقل اطلاعات اضافی اختیاری را نیز مشخص کنید.

سه آرگومان addListener() میانای برنامه‌سازی کاربردی درخواست وب تعاریف زیر را دارند:

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

در اینجا مثالی از گوش دادن به رویداد onBeforeRequest آورده شده است:

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

هر فراخوانی addListener() یک تابع بازخوانی اجباری را به‌عنوان پارامتر اول می‌گیرد. این تابع بازخوانی یک واژه‌نامه حاوی اطلاعات مربوط به درخواست نشانی وب فعلی را ارسال می‌کند. اطلاعات موجود در این فرهنگ لغت به نوع رویداد خاص و همچنین محتوای opt_extraInfoSpec بستگی دارد.

اگر آرایه اختیاری opt_extraInfoSpec حاوی رشته 'blocking' باشد (فقط برای رویدادهای خاص مجاز است)، تابع بازخوانی به‌صورت همگام مدیریت می‌شود. یعنی درخواست تا زمانی که تابع بازخوانی برگردانده نشود مسدود است. دراین‌صورت، فراخوانی برگشتی می‌تواند یک webRequest.BlockingResponse برگرداند که چرخه عمر بعدی درخواست را تعیین می‌کند. بسته به بافت، این پاسخ امکان لغو یا تغییر مسیر درخواست (onBeforeRequest)، لغو درخواست یا اصلاح سرصفحه‌ها (onBeforeSendHeaders، onHeadersReceived)، و لغو درخواست یا ارائه اعتبارنامه‌های اصالت‌سنجی (onAuthRequired) را فراهم می‌کند.

اگر آرایه اختیاری opt_extraInfoSpec حاوی رشته 'asyncBlocking' باشد (فقط برای onAuthRequired مجاز است)، افزونه می‌تواند webRequest.BlockingResponse را به‌صورت ناهمگام تولید کند.

webRequest.RequestFilter filter امکان محدود کردن درخواست‌هایی را که رویدادها برای آن‌ها در ابعاد مختلف راه‌اندازی می‌شوند فراهم می‌کند:

نشانی‌های وب
الگوهای نشانی وب مانند *://www.google.com/foo*bar.
انواع
انواع درخواست مثل main_frame (سندی که برای قاب سطح بالا بار می‌شود)، sub_frame (سندی که برای قاب جاسازی‌شده بار می‌شود)، و image (تصویری در وب‌سایت). webRequest.RequestFilter را ببینید.
شناسه برگه
شناسه یک برگه.
شناسه پنجره
شناسه پنجره.

بسته به نوع رویداد، می‌توانید رشته‌هایی را در opt_extraInfoSpec مشخص کنید تا اطلاعات بیشتری درباره درخواست بخواهید. این مورد برای ارائه اطلاعات دقیق درباره داده‌های درخواست فقط درصورت درخواست صریح استفاده می‌شود.

جزئیات پیاده‌سازی

هنگام توسعه افزونه‌ای که از میانای برنامه‌سازی کاربردی درخواست وب استفاده می‌کند، درک چندین جزئیات پیاده‌سازی می‌تواند مهم باشد:

web_accessible_resources

وقتی افزونه‌ای از APIهای webRequest برای هدایت درخواست منبع عمومی به منبعی که ازطریق وب دردسترس نیست استفاده می‌کند، مسدود می‌شود و منجر به خطا خواهد شد. موارد بالا حتی اگر منبعی که ازطریق وب قابل‌دسترسی نیست متعلق به افزونه هدایت‌کننده باشد نیز صادق است. برای اعلام منابعی که با میاناهای برنامه‌سازی کاربردی declarativeWebRequest استفاده می‌شوند، آرایه "web_accessible_resources" باید در مانیفست اعلام و پر شود، همان‌طور که در اینجا مستند شده است.

حل تعارض

در پیاده‌سازی فعلی میانای برنامه‌سازی کاربردی درخواست وب، اگر حداقل یک افزونه دستور لغو درخواست را بدهد، درخواست لغوشده درنظر گرفته می‌شود. اگر افزونه‌ای درخواستی را لغو کند، همه افزونه‌ها ازطریق رویداد onErrorOccurred مطلع می‌شوند. در هر زمان فقط یک افزونه می‌تواند درخواست را تغییر مسیر دهد یا سرصفحه را اصلاح کند. اگر بیش‌از یک افزونه برای اصلاح درخواست تلاش کند، افزونه‌ای که اخیراً نصب شده است برنده می‌شود و بقیه نادیده گرفته می‌شوند. اگر دستورالعمل افزونه برای اصلاح یا تغییر مسیر نادیده گرفته شود، به آن افزونه اطلاع داده نمی‌شود.

در حال ذخیره در حافظه نهان

Chrome از دو حافظه نهان استفاده می‌کند: حافظه نهان روی دیسک و حافظه نهان بسیار سریع درون حافظه. طول عمر حافظه نهان درون‌حافظه‌ای به طول عمر فرایند پردازش رندرینگ وابسته است که تقریباً با یک برگه مطابقت دارد. درخواست‌هایی که از حافظه نهان درون‌حافظه‌ای پاسخ داده می‌شوند برای میانای برنامه‌سازی کاربردی درخواست وب نامرئی هستند. اگر گرداننده درخواست رفتار خود را تغییر دهد (برای مثال، رفتاری که براساس آن درخواست‌ها مسدود می‌شوند)، بازآوری ساده صفحه ممکن است این رفتار تغییریافته را رعایت نکند. برای اطمینان از اعمال تغییر رفتار، handlerBehaviorChanged() را فراخوانی کنید تا حافظه نهان درون‌حافظه‌ای پاک شود. اما این کار را زیاد انجام ندهید؛ پاک کردن حافظه پنهان عملیات بسیار پرهزینه‌ای است. پس‌از ثبت یا لغو ثبت شنونده رویداد، نیازی به فراخوانی handlerBehaviorChanged() نیست.

مهرهای زمان

فقط تضمین می‌شود که ویژگی timestamp رویدادهای درخواست وب به‌صورت داخلی سازگار باشد. مقایسه یک رویداد با رویداد دیگر، افست صحیح بین آن‌ها را به شما می‌دهد، اما مقایسه آن‌ها با زمان فعلی در داخل افزونه (مثلاً ازطریق (new Date()).getTime()) ممکن است نتایج غیرمنتظره‌ای داشته باشد.

مدیریت کردن خطا

اگر سعی کنید رویدادی را با آرگومان‌های نامعتبر ثبت کنید، خطای جاوا اسکریپت ایجاد می‌شود و گرداننده رویداد ثبت نخواهد شد. اگر هنگام رسیدگی به رویدادی خطایی رخ دهد یا اگر گرداننده رویداد پاسخ مسدودکننده نامعتبری برگرداند، پیام خطایی در کنسول افزونه شما ثبت می‌شود و گرداننده برای آن درخواست نادیده گرفته می‌شود.

مثال‌ها

مثال زیر نشان می‌دهد که چگونه همه درخواست‌ها به www.evil.com را مسدود کنید:

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

ازآنجایی‌که این تابع از یک کنترل‌کننده رویداد مسدودکننده استفاده می‌کند، به "webRequest" و همچنین اجازه "webRequestBlocking" در فایل مانیفست نیاز دارد.

مثال زیر همان هدف را به‌شیوه‌ای کارآمدتر محقق می‌کند زیرا درخواست‌هایی که www.evil.com را هدف قرار نمی‌دهند لازم نیست به افزونه ارسال شوند:

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

مثال زیر نحوه حذف سرصفحه User-Agent از همه درخواست‌ها را نشان می‌دهد:

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"]
);

برای امتحان کردن chrome.webRequest API، نمونه webRequest را از مخزن chrome-extension-samples نصب کنید.

انواع

BlockingResponse

مقدار را برای کنترل‌کننده‌های رویدادی که extraInfoSpec «مسدودکننده» برای آن‌ها اعمال شده است برمی‌گرداند. به گرداننده رویداد اجازه می‌دهد درخواست‌های شبکه را تغییر دهد.

مشخصات

  • authCredentials

    شیء اختیاری

    فقط به‌عنوان پاسخ به رویداد onAuthRequired استفاده می‌شود. اگر تنظیم شود، درخواست بااستفاده از اعتبارنامه‌های ارائه‌شده انجام می‌شود.

    • گذرواژه

      رشته

    • نام کاربری

      رشته

  • لغو کردن

    بولی اختیاری

    اگر درست باشد، درخواست لغو می‌شود. این کار از ارسال درخواست جلوگیری می‌کند. این می‌تواند به‌عنوان پاسخی به رویدادهای onBeforeRequest،‏ onBeforeSendHeaders،‏ onHeadersReceived، و onAuthRequired استفاده شود.

  • redirectUrl

    رشته اختیاری

    فقط به‌عنوان پاسخ به رویدادهای onBeforeRequest و onHeadersReceived استفاده می‌شود. اگر تنظیم شود، از ارسال/تکمیل درخواست اصلی جلوگیری می‌شود و درعوض به نشانی وب ارائه‌شده هدایت می‌شود. هدایت به طرح‌های غیر-HTTP مانند data: مجاز است. بازهدایت‌هایی که با کنش بازهدایت شروع می‌شوند از روش درخواست اصلی برای بازهدایت استفاده می‌کنند، با یک استثنا: اگر بازهدایت در مرحله onHeadersReceived شروع شود، بازهدایت بااستفاده از روش GET صادر خواهد شد. هدایت‌ها از نشانی‌های وب با طرح‌های ws:// و wss:// نادیده گرفته می‌شوند.

  • requestHeaders

    HttpHeaders اختیاری

    فقط به‌عنوان پاسخ به رویداد onBeforeSendHeaders استفاده می‌شود. اگر تنظیم شود، درخواست با این سرصفحه‌های درخواست انجام می‌شود.

  • responseHeaders

    HttpHeaders اختیاری

    فقط به‌عنوان پاسخ به رویداد onHeadersReceived استفاده می‌شود. اگر تنظیم شود، فرض می‌شود که سرور با این سرصفحه‌های پاسخ پاسخ داده است. فقط درصورتی responseHeaders را برگردانید که واقعاً بخواهید سرصفحه‌ها را تغییر دهید تا تعداد تداخل‌ها محدود شود (فقط یک افزونه می‌تواند responseHeaders را برای هر درخواست تغییر دهد).

FormDataItem

Chrome نسخه ۶۶ و بالاتر

حاوی داده‌های منتقل‌شده در داده‌های فرم است. برای فرم urlencoded، اگر داده‌ها رشته utf-8 باشد، به‌صورت رشته ذخیره می‌شود و درغیراین‌صورت به‌صورت ArrayBuffer ذخیره می‌شود. برای داده‌های فرم، ArrayBuffer است. اگر داده‌های فرم نشان‌دهنده بارگذاری فایل باشد، رشته‌ای با نام فایل است، درصورتی‌که نام فایل ارائه شده باشد.

شمارشی

ArrayBuffer

رشته

HttpHeaders

آرایه‌ای از سرصفحه‌های HTTP. هر سرایند به‌صورت یک واژه‌نامه نشان داده می‌شود که حاوی کلیدهای name و value یا binaryValue است.

نوع

object[]

مشخصات

  • binaryValue

    number[] اختیاری

    مقدار سرایند HTTP اگر نتوان آن را با UTF-8 نشان داد، به‌عنوان مقادیر بایت تکی (۰..۲۵۵) ذخیره می‌شود.

  • نام

    رشته

    نام سرایند HTTP.

  • مقدار

    رشته اختیاری

    مقدار سرایند HTTP اگر بتوان آن را با UTF-8 نشان داد.

IgnoredActionType

Chrome نسخه ۷۰ به بالا

شمارشی

«redirect»

"request_headers"

"response_headers"

"auth_credentials"

OnAuthRequiredOptions

Chrome نسخه ۴۴ به بالا

شمارشی

«responseHeaders»
مشخص می‌کند که سرایندهای پاسخ باید در رویداد گنجانده شوند.

«مسدود کردن»
مشخص می‌کند که درخواست تا زمانی که تابع بازخوانی برگردد مسدود است.

"asyncBlocking"
مشخص می‌کند که تابع بازخوانی به‌صورت غیرهمگام مدیریت می‌شود.

«extraHeaders»
مشخص می‌کند که سرصفحه‌ها می‌توانند «هم‌رسانی منبع میان‌مبدئی» (CORS) را نقض کنند.

OnBeforeRedirectOptions

Chrome نسخه ۴۴ به بالا

شمارشی

«responseHeaders»
مشخص می‌کند که سرایندهای پاسخ باید در رویداد گنجانده شوند.

«extraHeaders»
مشخص می‌کند که سرصفحه‌ها می‌توانند «هم‌رسانی منبع میان‌مبدئی» (CORS) را نقض کنند.

OnBeforeRequestOptions

Chrome نسخه ۴۴ به بالا

شمارشی

«مسدود کردن»
مشخص می‌کند که درخواست تا زمانی که تابع بازخوانی برگردد مسدود است.

«requestBody»
مشخص می‌کند که بدنه درخواست باید در رویداد گنجانده شود.

«extraHeaders»
مشخص می‌کند که سرصفحه‌ها می‌توانند «هم‌رسانی منبع میان‌مبدئی» (CORS) را نقض کنند.

OnBeforeSendHeadersOptions

Chrome نسخه ۴۴ به بالا

شمارشی

«requestHeaders»
مشخص می‌کند که سرایند درخواست باید در رویداد گنجانده شود.

«مسدود کردن»
مشخص می‌کند که درخواست تا زمانی که تابع بازخوانی برگردد مسدود است.

«extraHeaders»
مشخص می‌کند که سرصفحه‌ها می‌توانند «هم‌رسانی منبع میان‌مبدئی» (CORS) را نقض کنند.

OnCompletedOptions

Chrome نسخه ۴۴ به بالا

شمارشی

«responseHeaders»
مشخص می‌کند که سرایندهای پاسخ باید در رویداد گنجانده شوند.

«extraHeaders»
مشخص می‌کند که سرصفحه‌ها می‌توانند «هم‌رسانی منبع میان‌مبدئی» (CORS) را نقض کنند.

OnErrorOccurredOptions

Chrome نسخه ۷۹ و بالاتر

مقدار

"extraHeaders"

OnHeadersReceivedOptions

Chrome نسخه ۴۴ به بالا

شمارشی

«مسدود کردن»
مشخص می‌کند که درخواست تا زمانی که تابع بازخوانی برگردد مسدود است.

«responseHeaders»
مشخص می‌کند که سرایندهای پاسخ باید در رویداد گنجانده شوند.

«extraHeaders»
مشخص می‌کند که سرصفحه‌ها می‌توانند «هم‌رسانی منبع میان‌مبدئی» (CORS) را نقض کنند.

«securityInfo»
مشخص می‌کند که SecurityInfo باید در رویداد گنجانده شود.

«securityInfoRawDer»
مشخص می‌کند که SecurityInfo با بایت‌های خام گواهینامه‌ها باید در رویداد گنجانده شود.

OnResponseStartedOptions

Chrome نسخه ۴۴ به بالا

شمارشی

«responseHeaders»
مشخص می‌کند که سرایندهای پاسخ باید در رویداد گنجانده شوند.

«extraHeaders»
مشخص می‌کند که سرصفحه‌ها می‌توانند «هم‌رسانی منبع میان‌مبدئی» (CORS) را نقض کنند.

OnSendHeadersOptions

Chrome نسخه ۴۴ به بالا

شمارشی

«requestHeaders»
مشخص می‌کند که سرایند درخواست باید در رویداد گنجانده شود.

«extraHeaders»
مشخص می‌کند که سرصفحه‌ها می‌توانند «هم‌رسانی منبع میان‌مبدئی» (CORS) را نقض کنند.

RequestFilter

شیئی که فیلترهای اعمال‌شده بر رویدادهای webRequest را توصیف می‌کند.

مشخصات

  • tabId

    شماره اختیاری

  • انواع

    ResourceType[] اختیاری

    فهرستی از انواع درخواست. درخواست‌هایی که با هیچ‌یک از انواع مطابقت نداشته باشند فیلتر خواهند شد.

  • نشانی‌های وب

    string[]

    فهرستی از نشانی‌های وب یا الگوهای نشانی وب. درخواست‌هایی که با هیچ‌یک از نشانی‌های وب مطابقت نداشته باشند فیلتر خواهند شد.

  • windowId

    شماره اختیاری

ResourceType

Chrome نسخه ۴۴ به بالا

شمارشی

«main_frame»
منبع را به‌عنوان قاب اصلی مشخص می‌کند.

"sub_frame"
منبع را به‌عنوان زیرقاب مشخص می‌کند.

«stylesheet»
منبع را به‌عنوان برگه سبک نگارش مشخص می‌کند.

«script»
منبع را به‌عنوان اسکریپت مشخص می‌کند.

«image»
منبع را به‌عنوان تصویر مشخص می‌کند.

«قلم»
منبع را به‌عنوان قلم مشخص می‌کند.

"object"
منبع را به‌عنوان شیء مشخص می‌کند.

«xmlhttprequest»
منبع را به‌عنوان XMLHttpRequest مشخص می‌کند.

"ping"
منبع را به‌عنوان پینگ مشخص می‌کند.

"csp_report"
منبع را به‌عنوان گزارش «خط‌مشی امنیتی محتوا» (CSP) مشخص می‌کند.

«media»
منبع را به‌عنوان شیء رسانه‌ای مشخص می‌کند.

«websocket»
منبع را به‌عنوان WebSocket مشخص می‌کند.

«webbundle»
منبع را به‌عنوان WebBundle مشخص می‌کند.

«other»
منبع را به‌عنوان نوعی مشخص می‌کند که در انواع فهرست‌شده گنجانده نشده است.

SecurityInfo

Chrome نسخه ۱۴۴ و بالاتر

مشخصات

  • گواهینامه‌ها

    object[]

    فهرست گواهینامه‌ها

    • اثر انگشت

      شیء

      اثر انگشت‌های گواهینامه.

      • sha256

        رشته

        اثر انگشت sha256 گواهینامه.

    • rawDER

      ArrayBuffer اختیاری

      بایت‌های خام گواهی سرور کدگذاری‌شده DER

  • ایالت

    رشته

    وضعیت اتصال. یکی از موارد امن، ناامن، خراب.

UploadData

حاوی داده‌های بارگذاری‌شده در درخواست نشانی وب است.

مشخصات

  • بایت

    هر اختیاری

    یک ArrayBuffer با کپی داده‌ها.

  • فایل

    رشته اختیاری

    رشته‌ای با مسیر و نام فایل.

مشخصات

MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES

حداکثر تعداد دفعاتی که handlerBehaviorChanged می‌تواند در هر فاصله زمانی پایدار ۱۰ دقیقه‌ای فراخوانی شود. handlerBehaviorChanged یک فراخوانی تابع پرهزینه است که نباید اغلب فراخوانی شود.

مقدار

20

روش‌ها

handlerBehaviorChanged()

قول 
chrome.webRequest.handlerBehaviorChanged(
  callback?: function,
): Promise<void>

وقتی رفتار گرداننده‌های webRequest تغییر کرده است، باید فراخوانی شود تا از گرداندن نادرست به‌دلیل ذخیره‌سازی در حافظه نهان جلوگیری شود. این فراخوانی تابع پرهزینه است. زیاد با آن تماس نگیرید.

پارامترها

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۱۱۶ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

رویدادها

onActionIgnored

Chrome نسخه ۷۰ به بالا 
chrome.webRequest.onActionIgnored.addListener(
  callback: function,
)

وقتی اصلاح پیشنهادی افزونه برای درخواست شبکه نادیده گرفته شود، فعال می‌شود. این اتفاق درصورت تداخل با افزونه‌های دیگر رخ می‌دهد.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (details: object) => void

    • جزئیات

      شیء

      • کنش پیشنهادی که نادیده گرفته شده است.

      • requestId

        رشته

        شناسه درخواست. شناسه‌های درخواست در یک جلسه مرورگر منحصربه‌فرد هستند. درنتیجه، می‌توان از آن‌ها برای مرتبط کردن رویدادهای مختلف یک درخواست استفاده کرد.

onAuthRequired

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

وقتی خطای اصالت‌سنجی دریافت شود، فعال می‌شود. شنونده سه گزینه دارد: می‌تواند اعتبارنامه‌های اصالت‌سنجی را ارائه دهد، می‌تواند درخواست را لغو کند و صفحه خطا را نمایش دهد، یا می‌تواند هیچ اقدامی درخصوص چالش انجام ندهد. اگر اطلاعات کاربری نامعتبر ارائه شود، ممکن است این روش چندین بار برای یک درخواست فراخوانی شود. توجه: فقط یکی از حالت‌های 'blocking' یا 'asyncBlocking' باید در پارامتر extraInfoSpec مشخص شود.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

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

    • جزئیات

      شیء

      • رقیب

        شیء

        سرور درخواست اصالت‌سنجی می‌کند.

        • میزبان

          رشته

        • درگاه

          شماره

      • documentId

        رشته اختیاری

        Chrome نسخه ۱۰۶ و بالاتر

        شناسه UUID سند ارائه‌دهنده درخواست.

      • Chrome نسخه ۱۰۶ و بالاتر

        چرخه حیاتی که سند در آن قرار دارد.

      • frameId

        شماره

        مقدار ۰ نشان می‌دهد که درخواست در قاب اصلی اتفاق می‌افتد؛ مقدار مثبت نشان‌دهنده شناسه قاب فرعی است که درخواست در آن اتفاق می‌افتد. اگر سند یک (زیر)قاب بار شود (type main_frame یا sub_frame است)، frameId شناسه این قاب را نشان می‌دهد، نه شناسه قاب بیرونی را. شناسه‌های قاب در هر برگه یکتا هستند.

      • Chrome نسخه ۱۰۶ و بالاتر

        نوع قابی که درخواست در آن رخ داده است.

      • آغازگر

        رشته اختیاری

        Chrome نسخه ۶۳ و بالاتر

        مبدأی که درخواست از آنجا آغاز شده است. این مورد با تغییر مسیر تغییر نمی‌کند. اگر این مبدأ مبهم باشد، از رشته «null» استفاده خواهد شد.

      • isProxy

        بولی

        True برای Proxy-Authenticate،‏ false برای WWW-Authenticate.

      • روش

        رشته

        روش HTTP استاندارد.

      • parentDocumentId

        رشته اختیاری

        Chrome نسخه ۱۰۶ و بالاتر

        شناسه UUID سند ولی که مالک این قاب است. اگر والدی وجود نداشته باشد، این تنظیم نمی‌شود.

      • parentFrameId

        شماره

        شناسه قابی که قاب ارسال‌کننده درخواست را دربرمی‌گیرد. اگر قاب ولی وجود نداشته باشد، روی ۱- تنظیم می‌شود.

      • قلمرو

        رشته اختیاری

        قلمرو اصالت‌سنجی ارائه‌شده توسط سرور، درصورت وجود.

      • requestId

        رشته

        شناسه درخواست. شناسه‌های درخواست در یک جلسه مرورگر منحصربه‌فرد هستند. درنتیجه، می‌توان از آن‌ها برای مرتبط کردن رویدادهای مختلف یک درخواست استفاده کرد.

      • responseHeaders

        HttpHeaders اختیاری

        سرایندهای پاسخ HTTP که همراه با این پاسخ دریافت شده‌اند.

      • طرح‌واره

        رشته

        طرح اصالت‌سنجی، مثلاً Basic یا Digest.

      • statusCode

        شماره

        Chrome نسخه ۴۳ و بالاتر

        کد وضعیت استاندارد HTTP که سرور برگردانده است.

      • statusLine

        رشته

        خط وضعیت HTTP پاسخ یا رشته «HTTP/0.9 200 OK» برای پاسخ‌های HTTP/0.9 (یعنی پاسخ‌هایی که خط وضعیت ندارند) یا رشته‌ای خالی اگر سرایندی وجود نداشته باشد.

      • tabId

        شماره

        شناسه زبانه‌ای که درخواست در آن انجام می‌شود. اگر درخواست به برگه‌ای مربوط نیست، روی ‎-1 تنظیم کنید.

      • timeStamp

        شماره

        زمان راه‌اندازی این سیگنال، برحسب میلی‌ثانیه از تاریخ.

      • نوع

        ResourceType

        نحوه استفاده از منبع درخواست‌شده.

      • نشانی وب

        رشته

    • asyncCallback

      تابع اختیاری

      Chrome نسخه ۵۸ به بالا

      پارامتر asyncCallback به‌صورت زیر است: 

      (response: BlockingResponse) => void

    • returns

      BlockingResponse | undefined

      اگر «مسدود کردن» در پارامتر «extraInfoSpec» مشخص شده باشد، شنونده رویداد باید شیئی از این نوع را برگرداند.

  • فیلتر کردن

    RequestFilter

  • extraInfoSpec

    OnAuthRequiredOptions[] اختیاری

onBeforeRedirect

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

وقتی بازهدایت آغازشده از سرور درحال وقوع باشد، فعال می‌شود.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (details: object) => void

    • جزئیات

      شیء

      • documentId

        رشته اختیاری

        Chrome نسخه ۱۰۶ و بالاتر

        شناسه UUID سند ارائه‌دهنده درخواست.

      • Chrome نسخه ۱۰۶ و بالاتر

        چرخه حیاتی که سند در آن قرار دارد.

      • frameId

        شماره

        مقدار ۰ نشان می‌دهد که درخواست در قاب اصلی اتفاق می‌افتد؛ مقدار مثبت نشان‌دهنده شناسه قاب فرعی است که درخواست در آن اتفاق می‌افتد. اگر سند یک (زیر)قاب بار شود (type main_frame یا sub_frame است)، frameId شناسه این قاب را نشان می‌دهد، نه شناسه قاب بیرونی را. شناسه‌های قاب در هر برگه یکتا هستند.

      • Chrome نسخه ۱۰۶ و بالاتر

        نوع قابی که درخواست در آن رخ داده است.

      • fromCache

        بولی

        نشان می‌دهد که آیا این پاسخ از حافظه نهان دیسک واکشی شده است یا نه.

      • آغازگر

        رشته اختیاری

        Chrome نسخه ۶۳ و بالاتر

        مبدأی که درخواست از آنجا آغاز شده است. این مورد با تغییر مسیر تغییر نمی‌کند. اگر این مبدأ مبهم باشد، از رشته «null» استفاده خواهد شد.

      • ip

        رشته اختیاری

        نشانی IP سروری که درخواست واقعاً به آن ارسال شده است. توجه داشته باشید که ممکن است نشانی IPv6 تحت‌اللفظی باشد.

      • روش

        رشته

        روش HTTP استاندارد.

      • parentDocumentId

        رشته اختیاری

        Chrome نسخه ۱۰۶ و بالاتر

        شناسه UUID سند ولی که مالک این قاب است. اگر والدی وجود نداشته باشد، این تنظیم نمی‌شود.

      • parentFrameId

        شماره

        شناسه قابی که قاب ارسال‌کننده درخواست را دربرمی‌گیرد. اگر قاب ولی وجود نداشته باشد، روی ۱- تنظیم می‌شود.

      • redirectUrl

        رشته

        نشانی وب جدید.

      • 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 به‌صورت زیر است: 

    (details: object) => BlockingResponse | undefined

    • جزئیات

      شیء

      • documentId

        رشته اختیاری

        Chrome نسخه ۱۰۶ و بالاتر

        شناسه UUID سند ارائه‌دهنده درخواست.

      • documentLifecycle

        extensionTypes.DocumentLifecycle اختیاری

        Chrome نسخه ۱۰۶ و بالاتر

        چرخه حیاتی که سند در آن قرار دارد.

      • frameId

        شماره

        مقدار ۰ نشان می‌دهد که درخواست در قاب اصلی اتفاق می‌افتد؛ مقدار مثبت نشان‌دهنده شناسه قاب فرعی است که درخواست در آن اتفاق می‌افتد. اگر سند یک (زیر)قاب بار شود (type main_frame یا sub_frame است)، frameId شناسه این قاب را نشان می‌دهد، نه شناسه قاب بیرونی را. شناسه‌های قاب در هر برگه یکتا هستند.

      • frameType

        extensionTypes.FrameType اختیاری

        Chrome نسخه ۱۰۶ و بالاتر

        نوع قابی که درخواست در آن رخ داده است.

      • آغازگر

        رشته اختیاری

        Chrome نسخه ۶۳ و بالاتر

        مبدأی که درخواست از آنجا آغاز شده است. این مورد با تغییر مسیر تغییر نمی‌کند. اگر این مبدأ مبهم باشد، از رشته «null» استفاده خواهد شد.

      • روش

        رشته

        روش HTTP استاندارد.

      • parentDocumentId

        رشته اختیاری

        Chrome نسخه ۱۰۶ و بالاتر

        شناسه UUID سند ولی که مالک این قاب است. اگر والدی وجود نداشته باشد، این تنظیم نمی‌شود.

      • parentFrameId

        شماره

        شناسه قابی که قاب ارسال‌کننده درخواست را دربرمی‌گیرد. اگر قاب ولی وجود نداشته باشد، روی ۱- تنظیم می‌شود.

      • requestBody

        شیء اختیاری

        حاوی داده‌های بدنه درخواست HTTP است. فقط درصورتی ارائه می‌شود که extraInfoSpec حاوی «requestBody» باشد.

        • خطا

          رشته اختیاری

          خطا هنگام دریافت داده‌های بدنه درخواست.

        • formData

          شیء اختیاری

          اگر روش درخواست POST باشد و بدنه دنباله‌ای از جفت‌های کلید-مقدار کدگذاری‌شده در UTF8 باشد، که به‌صورت multipart/form-data یا application/x-www-form-urlencoded کدگذاری شده است، این فرهنگ لغت وجود دارد و برای هر کلید حاوی فهرست همه مقادیر آن کلید است. اگر داده‌ها از نوع رسانه دیگری باشد، یا اگر بدشکل باشد، واژه‌نامه وجود ندارد. مقدار نمونه این واژه‌نامه {'key': ['value1', 'value2']} است.

        • خام

          UploadData[] اختیاری

          اگر روش درخواست PUT یا POST باشد و بدنه قبلاً در formData تجزیه نشده باشد، عناصر تجزیه‌نشده بدنه درخواست در این آرایه قرار می‌گیرند.

      • requestId

        رشته

        شناسه درخواست. شناسه‌های درخواست در یک جلسه مرورگر منحصربه‌فرد هستند. درنتیجه، می‌توان از آن‌ها برای مرتبط کردن رویدادهای مختلف یک درخواست استفاده کرد.

      • tabId

        شماره

        شناسه زبانه‌ای که درخواست در آن انجام می‌شود. اگر درخواست به برگه‌ای مربوط نیست، روی ‎-1 تنظیم کنید.

      • timeStamp

        شماره

        زمان راه‌اندازی این سیگنال، برحسب میلی‌ثانیه از تاریخ.

      • نوع

        ResourceType

        نحوه استفاده از منبع درخواست‌شده.

      • نشانی وب

        رشته

    • returns

      BlockingResponse | undefined

      اگر «مسدود کردن» در پارامتر «extraInfoSpec» مشخص شده باشد، شنونده رویداد باید شیئی از این نوع را برگرداند.

  • فیلتر کردن

    RequestFilter

  • extraInfoSpec

    OnBeforeRequestOptions[] اختیاری

onBeforeSendHeaders

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

وقتی سرصفحه‌های درخواست دردسترس باشند، پیش‌از ارسال درخواست اچ‌تی‌تی‌پی فعال می‌شود. این خطا ممکن است پس‌از برقراری اتصال TCP به سرور، اما قبل‌از ارسال هرگونه داده HTTP رخ دهد.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (details: object) => BlockingResponse | undefined

    • جزئیات

      شیء

      • documentId

        رشته اختیاری

        Chrome نسخه ۱۰۶ و بالاتر

        شناسه UUID سند ارائه‌دهنده درخواست.

      • Chrome نسخه ۱۰۶ و بالاتر

        چرخه حیاتی که سند در آن قرار دارد.

      • frameId

        شماره

        مقدار ۰ نشان می‌دهد که درخواست در قاب اصلی اتفاق می‌افتد؛ مقدار مثبت نشان‌دهنده شناسه قاب فرعی است که درخواست در آن اتفاق می‌افتد. اگر سند یک (زیر)قاب بار شود (type main_frame یا sub_frame است)، frameId شناسه این قاب را نشان می‌دهد، نه شناسه قاب بیرونی را. شناسه‌های قاب در هر برگه یکتا هستند.

      • Chrome نسخه ۱۰۶ و بالاتر

        نوع قابی که درخواست در آن رخ داده است.

      • آغازگر

        رشته اختیاری

        Chrome نسخه ۶۳ و بالاتر

        مبدأی که درخواست از آنجا آغاز شده است. این مورد با تغییر مسیر تغییر نمی‌کند. اگر این مبدأ مبهم باشد، از رشته «null» استفاده خواهد شد.

      • روش

        رشته

        روش HTTP استاندارد.

      • parentDocumentId

        رشته اختیاری

        Chrome نسخه ۱۰۶ و بالاتر

        شناسه UUID سند ولی که مالک این قاب است. اگر والدی وجود نداشته باشد، این تنظیم نمی‌شود.

      • parentFrameId

        شماره

        شناسه قابی که قاب ارسال‌کننده درخواست را دربرمی‌گیرد. اگر قاب ولی وجود نداشته باشد، روی ۱- تنظیم می‌شود.

      • requestHeaders

        HttpHeaders اختیاری

        سرصفحه‌های درخواست اچ‌تی‌تی‌پی که قرار است با این درخواست ارسال شوند.

      • requestId

        رشته

        شناسه درخواست. شناسه‌های درخواست در یک جلسه مرورگر منحصربه‌فرد هستند. درنتیجه، می‌توان از آن‌ها برای مرتبط کردن رویدادهای مختلف یک درخواست استفاده کرد.

      • tabId

        شماره

        شناسه زبانه‌ای که درخواست در آن انجام می‌شود. اگر درخواست به برگه‌ای مربوط نیست، روی ‎-1 تنظیم کنید.

      • timeStamp

        شماره

        زمان راه‌اندازی این سیگنال، برحسب میلی‌ثانیه از تاریخ.

      • نوع

        ResourceType

        نحوه استفاده از منبع درخواست‌شده.

      • نشانی وب

        رشته

    • returns

      BlockingResponse | undefined

      اگر «مسدود کردن» در پارامتر «extraInfoSpec» مشخص شده باشد، شنونده رویداد باید شیئی از این نوع را برگرداند.

  • فیلتر کردن

    RequestFilter

  • extraInfoSpec

    OnBeforeSendHeadersOptions[] اختیاری

onCompleted

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

وقتی درخواستی تکمیل می‌شود، فعال می‌شود.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (details: object) => void

    • جزئیات

      شیء

      • documentId

        رشته اختیاری

        Chrome نسخه ۱۰۶ و بالاتر

        شناسه UUID سند ارائه‌دهنده درخواست.

      • Chrome نسخه ۱۰۶ و بالاتر

        چرخه حیاتی که سند در آن قرار دارد.

      • frameId

        شماره

        مقدار ۰ نشان می‌دهد که درخواست در قاب اصلی اتفاق می‌افتد؛ مقدار مثبت نشان‌دهنده شناسه قاب فرعی است که درخواست در آن اتفاق می‌افتد. اگر سند یک (زیر)قاب بار شود (type main_frame یا sub_frame است)، frameId شناسه این قاب را نشان می‌دهد، نه شناسه قاب بیرونی را. شناسه‌های قاب در هر برگه یکتا هستند.

      • Chrome نسخه ۱۰۶ و بالاتر

        نوع قابی که درخواست در آن رخ داده است.

      • fromCache

        بولی

        نشان می‌دهد که آیا این پاسخ از حافظه نهان دیسک واکشی شده است یا نه.

      • آغازگر

        رشته اختیاری

        Chrome نسخه ۶۳ و بالاتر

        مبدأی که درخواست از آنجا آغاز شده است. این مورد با تغییر مسیر تغییر نمی‌کند. اگر این مبدأ مبهم باشد، از رشته «null» استفاده خواهد شد.

      • ip

        رشته اختیاری

        نشانی IP سروری که درخواست واقعاً به آن ارسال شده است. توجه داشته باشید که ممکن است نشانی IPv6 تحت‌اللفظی باشد.

      • روش

        رشته

        روش HTTP استاندارد.

      • parentDocumentId

        رشته اختیاری

        Chrome نسخه ۱۰۶ و بالاتر

        شناسه UUID سند ولی که مالک این قاب است. اگر والدی وجود نداشته باشد، این تنظیم نمی‌شود.

      • parentFrameId

        شماره

        شناسه قابی که قاب ارسال‌کننده درخواست را دربرمی‌گیرد. اگر قاب ولی وجود نداشته باشد، روی ۱- تنظیم می‌شود.

      • 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 به‌صورت زیر است: 

    (details: object) => void

    • جزئیات

      شیء

      • documentId

        رشته اختیاری

        Chrome نسخه ۱۰۶ و بالاتر

        شناسه UUID سند ارائه‌دهنده درخواست. اگر درخواست پیمایش قاب باشد، این مقدار وجود ندارد.

      • Chrome نسخه ۱۰۶ و بالاتر

        چرخه حیاتی که سند در آن قرار دارد.

      • خطا

        رشته

        توضیح خطا. تضمین نمی‌شود که این رشته بین نسخه‌های پخش سازگار با نسخه‌های قدیمی باقی بماند. نباید آن را تجزیه کنید و براساس محتوای آن عمل کنید.

      • frameId

        شماره

        مقدار ۰ نشان می‌دهد که درخواست در قاب اصلی اتفاق می‌افتد؛ مقدار مثبت نشان‌دهنده شناسه قاب فرعی است که درخواست در آن اتفاق می‌افتد. اگر سند یک (زیر)قاب بار شود (type main_frame یا sub_frame است)، frameId شناسه این قاب را نشان می‌دهد، نه شناسه قاب بیرونی را. شناسه‌های قاب در هر برگه یکتا هستند.

      • Chrome نسخه ۱۰۶ و بالاتر

        نوع قابی که درخواست در آن رخ داده است.

      • fromCache

        بولی

        نشان می‌دهد که آیا این پاسخ از حافظه نهان دیسک واکشی شده است یا نه.

      • آغازگر

        رشته اختیاری

        Chrome نسخه ۶۳ و بالاتر

        مبدأی که درخواست از آنجا آغاز شده است. این مورد با تغییر مسیر تغییر نمی‌کند. اگر این مبدأ مبهم باشد، از رشته «null» استفاده خواهد شد.

      • ip

        رشته اختیاری

        نشانی IP سروری که درخواست واقعاً به آن ارسال شده است. توجه داشته باشید که ممکن است نشانی IPv6 تحت‌اللفظی باشد.

      • روش

        رشته

        روش HTTP استاندارد.

      • parentDocumentId

        رشته اختیاری

        Chrome نسخه ۱۰۶ و بالاتر

        شناسه UUID سند ولی که مالک این قاب است. اگر والدی وجود نداشته باشد، این تنظیم نمی‌شود.

      • parentFrameId

        شماره

        شناسه قابی که قاب ارسال‌کننده درخواست را دربرمی‌گیرد. اگر قاب ولی وجود نداشته باشد، روی ۱- تنظیم می‌شود.

      • requestId

        رشته

        شناسه درخواست. شناسه‌های درخواست در یک جلسه مرورگر منحصربه‌فرد هستند. درنتیجه، می‌توان از آن‌ها برای مرتبط کردن رویدادهای مختلف یک درخواست استفاده کرد.

      • tabId

        شماره

        شناسه زبانه‌ای که درخواست در آن انجام می‌شود. اگر درخواست به برگه‌ای مربوط نیست، روی ‎-1 تنظیم کنید.

      • timeStamp

        شماره

        زمان راه‌اندازی این سیگنال، برحسب میلی‌ثانیه از تاریخ.

      • نوع

        ResourceType

        نحوه استفاده از منبع درخواست‌شده.

      • نشانی وب

        رشته

  • فیلتر کردن

    RequestFilter

  • extraInfoSpec

    OnErrorOccurredOptions[] اختیاری

onHeadersReceived

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

وقتی سرایندهای پاسخ HTTP درخواست دریافت شده باشد، فعال می‌شود.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (details: object) => BlockingResponse | undefined

    • جزئیات

      شیء

      • documentId

        رشته اختیاری

        Chrome نسخه ۱۰۶ و بالاتر

        شناسه UUID سند ارائه‌دهنده درخواست.

      • Chrome نسخه ۱۰۶ و بالاتر

        چرخه حیاتی که سند در آن قرار دارد.

      • frameId

        شماره

        مقدار ۰ نشان می‌دهد که درخواست در قاب اصلی اتفاق می‌افتد؛ مقدار مثبت نشان‌دهنده شناسه قاب فرعی است که درخواست در آن اتفاق می‌افتد. اگر سند یک (زیر)قاب بار شود (type main_frame یا sub_frame است)، frameId شناسه این قاب را نشان می‌دهد، نه شناسه قاب بیرونی را. شناسه‌های قاب در هر برگه یکتا هستند.

      • Chrome نسخه ۱۰۶ و بالاتر

        نوع قابی که درخواست در آن رخ داده است.

      • آغازگر

        رشته اختیاری

        Chrome نسخه ۶۳ و بالاتر

        مبدأی که درخواست از آنجا آغاز شده است. این مورد با تغییر مسیر تغییر نمی‌کند. اگر این مبدأ مبهم باشد، از رشته «null» استفاده خواهد شد.

      • روش

        رشته

        روش HTTP استاندارد.

      • parentDocumentId

        رشته اختیاری

        Chrome نسخه ۱۰۶ و بالاتر

        شناسه UUID سند ولی که مالک این قاب است. اگر والدی وجود نداشته باشد، این تنظیم نمی‌شود.

      • parentFrameId

        شماره

        شناسه قابی که قاب ارسال‌کننده درخواست را دربرمی‌گیرد. اگر قاب ولی وجود نداشته باشد، روی ۱- تنظیم می‌شود.

      • requestId

        رشته

        شناسه درخواست. شناسه‌های درخواست در یک جلسه مرورگر منحصربه‌فرد هستند. درنتیجه، می‌توان از آن‌ها برای مرتبط کردن رویدادهای مختلف یک درخواست استفاده کرد.

      • responseHeaders

        HttpHeaders اختیاری

        سرایندهای پاسخ HTTP که با این پاسخ دریافت شده‌اند.

      • securityInfo

        SecurityInfo اختیاری

        Chrome نسخه ۱۴۴ و بالاتر

        اطلاعات مربوط به اتصال TLS/QUIC که برای اتصال زیربنایی استفاده می‌شود. فقط درصورتی ارائه می‌شود که securityInfo در پارامتر extraInfoSpec مشخص شده باشد.

      • statusCode

        شماره

        Chrome نسخه ۴۳ و بالاتر

        کد وضعیت استاندارد HTTP که سرور برگردانده است.

      • statusLine

        رشته

        خط وضعیت HTTP پاسخ یا رشته «HTTP/0.9 200 OK» برای پاسخ‌های HTTP/0.9 (یعنی پاسخ‌هایی که خط وضعیت ندارند).

      • tabId

        شماره

        شناسه زبانه‌ای که درخواست در آن انجام می‌شود. اگر درخواست به برگه‌ای مربوط نیست، روی ‎-1 تنظیم کنید.

      • timeStamp

        شماره

        زمان راه‌اندازی این سیگنال، برحسب میلی‌ثانیه از تاریخ.

      • نوع

        ResourceType

        نحوه استفاده از منبع درخواست‌شده.

      • نشانی وب

        رشته

    • returns

      BlockingResponse | undefined

      اگر «مسدود کردن» در پارامتر «extraInfoSpec» مشخص شده باشد، شنونده رویداد باید شیئی از این نوع را برگرداند.

  • فیلتر کردن

    RequestFilter

  • extraInfoSpec

    OnHeadersReceivedOptions[] اختیاری

onResponseStarted

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

وقتی اولین بایت بدنه پاسخ دریافت می‌شود، فعال می‌شود. برای درخواست‌های HTTP، این یعنی خط وضعیت و سرایندهای پاسخ دردسترس هستند.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (details: object) => void

    • جزئیات

      شیء

      • documentId

        رشته اختیاری

        Chrome نسخه ۱۰۶ و بالاتر

        شناسه UUID سند ارائه‌دهنده درخواست.

      • Chrome نسخه ۱۰۶ و بالاتر

        چرخه حیاتی که سند در آن قرار دارد.

      • frameId

        شماره

        مقدار ۰ نشان می‌دهد که درخواست در قاب اصلی اتفاق می‌افتد؛ مقدار مثبت نشان‌دهنده شناسه قاب فرعی است که درخواست در آن اتفاق می‌افتد. اگر سند یک (زیر)قاب بار شود (type main_frame یا sub_frame است)، frameId شناسه این قاب را نشان می‌دهد، نه شناسه قاب بیرونی را. شناسه‌های قاب در هر برگه یکتا هستند.

      • Chrome نسخه ۱۰۶ و بالاتر

        نوع قابی که درخواست در آن رخ داده است.

      • fromCache

        بولی

        نشان می‌دهد که آیا این پاسخ از حافظه نهان دیسک واکشی شده است یا نه.

      • آغازگر

        رشته اختیاری

        Chrome نسخه ۶۳ و بالاتر

        مبدأی که درخواست از آنجا آغاز شده است. این مورد با تغییر مسیر تغییر نمی‌کند. اگر این مبدأ مبهم باشد، از رشته «null» استفاده خواهد شد.

      • ip

        رشته اختیاری

        نشانی IP سروری که درخواست واقعاً به آن ارسال شده است. توجه داشته باشید که ممکن است نشانی IPv6 تحت‌اللفظی باشد.

      • روش

        رشته

        روش HTTP استاندارد.

      • parentDocumentId

        رشته اختیاری

        Chrome نسخه ۱۰۶ و بالاتر

        شناسه UUID سند ولی که مالک این قاب است. اگر والدی وجود نداشته باشد، این تنظیم نمی‌شود.

      • parentFrameId

        شماره

        شناسه قابی که قاب ارسال‌کننده درخواست را دربرمی‌گیرد. اگر قاب ولی وجود نداشته باشد، روی ۱- تنظیم می‌شود.

      • 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[],
)

درست قبل‌از ارسال درخواست به سرور فعال می‌شود (اصلاحات فراخوان‌های قبلی onBeforeSendHeaders تا زمان فعال شدن onSendHeaders قابل‌مشاهده است).

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (details: object) => void

    • جزئیات

      شیء

      • documentId

        رشته اختیاری

        Chrome نسخه ۱۰۶ و بالاتر

        شناسه UUID سند ارائه‌دهنده درخواست.

      • Chrome نسخه ۱۰۶ و بالاتر

        چرخه حیاتی که سند در آن قرار دارد.

      • frameId

        شماره

        مقدار ۰ نشان می‌دهد که درخواست در قاب اصلی اتفاق می‌افتد؛ مقدار مثبت نشان‌دهنده شناسه قاب فرعی است که درخواست در آن اتفاق می‌افتد. اگر سند یک (زیر)قاب بار شود (type main_frame یا sub_frame است)، frameId شناسه این قاب را نشان می‌دهد، نه شناسه قاب بیرونی را. شناسه‌های قاب در هر برگه یکتا هستند.

      • Chrome نسخه ۱۰۶ و بالاتر

        نوع قابی که درخواست در آن رخ داده است.

      • آغازگر

        رشته اختیاری

        Chrome نسخه ۶۳ و بالاتر

        مبدأی که درخواست از آنجا آغاز شده است. این مورد با تغییر مسیر تغییر نمی‌کند. اگر این مبدأ مبهم باشد، از رشته «null» استفاده خواهد شد.

      • روش

        رشته

        روش HTTP استاندارد.

      • parentDocumentId

        رشته اختیاری

        Chrome نسخه ۱۰۶ و بالاتر

        شناسه UUID سند ولی که مالک این قاب است. اگر والدی وجود نداشته باشد، این تنظیم نمی‌شود.

      • parentFrameId

        شماره

        شناسه قابی که قاب ارسال‌کننده درخواست را دربرمی‌گیرد. اگر قاب ولی وجود نداشته باشد، روی ۱- تنظیم می‌شود.

      • requestHeaders

        HttpHeaders اختیاری

        سرصفحه‌های درخواست اچ‌تی‌تی‌پی که با این درخواست ارسال شده‌اند.

      • requestId

        رشته

        شناسه درخواست. شناسه‌های درخواست در یک جلسه مرورگر منحصربه‌فرد هستند. درنتیجه، می‌توان از آن‌ها برای مرتبط کردن رویدادهای مختلف یک درخواست استفاده کرد.

      • tabId

        شماره

        شناسه زبانه‌ای که درخواست در آن انجام می‌شود. اگر درخواست به برگه‌ای مربوط نیست، روی ‎-1 تنظیم کنید.

      • timeStamp

        شماره

        زمان راه‌اندازی این سیگنال، برحسب میلی‌ثانیه از تاریخ.

      • نوع

        ResourceType

        نحوه استفاده از منبع درخواست‌شده.

      • نشانی وب

        رشته

  • فیلتر کردن

    RequestFilter

  • extraInfoSpec

    OnSendHeadersOptions[] اختیاری