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

تعديل طلبات الشبكة في Manifest V3

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

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

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

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

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

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

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

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

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

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

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

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

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

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

نص برمجي لملف البيان Manifest V2 في الخلفية
chrome.webRequest.onBeforeRequest.addListener((e) => {
    return { cancel: true };
}, { urls: ["https://www.example.com/*"] }, ["blocking"]);

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

ملف قواعد الإصدار 3 من ملف البيان
[
  {
    "id" : 1,
    "priority": 1,
    "action" : { "type" : "block" },
    "condition" : {
      "urlFilter" : "||example.com",
      "resourceTypes" : ["main_frame"]
    }
  }
]

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

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

Manifest V2
  "permissions": [
    "webRequestBlocking",
    "https://*.example.com/*"
  ]
الإصدار 3 من ملف البيان
  "permissions": [
    "declarativeNetRequest",
  ]

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

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

نص برمجي لملف البيان Manifest V2 في الخلفية
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 الذي تتم فلترته.

ملف قاعدة Manifest V3
[
  {
    "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" بالإضافة إلى إذن المضيف.

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

Manifest V2
  "permissions": [
    "webRequestBlocking",
    "https://developer.chrome.com/docs/extensions/*",
    "https://developer.chrome.com/docs/extensions/reference"
  ]
الإصدار 3 من ملف البيان
  "permissions": [
    "declarativeNetRequestWithHostAccess"
  ],
  "host_permissions": [
    "https://developer.chrome.com/*"
  ]

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

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

نص برمجي لملف البيان 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". وهو يتيح القيم نفسها الواردة في الأمثلة السابقة.

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

ملف manifest.json في الإصدار 3 من ملف البيان
[
  {
    "id": 1,
    "priority": 1,
    "action": {
      "type": "modifyHeaders",
      "requestHeaders": [
        { "header": "cookie", "operation": "remove" }
      ]
    },
    "condition": {
      "urlFilter": "|*?no-cookies=1",
      "resourceTypes": ["main_frame"]
    }
  }
]

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

إصدار Manifest V2
  "permissions": [
    "webRequest",
    "webRequestBlocking",
    "https://*/*",
    "http://*/*"
  ],
الإصدار 3 من ملف البيان
  "permissions": [
    "declarativeNetRequest",
  ],
  "host_permissions": [
    ""
  ]