chrome.webRequest

الوصف

استخدِم واجهة برمجة التطبيقات chrome.webRequest لمراقبة حركة البيانات وتحليلها، وللتدخّل في الطلبات أثناء نقلها أو حظرها أو تعديلها.

الأذونات

webRequest

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

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

webRequestBlocking

مطلوب لتسجيل معالِجات أحداث الحظر. اعتبارًا من الإصدار Manifest V3، لا يتوفّر هذا الخيار إلا للإضافات المثبَّتة من خلال السياسة.

webRequestAuthProvider

مطلوب لاستخدام طريقة onAuthRequired. اطّلِع على التعامل مع المصادقة.

المفاهيم والاستخدام

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

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

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

دورة حياة طلب بيانات من الويب من منظور WebRequest API

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

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

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

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

  • التفويض
  • Cache-Control
  • الاتصال
  • Content-Length
  • المضيف
  • ‫If-Modified-Since
  • ‫If-None-Match
  • If-Range
  • Partial-Data
  • Pragma
  • Proxy-Authorization
  • Proxy-Connection
  • Transfer-Encoding

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

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

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

  • الأصل

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

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

  • Accept-Language
  • Accept-Encoding
  • المُحيل
  • ملف تعريف الارتباط

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

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

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

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

  • الرسائل الفردية التي يتم إرسالها عبر اتصال WebSocket ثابت
  • جارٍ إغلاق اتصال WebSocket.

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

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

بدءًا من الإصدار 96 من Chrome، تتيح واجهة برمجة التطبيقات webRequest اعتراض طلب المصافحة WebTransport عبر HTTP/3. بما أنّ المصافحة تتم عن طريق طلب HTTP CONNECT، فإنّ تسلسلها يتناسب مع نموذج 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 (مستند يتم تحميله لإطار مضمّن) وimage (صورة على موقع إلكتروني). يمكنك الاطّلاع على webRequest.RequestFilter.
رقم تعريف علامة التبويب
معرّف لعلامة تبويب واحدة
رقم تعريف النافذة
تمثّل هذه السمة معرّفًا لإحدى النوافذ.

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

التعامل مع المصادقة

للتعامل مع طلبات مصادقة HTTP، أضِف الإذن "webRequestAuthProvider" إلى ملف البيان:

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

يُرجى العِلم أنّه لا يلزم الحصول على هذا الإذن لتثبيت إضافة تتضمّن سياسة مع الإذن "webRequestBlocking".

لتوفير بيانات الاعتماد بشكل متزامن، اتّبِع الخطوات التالية:

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

لتوفير بيانات الاعتماد بشكل غير متزامن، اتّبِع الخطوات التالية:

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

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

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

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

يوضّح المثال التالي كيفية حذف عنوان User-Agent من جميع الطلبات:

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

لتجربة واجهة برمجة التطبيقات chrome.webRequest، ثبِّت نموذج webRequest من مستودع chrome-extension-samples.

الأنواع

BlockingResponse

تعرض هذه السمة قيمة لمعالِجات الأحداث التي تم تطبيق extraInfoSpec "الحظر" عليها. يسمح لمعالج الأحداث بتعديل طلبات الشبكة.

الخصائص

  • authCredentials

    العنصر اختياري

    يتم استخدامه فقط كردّ على الحدث onAuthRequired. في حال ضبط هذا الحقل، يتم تقديم الطلب باستخدام بيانات الاعتماد المتوفّرة.

    • كلمة المرور

      سلسلة

    • اسم المستخدم

      سلسلة

  • إلغاء

    boolean اختياري

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

  • redirectUrl

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

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

  • requestHeaders

    HttpHeaders اختيارية

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

  • responseHeaders

    HttpHeaders اختيارية

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

FormDataItem

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

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

Enum

ArrayBuffer

سلسلة

HttpHeaders

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

النوع

object[]

الخصائص

  • binaryValue

    number[] اختيارية

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

  • الاسم

    سلسلة

    اسم عنوان HTTP.

  • القيمة

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

    قيمة عنوان HTTP إذا كان يمكن تمثيله باستخدام UTF-8

IgnoredActionType

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

Enum

"redirect"

"request_headers"

"response_headers"

"auth_credentials"

OnAuthRequiredOptions

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

Enum

"responseHeaders"
تحدّد ما إذا كان يجب تضمين عناوين الاستجابة في الحدث.

"blocking"
تحدّد ما إذا كان سيتم حظر الطلب إلى أن تعرض دالة معاودة الاتصال.

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

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

OnBeforeRedirectOptions

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

Enum

"responseHeaders"
تحدّد ما إذا كان يجب تضمين عناوين الاستجابة في الحدث.

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

OnBeforeRequestOptions

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

Enum

"blocking"
تحدّد ما إذا كان سيتم حظر الطلب إلى أن تعرض دالة معاودة الاتصال.

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

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

OnBeforeSendHeadersOptions

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

Enum

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

"blocking"
تحدّد ما إذا كان سيتم حظر الطلب إلى أن تعرض دالة معاودة الاتصال.

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

OnCompletedOptions

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

Enum

"responseHeaders"
تحدّد ما إذا كان يجب تضمين عناوين الاستجابة في الحدث.

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

OnErrorOccurredOptions

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

القيمة

"extraHeaders"

OnHeadersReceivedOptions

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

Enum

"blocking"
تحدّد ما إذا كان سيتم حظر الطلب إلى أن تعرض دالة معاودة الاتصال.

"responseHeaders"
تحدّد ما إذا كان يجب تضمين عناوين الاستجابة في الحدث.

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

OnResponseStartedOptions

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

Enum

"responseHeaders"
تحدّد ما إذا كان يجب تضمين عناوين الاستجابة في الحدث.

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

OnSendHeadersOptions

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

Enum

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

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

RequestFilter

تمثّل هذه السمة عنصرًا يصف الفلاتر التي سيتم تطبيقها على أحداث webRequest.

الخصائص

  • tabId

    number اختياري

  • الأنواع

    ResourceType[] اختياري

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

  • عناوين url

    string[]

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

  • windowId

    number اختياري

ResourceType

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

Enum

"main_frame"
تحدّد هذه القيمة المورد على أنّه الإطار الرئيسي.

‫"sub_frame"
تحدّد هذه السمة المرجع كمستند مضمّن.

"stylesheet"
تحدّد هذه السمة المورد كجدول أسلوب.

"script"
تحدّد هذه القيمة المورد كنص برمجي.

"image"
تحدّد هذه القيمة المرجع على أنّه صورة.

"font"
تحدّد هذه السمة أنّ المورد هو خط.

"object"
تحدّد هذه السمة المورد ككائن.

"xmlhttprequest"
تحدّد هذه السمة المورد على أنّه XMLHttpRequest.

استبدِل
"ping" لتحديد المرجع كمصدر لطلبات ping.

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

"الوسائط"
تحدّد هذه السمة المورد ككائن وسائط.

"websocket"
تحدّد هذه السمة المورد على أنّه WebSocket.

"webbundle"
تحدّد هذه السمة المورد على أنّه WebBundle.

other
تحدّد هذه القيمة المورد كنوع غير مضمّن في الأنواع المُدرَجة.

UploadData

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

الخصائص

  • بايت

    أي اختياري

    تمثّل هذه السمة ArrayBuffer تحتوي على نسخة من البيانات.

  • ملف

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

    سلسلة تتضمّن مسار الملف واسمه

الخصائص

MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES

الحد الأقصى لعدد المرات التي يمكن فيها استدعاء handlerBehaviorChanged خلال فاصل زمني مستمر مدته 10 دقائق ‫handlerBehaviorChanged هو استدعاء دالة مكلف يجب عدم استخدامه بشكل متكرر.

القيمة

‫20

الطُرق

handlerBehaviorChanged()

chrome.webRequest.handlerBehaviorChanged(): Promise<void>

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

المرتجعات

  • Promise<void>

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

الفعاليات

onActionIgnored

الإصدار 70 من Chrome والإصدارات الأحدث 
chrome.webRequest.onActionIgnored.addListener(
  callback: function,
)

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

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (details: object) => void

    • التفاصيل

      عنصر

      • إجراء

        IgnoredActionType

        الإجراء المقترَح الذي تم تجاهله.

      • requestId

        سلسلة

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

onAuthRequired

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

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

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

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

    • التفاصيل

      عنصر

      • المنافس

        عنصر

        الخادم الذي يطلب المصادقة

        • مضيف

          سلسلة

        • المنفذ

          الرقم

      • documentId

        سلسلة

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

        المعرّف الفريد العالمي (UUID) للمستند الذي يقدّم الطلب

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

        دورة الحياة التي يكون فيها المستند

      • frameId

        الرقم

        تشير القيمة 0 إلى أنّ الطلب يحدث في الإطار الرئيسي، وتشير القيمة الموجبة إلى رقم تعريف إطار فرعي يحدث فيه الطلب. في حال تحميل مستند (إطار فرعي)، أي إذا كانت قيمة type هي main_frame أو sub_frame، يشير frameId إلى معرّف هذا الإطار، وليس معرّف الإطار الخارجي. تكون أرقام تعريف الإطارات فريدة داخل علامة تبويب.

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

        نوع الإطار الذي تم فيه الطلب.

      • بادئ التشغيل

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

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

        المصدر الذي بدأ منه الطلب ولا يتغيّر ذلك من خلال عمليات إعادة التوجيه. إذا كان هذا المصدر غير شفاف، سيتم استخدام السلسلة "null".

      • isProxy

        قيمة منطقية

        القيمة هي True بالنسبة إلى Proxy-Authenticate، وfalse بالنسبة إلى WWW-Authenticate.

      • method

        سلسلة

        طريقة HTTP عادية

      • parentDocumentId

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

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

        المعرّف الفريد العالمي (UUID) للمستند الرئيسي الذي يملك هذا الإطار لا يتم ضبط هذه السمة إذا لم يكن هناك عنصر رئيسي.

      • parentFrameId

        الرقم

        معرّف الإطار الذي يغلّف الإطار الذي أرسل الطلب يتم ضبط القيمة على -1 في حال عدم توفّر إطار رئيسي.

      • realm

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

        نطاق المصادقة الذي يوفّره الخادم، إذا كان متوفّرًا

      • requestId

        سلسلة

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

      • responseHeaders

        HttpHeaders اختيارية

        تمثّل هذه السمة عناوين استجابة HTTP التي تم تلقّيها مع هذه الاستجابة.

      • المخطط

        سلسلة

        نظام المصادقة، مثل Basic أو Digest

      • statusCode

        الرقم

        Chrome 43 والإصدارات الأحدث

        رمز حالة HTTP العادي الذي يعرضه الخادم.

      • statusLine

        سلسلة

        سطر حالة HTTP الخاص بالردّ أو السلسلة "HTTP/0.9 200 OK" للردود التي تستخدم HTTP/0.9 (أي الردود التي لا تتضمّن سطر حالة) أو سلسلة فارغة إذا لم تكن هناك عناوين

      • tabId

        الرقم

        رقم تعريف علامة التبويب التي يتم فيها تنفيذ الطلب اضبط القيمة على -1 إذا لم يكن الطلب مرتبطًا بعلامة تبويب.

      • timeStamp

        الرقم

        الوقت الذي يتم فيه تشغيل هذه الإشارة، بالمللي ثانية منذ بداية الحقبة

      • النوع

        ResourceType

        توضّح هذه السمة طريقة استخدام المورد المطلوب.

      • url

        سلسلة

    • asyncCallback

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

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

      تظهر المَعلمة asyncCallback على النحو التالي: 

      (response: BlockingResponse) => void

    • returns

      BlockingResponse | undefined

      إذا تم تحديد "blocking" في المَعلمة "extraInfoSpec"، يجب أن تعرض أداة معالجة الأحداث عنصرًا من هذا النوع.

  • تصفية

    RequestFilter

  • extraInfoSpec

    OnAuthRequiredOptions[] اختيارية

onBeforeRedirect

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

يتم إطلاق هذا الحدث عندما سيحدث توجيه من الخادم.

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (details: object) => void

    • التفاصيل

      عنصر

      • documentId

        سلسلة

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

        المعرّف الفريد العالمي (UUID) للمستند الذي يقدّم الطلب

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

        دورة الحياة التي يكون فيها المستند

      • frameId

        الرقم

        تشير القيمة 0 إلى أنّ الطلب يحدث في الإطار الرئيسي، وتشير القيمة الموجبة إلى رقم تعريف إطار فرعي يحدث فيه الطلب. في حال تحميل مستند (إطار فرعي)، أي إذا كانت قيمة type هي main_frame أو sub_frame، يشير frameId إلى معرّف هذا الإطار، وليس معرّف الإطار الخارجي. تكون أرقام تعريف الإطارات فريدة داخل علامة تبويب.

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

        نوع الإطار الذي تم فيه الطلب.

      • fromCache

        قيمة منطقية

        تشير إلى ما إذا تم جلب هذه الاستجابة من ذاكرة التخزين المؤقت على القرص.

      • بادئ التشغيل

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

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

        المصدر الذي بدأ منه الطلب ولا يتغيّر ذلك من خلال عمليات إعادة التوجيه. إذا كان هذا المصدر غير شفاف، سيتم استخدام السلسلة "null".

      • ip

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

        عنوان IP للخادم الذي تم إرسال الطلب إليه فعليًا. يُرجى العِلم أنّه قد يكون عنوان IPv6 حرفيًا.

      • method

        سلسلة

        طريقة HTTP عادية

      • parentDocumentId

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

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

        المعرّف الفريد العالمي (UUID) للمستند الرئيسي الذي يملك هذا الإطار لا يتم ضبط هذه السمة إذا لم يكن هناك عنصر رئيسي.

      • parentFrameId

        الرقم

        معرّف الإطار الذي يغلّف الإطار الذي أرسل الطلب يتم ضبط القيمة على -1 في حال عدم توفّر إطار رئيسي.

      • redirectUrl

        سلسلة

        عنوان URL الجديد

      • requestId

        سلسلة

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

      • responseHeaders

        HttpHeaders اختيارية

        عناوين استجابة HTTP التي تم تلقّيها مع عملية إعادة التوجيه هذه

      • statusCode

        الرقم

        رمز حالة HTTP العادي الذي يعرضه الخادم.

      • statusLine

        سلسلة

        سطر حالة HTTP الخاص بالردّ أو السلسلة "HTTP/0.9 200 OK" للردود التي تستخدم HTTP/0.9 (أي الردود التي لا تتضمّن سطر حالة) أو سلسلة فارغة إذا لم تكن هناك عناوين

      • tabId

        الرقم

        رقم تعريف علامة التبويب التي يتم فيها تنفيذ الطلب اضبط القيمة على -1 إذا لم يكن الطلب مرتبطًا بعلامة تبويب.

      • timeStamp

        الرقم

        الوقت الذي يتم فيه تشغيل هذه الإشارة، بالمللي ثانية منذ بداية الحقبة

      • النوع

        ResourceType

        توضّح هذه السمة طريقة استخدام المورد المطلوب.

      • url

        سلسلة

  • تصفية

    RequestFilter

  • extraInfoSpec

    OnBeforeRedirectOptions[] اختياري

onBeforeRequest

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

يتم إطلاقه عندما سيحدث طلب.

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (details: object) => BlockingResponse | undefined

    • التفاصيل

      عنصر

      • documentId

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

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

        المعرّف الفريد العالمي (UUID) للمستند الذي يقدّم الطلب

      • 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 في حال عدم توفّر إطار رئيسي.

      • requestBody

        العنصر اختياري

        يحتوي على بيانات نص طلب HTTP. يتم توفيرها فقط إذا كانت extraInfoSpec تتضمّن "requestBody".

        • خطأ

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

          أخطاء عند الحصول على بيانات نص الطلب

        • formData

          العنصر اختياري

          إذا كانت طريقة الطلب هي POST وكان النص عبارة عن سلسلة من أزواج المفتاح والقيمة بترميز UTF8، أو بترميز multipart/form-data أو application/x-www-form-urlencoded، يكون هذا القاموس متوفّرًا ويحتوي على قائمة بجميع قيم هذا المفتاح لكل مفتاح. إذا كانت البيانات من نوع وسائط آخر أو إذا كانت غير صالحة، لن يكون القاموس متوفّرًا. مثال على قيمة هذا القاموس هو {'key': ['value1', 'value2']}.

        • خام

          ‫UploadData[] اختياري

          إذا كانت طريقة الطلب هي PUT أو POST، ولم يتم تحليل النص الأساسي في formData، فسيتم تضمين عناصر نص الطلب غير المحلَّل في هذه المصفوفة.

      • requestId

        سلسلة

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

      • tabId

        الرقم

        رقم تعريف علامة التبويب التي يتم فيها تنفيذ الطلب اضبط القيمة على -1 إذا لم يكن الطلب مرتبطًا بعلامة تبويب.

      • timeStamp

        الرقم

        الوقت الذي يتم فيه تشغيل هذه الإشارة، بالمللي ثانية منذ بداية الحقبة

      • النوع

        ResourceType

        توضّح هذه السمة طريقة استخدام المورد المطلوب.

      • url

        سلسلة

    • returns

      BlockingResponse | undefined

      إذا تم تحديد "blocking" في المَعلمة "extraInfoSpec"، يجب أن تعرض أداة معالجة الأحداث عنصرًا من هذا النوع.

  • تصفية

    RequestFilter

  • extraInfoSpec

    OnBeforeRequestOptions[] اختيارية

onBeforeSendHeaders

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

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

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (details: object) => BlockingResponse | undefined

    • التفاصيل

      عنصر

      • documentId

        سلسلة

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

        المعرّف الفريد العالمي (UUID) للمستند الذي يقدّم الطلب

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

        دورة الحياة التي يكون فيها المستند

      • frameId

        الرقم

        تشير القيمة 0 إلى أنّ الطلب يحدث في الإطار الرئيسي، وتشير القيمة الموجبة إلى رقم تعريف إطار فرعي يحدث فيه الطلب. في حال تحميل مستند (إطار فرعي)، أي إذا كانت قيمة type هي main_frame أو sub_frame، يشير frameId إلى معرّف هذا الإطار، وليس معرّف الإطار الخارجي. تكون أرقام تعريف الإطارات فريدة داخل علامة تبويب.

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

        نوع الإطار الذي تم فيه الطلب.

      • بادئ التشغيل

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

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

        المصدر الذي بدأ منه الطلب ولا يتغيّر ذلك من خلال عمليات إعادة التوجيه. إذا كان هذا المصدر غير شفاف، سيتم استخدام السلسلة "null".

      • method

        سلسلة

        طريقة HTTP عادية

      • parentDocumentId

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

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

        المعرّف الفريد العالمي (UUID) للمستند الرئيسي الذي يملك هذا الإطار لا يتم ضبط هذه السمة إذا لم يكن هناك عنصر رئيسي.

      • parentFrameId

        الرقم

        معرّف الإطار الذي يغلّف الإطار الذي أرسل الطلب يتم ضبط القيمة على -1 في حال عدم توفّر إطار رئيسي.

      • requestHeaders

        HttpHeaders اختيارية

        عناوين طلبات HTTP التي سيتم إرسالها مع هذا الطلب

      • requestId

        سلسلة

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

      • tabId

        الرقم

        رقم تعريف علامة التبويب التي يتم فيها تنفيذ الطلب اضبط القيمة على -1 إذا لم يكن الطلب مرتبطًا بعلامة تبويب.

      • timeStamp

        الرقم

        الوقت الذي يتم فيه تشغيل هذه الإشارة، بالمللي ثانية منذ بداية الحقبة

      • النوع

        ResourceType

        توضّح هذه السمة طريقة استخدام المورد المطلوب.

      • url

        سلسلة

    • returns

      BlockingResponse | undefined

      إذا تم تحديد "blocking" في المَعلمة "extraInfoSpec"، يجب أن تعرض أداة معالجة الأحداث عنصرًا من هذا النوع.

  • تصفية

    RequestFilter

  • extraInfoSpec

    OnBeforeSendHeadersOptions[] اختياري

onCompleted

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

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

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (details: object) => void

    • التفاصيل

      عنصر

      • documentId

        سلسلة

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

        المعرّف الفريد العالمي (UUID) للمستند الذي يقدّم الطلب

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

        دورة الحياة التي يكون فيها المستند

      • frameId

        الرقم

        تشير القيمة 0 إلى أنّ الطلب يحدث في الإطار الرئيسي، وتشير القيمة الموجبة إلى رقم تعريف إطار فرعي يحدث فيه الطلب. في حال تحميل مستند (إطار فرعي)، أي إذا كانت قيمة type هي main_frame أو sub_frame، يشير frameId إلى معرّف هذا الإطار، وليس معرّف الإطار الخارجي. تكون أرقام تعريف الإطارات فريدة داخل علامة تبويب.

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

        نوع الإطار الذي تم فيه الطلب.

      • fromCache

        قيمة منطقية

        تشير إلى ما إذا تم جلب هذه الاستجابة من ذاكرة التخزين المؤقت على القرص.

      • بادئ التشغيل

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

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

        المصدر الذي بدأ منه الطلب ولا يتغيّر ذلك من خلال عمليات إعادة التوجيه. إذا كان هذا المصدر غير شفاف، سيتم استخدام السلسلة "null".

      • ip

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

        عنوان IP للخادم الذي تم إرسال الطلب إليه فعليًا. يُرجى العِلم أنّه قد يكون عنوان IPv6 حرفيًا.

      • method

        سلسلة

        طريقة HTTP عادية

      • parentDocumentId

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

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

        المعرّف الفريد العالمي (UUID) للمستند الرئيسي الذي يملك هذا الإطار لا يتم ضبط هذه السمة إذا لم يكن هناك عنصر رئيسي.

      • 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

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (details: object) => void

    • التفاصيل

      عنصر

      • documentId

        سلسلة

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

        المعرّف الفريد العالمي (UUID) للمستند الذي يقدّم الطلب لا تتوفّر هذه القيمة إذا كان الطلب عبارة عن عملية تنقّل في إطار.

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

        دورة الحياة التي يكون فيها المستند

      • خطأ

        سلسلة

        وصف الخطأ لا نضمن أن يظل هذا السلسلة متوافقًا مع الإصدارات القديمة بين الإصدارات. يجب عدم تحليل محتوى هذا الملف واتّخاذ إجراءات استنادًا إليه.

      • frameId

        الرقم

        تشير القيمة 0 إلى أنّ الطلب يحدث في الإطار الرئيسي، وتشير القيمة الموجبة إلى رقم تعريف إطار فرعي يحدث فيه الطلب. في حال تحميل مستند (إطار فرعي)، أي إذا كانت قيمة type هي main_frame أو sub_frame، يشير frameId إلى معرّف هذا الإطار، وليس معرّف الإطار الخارجي. تكون أرقام تعريف الإطارات فريدة داخل علامة تبويب.

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

        نوع الإطار الذي تم فيه الطلب.

      • fromCache

        قيمة منطقية

        تشير إلى ما إذا تم جلب هذه الاستجابة من ذاكرة التخزين المؤقت على القرص.

      • بادئ التشغيل

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

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

        المصدر الذي بدأ منه الطلب ولا يتغيّر ذلك من خلال عمليات إعادة التوجيه. إذا كان هذا المصدر غير شفاف، سيتم استخدام السلسلة "null".

      • ip

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

        عنوان IP للخادم الذي تم إرسال الطلب إليه فعليًا. يُرجى العِلم أنّه قد يكون عنوان IPv6 حرفيًا.

      • method

        سلسلة

        طريقة HTTP عادية

      • parentDocumentId

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

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

        المعرّف الفريد العالمي (UUID) للمستند الرئيسي الذي يملك هذا الإطار لا يتم ضبط هذه السمة إذا لم يكن هناك عنصر رئيسي.

      • parentFrameId

        الرقم

        معرّف الإطار الذي يغلّف الإطار الذي أرسل الطلب يتم ضبط القيمة على -1 في حال عدم توفّر إطار رئيسي.

      • requestId

        سلسلة

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

      • tabId

        الرقم

        رقم تعريف علامة التبويب التي يتم فيها تنفيذ الطلب اضبط القيمة على -1 إذا لم يكن الطلب مرتبطًا بعلامة تبويب.

      • timeStamp

        الرقم

        الوقت الذي يتم فيه تشغيل هذه الإشارة، بالمللي ثانية منذ بداية الحقبة

      • النوع

        ResourceType

        توضّح هذه السمة طريقة استخدام المورد المطلوب.

      • url

        سلسلة

  • تصفية

    RequestFilter

  • extraInfoSpec

    OnErrorOccurredOptions[] اختياري

onHeadersReceived

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

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

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (details: object) => BlockingResponse | undefined

    • التفاصيل

      عنصر

      • documentId

        سلسلة

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

        المعرّف الفريد العالمي (UUID) للمستند الذي يقدّم الطلب

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

        دورة الحياة التي يكون فيها المستند

      • frameId

        الرقم

        تشير القيمة 0 إلى أنّ الطلب يحدث في الإطار الرئيسي، وتشير القيمة الموجبة إلى رقم تعريف إطار فرعي يحدث فيه الطلب. في حال تحميل مستند (إطار فرعي)، أي إذا كانت قيمة type هي main_frame أو sub_frame، يشير frameId إلى معرّف هذا الإطار، وليس معرّف الإطار الخارجي. تكون أرقام تعريف الإطارات فريدة داخل علامة تبويب.

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

        نوع الإطار الذي تم فيه الطلب.

      • بادئ التشغيل

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

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

        المصدر الذي بدأ منه الطلب ولا يتغيّر ذلك من خلال عمليات إعادة التوجيه. إذا كان هذا المصدر غير شفاف، سيتم استخدام السلسلة "null".

      • method

        سلسلة

        طريقة HTTP عادية

      • parentDocumentId

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

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

        المعرّف الفريد العالمي (UUID) للمستند الرئيسي الذي يملك هذا الإطار لا يتم ضبط هذه السمة إذا لم يكن هناك عنصر رئيسي.

      • parentFrameId

        الرقم

        معرّف الإطار الذي يغلّف الإطار الذي أرسل الطلب يتم ضبط القيمة على -1 في حال عدم توفّر إطار رئيسي.

      • requestId

        سلسلة

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

      • responseHeaders

        HttpHeaders اختيارية

        تمثّل هذه السمة عناوين استجابة HTTP التي تم تلقّيها مع هذه الاستجابة.

      • statusCode

        الرقم

        Chrome 43 والإصدارات الأحدث

        رمز حالة HTTP العادي الذي يعرضه الخادم.

      • statusLine

        سلسلة

        سطر حالة HTTP للاستجابة أو السلسلة "HTTP/0.9 200 OK" للاستجابات التي تستخدم HTTP/0.9 (أي الاستجابات التي لا تتضمّن سطر حالة)

      • tabId

        الرقم

        رقم تعريف علامة التبويب التي يتم فيها تنفيذ الطلب اضبط القيمة على -1 إذا لم يكن الطلب مرتبطًا بعلامة تبويب.

      • timeStamp

        الرقم

        الوقت الذي يتم فيه تشغيل هذه الإشارة، بالمللي ثانية منذ بداية الحقبة

      • النوع

        ResourceType

        توضّح هذه السمة طريقة استخدام المورد المطلوب.

      • url

        سلسلة

    • returns

      BlockingResponse | undefined

      إذا تم تحديد "blocking" في المَعلمة "extraInfoSpec"، يجب أن تعرض أداة معالجة الأحداث عنصرًا من هذا النوع.

  • تصفية

    RequestFilter

  • extraInfoSpec

    OnHeadersReceivedOptions[] اختياري

onResponseStarted

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

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

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (details: object) => void

    • التفاصيل

      عنصر

      • documentId

        سلسلة

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

        المعرّف الفريد العالمي (UUID) للمستند الذي يقدّم الطلب

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

        دورة الحياة التي يكون فيها المستند

      • frameId

        الرقم

        تشير القيمة 0 إلى أنّ الطلب يحدث في الإطار الرئيسي، وتشير القيمة الموجبة إلى رقم تعريف إطار فرعي يحدث فيه الطلب. في حال تحميل مستند (إطار فرعي)، أي إذا كانت قيمة type هي main_frame أو sub_frame، يشير frameId إلى معرّف هذا الإطار، وليس معرّف الإطار الخارجي. تكون أرقام تعريف الإطارات فريدة داخل علامة تبويب.

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

        نوع الإطار الذي تم فيه الطلب.

      • fromCache

        قيمة منطقية

        تشير إلى ما إذا تم جلب هذه الاستجابة من ذاكرة التخزين المؤقت على القرص.

      • بادئ التشغيل

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

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

        المصدر الذي بدأ منه الطلب ولا يتغيّر ذلك من خلال عمليات إعادة التوجيه. إذا كان هذا المصدر غير شفاف، سيتم استخدام السلسلة "null".

      • ip

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

        عنوان IP للخادم الذي تم إرسال الطلب إليه فعليًا. يُرجى العِلم أنّه قد يكون عنوان IPv6 حرفيًا.

      • method

        سلسلة

        طريقة HTTP عادية

      • parentDocumentId

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

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

        المعرّف الفريد العالمي (UUID) للمستند الرئيسي الذي يملك هذا الإطار لا يتم ضبط هذه السمة إذا لم يكن هناك عنصر رئيسي.

      • 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

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (details: object) => void

    • التفاصيل

      عنصر

      • documentId

        سلسلة

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

        المعرّف الفريد العالمي (UUID) للمستند الذي يقدّم الطلب

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

        دورة الحياة التي يكون فيها المستند

      • frameId

        الرقم

        تشير القيمة 0 إلى أنّ الطلب يحدث في الإطار الرئيسي، وتشير القيمة الموجبة إلى رقم تعريف إطار فرعي يحدث فيه الطلب. في حال تحميل مستند (إطار فرعي)، أي إذا كانت قيمة type هي main_frame أو sub_frame، يشير frameId إلى معرّف هذا الإطار، وليس معرّف الإطار الخارجي. تكون أرقام تعريف الإطارات فريدة داخل علامة تبويب.

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

        نوع الإطار الذي تم فيه الطلب.

      • بادئ التشغيل

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

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

        المصدر الذي بدأ منه الطلب ولا يتغيّر ذلك من خلال عمليات إعادة التوجيه. إذا كان هذا المصدر غير شفاف، سيتم استخدام السلسلة "null".

      • method

        سلسلة

        طريقة HTTP عادية

      • parentDocumentId

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

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

        المعرّف الفريد العالمي (UUID) للمستند الرئيسي الذي يملك هذا الإطار لا يتم ضبط هذه السمة إذا لم يكن هناك عنصر رئيسي.

      • parentFrameId

        الرقم

        معرّف الإطار الذي يغلّف الإطار الذي أرسل الطلب يتم ضبط القيمة على -1 في حال عدم توفّر إطار رئيسي.

      • requestHeaders

        HttpHeaders اختيارية

        عناوين طلبات HTTP التي تم إرسالها مع هذا الطلب

      • requestId

        سلسلة

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

      • tabId

        الرقم

        رقم تعريف علامة التبويب التي يتم فيها تنفيذ الطلب اضبط القيمة على -1 إذا لم يكن الطلب مرتبطًا بعلامة تبويب.

      • timeStamp

        الرقم

        الوقت الذي يتم فيه تشغيل هذه الإشارة، بالمللي ثانية منذ بداية الحقبة

      • النوع

        ResourceType

        توضّح هذه السمة طريقة استخدام المورد المطلوب.

      • url

        سلسلة

  • تصفية

    RequestFilter

  • extraInfoSpec

    OnSendHeadersOptions[] اختياري