chrome.webRequest

توضیحات

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

مجوزها

webRequest

مانیفست

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

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

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

چرخه حیات درخواست‌ها

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

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

چرخه حیات یک درخواست وب از دیدگاه API درخواست وب

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

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

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

هدرهای زیر در حال حاضر به رویداد onBeforeSendHeaders ارائه نمی‌شوند . تضمینی وجود ندارد که این لیست کامل یا پایدار باشد.

  • مجوز
  • کنترل حافظه پنهان
  • اتصال
  • طول محتوا
  • میزبان
  • اگر-اصلاح-شده-از
  • اگر هیچ تطابقی وجود نداشته باشد
  • اگر-محدوده
  • داده‌های جزئی
  • پراگما
  • مجوز پروکسی
  • اتصال پروکسی
  • رمزگذاری انتقال

از کروم ۷۹ به بعد، تغییرات در هدر درخواست، بررسی‌های اشتراک‌گذاری منابع بین مبدا (CORS) را تحت تأثیر قرار می‌دهد. اگر هدرهای اصلاح‌شده برای درخواست‌های بین مبدا، معیارها را برآورده نکنند، منجر به ارسال پیش‌پرواز CORS می‌شود تا از سرور بپرسد که آیا چنین هدرهایی می‌توانند پذیرفته شوند یا خیر. اگر واقعاً نیاز به تغییر هدرها به روشی دارید که پروتکل CORS را نقض کند، باید 'extraHeaders' در opt_extraInfoSpec مشخص کنید. از سوی دیگر، تغییرات در هدر پاسخ برای فریب بررسی‌های CORS کار نمی‌کند. اگر نیاز به فریب پروتکل CORS دارید، باید 'extraHeaders' نیز برای تغییرات پاسخ مشخص کنید.

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

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

  • مبدا

از کروم ۷۲ به بعد، اگر نیاز دارید پاسخ‌ها را قبل از اینکه مسدودسازی خواندن متقابل مبدا (CORB) بتواند پاسخ را مسدود کند، تغییر دهید، باید 'extraHeaders' در opt_extraInfoSpec مشخص کنید.

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

  • زبان پذیرش
  • رمزگذاری پذیرش
  • ارجاع دهنده
  • کوکی

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

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

API درخواست وب (webRequest API) فقط درخواست‌هایی را نمایش می‌دهد که افزونه با توجه به مجوزهای میزبان خود، مجوز دیدن آنها را دارد. علاوه بر این، فقط طرح‌های زیر قابل دسترسی هستند: http:// ، https:// ، ftp:// ، file:// ، ws:// (از کروم ۵۸)، wss:// (از کروم ۵۸)، urn: (از کروم ۹۱) یا chrome-extension:// . علاوه بر این، حتی درخواست‌های خاصی با URLهایی که از یکی از طرح‌های فوق استفاده می‌کنند، پنهان هستند. این موارد شامل chrome-extension://other_extension_id است که در آن other_extension_id شناسه افزونه‌ای نیست که درخواست را مدیریت کند، https://www.google.com/chrome و سایر درخواست‌های حساس که هسته اصلی عملکرد مرورگر هستند. همچنین درخواست‌های XMLHttpRequest همزمان از افزونه شما از مسدود کردن کنترل‌کننده‌های رویداد پنهان می‌شوند تا از بن‌بست جلوگیری شود. توجه داشته باشید که برای برخی از طرح‌های پشتیبانی شده، مجموعه رویدادهای موجود ممکن است به دلیل ماهیت پروتکل مربوطه محدود باشد. برای مثال، برای فایل: scheme، فقط onBeforeRequest ، onResponseStarted ، onCompleted و onErrorOccurred می‌توانند ارسال شوند.

از کروم ۵۸ به بعد، webRequest API از رهگیری درخواست‌های WebSocket handshake پشتیبانی می‌کند. از آنجایی که این handshake از طریق یک درخواست ارتقاء HTTP انجام می‌شود، جریان آن با مدل webRequest مبتنی بر HTTP مطابقت دارد. توجه داشته باشید که این API رهگیری نمی‌کند :

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

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

از کروم ۷۲ به بعد، یک افزونه تنها در صورتی می‌تواند درخواست را رهگیری کند که مجوزهای میزبانی هم برای URL درخواستی و هم برای آغازگر درخواست را داشته باشد.

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

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

مفاهیم

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

منابع_قابل_دسترسی_به_وب

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

حل اختلاف

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

ذخیره سازی

کروم از دو حافظه پنهان استفاده می‌کند - یک حافظه پنهان روی دیسک و یک حافظه پنهان بسیار سریع در حافظه. طول عمر یک حافظه پنهان در حافظه به طول عمر یک فرآیند رندر متصل است که تقریباً معادل یک تب است. درخواست‌هایی که از حافظه پنهان در حافظه پاسخ داده می‌شوند، برای API درخواست وب نامرئی هستند. اگر یک کنترل‌کننده درخواست رفتار خود را تغییر دهد (به عنوان مثال، رفتاری که بر اساس آن درخواست‌ها مسدود می‌شوند)، یک به‌روزرسانی ساده صفحه ممکن است این رفتار تغییر یافته را در نظر نگیرد. برای اطمینان از اینکه تغییر رفتار اعمال می‌شود، تابع 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"]
);

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

انواع

BlockingResponse

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

خواص

  • اعتبارنامه‌های نویسنده

    شیء اختیاری

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

    • رمز عبور

      رشته

    • نام کاربری

      رشته

  • لغو

    بولی اختیاری

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

  • تغییر مسیر

    رشته اختیاری

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

  • درخواست‌ها

    HttpHeaders اختیاری است

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

  • هدرهای پاسخ

    HttpHeaders اختیاری است

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

FormDataItem

کروم ۶۶+

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

شمارشی

آرایه بافر

رشته

HttpHeaders

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

نوع

شیء[]

خواص

  • مقدار دودویی

    عدد[] اختیاری

    مقدار هدر HTTP، در صورتی که با UTF-8 قابل نمایش نباشد، به صورت مقادیر بایتی مجزا (0..255) ذخیره می‌شود.

  • نام

    رشته

    نام هدر HTTP.

  • ارزش

    رشته اختیاری

    مقدار هدر HTTP، در صورتی که بتوان آن را با UTF-8 نمایش داد.

IgnoredActionType

کروم ۷۰+

شمارشی

"تغییر مسیر"

"هدرهای درخواست"

"هدرهای_پاسخ"

"اعتبارنامه‌های_مجوز"

OnAuthRequiredOptions

کروم ۴۴+

شمارشی

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

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

"مسدودسازی ناهمگام"
مشخص می‌کند که تابع فراخوانی (callback) به صورت غیرهمزمان (asynchronous) مدیریت می‌شود.

"سربرگ‌های اضافی"
مشخص می‌کند که هدرها می‌توانند اشتراک‌گذاری منابع بین مبدا (CORS) را نقض کنند.

OnBeforeRedirectOptions

کروم ۴۴+

شمارشی

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

"سربرگ‌های اضافی"
مشخص می‌کند که هدرها می‌توانند اشتراک‌گذاری منابع بین مبدا (CORS) را نقض کنند.

OnBeforeRequestOptions

کروم ۴۴+

شمارشی

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

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

"سربرگ‌های اضافی"
مشخص می‌کند که هدرها می‌توانند اشتراک‌گذاری منابع بین مبدا (CORS) را نقض کنند.

OnBeforeSendHeadersOptions

کروم ۴۴+

شمارشی

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

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

"سربرگ‌های اضافی"
مشخص می‌کند که هدرها می‌توانند اشتراک‌گذاری منابع بین مبدا (CORS) را نقض کنند.

OnCompletedOptions

کروم ۴۴+

شمارشی

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

"سربرگ‌های اضافی"
مشخص می‌کند که هدرها می‌توانند اشتراک‌گذاری منابع بین مبدا (CORS) را نقض کنند.

OnErrorOccurredOptions

کروم ۷۹+

ارزش

"سربرگ‌های اضافی"

OnHeadersReceivedOptions

کروم ۴۴+

شمارشی

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

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

"سربرگ‌های اضافی"
مشخص می‌کند که هدرها می‌توانند اشتراک‌گذاری منابع بین مبدا (CORS) را نقض کنند.

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

"اطلاعات امنیتی خام"
مشخص می‌کند که SecurityInfo به همراه بایت‌های خام گواهی‌ها باید در رویداد گنجانده شود.

OnResponseStartedOptions

کروم ۴۴+

شمارشی

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

"سربرگ‌های اضافی"
مشخص می‌کند که هدرها می‌توانند اشتراک‌گذاری منابع بین مبدا (CORS) را نقض کنند.

OnSendHeadersOptions

کروم ۴۴+

شمارشی

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

"سربرگ‌های اضافی"
مشخص می‌کند که هدرها می‌توانند اشتراک‌گذاری منابع بین مبدا (CORS) را نقض کنند.

RequestFilter

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

خواص

  • شناسه برگه

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

  • انواع

    نوع منبع [] اختیاری

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

  • آدرس‌های اینترنتی

    رشته[]

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

  • شناسه پنجره

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

ResourceType

کروم ۴۴+

شمارشی

"فریم_اصلی"
منبع را به عنوان فریم اصلی مشخص می‌کند.

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

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

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

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

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

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

"درخواست xmlhttp"
منبع را به عنوان یک XMLHttpRequest مشخص می‌کند.

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

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

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

"سوکت وب"
منبع را به عنوان یک WebSocket مشخص می‌کند.

"بسته وب"
منبع را به عنوان یک WebBundle مشخص می‌کند.

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

SecurityInfo

در حال بررسی

خواص

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

    شیء[]

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

    • اثر انگشت

      شیء

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

      • sha256

        رشته

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

    • خام‌در

      ArrayBuffer اختیاری

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

  • ایالت

    رشته

    وضعیت اتصال. یکی از امن، ناامن، و دیگری از کار افتاده.

UploadData

شامل داده‌های آپلود شده در یک درخواست URL است.

خواص

  • بایت

    هر اختیاری

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

  • فایل

    رشته اختیاری

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

خواص

MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES

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

ارزش

۲۰

روش‌ها

handlerBehaviorChanged()

وعده
chrome.webRequest.handlerBehaviorChanged(
  callback?: function,
): Promise<void>

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

پارامترها

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    () => void

بازگشت‌ها

  • قول<void>

    کروم ۱۱۶+

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

رویدادها

onActionIgnored

کروم ۷۰+
chrome.webRequest.onActionIgnored.addListener(
  callback: function,
)

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

پارامترها

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

    (details: object) => void

    • جزئیات

      شیء

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

      • شناسه درخواست

        رشته

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

onAuthRequired

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

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

پارامترها

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

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

    • جزئیات

      شیء

      • رقیب

        شیء

        سرور درخواست احراز هویت می‌کند.

        • میزبان

          رشته

        • بندر

          شماره

      • شناسه سند

        رشته

        کروم ۱۰۶+

        UUID سندی که درخواست را انجام می‌دهد.

      • چرخه عمر سند

        extensionTypes.DocumentLifecycle

        کروم ۱۰۶+

        چرخه عمری که سند در آن قرار دارد.

      • شناسه قاب

        شماره

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

      • کروم ۱۰۶+

        نوع فریمی که درخواست در آن رخ داده است.

      • آغازگر

        رشته اختیاری

        کروم ۶۳+

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

      • ایس‌پروکسی

        بولی

        برای تأیید اعتبار از طریق پروکسی درست، و برای تأیید اعتبار از طریق WWW نادرست است.

      • روش

        رشته

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

      • شناسه سند والد

        رشته اختیاری

        کروم ۱۰۶+

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

      • شناسه والدفریم

        شماره

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

      • قلمرو

        رشته اختیاری

        حوزه احراز هویت ارائه شده توسط سرور، در صورت وجود.

      • شناسه درخواست

        رشته

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

      • هدرهای پاسخ

        HttpHeaders اختیاری است

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

      • طرح

        رشته

        طرح احراز هویت، مثلاً Basic یا Digest.

      • کد وضعیت

        شماره

        کروم ۴۳+

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

      • وضعیتخط

        رشته

        خط وضعیت HTTP پاسخ یا رشته 'HTTP/0.9 200 OK' برای پاسخ‌های HTTP/0.9 (یعنی پاسخ‌هایی که فاقد خط وضعیت هستند) یا یک رشته خالی در صورت عدم وجود سرصفحه.

      • شناسه برگه

        شماره

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

      • مهر زمانی

        شماره

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

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

      • آدرس اینترنتی

        رشته

    • asyncCallback

      تابع اختیاری

      کروم ۵۸+

      پارامتر asyncCallback به شکل زیر است: 

      (response: BlockingResponse) => void

    • بازده

      پاسخ مسدودکننده | تعریف نشده

      اگر در پارامتر "extraInfoSpec" عبارت "blocking" مشخص شده باشد، شنونده رویداد باید شیء‌ای از این نوع را برگرداند.

  • extraInfoSpec

    OnAuthRequiredOptions [] اختیاری

onBeforeRedirect

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

زمانی اجرا می‌شود که یک تغییر مسیر آغاز شده توسط سرور در شرف وقوع باشد.

پارامترها

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

    (details: object) => void

    • جزئیات

      شیء

      • شناسه سند

        رشته

        کروم ۱۰۶+

        UUID سندی که درخواست را انجام می‌دهد.

      • چرخه عمر سند

        extensionTypes.DocumentLifecycle

        کروم ۱۰۶+

        چرخه عمری که سند در آن قرار دارد.

      • شناسه قاب

        شماره

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

      • کروم ۱۰۶+

        نوع فریمی که درخواست در آن رخ داده است.

      • از حافظه پنهان

        بولی

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

      • آغازگر

        رشته اختیاری

        کروم ۶۳+

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

      • آی‌پی

        رشته اختیاری

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

      • روش

        رشته

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

      • شناسه سند والد

        رشته اختیاری

        کروم ۱۰۶+

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

      • شناسه والدفریم

        شماره

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

      • تغییر مسیر

        رشته

        آدرس اینترنتی جدید.

      • شناسه درخواست

        رشته

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

      • هدرهای پاسخ

        HttpHeaders اختیاری است

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

      • کد وضعیت

        شماره

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

      • وضعیتخط

        رشته

        خط وضعیت HTTP پاسخ یا رشته 'HTTP/0.9 200 OK' برای پاسخ‌های HTTP/0.9 (یعنی پاسخ‌هایی که فاقد خط وضعیت هستند) یا یک رشته خالی در صورت عدم وجود سرصفحه.

      • شناسه برگه

        شماره

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

      • مهر زمانی

        شماره

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

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

      • آدرس اینترنتی

        رشته

  • extraInfoSpec

    OnBeforeRedirectOptions [] اختیاری

onBeforeRequest

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

زمانی که یک درخواست در شرف وقوع است، اجرا می‌شود.

پارامترها

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

    (details: object) => BlockingResponse | undefined

    • جزئیات

      شیء

      • شناسه سند

        رشته اختیاری

        کروم ۱۰۶+

        UUID سندی که درخواست را انجام می‌دهد.

      • چرخه عمر سند

        extensionTypes.DocumentLifecycle اختیاری است

        کروم ۱۰۶+

        چرخه عمری که سند در آن قرار دارد.

      • شناسه قاب

        شماره

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

      • نوع قاب

        نوع فریم. نوع پسوند اختیاری است

        کروم ۱۰۶+

        نوع فریمی که درخواست در آن رخ داده است.

      • آغازگر

        رشته اختیاری

        کروم ۶۳+

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

      • روش

        رشته

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

      • شناسه سند والد

        رشته اختیاری

        کروم ۱۰۶+

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

      • شناسه والدفریم

        شماره

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

      • درخواستبدنه

        شیء اختیاری

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

        • خطا

          رشته اختیاری

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

        • فرم داده

          شیء اختیاری

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

        • خام

          آپلودداده [] اختیاری

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

      • شناسه درخواست

        رشته

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

      • شناسه برگه

        شماره

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

      • مهر زمانی

        شماره

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

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

      • آدرس اینترنتی

        رشته

    • بازده

      پاسخ مسدودکننده | تعریف نشده

      اگر در پارامتر "extraInfoSpec" عبارت "blocking" مشخص شده باشد، شنونده رویداد باید شیء‌ای از این نوع را برگرداند.

  • extraInfoSpec

    OnBeforeRequestOptions [] اختیاری

onBeforeSendHeaders

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

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

پارامترها

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

    (details: object) => BlockingResponse | undefined

    • جزئیات

      شیء

      • شناسه سند

        رشته

        کروم ۱۰۶+

        UUID سندی که درخواست را انجام می‌دهد.

      • چرخه عمر سند

        extensionTypes.DocumentLifecycle

        کروم ۱۰۶+

        چرخه عمری که سند در آن قرار دارد.

      • شناسه قاب

        شماره

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

      • کروم ۱۰۶+

        نوع فریمی که درخواست در آن رخ داده است.

      • آغازگر

        رشته اختیاری

        کروم ۶۳+

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

      • روش

        رشته

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

      • شناسه سند والد

        رشته اختیاری

        کروم ۱۰۶+

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

      • شناسه والدفریم

        شماره

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

      • درخواست‌ها

        HttpHeaders اختیاری است

        هدرهای درخواست HTTP که قرار است با این درخواست ارسال شوند.

      • شناسه درخواست

        رشته

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

      • شناسه برگه

        شماره

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

      • مهر زمانی

        شماره

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

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

      • آدرس اینترنتی

        رشته

    • بازده

      پاسخ مسدودکننده | تعریف نشده

      اگر در پارامتر "extraInfoSpec" عبارت "blocking" مشخص شده باشد، شنونده رویداد باید شیء‌ای از این نوع را برگرداند.

  • extraInfoSpec

    OnBeforeSendHeadersOptions [] اختیاری

onCompleted

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

زمانی که یک درخواست تکمیل می‌شود، اجرا می‌شود.

پارامترها

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

    (details: object) => void

    • جزئیات

      شیء

      • شناسه سند

        رشته

        کروم ۱۰۶+

        The UUID of the document making the request.

      • Chrome 106+

        The lifecycle the document is in.

      • frameId

        شماره

        The value 0 indicates that the request happens in the main frame; a positive value indicates the ID of a subframe in which the request happens. If the document of a (sub-)frame is loaded ( type is main_frame or sub_frame ), frameId indicates the ID of this frame, not the ID of the outer frame. Frame IDs are unique within a tab.

      • Chrome 106+

        The type of frame the request occurred in.

      • fromCache

        بولی

        Indicates if this response was fetched from disk cache.

      • آغازگر

        رشته اختیاری

        Chrome 63+

        The origin where the request was initiated. This does not change through redirects. If this is an opaque origin, the string 'null' will be used.

      • آی‌پی

        رشته اختیاری

        The server IP address that the request was actually sent to. Note that it may be a literal IPv6 address.

      • روش

        رشته

        Standard HTTP method.

      • parentDocumentId

        رشته اختیاری

        Chrome 106+

        The UUID of the parent document owning this frame. This is not set if there is no parent.

      • parentFrameId

        شماره

        ID of frame that wraps the frame which sent the request. Set to -1 if no parent frame exists.

      • شناسه درخواست

        رشته

        The ID of the request. Request IDs are unique within a browser session. As a result, they could be used to relate different events of the same request.

      • responseHeaders

        HttpHeaders optional

        The HTTP response headers that were received along with this response.

      • statusCode

        شماره

        Standard HTTP status code returned by the server.

      • statusLine

        رشته

        HTTP status line of the response or the 'HTTP/0.9 200 OK' string for HTTP/0.9 responses (ie, responses that lack a status line) or an empty string if there are no headers.

      • شناسه برگه

        شماره

        The ID of the tab in which the request takes place. Set to -1 if the request isn't related to a tab.

      • مهر زمانی

        شماره

        The time when this signal is triggered, in milliseconds since the epoch.

      • نوع

        ResourceType

        How the requested resource will be used.

      • آدرس اینترنتی

        رشته

  • فیلتر

    RequestFilter

  • extraInfoSpec

    OnCompletedOptions [] optional

onErrorOccurred

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

Fired when an error occurs.

پارامترها

  • تماس برگشتی

    تابع

    The callback parameter looks like: 

    (details: object) => void

    • جزئیات

      شیء

      • شناسه سند

        رشته

        Chrome 106+

        The UUID of the document making the request. This value is not present if the request is a navigation of a frame.

      • Chrome 106+

        The lifecycle the document is in.

      • خطا

        رشته

        The error description. This string is not guaranteed to remain backwards compatible between releases. You must not parse and act based upon its content.

      • frameId

        شماره

        The value 0 indicates that the request happens in the main frame; a positive value indicates the ID of a subframe in which the request happens. If the document of a (sub-)frame is loaded ( type is main_frame or sub_frame ), frameId indicates the ID of this frame, not the ID of the outer frame. Frame IDs are unique within a tab.

      • Chrome 106+

        The type of frame the request occurred in.

      • fromCache

        بولی

        Indicates if this response was fetched from disk cache.

      • آغازگر

        رشته اختیاری

        Chrome 63+

        The origin where the request was initiated. This does not change through redirects. If this is an opaque origin, the string 'null' will be used.

      • آی‌پی

        رشته اختیاری

        The server IP address that the request was actually sent to. Note that it may be a literal IPv6 address.

      • روش

        رشته

        Standard HTTP method.

      • parentDocumentId

        رشته اختیاری

        Chrome 106+

        The UUID of the parent document owning this frame. This is not set if there is no parent.

      • parentFrameId

        شماره

        ID of frame that wraps the frame which sent the request. Set to -1 if no parent frame exists.

      • شناسه درخواست

        رشته

        The ID of the request. Request IDs are unique within a browser session. As a result, they could be used to relate different events of the same request.

      • شناسه برگه

        شماره

        The ID of the tab in which the request takes place. Set to -1 if the request isn't related to a tab.

      • مهر زمانی

        شماره

        The time when this signal is triggered, in milliseconds since the epoch.

      • نوع

        ResourceType

        How the requested resource will be used.

      • آدرس اینترنتی

        رشته

  • فیلتر

    RequestFilter

  • extraInfoSpec

    OnErrorOccurredOptions [] optional

onHeadersReceived

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

Fired when HTTP response headers of a request have been received.

پارامترها

  • تماس برگشتی

    تابع

    The callback parameter looks like: 

    (details: object) => BlockingResponse | undefined

    • جزئیات

      شیء

      • شناسه سند

        رشته

        Chrome 106+

        The UUID of the document making the request.

      • Chrome 106+

        The lifecycle the document is in.

      • frameId

        شماره

        The value 0 indicates that the request happens in the main frame; a positive value indicates the ID of a subframe in which the request happens. If the document of a (sub-)frame is loaded ( type is main_frame or sub_frame ), frameId indicates the ID of this frame, not the ID of the outer frame. Frame IDs are unique within a tab.

      • Chrome 106+

        The type of frame the request occurred in.

      • آغازگر

        رشته اختیاری

        Chrome 63+

        The origin where the request was initiated. This does not change through redirects. If this is an opaque origin, the string 'null' will be used.

      • روش

        رشته

        Standard HTTP method.

      • parentDocumentId

        رشته اختیاری

        Chrome 106+

        The UUID of the parent document owning this frame. This is not set if there is no parent.

      • parentFrameId

        شماره

        ID of frame that wraps the frame which sent the request. Set to -1 if no parent frame exists.

      • شناسه درخواست

        رشته

        The ID of the request. Request IDs are unique within a browser session. As a result, they could be used to relate different events of the same request.

      • responseHeaders

        HttpHeaders optional

        The HTTP response headers that have been received with this response.

      • securityInfo

        SecurityInfo optional

        در حال بررسی

        Information about the TLS/QUIC connection used for the underlying connection. Only provided if securityInfo is specified in the extraInfoSpec parameter.

      • statusCode

        شماره

        Chrome 43+

        Standard HTTP status code returned by the server.

      • statusLine

        رشته

        HTTP status line of the response or the 'HTTP/0.9 200 OK' string for HTTP/0.9 responses (ie, responses that lack a status line).

      • شناسه برگه

        شماره

        The ID of the tab in which the request takes place. Set to -1 if the request isn't related to a tab.

      • مهر زمانی

        شماره

        The time when this signal is triggered, in milliseconds since the epoch.

      • نوع

        ResourceType

        How the requested resource will be used.

      • آدرس اینترنتی

        رشته

    • بازده

      BlockingResponse | undefined

      If "blocking" is specified in the "extraInfoSpec" parameter, the event listener should return an object of this type.

  • فیلتر

    RequestFilter

  • extraInfoSpec

    OnHeadersReceivedOptions [] optional

onResponseStarted

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

Fired when the first byte of the response body is received. For HTTP requests, this means that the status line and response headers are available.

پارامترها

  • تماس برگشتی

    تابع

    The callback parameter looks like: 

    (details: object) => void

    • جزئیات

      شیء

      • شناسه سند

        رشته

        Chrome 106+

        The UUID of the document making the request.

      • Chrome 106+

        The lifecycle the document is in.

      • frameId

        شماره

        The value 0 indicates that the request happens in the main frame; a positive value indicates the ID of a subframe in which the request happens. If the document of a (sub-)frame is loaded ( type is main_frame or sub_frame ), frameId indicates the ID of this frame, not the ID of the outer frame. Frame IDs are unique within a tab.

      • Chrome 106+

        The type of frame the request occurred in.

      • fromCache

        بولی

        Indicates if this response was fetched from disk cache.

      • آغازگر

        رشته اختیاری

        Chrome 63+

        The origin where the request was initiated. This does not change through redirects. If this is an opaque origin, the string 'null' will be used.

      • آی‌پی

        رشته اختیاری

        The server IP address that the request was actually sent to. Note that it may be a literal IPv6 address.

      • روش

        رشته

        Standard HTTP method.

      • parentDocumentId

        رشته اختیاری

        Chrome 106+

        The UUID of the parent document owning this frame. This is not set if there is no parent.

      • parentFrameId

        شماره

        ID of frame that wraps the frame which sent the request. Set to -1 if no parent frame exists.

      • شناسه درخواست

        رشته

        The ID of the request. Request IDs are unique within a browser session. As a result, they could be used to relate different events of the same request.

      • responseHeaders

        HttpHeaders optional

        The HTTP response headers that were received along with this response.

      • statusCode

        شماره

        Standard HTTP status code returned by the server.

      • statusLine

        رشته

        HTTP status line of the response or the 'HTTP/0.9 200 OK' string for HTTP/0.9 responses (ie, responses that lack a status line) or an empty string if there are no headers.

      • شناسه برگه

        شماره

        The ID of the tab in which the request takes place. Set to -1 if the request isn't related to a tab.

      • مهر زمانی

        شماره

        The time when this signal is triggered, in milliseconds since the epoch.

      • نوع

        ResourceType

        How the requested resource will be used.

      • آدرس اینترنتی

        رشته

  • فیلتر

    RequestFilter

  • extraInfoSpec

    OnResponseStartedOptions [] optional

onSendHeaders

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

Fired just before a request is going to be sent to the server (modifications of previous onBeforeSendHeaders callbacks are visible by the time onSendHeaders is fired).

پارامترها

  • تماس برگشتی

    تابع

    The callback parameter looks like: 

    (details: object) => void

    • جزئیات

      شیء

      • شناسه سند

        رشته

        Chrome 106+

        The UUID of the document making the request.

      • Chrome 106+

        The lifecycle the document is in.

      • frameId

        شماره

        The value 0 indicates that the request happens in the main frame; a positive value indicates the ID of a subframe in which the request happens. If the document of a (sub-)frame is loaded ( type is main_frame or sub_frame ), frameId indicates the ID of this frame, not the ID of the outer frame. Frame IDs are unique within a tab.

      • Chrome 106+

        The type of frame the request occurred in.

      • آغازگر

        رشته اختیاری

        Chrome 63+

        The origin where the request was initiated. This does not change through redirects. If this is an opaque origin, the string 'null' will be used.

      • روش

        رشته

        Standard HTTP method.

      • parentDocumentId

        رشته اختیاری

        Chrome 106+

        The UUID of the parent document owning this frame. This is not set if there is no parent.

      • parentFrameId

        شماره

        ID of frame that wraps the frame which sent the request. Set to -1 if no parent frame exists.

      • requestHeaders

        HttpHeaders optional

        The HTTP request headers that have been sent out with this request.

      • شناسه درخواست

        رشته

        The ID of the request. Request IDs are unique within a browser session. As a result, they could be used to relate different events of the same request.

      • شناسه برگه

        شماره

        The ID of the tab in which the request takes place. Set to -1 if the request isn't related to a tab.

      • مهر زمانی

        شماره

        The time when this signal is triggered, in milliseconds since the epoch.

      • نوع

        ResourceType

        How the requested resource will be used.

      • آدرس اینترنتی

        رشته

  • فیلتر

    RequestFilter

  • extraInfoSpec

    OnSendHeadersOptions [] optional