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

تعديل طلبات الشبكة في 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 واحد

كانت حالة الاستخدام الشائعة في الإصدار 2 من ملف البيان هي حظر طلبات الويب باستخدام الحدث 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/*"
  ]

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

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

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": [
    ""
  ]