chrome.webRequest

الوصف

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

الأذونات

webRequest

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

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

webRequestBlocking

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

webRequestAuthProvider

مطلوب لاستخدام الطريقة onAuthRequired. عرض التعامل مع المصادقة:

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

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

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

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

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

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:

  • الأصل

بدءًا من الإصدار 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.

لا تعرض واجهة برمجة التطبيقات 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" لطلب أحداث إضافية. للحصول على معلومات حول الطلب. يُستخدم هذا الخيار لتقديم معلومات تفصيلية حول بيانات الطلب فقط. إذا تم طلبها صراحةً.

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

للتعامل مع طلبات مصادقة 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"]
);

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

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"

&quot;response_headers&quot;

&quot;auth_credentials&quot;

OnAuthRequiredOptions

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

Enum

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

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

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

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

OnBeforeRedirectOptions

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

Enum

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

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

OnBeforeRequestOptions

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

Enum

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

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

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

OnBeforeSendHeadersOptions

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

Enum

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

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

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

OnCompletedOptions

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

Enum

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

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

OnErrorOccurredOptions

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

القيمة

"extraHeaders"

OnHeadersReceivedOptions

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

Enum

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

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

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

OnResponseStartedOptions

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

Enum

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

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

OnSendHeadersOptions

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

Enum

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

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

RequestFilter

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

أماكن إقامة

  • tabId

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

  • الأنواع

    ResourceType[] اختياري

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

  • عناوين url

    سلسلة[]

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

  • windowId

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

ResourceType

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

Enum

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

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

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

&quot;script&quot;
يحدد المورد كنص برمجي.

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

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

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

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

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

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

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

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

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

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

UploadData

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

أماكن إقامة

  • بايت

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

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

  • ملف

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

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

أماكن إقامة

MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES

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

القيمة

20

الطُرق

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 أو الإصدارات الأحدث

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

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

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

      • frameId

        الرقم

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

      • الإصدار 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

    • returns

      BlockingResponse | غير محدّدة

      في حال إجراء "الحظر" في "extraInfoSpec" ، يجب أن يعرض مستمع الحدث كائنًا من هذا النوع.

  • تصفية

    RequestFilter

  • extraInfoSpec

    OnAuthRequiredOptions[] اختيارية

onBeforeRedirect

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

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

المعلمات

  • رد الاتصال

    دالة

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

    (details: object) => void

    • التفاصيل

      كائن

      • documentId

        سلسلة

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

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

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

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

      • frameId

        الرقم

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

      • الإصدار 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 أو الإصدارات الأحدث

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

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

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

      • frameId

        الرقم

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

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

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

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

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

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

        المصدر الذي تم فيه تقديم الطلب. ولا يتغيّر ذلك عند إجراء عمليات إعادة التوجيه. إذا كان هذا مصدرًا مبهمًا، ستظهر السلسلة "null" تنبؤي.

      • method

        سلسلة

        طريقة HTTP العادية

      • parentDocumentId

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

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

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

      • 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 أو الإصدارات الأحدث

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

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

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

      • frameId

        الرقم

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

      • الإصدار 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 أو الإصدارات الأحدث

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

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

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

      • خطأ

        سلسلة

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

      • frameId

        الرقم

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

      • الإصدار 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 أو الإصدارات الأحدث

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

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

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

      • frameId

        الرقم

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

      • الإصدار 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 أو الإصدارات الأحدث

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

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

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

      • frameId

        الرقم

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

      • الإصدار 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 أو الإصدارات الأحدث

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

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

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

      • frameId

        الرقم

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

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

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

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

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

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

        المصدر الذي تم فيه تقديم الطلب. ولا يتغيّر ذلك عند إجراء عمليات إعادة التوجيه. إذا كان هذا مصدرًا مبهمًا، ستظهر السلسلة "null" تنبؤي.

      • method

        سلسلة

        طريقة HTTP العادية

      • parentDocumentId

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

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

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

      • parentFrameId

        الرقم

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

      • requestHeaders

        HttpHeaders اختيارية

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

      • requestId

        سلسلة

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

      • tabId

        الرقم

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

      • timeStamp

        الرقم

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

      • كتابة

        ResourceType

        كيفية استخدام المورد المطلوب.

      • url

        سلسلة

  • تصفية

    RequestFilter

  • extraInfoSpec

    OnSendHeadersOptions[] اختيارية