chrome.declarativeNetRequest

الوصف

تُستخدَم واجهة برمجة التطبيقات chrome.declarativeNetRequest لحظر طلبات الشبكة أو تعديلها من خلال تحديد قواعد الإفصاح. ويتيح ذلك للإضافات تعديل طلبات الشبكة بدون اعتراضها وعرض محتواها، ما يوفّر المزيد من الخصوصية.

الأذونات

declarativeNetRequest
declarativeNetRequestWithHostAccess

يقدّم الإذنان "declarativeNetRequest" و "declarativeNetRequestWithHostAccess" الإمكانات نفسها. يكمن الاختلاف بينهما في وقت طلب الأذونات أو منحها.

"declarativeNetRequest"
يؤدي هذا الإجراء إلى إصدار تحذير بشأن الإذن عند التثبيت مع توفير إمكانية الوصول الضمني إلى قواعد allow وallowAllRequests وblock. يمكنك استخدام ذلك متى أمكن لتجنب الحاجة إلى طلب الوصول الكامل إلى المضيفين.
"declarativeNetRequestFeedback"
تفعيل ميزات تصحيح الأخطاء للإضافات التي تم فك ضغطها، وتحديدًا getMatchedRules() وonRuleMatchedDebug.
"declarativeNetRequestWithHostAccess"
لا يظهر تحذير بشأن الإذن أثناء التثبيت، ولكن يجب طلب أذونات المضيف قبل أن تتمكّن من تنفيذ أي إجراء على المضيف. ويكون هذا مناسبًا عندما تريد استخدام قواعد بيانية لطلب الشراء في إحدى الإضافات التي تتضمن أذونات المضيف بدون إنشاء تحذيرات إضافية.

مدى توفّر الخدمة

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

البيان

بالإضافة إلى الأذونات الموضّحة سابقًا، تتطلّب أنواع معيّنة من مجموعات القواعد، تحديدًا مجموعات القواعد الثابتة، الإفصاح عن مفتاح بيان "declarative_net_request"، والذي يجب أن يكون قاموسًا يتضمّن مفتاحًا واحدًا يسمّى "rule_resources". هذا المفتاح هو مصفوفة تحتوي على قواميس من النوع Ruleset، كما هو موضح في ما يلي. (يُرجى العلم أنّ اسم "مجموعة القواعد" لا يظهر في ملف JSON للبيان لأنه مجرد مصفوفة.) ويتم شرح مجموعات القواعد الثابتة لاحقًا في هذا المستند.

{
  "name": "My extension",
  ...

  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    }, {
      "id": "ruleset_2",
      "enabled": false,
      "path": "rules_2.json"
    }]
  },
  "permissions": [
    "declarativeNetRequest",
    "declarativeNetRequestFeedback",
  ],
  "host_permissions": [
    "http://www.blogger.com/*",
    "http://*.google.com/*"
  ],
  ...
}

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

لاستخدام واجهة برمجة التطبيقات هذه، حدِّد مجموعة قواعد واحدة أو أكثر. تحتوي مجموعة القواعد على مجموعة من القواعد. تؤدي قاعدة واحدة إلى تنفيذ أحد الإجراءات التالية:

  • حظر طلب شبكة
  • عليك ترقية المخطط (من http إلى https).
  • يمكنك منع حظر طلب من خلال إلغاء أي قواعد محظورة مطابقة.
  • إعادة توجيه طلب الشبكة.
  • تعديل عناوين الطلبات أو الاستجابة

هناك ثلاثة أنواع من مجموعات القواعد، تُدار بطرق مختلفة قليلاً.

ديناميكية
يمكنك مواصلة استخدام جلسات المتصفح وترقيات الإضافات، وتتم إدارتها باستخدام JavaScript أثناء استخدام إحدى الإضافات.
الجلسة
يتم محو البيانات عند إيقاف المتصفّح وعند تثبيت إصدار جديد من الإضافة. تتم إدارة قواعد الجلسات باستخدام JavaScript عندما تكون الإضافة قيد الاستخدام.
ثابت
يتم تقديم حزمة واحدة وتثبيتها وتحديثها عند تثبيت إضافة أو ترقيتها. يتم تخزين القواعد الثابتة في ملفات قواعد بتنسيق JSON ويتم إدراجها في ملف البيان.

تشرح الأقسام القليلة التالية أنواع مجموعات القواعد بالتفصيل.

مجموعات القواعد الديناميكية وعلى مستوى الجلسة

تتم إدارة مجموعات القواعد الديناميكية ومجموعات القواعد للجلسة باستخدام JavaScript عندما تكون الإضافة قيد الاستخدام.

  • تظلّ القواعد الديناميكية سارية في جميع جلسات المتصفّح وترقيات الإضافات.
  • يتم محو قواعد الجلسات عند إيقاف المتصفّح وعند تثبيت إصدار جديد من الإضافة.

هناك نوع واحد فقط من أنواع مجموعات القواعد هذه. يمكن للإضافة إضافة قواعد إليها أو إزالتها بشكل ديناميكي من خلال طلب updateDynamicRules() وupdateSessionRules()، بشرط عدم تجاوز حدود القواعد. للحصول على معلومات عن حدود القواعد، يُرجى الاطّلاع على حدود القواعد. يمكنك الاطّلاع على مثال على ذلك ضمن أمثلة الرموز.

مجموعات القواعد الثابتة

وعلى عكس القواعد الديناميكية وقواعد الجلسات، يتم تجميع القواعد الثابتة وتثبيتها وتحديثها عند تثبيت إضافة أو ترقيتها. ويتم تخزينها في ملفات قواعد بتنسيق JSON، تتم الإشارة إليها للإضافة باستخدام المفتاحَين "declarative_net_request" و"rule_resources" كما هو موضَّح أعلاه، بالإضافة إلى قاموس واحد أو أكثر من قواميس Ruleset. يحتوي قاموس Ruleset على مسار إلى ملف القواعد ومعرّفًا لمجموعة القواعد المضمّنة في الملف، وما إذا كانت مجموعة القواعد مفعّلة أو غير مفعّلة. يُعدّ الخياران الأخيران مهمَين عند تفعيل مجموعة قواعد أو إيقافها آليًا.

{
  ...
  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    },
    ...
    ]
  }
  ...
}

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

تفعيل القواعد الثابتة ومجموعات القواعد وإيقافها

يمكن تفعيل كلّ من القواعد الثابتة الفردية ومجموعات القواعد الثابتة الكاملة أو إيقافها في وقت التشغيل.

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

ولأسباب تتعلق بالأداء، هناك أيضًا حدود لعدد القواعد ومجموعات القواعد التي يمكن تفعيلها في وقت واحد. يمكنك الاتصال بالرقم getAvailableStaticRuleCount() للتحقّق من عدد القواعد الإضافية التي يمكن تفعيلها. للحصول على معلومات عن حدود القواعد، يُرجى الاطّلاع على حدود القواعد.

لتفعيل القواعد الثابتة أو إيقافها، اطلب الرمز updateStaticRules(). تستخدم هذه الطريقة الكائن UpdateStaticRulesOptions الذي يحتوي على صفائف من أرقام تعريف القواعد المطلوب تفعيلها أو إيقافها. يتم تحديد المعرّفات باستخدام المفتاح "id" في قاموس Ruleset.

لتفعيل rulesets الثابتة أو إيقافها، اطلب الرمز updateEnabledRulesets(). تستخدم هذه الطريقة الكائن UpdateRulesetOptions، الذي يحتوي على صفائف من معرّفات مجموعات القواعد المطلوب تفعيلها أو إيقافها. يتم تحديد المعرّفات باستخدام المفتاح "id" في قاموس Ruleset.

إنشاء القواعد

بغض النظر عن النوع، تبدأ القاعدة بأربعة حقول كما هو موضح في ما يلي. على الرغم من أنّ المفتاحَين "id" و"priority" يستخدمان رقمًا، قد يوفّر مفتاحا "action" و"condition" عدة شروط للحظر وإعادة التوجيه. تحظر القاعدة التالية جميع طلبات النصوص البرمجية الناشئة من "foo.com" إلى أي عنوان URL يحتوي على "abc" كسلسلة فرعية.

{
  "id" : 1,
  "priority": 1,
  "action" : { "type" : "block" },
  "condition" : {
    "urlFilter" : "abc",
    "initiatorDomains" : ["foo.com"],
    "resourceTypes" : ["script"]
  }
}

الأحرف المطابقة لفلتر urlFilter

يسمح مفتاح "condition" للقاعدة لمفتاح "urlFilter" بالعمل على عناوين URL ضمن نطاق محدّد. يمكنك إنشاء أنماط باستخدام الرموز المميزة لمطابقة الأنماط. وفي ما يلي بعض الأمثلة.

urlFilter سلسلة مطابقة لـ لا يطابق
"abc" https://abcd.com
https://example.com/abcd		 https://ab.com
"abc*d" https://abcd.com
https://example.com/abcxyzd		 https://abc.com
"||a.example.com" https://a.example.com/
https://b.a.example.com/xyz		 https://example.com/
"|https*" https://example.com http://example.com/
http://https.com
"example*^123|" https://example.com/123
http://abc.com/example?123		 https://example.com/1234
https://abc.com/example0123

تحديد أولوية القواعد

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

  1. ويتم تحديد أولوية القواعد داخل الإضافة.
  2. وإذا كان بإمكان أكثر من إضافة واحدة تطبيق قاعدة على أحد الطلبات، سيتم تحديد أولوية جميع الإضافات التي تتطابق مع طلب معيَّن.

نفكر في المطابقة بهذه الطريقة: ستُمنح أي قاعدة تمنحها إضافة معيّنة الأولوية مقابل قواعد من إضافات أخرى.

تحديد أولوية القواعد داخل الإضافة

يتم تحديد الأولويات ضمن عملية إضافة واحدة باتّباع العملية التالية:

  1. يتم عرض القاعدة ذات أعلى أولوية من تحديد المطوّر (بمعنى آخر، الحقل "priority").

  2. إذا كانت هناك أكثر من قاعدة ذات الأولوية القصوى التي يحدِّدها المطوِّر، سيتم منح الأولوية للقواعد باستخدام الحقل "action"، بالترتيب التالي:

    1. allow
    2. allowAllRequests
    3. block
    4. upgradeScheme
    5. redirect

  3. إذا لم يكن نوع الإجراء block أو redirect، يتم تقييم أي قواعد modifyHeaders مطابقة. ويُرجى العلم بأنّه في حال توفُّر أي قواعد ذات أولوية يحددها المطوّر أقل من الأولوية المحدّدة لكل من allow وallowAllRequests، سيتم تجاهل هذه القواعد.

  4. إذا عدَّلت عدة قواعد العنوان نفسه، يتم تحديد التعديل من خلال حقل "priority" الذي حدّده المطوّر ومن خلال العمليات المحدّدة.

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

تحديد أولوية القواعد بين الإضافات

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

  1. ويتم تحديد أولوية القواعد باستخدام الحقل "action" بالترتيب التالي:

    1. block
    2. ‫redirect أو upgradeScheme
    3. ‫allow أو allowAllRequests

  2. وفي حال تطابق أكثر من قاعدة، تُمنَح الأولوية لآخر إضافة مثبَّتة.

حدود القواعد

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

القواعد الثابتة

القواعد الثابتة هي تلك المحدَّدة في ملفات القواعد المعرَّفة في ملف البيان. يمكن أن تحدد الإضافة ما يصل إلى 100 rulesets ثابتة كجزء من مفتاح بيان "rule_resources"، لكن لا يمكن تفعيل أكثر من 50 مجموعة من هذه القواعد في المرة الواحدة. وتُسمى هذه العملية اسم MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. وتضمن هذه القواعد إجمالاً أن يضم ما لا يقل عن 30,000 قاعدة. يُطلق على ذلك اسم GUARANTEED_MINIMUM_STATIC_RULES.

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

قواعد الجلسة

يمكن أن تحتوي الإضافة على ما يصل إلى 5,000 قاعدة جلسة. ويظهر هذا التصنيف باسم MAX_NUMBER_OF_SESSION_RULES.

قبل استخدام Chrome 120، كان هناك حدّ أقصى يبلغ 5, 000 قاعدة ديناميكية وقاعدة جلسات معًا.

القواعد الديناميكية

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

بدءًا من إصدار Chrome 121، هناك حد أقصى أكبر من 30,000 قاعدة متاحة للقواعد الديناميكية الآمنة، يُشار إليها باسم MAX_NUMBER_OF_DYNAMIC_RULES. والقواعد الآمنة هي قواعد تتضمّن إجراء block أو allow أو allowAllRequests أو upgradeScheme. أي قواعد غير آمنة تتم إضافتها ضمن الحدّ الأقصى البالغ 5,000 تُحتسب أيضًا ضمن هذا الحدّ.

قبل استخدام Chrome 120، كان هناك حدّ أقصى مجمّع لقاعدة ديناميكية وقاعدة جلسات يبلغ عددها 5, 000.

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

يمكن لجميع أنواع القواعد استخدام التعبيرات العادية، ومع ذلك، لا يمكن أن يتجاوز إجمالي عدد قواعد التعبير العادي لكل نوع 1000. ويُطلق على ذلك اسم MAX_NUMBER_OF_REGEX_RULES.

بالإضافة إلى ذلك، يجب أن يكون حجم كل قاعدة أقل من 2 كيلوبايت بعد تجميعها. ويرتبط هذا بشكل تقريبي بمدى تعقيد القاعدة. وإذا حاولت تحميل قاعدة تتجاوز هذا الحدّ، سيظهر لك تحذير مثل ما يلي وسيتم تجاهل القاعدة.

rules_1.json: Rule with id 1 specified a more complex regex than allowed
as part of the "regexFilter" key.

التفاعلات مع عاملي الخدمة

لا ينطبق declarativeNetRequest إلا على الطلبات التي تصل إلى تكديس الشبكة. يشمل ذلك الاستجابات من ذاكرة التخزين المؤقت لبروتوكول HTTP، إلا أنّه قد لا يتضمّن استجابات تمر من خلال معالج onfetch لمشغّل الخدمات. لن يؤثر declarativeNetRequest في الاستجابات التي أنشأها مشغّل الخدمات أو التي تم استردادها من CacheStorage، ولكنه سيؤثر في عمليات الاستدعاء إلى fetch() التي يتم إجراؤها في مشغّل الخدمات.

الموارد التي يمكن الوصول إليها على الويب

لا يمكن لقاعدة declarativeNetRequest إعادة التوجيه من طلب مورد عام إلى مورد لا يمكن الوصول إليه من خلال الويب. ويؤدي ذلك إلى حدوث خطأ. وينطبق هذا حتى إذا كان المورد المحدد الذي يمكن الوصول إليه على الويب مملوكًا من خلال إضافة إعادة التوجيه. للإعلان عن موارد declarativeNetRequest، استخدِم مصفوفة "web_accessible_resources" في البيان.

أمثلة

أمثلة على التعليمات البرمجية

تعديل القواعد الديناميكية

يوضح المثال التالي كيفية طلب الرقم updateDynamicRules(). إجراءات updateSessionRules() هي نفسها.

// Get arrays containing new and old rules
const newRules = await getNewRules();
const oldRules = await chrome.declarativeNetRequest.getDynamicRules();
const oldRuleIds = oldRules.map(rule => rule.id);

// Use the arrays to update the dynamic rules
await chrome.declarativeNetRequest.updateDynamicRules({
  removeRuleIds: oldRuleIds,
  addRules: newRules
});

تعديل مجموعات القواعد الثابتة

يوضح المثال التالي كيفية تفعيل أو إيقاف مجموعات القواعد مع الأخذ في الاعتبار عدد مجموعات القواعد الثابتة المتاحة والحد الأقصى لعدد مجموعات القواعد الثابتة المفعَّلة. يمكنك إجراء ذلك عندما يتجاوز عدد القواعد الثابتة التي تحتاجها العدد المسموح به. ولكي يحدث ذلك، يجب تثبيت بعض مجموعات القواعد مع إيقاف بعض منها (مع ضبط "Enabled" على false ضمن ملف البيان).

async function updateStaticRules(enableRulesetIds, disableCandidateIds) {
  // Create the options structure for the call to updateEnabledRulesets()
  let options = { enableRulesetIds: enableRulesetIds }
  // Get the number of enabled static rules
  const enabledStaticCount = await chrome.declarativeNetRequest.getEnabledRulesets();
  // Compare rule counts to determine if anything needs to be disabled so that
  // new rules can be enabled
  const proposedCount = enableRulesetIds.length;
  if (enabledStaticCount + proposedCount > chrome.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS) {
    options.disableRulesetIds = disableCandidateIds
  }
  // Update the enabled static rules
  await chrome.declarativeNetRequest.updateEnabledRulesets(options);
}

أمثلة على القواعد

توضّح الأمثلة التالية كيفية منح Chrome الأولوية للقواعد في إحدى الإضافات. عند مراجعتها، قد تحتاج إلى فتح قواعد تحديد الأولويات في نافذة منفصلة.

مفتاح "الأولوية"

تتطلّب هذه الأمثلة إذن المضيف من أجل *://*.example.com/*.

لتحديد أولوية عنوان URL معيّن، اطّلِع على المفتاح "priority" (من تحديد المطوّر) والمفتاح "action" والمفتاح "urlFilter". تشير هذه الأمثلة إلى مثال ملف القاعدة المعروض أسفلها.

الانتقال إلى https://google.com
تغطّي قاعدتان عنوان URL هذا: القاعدتان اللتان تتضمّنان رقمَي التعريف 1 و4. تسري القاعدة التي تتضمّن رقم التعريف 1 لأنّ الإجراءات "block" لها أولوية أعلى من "redirect" إجراء. ولا تنطبق القواعد المتبقية لأنّها تستهدف عناوين URL الأطول.
الانتقال إلى https://google.com/1234
نظرًا لأن عنوان URL أطول، أصبحت القاعدة ذات رقم التعريف 2 مطابقة الآن بالإضافة إلى القواعد ذات المعرّفين 1 و4. تسري القاعدة التي تتضمّن رقم التعريف 2 لأنّ الأولوية للدالة "allow" أعلى من "block" و"redirect".
الانتقال إلى https://google.com/12345
تتطابق القواعد الأربع جميعها مع عنوان URL هذا. تسري القاعدة التي تتضمّن رقم التعريف 3 لأنّ الأولوية التي يحدِّدها المطوِّر هي أعلى مجموعة في المجموعة.
[
  {
    "id": 1,
    "priority": 1,
    "action": { "type": "block" },
    "condition": {"urlFilter": "google.com", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 2,
    "priority": 1,
    "action": { "type": "allow" },
    "condition": { "urlFilter": "google.com/123", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 3,
    "priority": 2,
    "action": { "type": "block" },
    "condition": { "urlFilter": "google.com/12345", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 4,
    "priority": 1,
    "action": { "type": "redirect", "redirect": { "url": "https://example.com" } },
    "condition": { "urlFilter": "google.com", "resourceTypes": ["main_frame"] }
  },
]

عمليات إعادة التوجيه

يتطلّب المثال أدناه إذن المضيف من أجل *://*.example.com/*.

يوضّح المثال التالي كيفية إعادة توجيه طلب من example.com إلى صفحة داخل الإضافة نفسها. يؤدي مسار الإضافة /a.jpg إلى الانتقال إلى chrome-extension://EXTENSION_ID/a.jpg، حيث يمثّل EXTENSION_ID رقم تعريف الإضافة. لكي يعمل ذلك، يجب أن يذكر البيان /a.jpg باعتباره موردًا يمكن الوصول إليه من خلال الويب.

{
  "id": 1,
  "priority": 1,
  "action": { "type": "redirect", "redirect": { "extensionPath": "/a.jpg" } },
  "condition": {
    "urlFilter": "https://www.example.com",
    "resourceTypes": ["main_frame"]
  }
}

في ما يلي استخدام المفتاح "transform" لإعادة التوجيه إلى نطاق فرعي للموقع example.com. ويستخدم علامة ارتساء اسم النطاق ("||") لاعتراض الطلبات باستخدام أي مخطط من example.com. ويحدّد المفتاح "scheme" في "transform" أنّ عمليات إعادة التوجيه إلى النطاق الفرعي ستستخدم دائمًا "https".

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": {
      "transform": { "scheme": "https", "host": "new.example.com" }
    }
  },
  "condition": {
    "urlFilter": "||example.com",
    "resourceTypes": ["main_frame"]
  }
}

يستخدم المثال التالي تعبيرات عادية لإعادة التوجيه من https://www.abc.xyz.com/path إلى https://abc.xyz.com/path. في مفتاح "regexFilter"، لاحِظ كيفية تخطي النقاط وأن مجموعة الالتقاط تختار "abc" أو "def". يحدد مفتاح "regexSubstitution" أول تطابق تم عرضه للتعبير العادي باستخدام "\1". في هذه الحالة، يتم الحصول على "abc" من عنوان URL المُعاد توجيهه ووضعه في الاستبدال.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": {
      "regexSubstitution": "https://\\1.xyz.com/"
    }
  },
  "condition": {
    "regexFilter": "^https://www\\.(abc|def)\\.xyz\\.com/",
    "resourceTypes": [
      "main_frame"
    ]
  }
}

العناوين

في المثال التالي، تتم إزالة جميع ملفات تعريف الارتباط من الإطار الرئيسي وأي إطارات فرعية.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "modifyHeaders",
    "requestHeaders": [{ "header": "cookie", "operation": "remove" }]
  },
  "condition": { "resourceTypes": ["main_frame", "sub_frame"] }
}

الأنواع

DomainType

يصف هذا ما إذا كان الطلب مخصّصًا أولاً أم طرفًا ثالثًا في الإطار الذي نشأ فيه. ويقال أن الطلب هو الطرف الأول إذا كان له النطاق نفسه (eTLD+1) الذي يتضمّن الإطار الذي نشأ فيه الطلب.

التعداد

"firstparty"
يكون طلب الشبكة هو الطرف الأول في الإطار الذي نشأ فيه.

"الطرف الثالث"
طلب الشبكة هو جهة خارجية تابعة للإطار الذي نشأ فيه.

ExtensionActionOptions

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

أماكن إقامة

  • displayActionCountAsBadgeText

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

    ما إذا كان سيتم عرض عدد الإجراءات لإحدى الصفحات تلقائيًا كنص لشارة الإضافة. ويستمر هذا الخيار المفضّل على مستوى الجلسات.

  • tabUpdate

    TabActionCountUpdate اختيارية

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

    تفاصيل حول كيفية تعديل عدد الإجراءات في علامة التبويب

GetDisabledRuleIdsOptions

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

أماكن إقامة

  • rulesetId

    سلسلة

    رقم التعريف المتجاوب مع Ruleset ثابتة.

GetRulesFilter

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

أماكن إقامة

  • ruleIds

    number[] اختيارية

    وفي حال تحديدها، لا يتم تضمين سوى القواعد ذات أرقام التعريف المطابقة.

HeaderOperation

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

يصف هذا العمليات المحتملة لقاعدة "modifyHeaders".

التعداد

"append"
لإضافة إدخال جديد للعنوان المحدّد. هذه العملية غير متاحة لعناوين الطلبات.

"set"
يضبط هذا الحقل قيمة جديدة للعنوان المحدَّد، مع إزالة أي عناوين حالية تحمل الاسم نفسه.

"remove"
لإزالة جميع الإدخالات الخاصة بالعنوان المحدَّد

IsRegexSupportedResult

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

أماكن إقامة

  • isSupported

    boolean

  • السبب

    UnsupportedRegexReason اختيارية

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

MatchedRule

أماكن إقامة

  • ruleId

    الرقم

    رقم تعريف القاعدة المُطابِقة.

  • rulesetId

    سلسلة

    رقم تعريف Ruleset التي تنتمي إليها هذه القاعدة. بالنسبة إلى أي قاعدة تنشأ من مجموعة القواعد الديناميكية، سيكون ذلك مساويًا لـ DYNAMIC_RULESET_ID.

MatchedRuleInfo

أماكن إقامة

  • قاعدة

    MatchedRule

  • tabId

    الرقم

    TabId لعلامة التبويب التي نشأ منها الطلب، إذا كانت علامة التبويب لا تزال نشطة. غير ذلك -1.

  • timeStamp

    الرقم

    وقت مطابقة القاعدة. ستتوافق الطوابع الزمنية مع اصطلاح JavaScript في الأوقات، أي عدد المللي ثانية منذ الفترة.

MatchedRuleInfoDebug

أماكن إقامة

  • تفاصيل حول الطلب الذي تمت مطابقة القاعدة له.

  • قاعدة

    MatchedRule

MatchedRulesFilter

أماكن إقامة

  • minTimeStamp

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

    وفي حال تحديدها، تتم مطابقة القواعد بعد الطابع الزمني المحدّد فقط.

  • tabId

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

    وفي حال تحديدها، ستتم مطابقة قواعد علامة التبويب المحدّدة فقط. يطابق القواعد غير المرتبطة بأي علامة تبويب نشطة في حال ضبطها على -1.

ModifyHeaderInfo

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

أماكن إقامة

  • header

    سلسلة

    تمثّل هذه السمة اسم العنوان الذي سيتم تعديله.

  • عملية

    HeaderOperation

    العملية التي سيتم تنفيذها على عنوان.

  • القيمة

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

    القيمة الجديدة للعنوان. يجب أن تكون محددة لعمليات append وset.

QueryKeyValue

أماكن إقامة

  • مفتاح

    سلسلة

  • replaceOnly

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

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

    إذا كانت القيمة true، لا يتم استبدال مفتاح طلب البحث إلا إذا كان متوفرًا. بخلاف ذلك، تتم إضافة المفتاح أيضًا إذا كان مفقودًا. يكون الإعداد التلقائي بالقيمة "خطأ".

  • القيمة

    سلسلة

QueryTransform

أماكن إقامة

  • addOrReplaceParams

    QueryKeyValue[] اختيارية

    قائمة بأزواج المفتاح/القيمة لطلب البحث المطلوب إضافتها أو استبدالها.

  • removeParams

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

    قائمة مفاتيح طلبات البحث المطلوب إزالتها

Redirect

أماكن إقامة

  • extensionPath

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

    المسار المرتبط بدليل الإضافة يجب أن يبدأ بـ "/".

  • regexSubstitution

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

    نمط بديل للقواعد التي تحدّد regexFilter سيتم استبدال أول مطابقة لـ regexFilter ضمن عنوان URL بهذا النمط. ضمن regexSubstitution، يمكن استخدام الأرقام ذات الشرطة المائلة للخلف (من \1 إلى \9) لإدراج مجموعات الالتقاط المقابلة. \0 يشير إلى النص المتطابق بالكامل.

  • تحويل

    URLTransform اختياري

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

  • url

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

    عنوان URL لإعادة التوجيه. لا يُسمح بعمليات إعادة التوجيه إلى عناوين URL التي تستخدم JavaScript.

RegexOptions

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

أماكن إقامة

  • isCaseSensitive

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

    تحدِّد هذه السمة ما إذا كانت قيمة regex المحدّدة حسّاسة لحالة الأحرف. الإعداد التلقائي صحيح.

  • تعبير عادي

    سلسلة

    السريع العادي المطلوب التحقق منه.

  • requireCapturing

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

    ما إذا كان regex المحدّد يتطلّب الالتقاط. لا يلزم الالتقاط إلا لقواعد إعادة التوجيه التي تحدِّد إجراء regexSubstition. والقيمة التلقائية هي false.

RequestDetails

أماكن إقامة

  • documentId

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

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

    المعرّف الفريد لمستند الإطار، إذا كان هذا الطلب متعلقًا بإطار

  • documentLifecycle

    DocumentLifecycle اختيارية

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

    دورة حياة مستند الإطار، إذا كان هذا الطلب متعلقًا بإطار.

  • frameId

    الرقم

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

  • frameType

    FrameType اختيارية

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

    نوع الإطار إذا كان هذا الطلب متعلقًا بإطار

  • بادئ تشغيل

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

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

  • method

    سلسلة

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

  • parentDocumentId

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

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

    المعرّف الفريد للمستند الأصلي للإطار، إذا كان هذا الطلب متعلقًا بإطار وله أصل.

  • parentFrameId

    الرقم

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

  • requestId

    سلسلة

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

  • tabId

    الرقم

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

  • كتابة

    ResourceType

    نوع مورد الطلب.

  • url

    سلسلة

    عنوان URL للطلب.

RequestMethod

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

يصف هذا طريقة طلب HTTP لطلب الشبكة.

التعداد

"connect"

"get"

"head"

"options"

"put"

ResourceType

يصف هذا نوع المورد الخاص بطلب الشبكة.

التعداد

"main_frame"

"sub_frame"

"script"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"webtransport"

Rule

أماكن إقامة

  • إجراء

    RuleAction

    الإجراء الذي يتم اتخاذه في حال مطابقة هذه القاعدة.

  • الشرط

    RuleCondition

    الشرط الذي يتم تفعيل هذه القاعدة بموجبه.

  • id

    الرقم

    معرّف يعرّف القاعدة بشكل فريد. إلزامية ويجب أن تكون >= 1.

  • الحملة

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

    أولوية القاعدة يكون الإعداد التلقائي بالقيمة 1. عند تحديدها، يجب أن تكون >= 1.

RuleAction

أماكن إقامة

  • إعادة توجيه

    إعادة التوجيه اختيارية

    تصف هذه السمة كيف يجب تنفيذ إعادة التوجيه. صالح فقط لقواعد إعادة التوجيه.

  • requestHeaders

    ModifyHeaderInfo[] اختيارية

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

    عناوين الطلب المطلوب تعديلها لا يكون هذا الحقل صالحًا إلا إذا كانت قيمة RuleActionType هي "modifyHeaders".

  • responseHeaders

    ModifyHeaderInfo[] اختيارية

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

    عناوين الاستجابة المطلوب تعديلها للطلب. لا يكون هذا الحقل صالحًا إلا إذا كانت قيمة RuleActionType هي "modifyHeaders".

  • كتابة

    RuleActionType

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

RuleActionType

تصف نوع الإجراء الذي يجب اتخاذه في حال تطابق شرط قاعدة معيّن.

التعداد

"block"
حظر طلب الشبكة

"redirect"
إعادة توجيه طلب الشبكة

"allow"
السماح بطلب الشبكة: ولن يتم اعتراض الطلب في حال توفُّر قاعدة السماح تطابقه.

"upgradeScheme"
عليك ترقية مخطط عنوان URL لطلب الشبكة إلى https إذا كان الطلب http أو ftp.

"modifyHeaders"
تعديل عناوين الطلبات/الاستجابة من طلب الشبكة

"allowAllRequests"
السماح بجميع الطلبات ضمن التدرج الهرمي للإطارات، بما في ذلك طلب الإطار نفسه

RuleCondition

أماكن إقامة

  • domainType

    DomainType اختياري

    يُحدِّد ما إذا كان طلب الشبكة هو الطرف الأول أو طرف ثالث للنطاق الذي نشأ منه. في حال حذفها، يتم قبول جميع الطلبات.

  • نطاقات

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

    تم إيقافه نهائيًا منذ استخدام الإصدار 101 من Chrome

    استخدام initiatorDomains كبديل

    لن تتطابق القاعدة إلا مع طلبات الشبكة الصادرة من قائمة domains.

  • excludedDomains

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

    تم إيقافه نهائيًا منذ استخدام الإصدار 101 من Chrome

    استخدام excludedInitiatorDomains كبديل

    لن تتطابق القاعدة مع طلبات الشبكة الصادرة من قائمة excludedDomains.

  • excludedInitiatorDomains

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

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

    لن تتطابق القاعدة مع طلبات الشبكة الصادرة من قائمة excludedInitiatorDomains. إذا كانت القائمة فارغة أو تم حذفها، لن يتم استبعاد أي نطاقات. وتكون لها الأولوية على initiatorDomains.

    ملاحظات:

    • ويُسمح أيضًا بالنطاقات الفرعية مثل "a.example.com".
    • يجب أن تتكون الإدخالات من أحرف ASCII فقط.
    • استخدِم ترميز punycode للنطاقات الدولية.
    • يتطابق هذا العنصر مع بادئ بدء الطلب وليس مع عنوان URL للطلب.
    • يتم أيضًا استبعاد النطاقات الفرعية للنطاقات المدرَجة.
  • excludedRequestDomains

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

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

    لن تتطابق القاعدة مع طلبات الشبكة عندما تتطابق النطاقات مع نطاق من قائمة excludedRequestDomains. إذا كانت القائمة فارغة أو تم حذفها، لن يتم استبعاد أي نطاقات. وتكون لها الأولوية على requestDomains.

    ملاحظات:

    • ويُسمح أيضًا بالنطاقات الفرعية مثل "a.example.com".
    • يجب أن تتكون الإدخالات من أحرف ASCII فقط.
    • استخدِم ترميز punycode للنطاقات الدولية.
    • يتم أيضًا استبعاد النطاقات الفرعية للنطاقات المدرَجة.
  • excludedRequestMethods

    RequestMethod[] اختيارية

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

    قائمة بطرق الطلب التي لن تتطابق معها القاعدة. يجب تحديد سمة واحدة فقط من requestMethods وexcludedRequestMethods. في حال عدم تحديد أيٍّ منهما، تتم مطابقة جميع طرق الطلب.

  • excludedResourceTypes

    ResourceType[] اختيارية

    قائمة بأنواع الموارد التي لن تتطابق معها القاعدة. يجب تحديد سمة واحدة فقط من resourceTypes وexcludedResourceTypes. وإذا لم يتم تحديد أي منهما، يتم حظر جميع أنواع الموارد باستثناء "main_frame".

  • excludedTabIds

    number[] اختيارية

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

    قائمة tabs.Tab.id التي يجب ألا تتطابق معها القاعدة. يستبعد رقم تعريف tabs.TAB_ID_NONE الطلبات التي لا تنشأ من علامة تبويب. متاحة فقط للقواعد على مستوى الجلسة.

  • initiatorDomains

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

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

    لن تتطابق القاعدة إلا مع طلبات الشبكة الصادرة من قائمة initiatorDomains. وإذا تم حذف القائمة، يتم تطبيق القاعدة على الطلبات الواردة من جميع النطاقات. قائمة فارغة غير مسموح بها.

    ملاحظات:

    • ويُسمح أيضًا بالنطاقات الفرعية مثل "a.example.com".
    • يجب أن تتكون الإدخالات من أحرف ASCII فقط.
    • استخدِم ترميز punycode للنطاقات الدولية.
    • يتطابق هذا العنصر مع بادئ بدء الطلب وليس مع عنوان URL للطلب.
    • وتتم أيضًا مطابقة النطاقات الفرعية للنطاقات المدرَجة.
  • isUrlFilterCaseSensitive

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

    تحدّد هذه السمة ما إذا كان urlFilter أو regexFilter (أيهما محدّد) حسّاسًا لحالة الأحرف. والقيمة التلقائية هي "خطأ".

  • regexFilter

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

    تعبير عادي للمطابقة مع عنوان URL لطلب الشبكة ويتبع ذلك بنية RE2.

    ملاحظة: يمكن تحديد سمة واحدة فقط من urlFilter أو regexFilter.

    ملاحظة: يجب أن يتكوّن regexFilter من أحرف ASCII فقط. يتطابق هذا مع عنوان URL حيث يتم ترميز المضيف بتنسيق punycode (في حالة النطاقات الدولية) وأي أحرف أخرى غير ASCII هي عنوان URL بترميز utf-8.

  • requestDomains

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

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

    لن تتطابق القاعدة مع طلبات الشبكة إلا عندما يتطابق النطاق مع طلب واحد من قائمة requestDomains. وإذا تم حذف القائمة، يتم تطبيق القاعدة على الطلبات الواردة من جميع النطاقات. قائمة فارغة غير مسموح بها.

    ملاحظات:

    • ويُسمح أيضًا بالنطاقات الفرعية مثل "a.example.com".
    • يجب أن تتكون الإدخالات من أحرف ASCII فقط.
    • استخدِم ترميز punycode للنطاقات الدولية.
    • وتتم أيضًا مطابقة النطاقات الفرعية للنطاقات المدرَجة.
  • requestMethods

    RequestMethod[] اختيارية

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

    قائمة بطرق طلب HTTP التي يمكن أن تتطابق معها القاعدة. قائمة فارغة غير مسموح بها.

    ملاحظة: سيؤدي تحديد شرط قاعدة requestMethods إلى استبعاد الطلبات التي لا تستخدم بروتوكول HTTP، في حين أنّ تحديد excludedRequestMethods لن يستبعد الطلبات التي لا تستخدم بروتوكول HTTP.

  • resourceTypes

    ResourceType[] اختيارية

    قائمة بأنواع الموارد التي يمكن أن تتطابق معها القاعدة. قائمة فارغة غير مسموح بها.

    ملاحظة: يجب تحديد هذا الخيار لقواعد allowAllRequests، وقد يتضمّن فقط نوعَي الموارد sub_frame وmain_frame.

  • tabIds

    number[] اختيارية

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

    قائمة tabs.Tab.id التي يجب أن تتطابق معها القاعدة. يتطابق رقم تعريف tabs.TAB_ID_NONE مع الطلبات التي لا تنشأ من علامة تبويب. قائمة فارغة غير مسموح بها. متاحة فقط للقواعد على مستوى الجلسة.

  • urlFilter

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

    النمط الذي تمت مطابقته مع عنوان URL لطلب الشبكة. التركيبات المتوافقة:

    '*' : حرف البدل: يطابق أي عدد من الأحرف.

    '|' : ارتساء أيسر/يمين: إذا تم استخدامه في أي من نهاية النمط، يتم تحديد بداية/نهاية عنوان URL على التوالي.

    '||' : ارتساء اسم النطاق: إذا تم استخدامه في بداية النمط، يتم تحديد بداية نطاق (- فرعي) لعنوان URL.

    '^' : حرف فاصل: يتطابق هذا مع أي حرف باستثناء حرف أو رقم أو أي مما يلي: _ أو - أو . أو %. ويتطابق ذلك أيضًا مع نهاية عنوان URL.

    وبالتالي، يتألف urlFilter من الأجزاء التالية: (إرساء اختياري لاسم النطاق/الأيسر) + النمط + (إرساء أيمن اختياري).

    تتم مطابقة جميع عناوين URL في حال حذفها. لا يُسمح باستخدام سلسلة فارغة.

    لا يُسمح بنمط يبدأ بـ ||*. يمكنك استخدام * كبديل.

    ملاحظة: يمكن تحديد سمة واحدة فقط من urlFilter أو regexFilter.

    ملاحظة: يجب أن يتكوّن urlFilter من أحرف ASCII فقط. يتطابق هذا مع عنوان URL حيث يتم ترميز المضيف بتنسيق punycode (في حالة النطاقات الدولية) وأي أحرف أخرى غير ASCII هي عنوان URL بترميز utf-8. على سبيل المثال، عندما يكون عنوان URL للطلب هو http://abc.рFORM?q=FORM، ستتم مطابقة السمة urlFilter مع عنوان URL التالي: http://abc.xn--p1ai/?q=%D1%84.

Ruleset

أماكن إقامة

  • مفعّلة

    boolean

    ما إذا كانت مجموعة القواعد مفعَّلة تلقائيًا.

  • id

    سلسلة

    سلسلة غير فارغة تعرِّف مجموعة القواعد بشكلٍ فريد. إنّ المعرّفات التي تبدأ بـ "_" محجوزة للاستخدام الداخلي.

  • المسار

    سلسلة

    مسار مجموعة قواعد JSON ذات الصلة بدليل الإضافة

RulesMatchedDetails

أماكن إقامة

  • rulesMatchedInfo

    MatchedRuleInfo[]

    قواعد تتطابق مع الفلتر المحدّد.

TabActionCountUpdate

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

أماكن إقامة

  • زيادة

    الرقم

    المبلغ المطلوب زيادة عدد الإجراءات لعلامة التبويب به. وستؤدي القيم السالبة إلى تقليل العدد.

  • tabId

    الرقم

    علامة التبويب التي يتم تعديل عدد الإجراءات لها

TestMatchOutcomeResult

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

أماكن إقامة

  • matchedRules

    MatchedRule[]

    القواعد (إن وجدت) التي تتطابق مع الطلب الافتراضي.

TestMatchRequestDetails

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

أماكن إقامة

  • بادئ تشغيل

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

    عنوان URL الذي بدأ الطلب (إن وجد) للطلب الافتراضي

  • method

    RequestMethod اختيارية

    طريقة HTTP عادية للطلب الافتراضي. يتم ضبط الإعداد التلقائي على "get" لطلبات HTTP، ويتم تجاهله للطلبات التي لا تستخدم HTTP.

  • tabId

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

    رقم تعريف علامة التبويب التي يحدث فيها الطلب الافتراضي. لا يجب أن يتطابق مع معرّف علامة تبويب حقيقي. القيمة التلقائية هي -1، ما يعني أنّ الطلب غير مرتبط بعلامة تبويب.

  • كتابة

    ResourceType

    نوع مرجع الطلب الافتراضي

  • url

    سلسلة

    تمثّل هذه السمة عنوان URL للطلب الافتراضي.

UnsupportedRegexReason

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

تصف هذه السمة سبب عدم توافق تعبير عادي معيّن.

التعداد

"syntaxError"
التعبير العادي غير صحيح من ناحية البنية أو يستخدم ميزات غير متاحة في بنية RE2.

"memorylimitExceeded"
يتجاوز التعبير العادي الحد المسموح به للذاكرة.

UpdateRuleOptions

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

أماكن إقامة

  • addRules

    القاعدة[] اختيارية

    القواعد التي يجب إضافتها.

  • removeRuleIds

    number[] اختيارية

    معرّفات القواعد المطلوب إزالتها. وسيتم تجاهل أي معرّفات غير صالحة.

UpdateRulesetOptions

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

أماكن إقامة

  • disableRulesetIds

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

    مجموعة أرقام التعريف المقابلة لـ Ruleset ثابتة التي يجب إيقافها.

  • enableRulesetIds

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

    مجموعة أرقام التعريف المقابلة لـ Ruleset ثابتة التي يجب تفعيلها.

UpdateStaticRulesOptions

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

أماكن إقامة

  • disableRuleIds

    number[] اختيارية

    مجموعة من أرقام التعريف المقابلة للقواعد في Ruleset التي يجب إيقافها.

  • enableRuleIds

    number[] اختيارية

    مجموعة من أرقام التعريف المقابلة للقواعد في Ruleset المطلوب تفعيلها.

  • rulesetId

    سلسلة

    رقم التعريف المتجاوب مع Ruleset ثابتة.

URLTransform

أماكن إقامة

  • جزء

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

    الجزء الجديد للطلب. يجب أن يكون الحقل فارغًا، وفي هذه الحالة يتم محو الجزء الحالي، أو يجب أن يبدأ بـ "#".

  • مضيف

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

    المضيف الجديد للطلب.

  • كلمة مرور

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

    كلمة المرور الجديدة للطلب.

  • المسار

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

    المسار الجديد للطلب. إذا كان هذا الحقل فارغًا، سيتم محو المسار الحالي.

  • المنفذ

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

    المنفذ الجديد للطلب إذا كان المنفذ فارغًا، سيتم محو المنفذ الحالي.

  • query

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

    الاستعلام الجديد للطلب. ويجب أن يكون فارغًا، وفي هذه الحالة يتم محو الاستعلام الحالي؛ أو يجب أن يبدأ بـ "?".

  • queryTransform

    QueryTransform اختيارية

    إضافة أزواج المفتاح/القيمة أو إزالتها أو استبدالها في طلب البحث

  • المخطط

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

    المخطط الجديد للطلب. القيم المسموح بها هي "http" و"https" و"ftp" و "chrome-extension".

  • اسم مستخدم

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

    اسم المستخدم الجديد للطلب.

أماكن إقامة

DYNAMIC_RULESET_ID

رقم تعريف مجموعة القواعد للقواعد الديناميكية التي أضافتها الإضافة.

القيمة

GETMATCHEDRULES_QUOTA_INTERVAL

الفاصل الزمني الذي يمكن خلاله إجراء مكالمات MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules، يتم تحديده بالدقائق. لن تنجح المكالمات الإضافية على الفور وسيتم ضبط runtime.lastError. ملاحظة: يتم استثناء مكالمات getMatchedRules المرتبطة بإيماءة مستخدم من الحصة.

القيمة

10

GUARANTEED_MINIMUM_STATIC_RULES

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

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

القيمة

30,000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

عدد المرّات التي يمكن فيها الاتصال بـ "getMatchedRules" خلال فترة GETMATCHEDRULES_QUOTA_INTERVAL.

القيمة

20

MAX_NUMBER_OF_DYNAMIC_RULES

الحدّ الأقصى لعدد القواعد الديناميكية التي يمكن لأي إضافة إدراجها.

القيمة

30,000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

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

الحد الأقصى لعدد Rulesets الثابتة التي يمكن للإضافة تفعيلها في أي وقت.

القيمة

50

MAX_NUMBER_OF_REGEX_RULES

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

القيمة

1,000

MAX_NUMBER_OF_SESSION_RULES

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

الحدّ الأقصى لعدد القواعد على مستوى الجلسة التي يمكن لأي إضافة إدراجها.

القيمة

5,000

MAX_NUMBER_OF_STATIC_RULESETS

الحد الأقصى لعدد Rulesets الثابتة التي يمكن للإضافة تحديدها كجزء من مفتاح بيان "rule_resources"

القيمة

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

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

الحدّ الأقصى لعدد القواعد الديناميكية "غير الآمنة" التي يمكن أن تدرجها إحدى الإضافات.

القيمة

5,000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

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

الحدّ الأقصى لعدد القواعد "غير الآمنة" على مستوى الجلسة التي يمكن للإضافة إدراجها.

القيمة

5,000

SESSION_RULESET_ID

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

رقم تعريف مجموعة القواعد للقواعد على مستوى الجلسة التي أضافتها الإضافة.

القيمة

"_session"

الطُرق

getAvailableStaticRuleCount()

الوعد الإصدار 89 من Chrome أو الإصدارات الأحدث 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
)

تعرض عدد القواعد الثابتة التي يمكن للإضافة تفعيلها قبل الوصول إلى الحد الأقصى للقواعد الثابتة الشاملة.

المَعلمات

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

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

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

    (count: number)=>void

    • العدد

      الرقم

المرتجعات

  • وعد<الرقم>

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

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

getDisabledRuleIds()

البيانات المضمونة Chrome 111 والإصدارات الأحدث 
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
  callback?: function,
)

لعرض قائمة القواعد الثابتة غير المفعَّلة حاليًا في Ruleset.

المَعلمات

  • الخيارات

    GetDisabledRuleIdsOptions

    تحدّد هذه السمة مجموعة القواعد المطلوب طلبها.

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

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

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

    (disabledRuleIds: number[])=>void

    • disabledRuleIds

      الرقم[]

المرتجعات

  • وعد<رقم[]>

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

getDynamicRules()

وعد 
chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
  callback?: function,
)

تعرض المجموعة الحالية من القواعد الديناميكية للإضافة. يمكن للمتصلين اختياريًا فلترة قائمة القواعد التي تم جلبها من خلال تحديد filter.

المَعلمات

  • filter

    GetRulesFilter اختيارية

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

    كائن لفلترة قائمة القواعد التي تم جلبها.

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

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

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

    (rules: Rule[])=>void

المرتجعات

  • وعد<قاعدة[]>

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

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

getEnabledRulesets()

وعد 
chrome.declarativeNetRequest.getEnabledRulesets(
  callback?: function,
)

تعرض أرقام تعريف المجموعة الحالية لمجموعات القواعد الثابتة المفعَّلة.

المَعلمات

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

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

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

    (rulesetIds: string[])=>void

    • rulesetIds

      سلسلة[]

المرتجعات

  • وعد<string[]>

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

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

getMatchedRules()

وعد 
chrome.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
  callback?: function,
)

تعرض جميع القواعد المطابقة للإضافة. يمكن للمتصلين اختياريًا فلترة قائمة القواعد المطابقة عن طريق تحديد filter. لا تتوفّر هذه الطريقة إلا للإضافات التي لديها إذن ""declarativeNetRequestFeedback"" أو التي لديها إذن ""activeTab"" ممنوح للإضافة "tabId" المحدّدة في "filter". ملاحظة: لن يتم عرض القواعد غير المرتبطة بمستند نشط تمت مطابقته قبل أكثر من خمس دقائق.

المَعلمات

  • filter

    MatchedRulesFilter اختيارية

    كائن لفلترة قائمة القواعد المُطابِقة.

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

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

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

    (details: RulesMatchedDetails)=>void

المرتجعات

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

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

getSessionRules()

الوعد الإصدار 90 من Chrome أو الإصدارات الأحدث 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
  callback?: function,
)

تعرِض المجموعة الحالية من القواعد على مستوى الجلسة للإضافة. يمكن للمتصلين اختياريًا فلترة قائمة القواعد التي تم جلبها من خلال تحديد filter.

المَعلمات

  • filter

    GetRulesFilter اختيارية

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

    كائن لفلترة قائمة القواعد التي تم جلبها.

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

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

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

    (rules: Rule[])=>void

المرتجعات

  • وعد<قاعدة[]>

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

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

isRegexSupported()

الوعد الإصدار 87 من Chrome أو الإصدارات الأحدث 
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
  callback?: function,
)

للتحقّق مما إذا كان التعبير العادي المحدّد سيصبح متاحًا كشرط للقاعدة regexFilter.

المَعلمات

  • regexOptions

    RegexOptions

    التعبير العادي المطلوب التحقّق منه.

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

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

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

    (result: IsRegexSupportedResult)=>void

المرتجعات

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

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

setExtensionActionOptions()

البيانات المضمونة Chrome 88 والإصدارات الأحدث 
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
  callback?: function,
)

تحدِّد هذه السياسة ما إذا كان يجب عرض عدد الإجراءات لعلامات التبويب كنص لشارة إجراء الإضافة، وتوفّر طريقة لزيادة عدد هذا الإجراءات.

المَعلمات

  • الخيارات

    ExtensionActionOptions

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

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

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

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

    ()=>void

المرتجعات

  • Promise<void>

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

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

testMatchOutcome()

الوعد Chrome 103 والإصدارات الأحدث 
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
)

تتحقّق مما إذا كانت أي من قواعد deflarativeNetRequest للإضافة تتطابق مع طلب افتراضي. ملاحظة: لا تتوفّر هذه الميزة إلا للإضافات التي تم فك ضغطها، وذلك لأنّه يتم استخدامها فقط أثناء تطوير الإضافات.

المَعلمات

المرتجعات

  • تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

updateDynamicRules()

وعد 
chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
  callback?: function,
)

لتعديل المجموعة الحالية من القواعد الديناميكية للإضافة. تتم أولاً إزالة القواعد التي لها أرقام تعريف مُدرَجة في options.removeRuleIds، ثم تُضاف القواعد المقدَّمة في options.addRules. ملاحظات:

  • يتم هذا التعديل من خلال عملية شاملة واحدة: إمّا إضافة جميع القواعد المحدَّدة وإزالتها أو عرض خطأ.
  • تظل هذه القواعد سارية في جميع جلسات المتصفِّح وفي جميع تحديثات الإضافات.
  • لا يمكن إزالة القواعد الثابتة المحدّدة كجزء من حزمة الإضافة باستخدام هذه الدالة.
  • MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES هو الحد الأقصى لعدد القواعد الديناميكية المجمّعة وقواعد الجلسات التي يمكن لأي إضافة إدراجها.

المَعلمات

  • الخيارات

    UpdateRuleOptions

    الإصدار 87 من Chrome والإصدارات الأحدث
  • معاودة الاتصال

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

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

    ()=>void

المرتجعات

  • Promise<void>

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

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

updateEnabledRulesets()

وعد 
chrome.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
  callback?: function,
)

تُعدِّل مجموعة القواعد الثابتة المفعَّلة للإضافة. تتم أولاً إزالة مجموعات القواعد التي لها أرقام تعريف مُدرَجة في options.disableRulesetIds، ثم تتم إضافة مجموعات القواعد المدرَجة في options.enableRulesetIds. تجدر الإشارة إلى أنّ مجموعة القواعد الثابتة المفعّلة تظلّ في جميع الجلسات وليس على مستوى تحديثات الإضافات، أي أنّ مفتاح البيان rule_resources سيحدِّد مجموعة القواعد الثابتة المفعَّلة في كل تحديث للإضافة.

المَعلمات

  • الخيارات

    UpdateRulesetOptions

    الإصدار 87 من Chrome والإصدارات الأحدث
  • معاودة الاتصال

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

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

    ()=>void

المرتجعات

  • Promise<void>

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

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

updateSessionRules()

الوعد الإصدار 90 من Chrome أو الإصدارات الأحدث 
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
  callback?: function,
)

يُعدّل المجموعة الحالية من القواعد على مستوى الجلسة للإضافة. تتم أولاً إزالة القواعد التي لها أرقام تعريف مُدرَجة في options.removeRuleIds، ثم تُضاف القواعد المقدَّمة في options.addRules. ملاحظات:

  • يتم هذا التعديل من خلال عملية شاملة واحدة: إمّا إضافة جميع القواعد المحدَّدة وإزالتها أو عرض خطأ.
  • لا يتم الاحتفاظ بهذه القواعد في جميع الجلسات ويتم الاحتفاظ بنسخة احتياطية منها في الذاكرة.
  • MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES هو الحد الأقصى لعدد القواعد الديناميكية المجمّعة وقواعد الجلسات التي يمكن لأي إضافة إدراجها.

المَعلمات

  • الخيارات

    UpdateRuleOptions

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

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

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

    ()=>void

المرتجعات

  • Promise<void>

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

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

updateStaticRules()

البيانات المضمونة Chrome 111 والإصدارات الأحدث 
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
  callback?: function,
)

لإيقاف القواعد الثابتة الفردية وتفعيلها في Ruleset وتصبح التغييرات التي تطرأ على القواعد التي تخص Ruleset غير مفعَّلة في المرة التالية التي يتم فيها تفعيل هذه الميزة.

المَعلمات

  • الخيارات

    UpdateStaticRulesOptions

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

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

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

    ()=>void

المرتجعات

  • Promise<void>

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

فعاليات

onRuleMatchedDebug

chrome.declarativeNetRequest.onRuleMatchedDebug.addListener(
  callback: function,
)

يتم تنشيطها عند مطابقة قاعدة مع طلب. لا تتوفّر هذه الميزة إلا للإضافات التي تم فك ضغطها والتي لديها إذن "declarativeNetRequestFeedback"، لأنّ هذه الميزة مخصّصة للاستخدام لأغراض تصحيح الأخطاء فقط.

المَعلمات