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). قد يحدث ذلك عدة مرات لكل طلب بسبب عمليات إعادة التوجيه وطلبات المصادقة. يهدف هذا الحدث إلى السماح للإضافات بإضافة عناوين الردود وتعديلها وحذفها، مثل عناوين نوع المحتوى الواردة. وتعالج أوامر التخزين المؤقت قبل بدء هذا الحدث، لذا فإن تعديل العناوين مثل التحكم في ذاكرة التخزين المؤقت لا يؤثر على ذاكرة التخزين المؤقت للمتصفح. ويتيح لك أيضًا إلغاء الطلب أو إعادة توجيهه.
onAuthRequired (متزامن اختياريًا)
يتم تنشيطه عندما يتطلب الطلب مصادقة المستخدم. يمكن معالجة هذا الحدث بشكل متزامن لتوفير بيانات اعتماد المصادقة. يُرجى العلم بأنّ الإضافات قد توفّر بيانات اعتماد غير صالحة. احرص على عدم إدخال تكرار لا نهائي من خلال تقديم بيانات اعتماد غير صالحة بشكل متكرر. يمكن استخدام هذه الطريقة أيضًا لإلغاء الطلب.
onBeforeRedirect
يتم تنشيطها عندما تكون عملية إعادة التوجيه على وشك التنفيذ. يمكن بدء عملية إعادة التوجيه باستخدام رمز استجابة HTTP أو إضافة معيّنة. يُرجى العلم أنّ هذا الحدث يقدّم معلومات وتتم معالجته بشكل غير متزامن. ولا يسمح لك بتعديل الطلب أو إلغائه.
onResponseStarted
يتم تنشيطها عند تلقّي البايت الأول من نص الاستجابة. بالنسبة إلى طلبات HTTP، يعني هذا توفّر سطر الحالة وعناوين الاستجابة. يعد هذا الحدث إعلاميًا وتتم التعامل معه بشكل غير متزامن. ولا يسمح بتعديل الطلب أو إلغائه.
onCompleted
يتم تنشيطها عند معالجة الطلب بنجاح.
onErrorOccurred
يتم تنشيطها عندما تعذّرت معالجة الطلب بنجاح.

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

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

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

  • التفويض
  • التحكّم في ذاكرة التخزين المؤقت
  • الاتصال
  • Content-Length
  • المضيف
  • إذا تم تعديلها منذ
  • علامة If-None-Match
  • If-Range (إذا كان النطاق)
  • البيانات الجزئية
  • براغما
  • تفويض الخادم الوكيل
  • الاتصال بالخادم الوكيل
  • ترميز النقل

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

بدءًا من الإصدار 79 من Chrome، لا تعترض واجهة برمجة التطبيقات webRequest API طلبات الاستجابة لطلبات 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:

  • الموافقة-اللغة
  • قبول الترميز
  • المُحيل
  • كعكة

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

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

لا تعرض واجهة webRequest API سوى الطلبات التي لدى الإضافة إذن بالاطّلاع عليها، وذلك بموجب أذونات المضيف. بالإضافة إلى ذلك، يمكن الوصول إلى المخطّطات التالية فقط: 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 فقط.

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

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

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

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

بدءًا من الإصدار 96 من Chrome، تدعم واجهة برمجة التطبيقات webRequest API اعتراض طلب 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 بشكل غير متزامن.

تسمح filter webRequest.RequestFilter بتقييد الطلبات التي يتم بدء الأحداث فيها بسمات مختلفة:

عناوين 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 لإعادة توجيه طلب مورد عام إلى مورد لا يمكن الوصول إليه عبر الويب، يتم حظر الإضافة ويؤدي إلى حدوث خطأ. ينطبق ما سبق حتى إذا كان المورد الذي لا يمكن الوصول إليه من خلال الويب مملوكًا لإضافة إعادة التوجيه. للإعلان عن الموارد التي سيتم استخدامها مع واجهات clarativeWebRequest API، يجب الإعلان عن المصفوفة "web_accessible_resources" وتعبئتها في ملف البيان على النحو الموضَّح هنا.

حل النزاعات

في طريقة التنفيذ الحالية لواجهة برمجة تطبيقات Web request API، يتم اعتبار الطلب ملغىً إذا طلبت إضافة واحدة على الأقل إلغاء الطلب. إذا ألغت الإضافة طلبًا، يتم إشعار جميع الإضافات من خلال حدث 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-pattern.

الأنواع

BlockingResponse

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

أماكن إقامة

  • authCredentials

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

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

    • كلمة مرور

      سلسلة

    • اسم مستخدم

      سلسلة

  • إلغاء

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

    إذا كانت القيمة true، يتم إلغاء الطلب. ويؤدي ذلك إلى منع إرسال الطلب. يمكن استخدام هذا النوع من الأحداث كاستجابة لأحداث on beforeRequest و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 والإصدارات الأحدث

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

التعداد

ArrayBuffer

سلسلة

HttpHeaders

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

النوع

الكائن[]

أماكن إقامة

  • binaryValue

    number[] اختيارية

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

  • اسم

    سلسلة

    اسم عنوان HTTP.

  • القيمة

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

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

IgnoredActionType

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

التعداد

"request_headers"

"auth_credentials"

OnAuthRequiredOptions

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

التعداد

"ResponseHeaders"
تشير إلى أنّه يجب تضمين عناوين الاستجابة في الحدث.

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

"asyncblock"
يحدد هذا الإعداد أنه يتم التعامل مع وظيفة معاودة الاتصال بشكل غير متزامن.

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

OnBeforeRedirectOptions

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

التعداد

"ResponseHeaders"
تشير إلى أنّه يجب تضمين عناوين الاستجابة في الحدث.

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

OnBeforeRequestOptions

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

التعداد

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

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

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

OnBeforeSendHeadersOptions

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

التعداد

"requestHeaders"
يحدد تضمين عنوان الطلب في الحدث.

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

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

OnCompletedOptions

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

التعداد

"ResponseHeaders"
تشير إلى أنّه يجب تضمين عناوين الاستجابة في الحدث.

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

OnErrorOccurredOptions

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

القيمة

"extraHeaders"

OnHeadersReceivedOptions

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

التعداد

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

"ResponseHeaders"
تشير إلى أنّه يجب تضمين عناوين الاستجابة في الحدث.

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

OnResponseStartedOptions

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

التعداد

"ResponseHeaders"
تشير إلى أنّه يجب تضمين عناوين الاستجابة في الحدث.

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

OnSendHeadersOptions

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

التعداد

"requestHeaders"
يحدد تضمين عنوان الطلب في الحدث.

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

RequestFilter

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

أماكن إقامة

  • tabId

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

  • الأنواع

    ResourceType[] اختيارية

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

  • urls

    سلسلة[]

    قائمة بعناوين URL أو أنماط عناوين URL وستتم فلترة الطلبات التي لا يمكن أن تتطابق مع أيٍّ من عناوين URL.

  • windowId

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

ResourceType

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

التعداد

"main_frame"
تحديد المورد كإطار رئيسي

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

"stylesheet"
يحدد المورد على أنه ورقة أنماط.

"script"
يحدد المورد على أنه نص برمجي.

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

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

"object"
يحدد المورد على أنه كائن.

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

"ping"
يحدد المورد على أنه فحص اتصال.

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

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

"websocket"
يحدد المورد على أنه WebSocket.

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

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

UploadData

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

أماكن إقامة

  • بايت

    أي اختياري

    مصفوفة مصفوفة تضمّ نسخة من البيانات.

  • ملف

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

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

أماكن إقامة

MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES

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

القيمة

20

الطُرق

handlerBehaviorChanged()

وعد 
chrome.webRequest.handlerBehaviorChanged(
  callback?: function,
)

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

المَعلمات

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

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

    تتوفّر الوعود في إصدار 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

    • التفاصيل

      كائن

      • منافس

        كائن

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

        • مضيف

          سلسلة

        • المنفذ

          الرقم

      • documentId

        سلسلة

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

        المعرِّف الفريد العالمي للمستند الذي يُرسل الطلب

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

        دورة حياة المستند.

      • frameId

        الرقم

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

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

        نوع الإطار الذي حدث فيه الطلب.

      • بادئ تشغيل

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

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

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

      • isProxy

        boolean

        True بالنسبة إلى Proxy-Authenticate، وخطأ لـ WWW-Authenticate.

      • method

        سلسلة

        طريقة HTTP القياسية.

      • parentDocumentId

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

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

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

      • 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

        سلسلة

    • asyncCallback

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

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

      تبدو معلَمة asyncCallback على النحو التالي: 

      (response: BlockingResponse)=>void

    • returns

      BlockingResponse|غير محدّدة

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

  • filter

    RequestFilter

  • extraInfoSpec

    OnAuthRequiredOptions[] اختيارية

onBeforeRedirect

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

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

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (details: object)=>void

    • التفاصيل

      كائن

      • documentId

        سلسلة

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

        المعرِّف الفريد العالمي للمستند الذي يُرسل الطلب

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

        دورة حياة المستند.

      • frameId

        الرقم

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

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

        نوع الإطار الذي حدث فيه الطلب.

      • fromCache

        boolean

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

      • بادئ تشغيل

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

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

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

      • ip

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

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

      • method

        سلسلة

        طريقة HTTP القياسية.

      • parentDocumentId

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

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

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

      • 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

        سلسلة

  • filter

    RequestFilter

  • extraInfoSpec

    OnBeforeRedirectOptions[] اختيارية

onBeforeRequest

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

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

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (details: object)=>BlockingResponse|undefined

    • التفاصيل

      كائن

      • documentId

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

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

        المعرِّف الفريد العالمي للمستند الذي يُرسل الطلب

      • documentLifecycle

        extensionTypes.DocumentLifecycle اختيارية

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

        دورة حياة المستند.

      • frameId

        الرقم

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

      • frameType

        extensionTypes.FrameType اختيارية

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

        نوع الإطار الذي حدث فيه الطلب.

      • بادئ تشغيل

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

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

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

      • method

        سلسلة

        طريقة HTTP القياسية.

      • parentDocumentId

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

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

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

      • parentFrameId

        الرقم

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

      • requestBody

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

        يحتوي على بيانات النص الأساسي لطلب HTTP. يتم توفير هذه السمة فقط إذا كانت قيمة additionalInfoSpec تحتوي على "requestBody".

        • خطأ

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

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

        • formData

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

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

        • نقي

          UploadData[] اختيارية

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

      • requestId

        سلسلة

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

      • tabId

        الرقم

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

      • timeStamp

        الرقم

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

      • كتابة

        ResourceType

        طريقة استخدام المرجع المطلوب

      • url

        سلسلة

    • returns

      BlockingResponse|غير محدّدة

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

  • filter

    RequestFilter

  • extraInfoSpec

    OnBeforeRequestOptions[] اختيارية

onBeforeSendHeaders

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

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

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (details: object)=>BlockingResponse|undefined

    • التفاصيل

      كائن

      • documentId

        سلسلة

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

        المعرِّف الفريد العالمي للمستند الذي يُرسل الطلب

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

        دورة حياة المستند.

      • frameId

        الرقم

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

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

        نوع الإطار الذي حدث فيه الطلب.

      • بادئ تشغيل

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

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

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

      • method

        سلسلة

        طريقة HTTP القياسية.

      • parentDocumentId

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

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

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

      • parentFrameId

        الرقم

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

      • requestHeaders

        HttpHeaders اختياري

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

      • requestId

        سلسلة

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

      • tabId

        الرقم

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

      • timeStamp

        الرقم

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

      • كتابة

        ResourceType

        طريقة استخدام المرجع المطلوب

      • url

        سلسلة

    • returns

      BlockingResponse|غير محدّدة

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

  • filter

    RequestFilter

  • extraInfoSpec

    OnBeforeSendHeadersOptions[] اختيارية

onCompleted

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

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

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (details: object)=>void

    • التفاصيل

      كائن

      • documentId

        سلسلة

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

        المعرِّف الفريد العالمي للمستند الذي يُرسل الطلب

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

        دورة حياة المستند.

      • frameId

        الرقم

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

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

        نوع الإطار الذي حدث فيه الطلب.

      • fromCache

        boolean

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

      • بادئ تشغيل

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

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

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

      • ip

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

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

      • method

        سلسلة

        طريقة HTTP القياسية.

      • parentDocumentId

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

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

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

      • parentFrameId

        الرقم

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

      • requestId

        سلسلة

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

      • responseHeaders

        HttpHeaders اختياري

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

      • statusCode

        الرقم

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

      • statusLine

        سلسلة

        سطر حالة HTTP للاستجابة أو سلسلة "HTTP/0.9 200 OK" لاستجابات HTTP/0.9 (أي الاستجابات التي تفتقر إلى سطر حالة) أو سلسلة فارغة في حال عدم وجود رؤوس.

      • tabId

        الرقم

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

      • timeStamp

        الرقم

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

      • كتابة

        ResourceType

        طريقة استخدام المرجع المطلوب

      • url

        سلسلة

  • filter

    RequestFilter

  • extraInfoSpec

    OnCompletedOptions[] اختيارية

onErrorOccurred

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

يتم تنشيطها عند حدوث خطأ.

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (details: object)=>void

    • التفاصيل

      كائن

      • documentId

        سلسلة

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

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

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

        دورة حياة المستند.

      • خطأ

        سلسلة

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

      • frameId

        الرقم

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

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

        نوع الإطار الذي حدث فيه الطلب.

      • fromCache

        boolean

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

      • بادئ تشغيل

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

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

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

      • ip

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

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

      • method

        سلسلة

        طريقة HTTP القياسية.

      • parentDocumentId

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

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

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

      • parentFrameId

        الرقم

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

      • requestId

        سلسلة

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

      • tabId

        الرقم

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

      • timeStamp

        الرقم

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

      • كتابة

        ResourceType

        طريقة استخدام المرجع المطلوب

      • url

        سلسلة

  • filter

    RequestFilter

  • extraInfoSpec

    OnErrorOccurredOptions[] اختيارية

onHeadersReceived

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

يتم تنشيطها عند استلام رؤوس استجابة HTTP لأحد الطلبات.

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (details: object)=>BlockingResponse|undefined

    • التفاصيل

      كائن

      • documentId

        سلسلة

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

        المعرِّف الفريد العالمي للمستند الذي يُرسل الطلب

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

        دورة حياة المستند.

      • frameId

        الرقم

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

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

        نوع الإطار الذي حدث فيه الطلب.

      • بادئ تشغيل

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

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

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

      • method

        سلسلة

        طريقة HTTP القياسية.

      • parentDocumentId

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

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

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

      • 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|غير محدّدة

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

  • filter

    RequestFilter

  • extraInfoSpec

    OnHeadersReceivedOptions[] اختيارية

onResponseStarted

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

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

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (details: object)=>void

    • التفاصيل

      كائن

      • documentId

        سلسلة

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

        المعرِّف الفريد العالمي للمستند الذي يُرسل الطلب

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

        دورة حياة المستند.

      • frameId

        الرقم

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

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

        نوع الإطار الذي حدث فيه الطلب.

      • fromCache

        boolean

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

      • بادئ تشغيل

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

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

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

      • ip

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

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

      • method

        سلسلة

        طريقة HTTP القياسية.

      • parentDocumentId

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

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

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

      • parentFrameId

        الرقم

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

      • requestId

        سلسلة

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

      • responseHeaders

        HttpHeaders اختياري

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

      • statusCode

        الرقم

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

      • statusLine

        سلسلة

        سطر حالة HTTP للاستجابة أو سلسلة "HTTP/0.9 200 OK" لاستجابات HTTP/0.9 (أي الاستجابات التي تفتقر إلى سطر حالة) أو سلسلة فارغة في حال عدم وجود رؤوس.

      • tabId

        الرقم

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

      • timeStamp

        الرقم

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

      • كتابة

        ResourceType

        طريقة استخدام المرجع المطلوب

      • url

        سلسلة

  • filter

    RequestFilter

  • extraInfoSpec

    OnResponseStartedOptions[] اختيارية

onSendHeaders

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

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

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (details: object)=>void

    • التفاصيل

      كائن

      • documentId

        سلسلة

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

        المعرِّف الفريد العالمي للمستند الذي يُرسل الطلب

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

        دورة حياة المستند.

      • frameId

        الرقم

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

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

        نوع الإطار الذي حدث فيه الطلب.

      • بادئ تشغيل

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

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

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

      • method

        سلسلة

        طريقة HTTP القياسية.

      • parentDocumentId

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

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

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

      • parentFrameId

        الرقم

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

      • requestHeaders

        HttpHeaders اختياري

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

      • requestId

        سلسلة

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

      • tabId

        الرقم

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

      • timeStamp

        الرقم

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

      • كتابة

        ResourceType

        طريقة استخدام المرجع المطلوب

      • url

        سلسلة

  • filter

    RequestFilter

  • extraInfoSpec

    OnSendHeadersOptions[] اختيارية