تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

chrome.webRequest

الوصف

استخدِم chrome.webRequest API لرصد الزيارات وتحليلها واعتراض الطلبات أثناء تشغيلها أو حظرها أو تعديلها.

الأذونات

webRequest

البيان

يجب الإفصاح عن إذن "webRequest" في بيان الإضافة لاستخدام طلب الويب. بالإضافة إلى أذونات المضيف اللازمة. لاعتراض طلب مورد فرعي، يجب أن يكون لدى الإضافة الإذن بالوصول إلى كل من عنوان URL المطلوب وبادئه. على سبيل المثال:

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

اعتبارًا من الإصدار 108 من Chrome، يمكنك تقديم بيانات الاعتماد بشكل غير متزامن لأحداث onAuthRequired في حال استخدام "webRequest" و"webRequestAuthProvider". الأذونات.

ملاحظة: اعتبارًا من إصدار Manifest V3، لم يعُد إذن "webRequestBlocking" متاحًا لمعظم الإضافات. يمكنك استخدام السياسة "declarativeNetRequest" التي تتيح استخدام declarativeNetRequest API. بالإضافة إلى "webRequestBlocking"، لن يتم تغيير واجهة برمجة التطبيقات webRequest وستكون متاحة للاستخدام العادي. يمكن أن تستمر الإضافات المثبَّتة للسياسة في استخدام "webRequestBlocking".

دورة حياة الطلبات

تحدد واجهة برمجة التطبيقات لطلب الويب مجموعة من الأحداث التي تتبع دورة حياة طلب الويب. يمكنك استخدام هذه الأحداث لرصد الزيارات وتحليلها. فبعض الأحداث المتزامنة سوف تتيح لك اعتراض طلب أو حظره أو تعديله.

يتم هنا توضيح دورة حياة الحدث للطلبات الناجحة، متبوعة بتعريفات الحدث:

دورة حياة طلب الويب من منظور واجهة برمجة تطبيقات طلب الويب

onBeforeRequest (متزامن اختياريًا): يتم تنشيطها عندما يكون الطلب على وشك الحدوث. يتم إرسال هذا الحدث قبل إجراء أي اتصال لبروتوكول التحكم في الإرسال (TCP) ويمكن أن تُستخدَم لإلغاء الطلبات أو إعادة توجيهها.
onBeforeSendHeaders (متزامن اختياريًا): يتم تنشيطها عندما يكون الطلب على وشك الحدوث ويتم إعداد العناوين الأولية. الفعالية هي تهدف إلى السماح للإضافات بإضافة عناوين الطلبات (*) وتعديلها وحذفها. تشير رسالة الأشكال البيانية يتم نقل الحدث onBeforeSendHeaders إلى جميع المشتركين، لذلك قد يحاول مشتركون مختلفون تعديل الطلب يُرجى الاطّلاع على قسم تفاصيل التنفيذ لمعرفة كيفية التعامل مع هذه المشكلة. هذا الحدث لإلغاء الطلب.
onSendHeaders: أتاحت عمليات إطلاق النار بعد كل الإضافات إمكانية تعديل عناوين الطلبات وتقديم النتيجة النهائية إصدار (*). يتم تشغيل الحدث قبل إرسال العناوين إلى الشبكة. هذا الحدث هو المعلومات والتعامل معها بشكل غير متزامن. ولا يسمح بتعديل الطلب أو إلغائه.
onHeadersReceived (متزامن اختياريًا): يتم تنشيطها في كل مرة يتم فيها تلقّي عنوان استجابة HTTP(S). بسبب عمليات إعادة التوجيه والمصادقة أن يحدث ذلك عدة مرات لكل طلب. يهدف هذا الحدث إلى السماح للإضافات إضافة عناوين الاستجابة وتعديلها وحذفها، مثل عناوين نوع المحتوى الواردة التخزين المؤقت تتم معالجة الأوامر قبل تشغيل هذا الحدث، لذا فإن تعديل العناوين مثل التحكم في ذاكرة التخزين المؤقت ليس له أي تأثير في ذاكرة التخزين المؤقت في المتصفح. ويتيح لك أيضًا إلغاء الطلب أو إعادة توجيهه.
onAuthRequired (متزامن اختياريًا): يتم تنشيطه عندما يتطلب الطلب مصادقة المستخدم. يمكن التعامل مع هذا الحدث بشكل متزامن تقديم بيانات اعتماد المصادقة. تجدر الإشارة إلى أنّ الإضافات قد توفّر بيانات اعتماد غير صالحة. مع أطيب التحيات، عدم الدخول في حلقة لانهائية من خلال تقديم بيانات اعتماد غير صالحة بشكل متكرر. يمكن استخدام هذه البيانات أيضًا إلغاء الطلب
onBeforeRedirect: يتم تنشيطه عندما تكون عملية إعادة التوجيه على وشك تنفيذ. يمكن بدء إعادة التوجيه عن طريق استجابة HTTP الرمز أو باستخدام إضافة. هذا الحدث إعلامي وتتم معالجته بشكل غير متزامن. عدم السماح لتعديل الطلب أو إلغائه.
onResponseStarted: يتم تنشيطها عند تلقّي البايت الأول من نص الاستجابة. بالنسبة لطلبات HTTP، هذا يعني أن وحدة سطر الحالة وعناوين الاستجابة متاحين. هذا الحدث إعلامي ومعالجته بشكل غير متزامن. ولا يسمح بتعديل الطلب أو إلغائه.
onCompleted: يتم تنشيطه عند معالجة الطلب بنجاح.
onErrorOccurred: يتم تنشيطها عند تعذُّر معالجة الطلب بنجاح.

تضمن واجهة برمجة تطبيقات طلب الويب أن تكون قيمة onCompleted أو onErrorOccurred لكل طلب يتم تنشيطها كحدث نهائي مع استثناء واحد: إذا تمت إعادة توجيه الطلب إلى عنوان URL data://، onBeforeRedirect هو آخر حدث تم الإبلاغ عنه.

* لاحظ أن واجهة برمجة التطبيقات لطلب الويب تقدم تجريدًا لحزمة الشبكة إلى الإضافة. داخليًا، يمكن تقسيم طلب عنوان URL واحد إلى عدة طلبات HTTP (على سبيل المثال، لجلب طلبات فردية نطاقات البايت من ملف كبير) أو يمكن التعامل معها بواسطة مكدس الشبكة دون الاتصال بوحدة الشبكة. ولهذا السبب، لا توفّر واجهة برمجة التطبيقات عناوين HTTP النهائية التي يتم إرسالها إلى الشبكة. على سبيل المثال، تكون جميع العناوين المرتبطة بالتخزين المؤقت غير مرئية للإضافة.

العناوين التالية غير متوفرة حاليًا لحدث onBeforeSendHeaders. هذه القائمة ليس مضمونًا أن تكون كاملة أو مستقرة.

التفويض
التحكّم في ذاكرة التخزين المؤقت
الاتصال
مدة المحتوى
المضيف
إذا تم التعديل منذ
عدم التطابق
إذا كان النطاق
بيانات جزئية
براغما
تفويض الخادم الوكيل
اتصال الخادم الوكيل
Transfer-Encoding

بدءًا من الإصدار Chrome 79، ستؤثّر تعديلات عناوين الطلبات في مشاركة الموارد المتعدّدة المصادر (CORS) عمليات التحقق. في حال عدم استيفاء العناوين المعدَّلة للطلبات المتعددة المصادر المعايير، سيؤدي ذلك إلى إرسال طلب CORS المبدئي لسؤال الخادم عما إذا كان من الممكن قبول هذه العناوين. إذا كنت حقًا بحاجة إلى تعديل العناوين بطريقة تنتهك بروتوكول CORS، يجب تحديد 'extraHeaders' في opt_extraInfoSpec ومن ناحية أخرى، لا تعمل تعديلات عناوين الاستجابة لخداع سياسة مشاركة الموارد المتعددة المصادر (CORS). عمليات التحقق. إذا أردت خداع بروتوكول CORS، فعليك أيضًا تحديد 'extraHeaders' وتعديلات الرد.

بدءًا من الإصدار 79 من Chrome، لا تعترض واجهة برمجة التطبيقات webRequest طلبات طلب CORS المبدئي الردود افتراضيًا. يكون الطلب الأولي لسياسة مشاركة الموارد المتعددة المصادر (CORS) لعنوان URL الخاص بالطلب مرئيًا للإضافة في حال توفُّر أداة استماع مع 'extraHeaders' محددة في opt_extraInfoSpec لعنوان URL للطلب. يمكن أن يستخدم onBeforeRequest أيضًا 'extraHeaders' من Chrome 79.

بدايةً من الإصدار 79 من Chrome، لم يتم توفير عنوان الطلب التالي ولا يمكن تعديله أو تمت الإزالة بدون تحديد 'extraHeaders' في opt_extraInfoSpec:

الأصل

ملاحظة: قد لا يعمل تعديل عنوان طلب Origin على النحو المنشود وقد يؤدي إلى حدثت أخطاء غير متوقّعة في عمليات التحقّق من سياسة مشاركة الموارد المتعددة المصادر (CORS) الخاصة بالاستجابة. هذا لأنه في حين أن الإضافات لا يمكنها تعديل عنوان طلب المصدر، فلن يتمكن من تغيير request origin أو بادئ التشغيل، وهو مفهوم محدد في مواصفات الجلب لتمثيل الشخص الذي يبدأ الطلب. في مثل هذا السيناريو، السماح بوصول خادم CORS للطلب المعدّل ووضع Origin للرأس في عنوان Access-Control-Allow-Origin في الردّ. لكنها لن تتطابق مع العنصر غير القابل للتغيير request origin وسيؤدي ذلك إلى عدم نجاح سياسة مشاركة الموارد المتعددة المصادر (CORS).

بدءًا من الإصدار 72 من Chrome، إذا كنت بحاجة إلى تعديل الردود قبل حظر القراءة من مصادر متعددة (CORB) حظر الرد، يجب تحديد 'extraHeaders' في opt_extraInfoSpec.

بدءًا من الإصدار 72 من Chrome، لم يتم توفير عناوين الطلبات التالية ولا يمكن تعديلها. أو تمت إزالته بدون تحديد 'extraHeaders' في opt_extraInfoSpec:

اللغة المقبولة
Accept-Encoding
المُحيل
ملف تعريف الارتباط

بدءًا من الإصدار 72 من Chrome، لم يتم توفير عنوان الاستجابة Set-Cookie ولا يمكن تعديله أو إزالتها بدون تحديد 'extraHeaders' في opt_extraInfoSpec.

بدايةً من الإصدار 89 من Chrome، لا يمكن تعديل عنوان الاستجابة X-Frame-Options بفعالية. أو إزالتها بدون تحديد 'extraHeaders' في opt_extraInfoSpec.

ملاحظة: قد يؤدي تحديد 'extraHeaders' في opt_extraInfoSpec إلى تأثير سلبي على الأداء، لذلك يجب استخدامه عند الضرورة فقط.

لا تعرض واجهة برمجة التطبيقات webRequest إلا الطلبات التي يكون للإضافة الإذن بالاطّلاع عليها، نظرًا لمضيفها الأذونات. علاوة على ذلك، يمكن الوصول إلى المخططات التالية فقط: http:// وhttps:// ftp:// أو file:// أو ws:// (اعتبارًا من Chrome 58) أو wss:// (اعتبارًا من الإصدار 58 من Chrome) أو urn: (اعتبارًا من الإصدار 91 من Chrome) chrome-extension:// بالإضافة إلى ذلك، حتى بعض الطلبات التي لها عناوين URL تستخدم أحد المخططات المذكورة أعلاه مخفية. وتشمل هذه الأحداث chrome-extension://other_extension_id حيث لا ينطبق other_extension_id ومُعرّف الإضافة للتعامل مع الطلب، وhttps://www.google.com/chrome ومعلومات حساسة أخرى وظيفة أساسية في المتصفح. كما أن طلبات XMLHttpRequest المتزامنة من إضافتك هي من حظر معالِجات الأحداث لمنع حالات التعطُّل. لاحظ أنه بالنسبة لبعض غير مدعومة، التي قد تكون مجموعة الأحداث المتاحة محدودة نظرًا لطبيعة والبروتوكول المقابل. على سبيل المثال، بالنسبة إلى الملف: scheme، onBeforeRequest فقط، قد يتم إرسال onResponseStarted وonCompleted وonErrorOccurred.

بدءًا من الإصدار 58 من Chrome، تتيح واجهة برمجة التطبيقات webRequest اعتراض طلب تأكيد الاتصال في WebSocket. ونظرًا لأن عملية تأكيد الاتصال تتم عن طريق طلب ترقية HTTP، يتناسب تدفقها مع توجيه HTTP نموذج webRequest. يُرجى العلم أنّ واجهة برمجة التطبيقات لا تعترض ما يلي:

رسائل فردية تم إرسالها عبر اتصال WebSocket تم إنشاؤه
يتم إغلاق الاتصال بخادم WebSocket.

إنّ عمليات إعادة التوجيه غير متاحة لطلبات WebSocket.

بدءًا من الإصدار 72 من Chrome، لن تتمكن الإضافة من اعتراض طلب إلا إذا كان لديها مضيف الأذونات لكل من عنوان URL المطلوب وبادئ الطلب.

بدءًا من Chrome 96، تتيح واجهة برمجة التطبيقات webRequest اعتراض بروتوكول WebTransport عبر HTTP/3. طلب تأكيد الاتصال. نظرًا لأن عملية تأكيد الاتصال تتم عن طريق طلب اتصال HTTP، فإن مسارها يلائم إلى نموذج webRequest موجه نحو HTTP. تجدر الإشارة إلى ما يلي:

بعد إنشاء الجلسة، لا يمكن للإضافات مراقبة الجلسة أو التدخل فيها من خلال واجهة برمجة تطبيقات webRequest.
يتم تجاهل تعديل عناوين طلبات 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() دالة رد اتصال إلزامية كمعلمة أولى. معاودة الاتصال هذه قاموسًا يحتوي على معلومات حول طلب عنوان URL الحالي. تشير رسالة الأشكال البيانية المعلومات في هذا القاموس على نوع الحدث المحدد بالإضافة إلى محتوى opt_extraInfoSpec

إذا كانت مصفوفة opt_extraInfoSpec الاختيارية تحتوي على السلسلة 'blocking' (يُسمح بها فقط أحداث محددة)، يتم التعامل مع دالة معاودة الاتصال بشكل متزامن. هذا يعني أن الطلب حتى يتم إرجاع دالة رد الاتصال. في هذه الحالة، يمكن أن تقوم معاودة الاتصال بإرجاع webRequest.BlockingResponse الذي يحدّد دورة الحياة الإضافية للطلب. حسب استنادًا إلى السياق، تسمح هذه الاستجابة بإلغاء طلب أو إعادة توجيهه (onBeforeRequest)، إلغاء طلب أو تعديل العناوين (onBeforeSendHeaders أو onHeadersReceived) إلغاء طلب أو تقديم بيانات اعتماد المصادقة (onAuthRequired)

إذا كانت مصفوفة opt_extraInfoSpec الاختيارية تحتوي على السلسلة 'asyncBlocking' بدلاً من ذلك (فقط مسموح به في onAuthRequired)، يمكن للإضافة إنشاء webRequest.BlockingResponse بشكل غير متزامن.

تسمح webRequest.RequestFilter filter بالحدّ من عدد الطلبات المتعلّقة بالأحداث. تظهر في أبعاد مختلفة:

عناوين URL: أنماط عناوين URL مثل *://www.google.com/foo*bar.
الأنواع: أنواع الطلبات، مثل main_frame (مستند يتم تحميله لإطار من المستوى الأعلى)، sub_frame (a مستند يتم تحميله لإطار مضمّن) وimage (صورة على موقع إلكتروني). عرض webRequest.RequestFilter
رقم تعريف علامة التبويب: المعرّف لعلامة تبويب واحدة
رقم تعريف النافذة: معرّف نافذة

استنادًا إلى نوع الحدث، يمكنك تحديد سلاسل في "opt_extraInfoSpec" لطلب أحداث إضافية. للحصول على معلومات حول الطلب. يُستخدم هذا الخيار لتقديم معلومات تفصيلية حول بيانات الطلب فقط. إذا تم طلبها صراحةً.

تفاصيل التنفيذ

قد يكون من المهم فهم العديد من تفاصيل التنفيذ عند تطوير إضافة تستخدم واجهة برمجة تطبيقات طلب الويب:

web_accessible_resources

عندما تستخدم إضافة واجهات برمجة تطبيقات webRequest لإعادة توجيه طلب مورد عام إلى مورد لا يمكن الوصول إليه عبر الويب، يتم حظرها وسيؤدي إلى حدوث خطأ. ينطبق ما ورد أعلاه حتى إذا كان المورد الذي لا يمكن الوصول إليه عبر الويب مملوكًا من خلال إضافة إعادة التوجيه. للإبلاغ عن موارد للاستخدام مع واجهات برمجة تطبيقات declarativeWebRequest، يجب الإعلان عن المصفوفة "web_accessible_resources" وتعبئتها في البيان على النحو الموضّح هنا.

حل النزاعات

في إطار التنفيذ الحالي لواجهة برمجة تطبيقات طلب الويب، يُعتبر الطلب مُلغى في حالة وتطلب إضافة واحدة على الأقل إلغاء الطلب. إذا ألغت الإضافة طلبًا، سيتم يتم إشعار الإضافات بواسطة حدث onErrorOccurred. يمكن لإضافة واحدة فقط إعادة توجيه طلب أو تعديل عنوان في كل مرة. إذا حاولت أكثر من إضافة تعديل الطلب، سيتم أحدث إضافة تم تثبيتها ويتم تجاهل كل الإضافات الأخرى. لا يتم إشعار الإضافة في حال تم تجاهل تعليماته الخاصة بتعديل أو إعادة التوجيه.

التخزين المؤقت

يستخدم Chrome ذاكرتَي تخزين، وهما ذاكرة تخزين مؤقت على القرص وذاكرة تخزين مؤقت سريعة للغاية في الذاكرة. عمر ترتبط ذاكرة التخزين المؤقت في الذاكرة منذ إنشاء عملية العرض، والتي تتوافق تقريبًا مع علامة تبويب. لا تظهر الطلبات التي تمت الردّ عليها من ذاكرة التخزين المؤقت في الذاكرة لواجهة برمجة تطبيقات طلبات الويب. إذا يغير معالج الطلبات سلوكه (على سبيل المثال، السلوك الذي يتم وفقًا له محظور)، قد لا تراعي عملية إعادة تحميل الصفحة البسيطة هذا السلوك المتغير. للتأكد من أن السلوك تم إجراء تغيير، اتصل على handlerBehaviorChanged() لمحو ذاكرة التخزين المؤقت. لكن لا تفعل ذلك في كثير من الأحيان؛ مسح ذاكرة التخزين المؤقت عملية مكلفة للغاية. لست بحاجة إلى الاتصال handlerBehaviorChanged() بعد تسجيل أداة معالجة حدث أو إلغاء تسجيلها.

الطوابع الزمنية

يمكن ضمان اتساق السمة timestamp لأحداث طلبات الويب فقط داخليًا. تمنحك مقارنة حدث بحدث آخر معادلة فرق الوقت بينهما، إلا أن المقارنة إلى الوقت الحالي داخل الإضافة (عبر (new Date()).getTime()، على سبيل المثال) والحصول على نتائج غير متوقعة.

خطأ أثناء المعالجة

إذا حاولت تسجيل حدث باستخدام وسيطات غير صالحة، سيظهر خطأ JavaScript. فلن يتم تسجيل معالج الحدث. إذا حدث خطأ أثناء التعامل مع حدث أو إذا يعرض معالج الأحداث استجابة حظر غير صالحة، ويتم تسجيل رسالة خطأ في معرِّف الإضافة وحدة التحكم، ويتم تجاهل المعالج لهذا الطلب.

أمثلة

يوضّح المثال التالي كيفية حظر جميع الطلبات الموجّهة إلى 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"]
);

يوضِّح المثال التالي كيفية حذف رأس وكيل المستخدم من جميع الطلبات:

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، تثبيت نموذج webRequest من chrome-extension-samples المستودع.

الأنواع

BlockingResponse

عرض قيمة لمعالِجات الأحداث التي تحتوي على علامة "الحظر" تم تطبيق مواصفات إضافية. يسمح لمعالِج الحدث بتعديل طلبات الشبكة.

أماكن إقامة

authCredentials

الكائن اختياري

لا يُستخدَم هذا الإجراء إلا كردّ على حدث onAuthrequired. وفي حال ضبطها، يتم تقديم الطلب باستخدام بيانات الاعتماد المقدَّمة.
- كلمة المرور
  
  سلسلة
- اسم مستخدم
  
  سلسلة
إلغاء

قيمة منطقية اختيارية

إذا كانت القيمة هي true، سيتم إلغاء الطلب. ويؤدي هذا الإجراء إلى منع إرسال الطلب. ويمكن استخدام هذا كرد على أحداث onBeforeRequest وonBeforeSendHeaders وonHeadersReceived وonAuthrequired.
redirectUrl

سلسلة اختيارية

يُستخدم فقط كرد على حدثَي onBeforeRequest وonHeadersReceived. في حال ضبط هذه السياسة، سيتم منع إرسال أو إكمال الطلب الأصلي، وستتم إعادة توجيهه إلى عنوان URL المحدَّد بدلاً من ذلك. يُسمح بإعادة التوجيه إلى أنظمة ليست HTTP، مثل data:. تستخدم عمليات إعادة التوجيه التي يبدأها إجراء إعادة توجيه طريقة الطلب الأصلية لإعادة التوجيه، مع استثناء واحد: إذا بدأت عملية إعادة التوجيه في مرحلة onHeadersReceived، فسيتم إصدار عملية إعادة التوجيه باستخدام طريقة GET. ويتم تجاهل عمليات إعادة التوجيه من عناوين URL التي تتضمّن مخطّطَين ws:// وwss://.
requestHeaders

HttpHeaders اختيارية

يُستخدم فقط كرد على حدث onBeforeSendHeaders. وفي حال ضبطها، يتم الطلب باستخدام عناوين الطلبات هذه بدلاً من ذلك.
responseHeaders

HttpHeaders اختيارية

تُستخدم فقط كرد على حدث onHeadersReceived. في حال ضبطها، من المفترض أن يستجيب الخادم بعناوين الاستجابة هذه بدلاً من ذلك. يجب عرض responseHeaders فقط إذا كنت تريد تعديل العناوين للحدّ من عدد التعارضات (يمكن لإضافة واحدة فقط تعديل responseHeaders لكل طلب).

FormDataItem

الإصدار 66 من Chrome أو الإصدارات الأحدث

يحتوي على البيانات التي تم تمريرها ضمن بيانات النموذج. بالنسبة إلى النموذج المُرمّز باستخدام عنوان URL، يتم تخزينه كسلسلة إذا كانت البيانات سلسلة utf-8 أو ArrayBuffer في الحالات الأخرى. بالنسبة لبيانات النموذج، يكون ArrayBuffer. إذا كانت بيانات النموذج تمثل تحميل الملف، فهي عبارة عن سلسلة باسم ملف، إذا تم تقديم اسم الملف.

Enum

مخزن المصفوفات

سلسلة

HttpHeaders

مصفوفة من عناوين HTTP. يتم تمثيل كل عنوان كقاموس يحتوي على المفاتيح name وإما value أو binaryValue.

النوع

object[]

أماكن إقامة

binaryValue

number[] اختياري

قيمة عنوان HTTP إذا تعذّر تمثيلها بمعيار UTF-8، حيث يتم تخزينها كقيم بايت فردية (0..255).
الاسم

سلسلة

اسم عنوان HTTP
القيمة

سلسلة اختيارية

قيمة عنوان HTTP إذا كان من الممكن تمثيلها بترميز UTF-8.

IgnoredActionType

الإصدار 70 من Chrome أو الإصدارات الأحدث

Enum

"إعادة التوجيه"

"request_headers"

"response_headers"

"auth_credentials"

OnAuthRequiredOptions

الإصدار 44 من Chrome أو الإصدارات الأحدث

Enum

"responseHeaders"
يحدد هذا الحقل أنه يجب تضمين عناوين الاستجابة في الحدث.

"blocking"
يحدد هذا الخيار حظر الطلب إلى أن تعود دالة الاستدعاء.

"asyncBlocking"
يحدِّد هذا الخيار التعامل مع دالة معاودة الاتصال بشكل غير متزامن.

"extraHeaders"
يحدد هذا العمود أنّ العناوين يمكن أن تنتهك مشاركة الموارد المتعدّدة المصادر (CORS).

OnBeforeRedirectOptions

الإصدار 44 من Chrome أو الإصدارات الأحدث

Enum

"responseHeaders"
يحدد هذا الحقل أنه يجب تضمين عناوين الاستجابة في الحدث.

"extraHeaders"
يحدد هذا العمود أنّ العناوين يمكن أن تنتهك مشاركة الموارد المتعدّدة المصادر (CORS).

OnBeforeRequestOptions

الإصدار 44 من Chrome أو الإصدارات الأحدث

Enum

"blocking"
يحدد هذا الخيار حظر الطلب إلى أن تعود دالة الاستدعاء.

"requestBody"
يحدد هذا الإعداد أنه يجب تضمين نص الطلب في الحدث.

"extraHeaders"
يحدد هذا العمود أنّ العناوين يمكن أن تنتهك مشاركة الموارد المتعدّدة المصادر (CORS).

OnBeforeSendHeadersOptions

الإصدار 44 من Chrome أو الإصدارات الأحدث

Enum

"requestHeaders"
يحدد هذا الخيار أنه يجب تضمين عنوان الطلب في الحدث.

"blocking"
يحدد هذا الخيار حظر الطلب إلى أن تعود دالة الاستدعاء.

"extraHeaders"
يحدد هذا العمود أنّ العناوين يمكن أن تنتهك مشاركة الموارد المتعدّدة المصادر (CORS).

OnCompletedOptions

الإصدار 44 من Chrome أو الإصدارات الأحدث

Enum

"responseHeaders"
يحدد هذا الحقل أنه يجب تضمين عناوين الاستجابة في الحدث.

"extraHeaders"
يحدد هذا العمود أنّ العناوين يمكن أن تنتهك مشاركة الموارد المتعدّدة المصادر (CORS).

OnErrorOccurredOptions

الإصدار 79 من Chrome أو الإصدارات الأحدث

القيمة

"extraHeaders"

OnHeadersReceivedOptions

الإصدار 44 من Chrome أو الإصدارات الأحدث

Enum

"blocking"
يحدد هذا الخيار حظر الطلب إلى أن تعود دالة الاستدعاء.

"responseHeaders"
يحدد هذا الحقل أنه يجب تضمين عناوين الاستجابة في الحدث.

"extraHeaders"
يحدد هذا العمود أنّ العناوين يمكن أن تنتهك مشاركة الموارد المتعدّدة المصادر (CORS).

OnResponseStartedOptions

الإصدار 44 من Chrome أو الإصدارات الأحدث

Enum

"responseHeaders"
يحدد هذا الحقل أنه يجب تضمين عناوين الاستجابة في الحدث.

"extraHeaders"
يحدد هذا العمود أنّ العناوين يمكن أن تنتهك مشاركة الموارد المتعدّدة المصادر (CORS).

OnSendHeadersOptions

الإصدار 44 من Chrome أو الإصدارات الأحدث

Enum

"requestHeaders"
يحدد هذا الخيار أنه يجب تضمين عنوان الطلب في الحدث.

"extraHeaders"
يحدد هذا العمود أنّ العناوين يمكن أن تنتهك مشاركة الموارد المتعدّدة المصادر (CORS).

RequestFilter

كائن يصف الفلاتر لتطبيقه على أحداث webRequest.

أماكن إقامة

tabId

الرقم اختياري
الأنواع

ResourceType[] اختياري

قائمة بأنواع الطلبات. وسيتم استبعاد الطلبات التي لا يمكن أن تتطابق مع أي نوع من الأنواع.
عناوين url

سلسلة[]

قائمة بعناوين URL أو أنماط عناوين URL. وسيتم استبعاد الطلبات التي لا تتطابق مع أي من عناوين URL.
windowId

الرقم اختياري

ResourceType

الإصدار 44 من Chrome أو الإصدارات الأحدث

Enum

"main_frame"
يحدد المورد باعتباره الإطار الرئيسي.

"sub_frame"
يحدد المورد كإطار فرعي.

"ورقة الأنماط"
تحديد المورد كورقة أنماط.

"script"
يحدد المورد كنص برمجي.

"image"
تحديد المورد كصورة.

"font"
يحدد المورد كخط.

"object"
تحديد المورد ككائن.

"xmlhttprequest"
يحدد المورد على أنه XMLHttpRequest.

"ping"
يحدد المورد كملف فحص الاتصال.

"csp_report"
يحدد المورد كتقرير سياسة أمان المحتوى (CSP).

"media"
يحدد المورد ككائن وسائط.

"websocket"
يحدد المصدر كWebSocket.

"webbundle"
تحديد المورد على أنه WebBundle.

"other"
يحدد المصدر كنوع غير مضمن في الأنواع المدرجة.

UploadData

يحتوي على بيانات تم تحميلها في طلب عنوان URL.

أماكن إقامة

بايت

أي خيار اختياري

ArrayBuffer مع نسخة من البيانات
ملف

سلسلة اختيارية

سلسلة تحتوي على مسار الملف واسمه.

أماكن إقامة

MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES

الحد الأقصى لعدد المرات التي يمكن فيها استدعاء الدالة handlerBehaviorChanged كل فاصل زمني مستدام مدته 10 دقائق. handlerBehaviorChanged هو استدعاء دالة مكلف ولا ينبغي استدعاؤه كثيرًا.

القيمة

الطُرق

handlerBehaviorChanged()

وعود

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

يجب طلب هذه البيانات عند تغيير سلوك معالِجات webRequest لمنع المعالجة غير الصحيحة بسبب التخزين المؤقت. استدعاء هذه الدالة مكلف. لا تتصل به كثيرًا.

المعلمات

رد الاتصال

الدالة اختيارية

تظهر المَعلمة callback على النحو التالي:
```
() => void
```

المرتجعات

وعود <باطلة>

الإصدار 116 من Chrome أو الإصدارات الأحدث

لا تتوفّر الوعود إلا مع إصدار Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.

فعاليات

onActionIgnored

الإصدار 70 من Chrome أو الإصدارات الأحدث

chrome.webRequest.onActionIgnored.addListener(
  callback: function,
)

يتم إطلاقه عند تجاهل تعديل الإضافة المقترح لطلب الشبكة. ويحدث ذلك في حال حدوث تعارض مع إضافات أخرى.

المعلمات

رد الاتصال

دالة

تظهر المَعلمة callback على النحو التالي:
```
(details: object) => void
```
- التفاصيل
  
  كائن
  - إجراء
    
    IgnoredActionType
    
    الإجراء المقترَح الذي تم تجاهله.
  - requestId
    
    سلسلة
    
    رقم تعريف الطلب. تكون معرّفات الطلبات فريدة ضمن جلسة متصفّح. ونتيجة لذلك، يمكن استخدامها لربط أحداث مختلفة للطلب نفسه.

onAuthRequired

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

يتم الإطلاق عند تلقّي خطأ في المصادقة. ويكون لدى المستمع ثلاثة خيارات: يمكنه تقديم بيانات اعتماد المصادقة أو إلغاء الطلب وعرض صفحة الخطأ أو عدم اتخاذ أي إجراء بشأن اختبار التحقّق. في حال تقديم بيانات اعتماد غير صالحة للمستخدم، قد يتم طلب ذلك عدة مرات للطلب نفسه. تجدر الإشارة إلى أنّه يجب تحديد وضع واحد فقط من وضعَي 'blocking' أو 'asyncBlocking' في المَعلمة extraInfoSpec.

المعلمات

رد الاتصال

دالة

تظهر المَعلمة callback على النحو التالي:
```
(details: object, asyncCallback?: function) => BlockingResponse | undefined
```
- التفاصيل
  
  كائن
  - 1، 2، 3 اجمُد
    
    كائن
    
    الخادم الذي يطلب المصادقة.
    
    مضيف
    
    سلسلة
    
    المنفذ
    
    الرقم
  - documentId
    
    سلسلة
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    المعرّف الفريد العالمي للمستند الذي يقدّم الطلب.
  - documentLifecycle
    
    extensionTypes.DocumentLifecycle
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    دورة النشاط التي يكون فيها المستند
  - frameId
    
    الرقم
    
    تشير القيمة 0 إلى أن الطلب يحدث في الإطار الرئيسي؛ تشير القيمة الموجبة إلى معرف الإطار الفرعي الذي يحدث فيه الطلب. في حال تحميل مستند الإطار (الفرعي) (القيمة type هي main_frame أو sub_frame)، تشير القيمة frameId إلى معرّف هذا الإطار، وليس رقم تعريف الإطار الخارجي. تكون معرفات الإطارات فريدة داخل علامة تبويب.
  - frameType
    
    extensionTypes.FrameType
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    نوع الإطار الذي تم إدخال الطلب فيه.
  - بادئ التشغيل
    
    سلسلة اختيارية
    
    الإصدار 63 من Chrome أو الإصدارات الأحدث
    
    المصدر الذي تم فيه تقديم الطلب. ولا يتغيّر ذلك عند إجراء عمليات إعادة التوجيه. إذا كان هذا مصدرًا مبهمًا، ستظهر السلسلة "null" تنبؤي.
  - isProxy
    
    منطقي
    
    True لمصادقة الخادم الوكيل، وخطأ لـ WWW-Authenticate.
  - method
    
    سلسلة
    
    طريقة HTTP العادية
  - parentDocumentId
    
    سلسلة اختيارية
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    المعرّف الفريد العالمي للمستند الرئيسي الذي يملك هذا الإطار. ولا يتم ضبط ذلك إذا لم يكن هناك عنصر رئيسي.
  - parentFrameId
    
    الرقم
    
    رقم تعريف الإطار الذي يلتف حول الإطار الذي أرسل الطلب. اضبط القيمة على -1 في حال عدم توفّر إطار رئيسي.
  - النطاق
    
    سلسلة اختيارية
    
    نطاق المصادقة الذي يوفره الخادم، إن وجد.
  - requestId
    
    سلسلة
    
    رقم تعريف الطلب. تكون معرّفات الطلبات فريدة ضمن جلسة متصفّح. ونتيجة لذلك، يمكن استخدامها لربط أحداث مختلفة للطلب نفسه.
  - responseHeaders
    
    HttpHeaders اختيارية
    
    عناوين استجابة HTTP التي تم تلقّيها مع هذه الاستجابة
  - المخطط
    
    سلسلة
    
    مخطط المصادقة، مثل "أساسي" أو "ملخّص"
  - statusCode
    
    الرقم
    
    الإصدار 43 من Chrome أو الإصدارات الأحدث
    
    رمز حالة HTTP العادي الذي يعرضه الخادم.
  - statusLine
    
    سلسلة
    
    سطر حالة HTTP للاستجابة أو "HTTP/0.9 200 OK" سلسلة لاستجابات HTTP/0.9 (أي الاستجابات التي تفتقر إلى سطر الحالة) أو سلسلة فارغة إذا لم تكن هناك عناوين
  - tabId
    
    الرقم
    
    رقم تعريف علامة التبويب التي يحدث فيها الطلب. اضبط القيمة على -1 إذا لم يكن الطلب مرتبطًا بعلامة تبويب.
  - timeStamp
    
    الرقم
    
    الوقت الذي يتم فيه تشغيل هذه الإشارة، بالمللي ثانية منذ تاريخ بدء حساب الفترة
  - كتابة
    
    ResourceType
    
    كيفية استخدام المورد المطلوب.
  - url
    
    سلسلة
- asyncCallback
  
  الدالة اختيارية
  
  الإصدار 58 من Chrome أو الإصدارات الأحدث
  
  تظهر المَعلمة asyncCallback على النحو التالي:
```
(response: BlockingResponse) => void
```
  - رد
    
    BlockingResponse
- returns
  BlockingResponse | غير محدّدة
  
  في حال إجراء "الحظر" في "extraInfoSpec" ، يجب أن يعرض مستمع الحدث كائنًا من هذا النوع.
تصفية

RequestFilter
extraInfoSpec

OnAuthRequiredOptions[] اختيارية

onBeforeRedirect

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

يتم إطلاقها عندما تكون عملية إعادة التوجيه التي بدأها الخادم على وشك حدوثها.

المعلمات

رد الاتصال

دالة

تظهر المَعلمة callback على النحو التالي:
```
(details: object) => void
```
- التفاصيل
  
  كائن
  - documentId
    
    سلسلة
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    المعرّف الفريد العالمي للمستند الذي يقدّم الطلب.
  - documentLifecycle
    
    extensionTypes.DocumentLifecycle
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    دورة الحياة التي يكون فيها المستند
  - frameId
    
    الرقم
    
    تشير القيمة 0 إلى أن الطلب يحدث في الإطار الرئيسي؛ تشير القيمة الموجبة إلى معرف الإطار الفرعي الذي يحدث فيه الطلب. في حال تحميل مستند الإطار (الفرعي) (القيمة type هي main_frame أو sub_frame)، تشير القيمة frameId إلى معرّف هذا الإطار، وليس رقم تعريف الإطار الخارجي. تكون معرفات الإطارات فريدة داخل علامة تبويب.
  - frameType
    
    extensionTypes.FrameType
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    نوع الإطار الذي تم إدخال الطلب فيه.
  - fromCache
    
    منطقي
    
    يشير هذا الحقل إلى ما إذا تم جلب هذه الاستجابة من ذاكرة التخزين المؤقت على القرص.
  - بادئ التشغيل
    
    سلسلة اختيارية
    
    الإصدار 63 من Chrome أو الإصدارات الأحدث
    
    المصدر الذي تم فيه تقديم الطلب. ولا يتغيّر ذلك عند إجراء عمليات إعادة التوجيه. إذا كان هذا مصدرًا مبهمًا، ستظهر السلسلة "null" تنبؤي.
  - ip
    
    سلسلة اختيارية
    
    عنوان IP للخادم الذي تم إرسال الطلب إليه فعلاً. لاحظ أنه قد يكون عنوان IPv6 حرفيًا.
  - method
    
    سلسلة
    
    طريقة HTTP العادية
  - parentDocumentId
    
    سلسلة اختيارية
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    المعرّف الفريد العالمي للمستند الرئيسي الذي يملك هذا الإطار. ولا يتم ضبط ذلك إذا لم يكن هناك عنصر رئيسي.
  - parentFrameId
    
    الرقم
    
    رقم تعريف الإطار الذي يلتف حول الإطار الذي أرسل الطلب. اضبط القيمة على -1 في حال عدم توفّر إطار رئيسي.
  - redirectUrl
    
    سلسلة
    
    عنوان URL الجديد.
  - requestId
    
    سلسلة
    
    رقم تعريف الطلب. تكون معرّفات الطلبات فريدة ضمن جلسة متصفّح. ونتيجة لذلك، يمكن استخدامها لربط أحداث مختلفة للطلب نفسه.
  - responseHeaders
    
    HttpHeaders اختيارية
    
    عناوين استجابة HTTP التي تم تلقّيها مع إعادة التوجيه هذه.
  - statusCode
    
    الرقم
    
    رمز حالة HTTP العادي الذي يعرضه الخادم.
  - statusLine
    
    سلسلة
    
    سطر حالة HTTP للاستجابة أو "HTTP/0.9 200 OK" سلسلة لاستجابات HTTP/0.9 (أي الاستجابات التي تفتقر إلى سطر الحالة) أو سلسلة فارغة إذا لم تكن هناك عناوين
  - tabId
    
    الرقم
    
    رقم تعريف علامة التبويب التي يحدث فيها الطلب. اضبط القيمة على -1 إذا لم يكن الطلب مرتبطًا بعلامة تبويب.
  - timeStamp
    
    الرقم
    
    الوقت الذي يتم فيه تشغيل هذه الإشارة، بالمللي ثانية منذ تاريخ بدء حساب الفترة
  - كتابة
    
    ResourceType
    
    كيفية استخدام المورد المطلوب.
  - url
    
    سلسلة
تصفية

RequestFilter
extraInfoSpec

OnBeforeRedirectOptions[] اختياري

onBeforeRequest

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

يتم تنشيطها عندما يكون الطلب على وشك الحدوث.

المعلمات

رد الاتصال

دالة

تظهر المَعلمة callback على النحو التالي:
```
(details: object) => BlockingResponse | undefined
```
- التفاصيل
  
  كائن
  - documentId
    
    سلسلة اختيارية
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    المعرّف الفريد العالمي للمستند الذي يقدّم الطلب.
  - documentLifecycle
    
    extensionTypes.DocumentLifecycle optional
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    دورة الحياة التي يكون فيها المستند
  - frameId
    
    الرقم
    
    تشير القيمة 0 إلى أن الطلب يحدث في الإطار الرئيسي؛ تشير القيمة الموجبة إلى معرف الإطار الفرعي الذي يحدث فيه الطلب. في حال تحميل مستند الإطار (الفرعي) (القيمة type هي main_frame أو sub_frame)، تشير القيمة frameId إلى معرّف هذا الإطار، وليس رقم تعريف الإطار الخارجي. تكون معرفات الإطارات فريدة داخل علامة تبويب.
  - frameType
    
    extensionTypes.FrameType optional
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    نوع الإطار الذي تم إدخال الطلب فيه.
  - بادئ التشغيل
    
    سلسلة اختيارية
    
    الإصدار 63 من Chrome أو الإصدارات الأحدث
    
    المصدر الذي تم فيه تقديم الطلب. ولا يتغيّر ذلك عند إجراء عمليات إعادة التوجيه. إذا كان هذا مصدرًا مبهمًا، ستظهر السلسلة "null" تنبؤي.
  - method
    
    سلسلة
    
    طريقة HTTP العادية
  - parentDocumentId
    
    سلسلة اختيارية
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    المعرّف الفريد العالمي للمستند الرئيسي الذي يملك هذا الإطار. ولا يتم ضبط ذلك إذا لم يكن هناك عنصر رئيسي.
  - parentFrameId
    
    الرقم
    
    رقم تعريف الإطار الذي يلتف حول الإطار الذي أرسل الطلب. اضبط القيمة على -1 في حال عدم توفّر إطار رئيسي.
  - requestBody
    
    الكائن اختياري
    
    يحتوي على بيانات نص طلب HTTP. لا يتم تقديمه إلا إذا احتوت ExtraInfoSpec على "requestBody".
    
    خطأ
    
    سلسلة اختيارية
    
    حدثت أخطاء عند الحصول على بيانات نص الطلب.
    
    formData
    
    الكائن اختياري
    
    إذا كانت طريقة الطلب هي POST وكان النص الأساسي عبارة عن سلسلة من أزواج المفتاح/القيمة تم ترميزها بترميز UTF8، حيث تم ترميزها إما على هيئة Multipart/form-data أو application/x-www-form-urlencrypt، يكون هذا القاموس متوفرًا ولكل مفتاح يحتوي على قائمة بجميع القيم لهذا المفتاح. إذا كانت البيانات من نوع وسائط آخر، أو إذا كانت مكتوبة بشكل غير صحيح، فإن القاموس غير موجود. مثال على قيمة هذا القاموس هي {'key': ['value1', 'value2']}.
    
    خام
    
    UploadData[] اختيارية
    
    إذا كانت طريقة الطلب هي PUT أو POST، ولم يتم تحليل النص الأساسي في formData، سيتم تضمين عناصر نص الطلب التي لم يتم تحليلها في هذا الصفيف.
  - requestId
    
    سلسلة
    
    رقم تعريف الطلب. تكون معرّفات الطلبات فريدة ضمن جلسة متصفّح. ونتيجة لذلك، يمكن استخدامها لربط أحداث مختلفة للطلب نفسه.
  - tabId
    
    الرقم
    
    رقم تعريف علامة التبويب التي يحدث فيها الطلب. اضبط القيمة على -1 إذا لم يكن الطلب مرتبطًا بعلامة تبويب.
  - timeStamp
    
    الرقم
    
    الوقت الذي يتم فيه تشغيل هذه الإشارة، بالمللي ثانية منذ تاريخ بدء حساب الفترة
  - كتابة
    
    ResourceType
    
    كيفية استخدام المورد المطلوب.
  - url
    
    سلسلة
- returns
  BlockingResponse | غير محدّدة
  
  في حال إجراء "الحظر" في "extraInfoSpec" ، يجب أن يعرض مستمع الحدث كائنًا من هذا النوع.
تصفية

RequestFilter
extraInfoSpec

OnBeforeRequestOptions[] اختياري

onBeforeSendHeaders

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

يتم تنشيطها قبل إرسال طلب HTTP، بعد توفُّر عناوين الطلبات. قد يحدث هذا بعد إجراء اتصال TCP للخادم، ولكن قبل إرسال أي بيانات HTTP.

المعلمات

رد الاتصال

دالة

تظهر المَعلمة callback على النحو التالي:
```
(details: object) => BlockingResponse | undefined
```
- التفاصيل
  
  كائن
  - documentId
    
    سلسلة
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    المعرّف الفريد العالمي للمستند الذي يقدّم الطلب.
  - documentLifecycle
    
    extensionTypes.DocumentLifecycle
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    دورة الحياة التي يكون فيها المستند
  - frameId
    
    الرقم
    
    تشير القيمة 0 إلى أن الطلب يحدث في الإطار الرئيسي؛ تشير القيمة الموجبة إلى معرف الإطار الفرعي الذي يحدث فيه الطلب. في حال تحميل مستند الإطار (الفرعي) (القيمة type هي main_frame أو sub_frame)، تشير القيمة frameId إلى معرّف هذا الإطار، وليس رقم تعريف الإطار الخارجي. تكون معرفات الإطارات فريدة داخل علامة تبويب.
  - frameType
    
    extensionTypes.FrameType
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    نوع الإطار الذي تم إدخال الطلب فيه.
  - بادئ التشغيل
    
    سلسلة اختيارية
    
    الإصدار 63 من Chrome أو الإصدارات الأحدث
    
    المصدر الذي تم فيه تقديم الطلب. ولا يتغيّر ذلك عند إجراء عمليات إعادة التوجيه. إذا كان هذا مصدرًا مبهمًا، ستظهر السلسلة "null" تنبؤي.
  - method
    
    سلسلة
    
    طريقة HTTP العادية
  - parentDocumentId
    
    سلسلة اختيارية
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    المعرّف الفريد العالمي (UUID) للمستند الرئيسي الذي يملك هذا الإطار. ولا يتم ضبط ذلك إذا لم يكن هناك عنصر رئيسي.
  - parentFrameId
    
    الرقم
    
    رقم تعريف الإطار الذي يلتف حول الإطار الذي أرسل الطلب. اضبط القيمة على -1 في حال عدم توفّر إطار رئيسي.
  - requestHeaders
    
    HttpHeaders اختيارية
    
    عناوين طلبات HTTP التي سيتم إرسالها مع هذا الطلب.
  - requestId
    
    سلسلة
    
    رقم تعريف الطلب. تكون معرّفات الطلبات فريدة ضمن جلسة متصفّح. ونتيجة لذلك، يمكن استخدامها لربط أحداث مختلفة للطلب نفسه.
  - tabId
    
    الرقم
    
    رقم تعريف علامة التبويب التي يحدث فيها الطلب. اضبط القيمة على -1 إذا لم يكن الطلب مرتبطًا بعلامة تبويب.
  - timeStamp
    
    الرقم
    
    الوقت الذي يتم فيه تشغيل هذه الإشارة، بالمللي ثانية منذ تاريخ بدء حساب الفترة
  - كتابة
    
    ResourceType
    
    كيفية استخدام المورد المطلوب.
  - url
    
    سلسلة
- returns
  BlockingResponse | غير محدّدة
  
  في حال إجراء "الحظر" في "extraInfoSpec" ، يجب أن يعرض مستمع الحدث كائنًا من هذا النوع.
تصفية

RequestFilter
extraInfoSpec

OnBeforeSendHeadersOptions[] اختياري

onCompleted

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

يتم الإطلاق عند اكتمال طلب.

المعلمات

رد الاتصال

دالة

تظهر المَعلمة callback على النحو التالي:
```
(details: object) => void
```
- التفاصيل
  
  كائن
  - documentId
    
    سلسلة
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    المعرّف الفريد العالمي للمستند الذي يقدّم الطلب.
  - documentLifecycle
    
    extensionTypes.DocumentLifecycle
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    دورة الحياة التي يكون فيها المستند
  - frameId
    
    الرقم
    
    تشير القيمة 0 إلى أن الطلب يحدث في الإطار الرئيسي؛ تشير القيمة الموجبة إلى معرف الإطار الفرعي الذي يحدث فيه الطلب. في حال تحميل مستند الإطار (الفرعي) (القيمة type هي main_frame أو sub_frame)، تشير القيمة frameId إلى معرّف هذا الإطار، وليس رقم تعريف الإطار الخارجي. تكون معرفات الإطارات فريدة داخل علامة تبويب.
  - frameType
    
    extensionTypes.FrameType
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    نوع الإطار الذي تم إدخال الطلب فيه.
  - fromCache
    
    منطقي
    
    يشير هذا الحقل إلى ما إذا تم جلب هذه الاستجابة من ذاكرة التخزين المؤقت على القرص.
  - بادئ التشغيل
    
    سلسلة اختيارية
    
    الإصدار 63 من Chrome أو الإصدارات الأحدث
    
    المصدر الذي تم فيه تقديم الطلب. ولا يتغيّر ذلك عند إجراء عمليات إعادة التوجيه. إذا كان هذا مصدرًا مبهمًا، ستظهر السلسلة "null" تنبؤي.
  - ip
    
    سلسلة اختيارية
    
    عنوان IP للخادم الذي تم إرسال الطلب إليه فعلاً. لاحظ أنه قد يكون عنوان IPv6 حرفيًا.
  - method
    
    سلسلة
    
    طريقة HTTP العادية
  - parentDocumentId
    
    سلسلة اختيارية
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    المعرّف الفريد العالمي للمستند الرئيسي الذي يملك هذا الإطار. ولا يتم ضبط ذلك إذا لم يكن هناك عنصر رئيسي.
  - parentFrameId
    
    الرقم
    
    رقم تعريف الإطار الذي يلتف حول الإطار الذي أرسل الطلب. اضبط القيمة على -1 في حال عدم توفّر إطار رئيسي.
  - requestId
    
    سلسلة
    
    رقم تعريف الطلب. تكون معرّفات الطلبات فريدة ضمن جلسة متصفّح. ونتيجة لذلك، يمكن استخدامها لربط أحداث مختلفة للطلب نفسه.
  - responseHeaders
    
    HttpHeaders اختيارية
    
    عناوين استجابة HTTP التي تم تلقّيها مع هذه الاستجابة
  - statusCode
    
    الرقم
    
    رمز حالة HTTP العادي الذي يعرضه الخادم.
  - statusLine
    
    سلسلة
    
    سطر حالة HTTP للاستجابة أو "HTTP/0.9 200 OK" سلسلة لاستجابات HTTP/0.9 (أي الاستجابات التي تفتقر إلى سطر الحالة) أو سلسلة فارغة إذا لم تكن هناك عناوين
  - tabId
    
    الرقم
    
    رقم تعريف علامة التبويب التي يحدث فيها الطلب. اضبط القيمة على -1 إذا لم يكن الطلب مرتبطًا بعلامة تبويب.
  - timeStamp
    
    الرقم
    
    الوقت الذي يتم فيه تشغيل هذه الإشارة، بالمللي ثانية منذ تاريخ بدء حساب الفترة
  - كتابة
    
    ResourceType
    
    كيفية استخدام المورد المطلوب.
  - url
    
    سلسلة
تصفية

RequestFilter
extraInfoSpec

OnCompletedOptions[] اختياري

onErrorOccurred

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

يتم الإطلاق عند حدوث خطأ.

المعلمات

رد الاتصال

دالة

تظهر المَعلمة callback على النحو التالي:
```
(details: object) => void
```
- التفاصيل
  
  كائن
  - documentId
    
    سلسلة
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    المعرّف الفريد العالمي للمستند الذي يقدّم الطلب. ولا تكون هذه القيمة متوفّرة إذا كان الطلب عبارة عن تنقُّل في إطار.
  - documentLifecycle
    
    extensionTypes.DocumentLifecycle
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    دورة الحياة التي يكون فيها المستند
  - خطأ
    
    سلسلة
    
    وصف الخطأ. لا يمكن ضمان بقاء هذه السلسلة متوافقة مع الإصدارات القديمة. لا يجوز لك تحليل المحتوى واتخاذ إجراء بناءً عليه.
  - frameId
    
    الرقم
    
    تشير القيمة 0 إلى أن الطلب يحدث في الإطار الرئيسي؛ تشير القيمة الموجبة إلى معرف الإطار الفرعي الذي يحدث فيه الطلب. في حال تحميل مستند الإطار (الفرعي) (القيمة type هي main_frame أو sub_frame)، تشير القيمة frameId إلى معرّف هذا الإطار، وليس رقم تعريف الإطار الخارجي. تكون معرفات الإطارات فريدة داخل علامة تبويب.
  - frameType
    
    extensionTypes.FrameType
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    نوع الإطار الذي تم إدخال الطلب فيه.
  - fromCache
    
    منطقي
    
    يشير هذا الحقل إلى ما إذا تم جلب هذه الاستجابة من ذاكرة التخزين المؤقت على القرص.
  - بادئ التشغيل
    
    سلسلة اختيارية
    
    الإصدار 63 من Chrome أو الإصدارات الأحدث
    
    المصدر الذي تم فيه تقديم الطلب. ولا يتغيّر ذلك عند إجراء عمليات إعادة التوجيه. إذا كان هذا مصدرًا مبهمًا، ستظهر السلسلة "null" تنبؤي.
  - ip
    
    سلسلة اختيارية
    
    عنوان IP للخادم الذي تم إرسال الطلب إليه فعلاً. لاحظ أنه قد يكون عنوان IPv6 حرفيًا.
  - method
    
    سلسلة
    
    طريقة HTTP العادية
  - parentDocumentId
    
    سلسلة اختيارية
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    المعرّف الفريد العالمي للمستند الرئيسي الذي يملك هذا الإطار. ولا يتم ضبط ذلك إذا لم يكن هناك عنصر رئيسي.
  - parentFrameId
    
    الرقم
    
    رقم تعريف الإطار الذي يلتف حول الإطار الذي أرسل الطلب. اضبط القيمة على -1 في حال عدم توفّر إطار رئيسي.
  - requestId
    
    سلسلة
    
    رقم تعريف الطلب. تكون معرّفات الطلبات فريدة ضمن جلسة متصفّح. ونتيجة لذلك، يمكن استخدامها لربط أحداث مختلفة للطلب نفسه.
  - tabId
    
    الرقم
    
    رقم تعريف علامة التبويب التي يحدث فيها الطلب. اضبط القيمة على -1 إذا لم يكن الطلب مرتبطًا بعلامة تبويب.
  - timeStamp
    
    الرقم
    
    الوقت الذي يتم فيه تشغيل هذه الإشارة، بالمللي ثانية منذ تاريخ بدء حساب الفترة
  - كتابة
    
    ResourceType
    
    كيفية استخدام المورد المطلوب.
  - url
    
    سلسلة
تصفية

RequestFilter
extraInfoSpec

OnErrorOccurredOptions[] اختياري

onHeadersReceived

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

يتم إطلاقه عند تلقّي عناوين استجابة HTTP لأحد الطلبات.

المعلمات

رد الاتصال

دالة

تظهر المَعلمة callback على النحو التالي:
```
(details: object) => BlockingResponse | undefined
```
- التفاصيل
  
  كائن
  - documentId
    
    سلسلة
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    المعرّف الفريد العالمي للمستند الذي يقدّم الطلب.
  - documentLifecycle
    
    extensionTypes.DocumentLifecycle
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    دورة الحياة التي يكون فيها المستند
  - frameId
    
    الرقم
    
    تشير القيمة 0 إلى أن الطلب يحدث في الإطار الرئيسي؛ تشير القيمة الموجبة إلى معرف الإطار الفرعي الذي يحدث فيه الطلب. في حال تحميل مستند الإطار (الفرعي) (القيمة type هي main_frame أو sub_frame)، تشير القيمة frameId إلى معرّف هذا الإطار، وليس رقم تعريف الإطار الخارجي. تكون معرفات الإطارات فريدة داخل علامة تبويب.
  - frameType
    
    extensionTypes.FrameType
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    نوع الإطار الذي تم إدخال الطلب فيه.
  - بادئ التشغيل
    
    سلسلة اختيارية
    
    الإصدار 63 من Chrome أو الإصدارات الأحدث
    
    المصدر الذي تم فيه تقديم الطلب. ولا يتغيّر ذلك عند إجراء عمليات إعادة التوجيه. إذا كان هذا مصدرًا مبهمًا، ستظهر السلسلة "null" تنبؤي.
  - method
    
    سلسلة
    
    طريقة HTTP العادية
  - parentDocumentId
    
    سلسلة اختيارية
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    المعرّف الفريد العالمي للمستند الرئيسي الذي يملك هذا الإطار. ولا يتم ضبط ذلك إذا لم يكن هناك عنصر رئيسي.
  - parentFrameId
    
    الرقم
    
    رقم تعريف الإطار الذي يلتف حول الإطار الذي أرسل الطلب. اضبط القيمة على -1 في حال عدم توفّر إطار رئيسي.
  - requestId
    
    سلسلة
    
    رقم تعريف الطلب. تكون معرّفات الطلبات فريدة ضمن جلسة متصفّح. ونتيجة لذلك، يمكن استخدامها لربط أحداث مختلفة للطلب نفسه.
  - responseHeaders
    
    HttpHeaders اختيارية
    
    عناوين استجابة HTTP التي تم تلقّيها مع هذه الاستجابة
  - statusCode
    
    الرقم
    
    الإصدار 43 من Chrome أو الإصدارات الأحدث
    
    رمز حالة HTTP العادي الذي يعرضه الخادم.
  - statusLine
    
    سلسلة
    
    سطر حالة HTTP للاستجابة أو "HTTP/0.9 200 OK" سلسلة لاستجابات HTTP/0.9 (أي الاستجابات التي تفتقر إلى سطر الحالة).
  - tabId
    
    الرقم
    
    رقم تعريف علامة التبويب التي يحدث فيها الطلب. اضبط القيمة على -1 إذا لم يكن الطلب مرتبطًا بعلامة تبويب.
  - timeStamp
    
    الرقم
    
    الوقت الذي يتم فيه تشغيل هذه الإشارة، بالمللي ثانية منذ تاريخ بدء حساب الفترة
  - كتابة
    
    ResourceType
    
    كيفية استخدام المورد المطلوب.
  - url
    
    سلسلة
- returns
  BlockingResponse | غير محدّدة
  
  في حال إجراء "الحظر" في "extraInfoSpec" ، يجب أن يعرض مستمع الحدث كائنًا من هذا النوع.
تصفية

RequestFilter
extraInfoSpec

OnHeadersReceivedOptions[] اختياري

onResponseStarted

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

يتم إطلاقه عند تلقّي البايت الأول من نص الاستجابة. بالنسبة إلى طلبات HTTP، يعني هذا أنّ سطر الحالة وعناوين الاستجابة متاحان.

المعلمات

رد الاتصال

دالة

تظهر المَعلمة callback على النحو التالي:
```
(details: object) => void
```
- التفاصيل
  
  كائن
  - documentId
    
    سلسلة
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    المعرّف الفريد العالمي للمستند الذي يقدّم الطلب.
  - documentLifecycle
    
    extensionTypes.DocumentLifecycle
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    دورة الحياة التي يكون فيها المستند
  - frameId
    
    الرقم
    
    تشير القيمة 0 إلى أن الطلب يحدث في الإطار الرئيسي؛ تشير القيمة الموجبة إلى معرف الإطار الفرعي الذي يحدث فيه الطلب. في حال تحميل مستند الإطار (الفرعي) (القيمة type هي main_frame أو sub_frame)، تشير القيمة frameId إلى معرّف هذا الإطار، وليس رقم تعريف الإطار الخارجي. تكون معرفات الإطارات فريدة داخل علامة تبويب.
  - frameType
    
    extensionTypes.FrameType
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    نوع الإطار الذي تم إدخال الطلب فيه.
  - fromCache
    
    منطقي
    
    يشير هذا الحقل إلى ما إذا تم جلب هذه الاستجابة من ذاكرة التخزين المؤقت على القرص.
  - بادئ التشغيل
    
    سلسلة اختيارية
    
    الإصدار 63 من Chrome أو الإصدارات الأحدث
    
    المصدر الذي تم فيه تقديم الطلب. ولا يتغيّر ذلك عند إجراء عمليات إعادة التوجيه. إذا كان هذا مصدرًا مبهمًا، ستظهر السلسلة "null" تنبؤي.
  - ip
    
    سلسلة اختيارية
    
    عنوان IP للخادم الذي تم إرسال الطلب إليه فعلاً. لاحظ أنه قد يكون عنوان IPv6 حرفيًا.
  - method
    
    سلسلة
    
    طريقة HTTP العادية
  - parentDocumentId
    
    سلسلة اختيارية
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    المعرّف الفريد العالمي للمستند الرئيسي الذي يملك هذا الإطار. ولا يتم ضبط ذلك إذا لم يكن هناك عنصر رئيسي.
  - parentFrameId
    
    الرقم
    
    رقم تعريف الإطار الذي يلتف حول الإطار الذي أرسل الطلب. اضبط القيمة على -1 في حال عدم توفّر إطار رئيسي.
  - requestId
    
    سلسلة
    
    رقم تعريف الطلب. تكون معرّفات الطلبات فريدة ضمن جلسة متصفّح. ونتيجة لذلك، يمكن استخدامها لربط أحداث مختلفة للطلب نفسه.
  - responseHeaders
    
    HttpHeaders اختيارية
    
    عناوين استجابة HTTP التي تم تلقّيها مع هذه الاستجابة
  - statusCode
    
    الرقم
    
    رمز حالة HTTP العادي الذي يعرضه الخادم.
  - statusLine
    
    سلسلة
    
    سطر حالة HTTP للاستجابة أو "HTTP/0.9 200 OK" سلسلة لاستجابات HTTP/0.9 (أي الاستجابات التي تفتقر إلى سطر الحالة) أو سلسلة فارغة إذا لم تكن هناك عناوين
  - tabId
    
    الرقم
    
    رقم تعريف علامة التبويب التي يحدث فيها الطلب. اضبط القيمة على -1 إذا لم يكن الطلب مرتبطًا بعلامة تبويب.
  - timeStamp
    
    الرقم
    
    الوقت الذي يتم فيه تشغيل هذه الإشارة، بالمللي ثانية منذ تاريخ بدء حساب الفترة
  - كتابة
    
    ResourceType
    
    كيفية استخدام المورد المطلوب.
  - url
    
    سلسلة
تصفية

RequestFilter
extraInfoSpec

OnResponseStartedOptions[] اختياري

onSendHeaders

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

يتم تنشيطها قبل إرسال طلب إلى الخادم مباشرةً (تكون تعديلات استدعاءات onBeforeSendHeaders السابقة مرئية عند تنشيط onSendHeaders).

المعلمات

رد الاتصال

دالة

تظهر المَعلمة callback على النحو التالي:
```
(details: object) => void
```
- التفاصيل
  
  كائن
  - documentId
    
    سلسلة
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    المعرّف الفريد العالمي للمستند الذي يقدّم الطلب.
  - documentLifecycle
    
    extensionTypes.DocumentLifecycle
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    دورة الحياة التي يكون فيها المستند
  - frameId
    
    الرقم
    
    تشير القيمة 0 إلى أن الطلب يحدث في الإطار الرئيسي؛ تشير القيمة الموجبة إلى معرف الإطار الفرعي الذي يحدث فيه الطلب. في حال تحميل مستند الإطار (الفرعي) (القيمة type هي main_frame أو sub_frame)، تشير القيمة frameId إلى معرّف هذا الإطار، وليس رقم تعريف الإطار الخارجي. تكون معرفات الإطارات فريدة داخل علامة تبويب.
  - frameType
    
    extensionTypes.FrameType
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    نوع الإطار الذي تم إدخال الطلب فيه.
  - بادئ التشغيل
    
    سلسلة اختيارية
    
    الإصدار 63 من Chrome أو الإصدارات الأحدث
    
    المصدر الذي تم فيه تقديم الطلب. ولا يتغيّر ذلك عند إجراء عمليات إعادة التوجيه. إذا كان هذا مصدرًا مبهمًا، ستظهر السلسلة "null" تنبؤي.
  - method
    
    سلسلة
    
    طريقة HTTP العادية
  - parentDocumentId
    
    سلسلة اختيارية
    
    الإصدار 106 من Chrome أو الإصدارات الأحدث
    
    المعرّف الفريد العالمي للمستند الرئيسي الذي يملك هذا الإطار. ولا يتم ضبط ذلك إذا لم يكن هناك عنصر رئيسي.
  - parentFrameId
    
    الرقم
    
    رقم تعريف الإطار الذي يلتف حول الإطار الذي أرسل الطلب. اضبط القيمة على -1 في حال عدم توفّر إطار رئيسي.
  - requestHeaders
    
    HttpHeaders اختيارية
    
    عناوين طلبات HTTP التي تم إرسالها مع هذا الطلب.
  - requestId
    
    سلسلة
    
    رقم تعريف الطلب. تكون معرّفات الطلبات فريدة ضمن جلسة متصفّح. ونتيجة لذلك، يمكن استخدامها لربط أحداث مختلفة للطلب نفسه.
  - tabId
    
    الرقم
    
    رقم تعريف علامة التبويب التي يحدث فيها الطلب. اضبط القيمة على -1 إذا لم يكن الطلب مرتبطًا بعلامة تبويب.
  - timeStamp
    
    الرقم
    
    الوقت الذي يتم فيه تشغيل هذه الإشارة، بالمللي ثانية منذ تاريخ بدء حساب الفترة
  - كتابة
    
    ResourceType
    
    كيفية استخدام المورد المطلوب.
  - url
    
    سلسلة
تصفية

RequestFilter
extraInfoSpec

OnSendHeadersOptions[] اختيارية