استبدال أدوات معالجة طلبات الويب المحظورة

يغيّر الإصدار 3 من ملف البيان طريقة تعامل الإضافات مع تعديل طلبات الشبكة. بدلاً من اعتراض طلبات الشبكة وتعديلها في وقت التشغيل باستخدام chrome.webRequest، تحدّد الإضافة قواعد تصف الإجراءات التي يجب تنفيذها عند استيفاء مجموعة معيّنة من الشروط. يمكنك إجراء ذلك باستخدام Declarative Net Request API.

تختلف واجهة برمجة التطبيقات Web Request API عن واجهة برمجة التطبيقات Declarative Net Request API بشكل كبير. بدلاً من استبدال استدعاء دالة بآخر، عليك إعادة كتابة الرمز من حيث حالات الاستخدام. يشرح لك هذا القسم خطوات هذه العملية.

ليس عليك إجراء هذه التغييرات إذا كانت الإضافة مثبّتة بموجب سياسة. بالنسبة إلى الإضافات المثبَّتة من خلال السياسة، سيظل الإذن webRequestBlocking متاحًا في الإصدار 3 من بيان الإضافة.

هذا هو القسم الثاني من ثلاثة أقسام تصف التغييرات المطلوبة للرمز الذي لا يشكّل جزءًا من عامل خدمة الإضافة. توضّح هذه الصفحة كيفية تحويل طلبات الويب التي تحظرها الإضافة، والتي يستخدمها الإصدار Manifest V2، إلى طلبات الشبكة التعريفية، والتي يستخدمها الإصدار Manifest V3. يتناول القسمان الآخران تعديل الرمز اللازم للانتقال إلى الإصدار Manifest V3 وتحسين الأمان.

مقدمة

في الإصدار Manifest V2، كان حظر طلبات الويب يؤدي إلى انخفاض كبير في أداء الإضافات وأداء الصفحات التي تعمل معها. تتيح مساحة الاسم webRequest تسعة أحداث محتمَلة الحظر، ويستقبل كلّ منها عددًا غير محدود من معالِجات الأحداث. والأسوأ من ذلك أنّ كل صفحة ويب يمكن أن تحظرها إضافات متعددة، والأذونات المطلوبة لذلك تكون تدخّلية. يمنع الإصدار 3 من ملف البيان حدوث هذه المشكلة من خلال استبدال دوال الرجوع بقواعد تعريفية.

تحديث الأذونات

أدخِل التغييرات التالية على الحقل "permissions" في manifest.json.

• أزِل إذن "webRequest" إذا لم تعُد بحاجة إلى مراقبة طلبات الشبكة.
• نقل "أنماط المطابقة" من "permissions" إلى "host_permissions"

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

إنشاء قواعد طلب شبكة تعريفية

يتطلّب إنشاء قواعد طلبات الشبكة التعريفية إضافة عنصر "declarative_net_request" إلى manifest.json. يحتوي الحظر "declarative_net_request" على مصفوفة من عناصر "rule_resource" تشير إلى ملف قاعدة. يحتوي ملف القاعدة على مصفوفة من العناصر التي تحدّد إجراءً والشروط التي يتم فيها تنفيذ هذه الإجراءات.

حالات الاستخدام الشائعة

توضّح الأقسام التالية حالات الاستخدام الشائعة لطلبات الشبكة التعريفية. تقدّم التعليمات أدناه مخططًا موجزًا فقط. يمكنك الاطّلاع على مزيد من المعلومات حول كل التفاصيل الواردة هنا في مرجع واجهة برمجة التطبيقات ضمن chrome.declarativeNetRequest.

حظر عنوان URL واحد

كانت إحدى حالات الاستخدام الشائعة في الإصدار Manifest V2 هي حظر طلبات الويب باستخدام الحدث onBeforeRequest في النص البرمجي للخلفية.

chrome.webRequest.onBeforeRequest.addListener((e) => {
    return { cancel: true };
}, { urls: ["https://www.example.com/*"] }, ["blocking"]);

بالنسبة إلى الإصدار 3 من ملف البيان، أنشئ قاعدة declarativeNetRequest جديدة باستخدام نوع الإجراء "block". لاحظ العنصر "condition" في قاعدة المثال. يحلّ "urlFilter" محل الخيار urls الذي تم تمريره إلى أداة الاستماع webRequest. تحدّد مصفوفة "resourceTypes" فئة الموارد المطلوب حظرها. يحظر هذا المثال صفحة HTML الرئيسية فقط، ولكن يمكنك، على سبيل المثال، حظر الخطوط فقط.

[
  {
    "id" : 1,
    "priority": 1,
    "action" : { "type" : "block" },
    "condition" : {
      "urlFilter" : "||example.com",
      "resourceTypes" : ["main_frame"]
    }
  }
]

لإتاحة هذه الميزة، عليك تعديل أذونات الإضافة. في manifest.json، استبدِل الإذن "webRequestBlocking" بالإذن "declarativeNetRequest". يُرجى العِلم أنّه تتم إزالة عنوان URL من الحقل "permissions" لأنّ حظر المحتوى لا يتطلّب أذونات المضيف. كما هو موضّح أعلاه، يحدّد ملف القواعد المضيف أو المضيفين الذين ينطبق عليهم طلب الشبكة التوضيحي.

إذا أردت تجربة ذلك، يتوفّر الرمز أدناه في مستودع العيّنات.

  "permissions": [
    "webRequestBlocking",
    "https://*.example.com/*"
  ]

  "permissions": [
    "declarativeNetRequest",
  ]

إعادة توجيه عناوين URL متعددة

كانت إحدى حالات الاستخدام الشائعة الأخرى في الإصدار 2 من ملف البيان هي استخدام الحدث BeforeRequest لإعادة توجيه طلبات الويب.

chrome.webRequest.onBeforeRequest.addListener((e) => {
    console.log(e);
    return { redirectUrl: "https://developer.chrome.com/docs/extensions/mv3/intro/" };
  }, { 
    urls: [
      "https://developer.chrome.com/docs/extensions/mv2/"
    ]
  }, 
  ["blocking"]
);

بالنسبة إلى Manifest V3، استخدِم "redirect" نوع الإجراء. كما كان من قبل، يحلّ "urlFilter" محل الخيار url الذي تم تمريره إلى أداة معالجة webRequest. لاحظ أنّه في هذا المثال، يحتوي العنصر "action" في ملف القاعدة على حقل "redirect" يتضمّن عنوان URL الذي سيتم عرضه بدلاً من عنوان URL الذي يتم فلترته.

[
  {
    "id" : 1,
    "priority": 1,
    "action": {
      "type": "redirect",
      "redirect": { "url": "https://developer.chrome.com/docs/extensions/mv3/intro/" }
    },
    "condition": {
      "urlFilter": "https://developer.chrome.com/docs/extensions/mv2/",
      "resourceTypes": ["main_frame"]
    }
  }
]

يتطلّب هذا السيناريو أيضًا إجراء تغييرات على أذونات الإضافة. كما كان من قبل، استبدِل الإذن "webRequestBlocking" بالإذن "declarativeNetRequest". يتم نقل عناوين URL مرة أخرى من manifest.json إلى ملف قاعدة. يُرجى العِلم أنّ إعادة التوجيه تتطلّب أيضًا إذن "declarativeNetRequestWithHostAccess" بالإضافة إلى إذن المضيف.

إذا أردت تجربة ذلك، يتوفّر الرمز أدناه في مستودع العيّنات.

  "permissions": [
    "webRequestBlocking",
    "https://developer.chrome.com/docs/extensions/*",
    "https://developer.chrome.com/docs/extensions/reference"
  ]

  "permissions": [
    "declarativeNetRequestWithHostAccess"
  ],
  "host_permissions": [
    "https://developer.chrome.com/*"
  ]

حظر ملفات تعريف الارتباط

في Manifest V2، يتطلّب حظر ملفات تعريف الارتباط اعتراض عناوين طلبات الويب قبل إرسالها وإزالة ملف تعريف ارتباط معيّن.

chrome.webRequest.onBeforeSendHeaders.addListener(
  function(details) {
    removeHeader(details.requestHeaders, 'cookie');
    return {requestHeaders: details.requestHeaders};
  },
  // filters
  {urls: ['https://*/*', 'http://*/*']},
  // extraInfoSpec
  ['blocking', 'requestHeaders', 'extraHeaders']);

تتيح Manifest V3 أيضًا إجراء ذلك باستخدام قاعدة في ملف قواعد. في هذه المرة، يكون نوع الإجراء "modifyHeaders". يستقبل الملف مصفوفة من عناصر "requestHeaders" تحدّد العناوين المطلوب تعديلها وكيفية تعديلها. يُرجى العِلم أنّ الكائن "condition" يحتوي فقط على مصفوفة "resourceTypes". وهو يتوافق مع القيم نفسها الواردة في الأمثلة السابقة.

إذا أردت تجربة ذلك، يتوفّر الرمز أدناه في مستودع العيّنات.

[
  {
    "id": 1,
    "priority": 1,
    "action": {
      "type": "modifyHeaders",
      "requestHeaders": [
        { "header": "cookie", "operation": "remove" }
      ]
    },
    "condition": {
      "urlFilter": "|*?no-cookies=1",
      "resourceTypes": ["main_frame"]
    }
  }
]

يتطلّب هذا السيناريو أيضًا إجراء تغييرات على أذونات الإضافة. كما كان من قبل، استبدِل الإذن "webRequestBlocking" بالإذن "declarativeNetRequest".

  "permissions": [
    "webRequest",
    "webRequestBlocking",
    "https://*/*",
    "http://*/*"
  ],

  "permissions": [
    "declarativeNetRequest",
  ],
  "host_permissions": [
    ""
  ]