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. الحد الأقصى لعدد القواعد الثابتة غير المفعّلة هو 5,000 قاعدة.

لتفعيل مجموعات القواعد الثابتة أو إيقافها، استخدِم الدالة 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"]   } }

مطابقة عناوين URL

توفّر Declarative Net Request إمكانية مطابقة عناوين URL مع بنية مطابقة الأنماط أو التعبيرات العادية.

بنية فلتر عناوين URL

يسمح المفتاح "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://a.example.company		 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

التعبيرات العادية

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

كتابة شروط جيدة لعناوين URL

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

  • google.com تطابق https://example.com/?param=google.com بشكلٍ غير صحيح
  • ||google.com تطابق https://google.company بشكلٍ غير صحيح
  • https://www.google.com تطابق https://example.com/?param=https://www.google.com بشكلٍ غير صحيح

ننصحك باستخدام:

  • ‫||google.com/، الذي يتطابق مع جميع المسارات وجميع النطاقات الفرعية
  • ‫|https://www.google.com/ الذي يطابق جميع المسارات ولا يطابق أي نطاقات فرعية

وبالمثل، استخدِم الرمزين ^ و/ لتثبيت تعبير عادي. على سبيل المثال، يتطابق ^https:\/\/www\.google\.com\/ مع أي مسار على https://www.google.com.

تقييم القاعدة

يطبّق المتصفّح قواعد "عدم التتبّع" في مراحل مختلفة من دورة حياة طلب الشبكة.

قبل تقديم الطلب

قبل إرسال الطلب، يمكن لإحدى الإضافات حظره أو إعادة توجيهه (بما في ذلك ترقية المخطط من HTTP إلى HTTPS) باستخدام قاعدة مطابقة.

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

بعد ذلك، يختار Chrome مرشحًا واحدًا على الأكثر لكل طلب. يعثر Chrome على قاعدة مطابقة من خلال ترتيب جميع القواعد المطابقة حسب الأولوية. يتم ترتيب القواعد التي لها الأولوية نفسها حسب الإجراء (allow أو allowAllRequests > block > upgradeScheme > redirect).

إذا كان المرشّح هو قاعدة allow أو allowAllRequests، أو إذا كان الإطار الذي يتم فيه تقديم الطلب قد تطابق سابقًا مع قاعدة allowAllRequests ذات أولوية أعلى أو مساوية من هذه الإضافة، سيتم "السماح" بالطلب ولن يكون للإضافة أي تأثير عليه.

إذا أرادت أكثر من إضافة واحدة حظر هذا الطلب أو إعادة توجيهه، سيتم اختيار إجراء واحد. يُجري Chrome ذلك من خلال ترتيب القواعد بالترتيب block > redirect أو upgradeScheme > allow أو allowAllRequests. إذا كان نوعا القاعدتين متماثلَين، يختار Chrome القاعدة من الإضافة التي تم تثبيتها مؤخرًا.

قبل إرسال عناوين الطلبات

قبل أن يرسل Chrome عناوين الطلبات إلى الخادم، يتم تعديل العناوين استنادًا إلى قواعد modifyHeaders المطابقة.

ضمن إضافة واحدة، ينشئ Chrome قائمة بالتعديلات التي سيتم إجراؤها من خلال العثور على جميع قواعد modifyHeaders المطابقة. كما كان الحال من قبل، يتم تضمين القواعد التي لها أولوية أعلى من أي قواعد مطابقة allow أو allowAllRequests فقط.

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

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

عند تلقّي ردّ

بعد تلقّي عناوين الاستجابة، يقيّم Chrome القواعد التي تتضمّن شرط responseHeaders.

بعد ترتيب هذه القواعد حسب action وpriority واستبعاد أي قواعد أصبحت غير ضرورية بسبب قاعدة allow أو allowAllRequests مطابقة (يحدث ذلك بشكل مطابق للخطوات الواردة في "قبل الطلب")، قد يحظر Chrome الطلب أو يعيد توجيهه نيابةً عن إحدى الإضافات.

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

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

إذا لم يتم حظر الطلب أو إعادة توجيهه، يطبِّق Chrome أي قواعد modifyHeaders. يعمل تطبيق التعديلات على عناوين الاستجابة بالطريقة نفسها الموضّحة في "قبل إرسال عناوين الطلبات". لا يؤدي تطبيق تعديلات على عناوين الطلبات إلى أي نتيجة، لأنّه تم إرسال الطلب من قبل.

قواعد الأمان

يتم تعريف القواعد الآمنة على أنّها قواعد تتضمّن إجراءً من block أو allow أو allowAllRequests أو upgradeScheme. تخضع هذه القواعد لحصة أكبر من القواعد الديناميكية.

حدود القواعد

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

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

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

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

قواعد الجلسات

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

قبل الإصدار 120 من Chrome، كان هناك حد يبلغ 5000 قاعدة ديناميكية وقاعدة جلسة مجمّعة.

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

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

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

قبل الإصدار 120 من Chrome، كان هناك حد يبلغ 5000 قاعدة مجمّعة ديناميكية وقاعدة جلسة.

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

يمكن استخدام التعبيرات العادية مع جميع أنواع القواعد، ولكن يجب ألا يتجاوز العدد الإجمالي لقواعد التعبيرات العادية من كل نوع 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" في ملف البيان.

تعديل العنوان

لا تتوافق عملية الإلحاق إلا مع العناوين التالية: accept وaccept-encoding وaccept-language وaccess-control-request-headers وcache-control وconnection وcontent-language وcookie وforwarded وif-match وif-none-match وkeep-alive وrange وte وtrailer وtransfer-encoding وupgrade وuser-agent وvia وwant-digest وx-forwarded-for.

أمثلة

أمثلة على الرموز

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

يوضّح المثال التالي كيفية الاتصال بـ 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) مثل الإطار الذي نشأ فيه الطلب.

Enum

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

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

ExtensionActionOptions

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

الخصائص

  • displayActionCountAsBadgeText

    boolean اختياري

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

  • tabUpdate

    TabActionCountUpdate اختياري

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

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

GetDisabledRuleIdsOptions

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

الخصائص

  • rulesetId

    سلسلة

    المعرّف الذي يتوافق مع Ruleset ثابت.

GetRulesFilter

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

الخصائص

  • ruleIds

    number[] اختيارية

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

HeaderInfo

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

الخصائص

  • excludedValues

    string[] اختياري

    في حال تحديدها، لا تتم مطابقة هذا الشرط إذا كان العنوان متوفّرًا ولكن قيمته تحتوي على عنصر واحد على الأقل في هذه القائمة. يستخدم هذا الخيار بنية نمط المطابقة نفسها المستخدَمة في values.

  • header

    سلسلة

    تمثّل هذه السمة اسم العنوان. لا يتطابق هذا الشرط مع الاسم إلا إذا لم يتم تحديد كل من values وexcludedValues.

  • values

    string[] اختياري

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

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

    علامة الاستفهام (؟) : تتطابق مع صفر أو حرف واحد.

    يمكن إلغاء الحرفين "*" و"؟" باستخدام شرطة مائلة عكسية، مثل "\*" و"\؟".

HeaderOperation

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

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

Enum

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

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

"remove"
تزيل جميع الإدخالات للعنوان المحدّد.

IsRegexSupportedResult

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

الخصائص

  • isSupported

    قيمة منطقية

  • السبب

    UnsupportedRegexReason اختياري

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

MatchedRule

الخصائص

  • ruleId

    الرقم

    معرّف قاعدة مطابقة

  • rulesetId

    سلسلة

    تمثّل هذه السمة معرّف Ruleset الذي تنتمي إليه هذه القاعدة. بالنسبة إلى قاعدة مصدرها مجموعة القواعد الديناميكية، ستكون هذه القيمة مساوية DYNAMIC_RULESET_ID.

MatchedRuleInfo

الخصائص

  • قاعدة

    MatchedRule

  • tabId

    الرقم

    تمثّل هذه السمة رقم تعريف علامة التبويب التي نشأ منها الطلب إذا كانت علامة التبويب لا تزال نشطة. بخلاف ذلك، تكون القيمة -1.

  • timeStamp

    الرقم

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

MatchedRuleInfoDebug

الخصائص

MatchedRulesFilter

الخصائص

  • minTimeStamp

    number اختياري

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

  • tabId

    number اختياري

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

ModifyHeaderInfo

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

الخصائص

  • header

    سلسلة

    اسم العنوان المطلوب تعديله

  • عملية

    HeaderOperation

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

  • القيمة

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

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

QueryKeyValue

الخصائص

  • مفتاح

    سلسلة

  • replaceOnly

    boolean اختياري

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

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

  • القيمة

    سلسلة

QueryTransform

الخصائص

  • addOrReplaceParams

    QueryKeyValue[] اختياري

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

  • removeParams

    string[] اختياري

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

Redirect

الخصائص

  • extensionPath

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

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

  • regexSubstitution

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

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

  • تحويل

    URLTransform اختياري

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

  • url

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

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

RegexOptions

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

الخصائص

  • isCaseSensitive

    boolean اختياري

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

  • تعبير عادي

    سلسلة

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

  • requireCapturing

    boolean اختياري

    توضّح هذه السمة ما إذا كان يجب تسجيل regex المحدّد. لا يكون التسجيل مطلوبًا إلا لقواعد إعادة التوجيه التي تحدّد إجراء regexSubstition. القيمة التلقائية هي "خطأ".

RequestDetails

الخصائص

  • documentId

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

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

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

  • documentLifecycle

    ‫DocumentLifecycle اختياري

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

    تمثّل هذه السمة دورة حياة مستند الإطار، إذا كان هذا الطلب مخصّصًا لإطار.

  • frameId

    الرقم

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

  • frameType

    ‫FrameType اختياري

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

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

  • بادئ التشغيل

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

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

  • method

    سلسلة

    طريقة HTTP عادية

  • parentDocumentId

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

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

    المعرّف الفريد للمستند الرئيسي للإطار، إذا كان هذا الطلب مخصّصًا لإطار ويتضمّن مستندًا رئيسيًا

  • parentFrameId

    الرقم

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

  • requestId

    سلسلة

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

  • tabId

    الرقم

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

  • النوع

    ResourceType

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

  • url

    سلسلة

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

RequestMethod

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

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

Enum

"connect"

"delete"

"get"

"head"

"options"

"patch"

"post"

"put"

"other"

ResourceType

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

Enum

"main_frame"

"sub_frame"

"stylesheet"

"script"

"image"

"font"

"object"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"webtransport"

"webbundle"

"other"

Rule

الخصائص

  • إجراء

    RuleAction

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

  • الشرط

    RuleCondition

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

  • id

    الرقم

    معرّف يحدّد قاعدة بشكلٍ فريد. هذه السمة إلزامية ويجب أن تكون قيمتها أكبر من أو تساوي 1.

  • الحملة

    number اختياري

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

RuleAction

الخصائص

  • إعادة توجيه

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

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

  • requestHeaders

    ModifyHeaderInfo[] اختيارية

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

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

  • responseHeaders

    ModifyHeaderInfo[] اختيارية

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

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

  • النوع

    RuleActionType

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

RuleActionType

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

Enum

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

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

"allow"
يسمح بطلب الشبكة. لن يتم اعتراض الطلب إذا كانت هناك قاعدة سماح تطابقه.

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

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

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

RuleCondition

الخصائص

  • domainType

    DomainType اختياري

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

  • النطاقات

    string[] اختياري

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

    استخدِم initiatorDomains بدلاً من ذلك

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

  • excludedDomains

    string[] اختياري

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

    استخدِم excludedInitiatorDomains بدلاً من ذلك

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

  • excludedInitiatorDomains

    string[] اختياري

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

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

    ملاحظات:

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

    string[] اختياري

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

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

    ملاحظات:

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

    ‫RequestMethod[] اختياري

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

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

  • excludedResourceTypes

    ResourceType[] اختياري

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

  • excludedResponseHeaders

    HeaderInfo[] اختياري

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

    لا تتطابق القاعدة إذا كان الطلب يتطابق مع أي شرط من شروط عناوين الاستجابة في هذه القائمة (في حال تحديدها). في حال تحديد كل من excludedResponseHeaders وresponseHeaders، تكون الأولوية للسمة excludedResponseHeaders.

  • excludedTabIds

    number[] اختيارية

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

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

  • initiatorDomains

    string[] اختياري

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

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

    ملاحظات:

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

    boolean اختياري

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

  • regexFilter

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

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

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

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

  • requestDomains

    string[] اختياري

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

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

    ملاحظات:

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

    ‫RequestMethod[] اختياري

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

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

    ملاحظة: سيؤدي تحديد شرط قاعدة requestMethods أيضًا إلى استبعاد الطلبات غير المستندة إلى HTTP(s)، بينما لن يؤدي تحديد excludedRequestMethods إلى ذلك.

  • resourceTypes

    ResourceType[] اختياري

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

    ملاحظة: يجب تحديد ذلك لقواعد allowAllRequests، ويمكن أن يشمل نوعَي الموارد sub_frame وmain_frame فقط.

  • responseHeaders

    HeaderInfo[] اختياري

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

    تتطابق القاعدة إذا كان الطلب يتطابق مع أي شرط من شروط عناوين الاستجابة في هذه القائمة (في حال تحديده).

  • tabIds

    number[] اختيارية

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

    قائمة 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.рф?q=ф، ستتم مطابقة urlFilter مع عنوان URL http://abc.xn--p1ai/?q=%D1%84.

Ruleset

الخصائص

  • مفعّلة

    قيمة منطقية

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

  • id

    سلسلة

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

  • المسار

    سلسلة

    مسار مجموعة قواعد JSON بالنسبة إلى دليل الإضافة

RulesMatchedDetails

الخصائص

  • rulesMatchedInfo

    MatchedRuleInfo[]

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

TabActionCountUpdate

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

الخصائص

  • زيادة

    الرقم

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

  • tabId

    الرقم

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

TestMatchOutcomeResult

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

الخصائص

  • matchedRules

    MatchedRule[]

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

TestMatchRequestDetails

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

الخصائص

  • بادئ التشغيل

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

    عنوان URL الخاص بالمشغِّل (إن وُجد) للطلب الافتراضي

  • method

    RequestMethod اختياري

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

  • responseHeaders

    العنصر اختياري

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

    العناوين المقدَّمة من خلال ردّ افتراضي في حال عدم حظر الطلب أو إعادة توجيهه قبل إرساله يتم تمثيله كعنصر يربط اسم العنوان بقائمة من قيم السلسلة. في حال عدم تحديد ذلك، ستعرض الاستجابة الافتراضية عناوين استجابة فارغة، والتي يمكن أن تتطابق مع القواعد التي تتطابق مع عدم توفّر العناوين. مثلاً {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}

  • tabId

    number اختياري

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

  • النوع

    ResourceType

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

  • url

    سلسلة

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

UnsupportedRegexReason

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

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

Enum

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

"memoryLimitExceeded"
يتجاوز التعبير العادي حد الذاكرة.

UpdateRuleOptions

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

الخصائص

  • addRules

    Rule[] اختياري

    القواعد المطلوب إضافتها

  • removeRuleIds

    number[] اختيارية

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

UpdateRulesetOptions

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

الخصائص

  • disableRulesetIds

    string[] اختياري

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

  • enableRulesetIds

    string[] اختياري

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

UpdateStaticRulesOptions

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

الخصائص

  • disableRuleIds

    number[] اختيارية

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

  • enableRuleIds

    number[] اختيارية

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

  • rulesetId

    سلسلة

    المعرّف الذي يتوافق مع Ruleset ثابت.

URLTransform

الخصائص

  • جزء

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

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

  • مضيف

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

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

  • كلمة المرور

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

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

  • المسار

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

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

  • المنفذ

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

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

  • query

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

    تمثّل هذه السمة طلب البحث الجديد للطلب. يجب أن يكون فارغًا، وفي هذه الحالة تتم إزالة طلب البحث الحالي، أو يجب أن يبدأ بعلامة "؟".

  • queryTransform

    QueryTransform اختياري

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

  • المخطط

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

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

  • اسم المستخدم

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

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

الخصائص

DYNAMIC_RULESET_ID

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

القيمة

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

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

القيمة

‫10

GUARANTEED_MINIMUM_STATIC_RULES

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

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

القيمة

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

عدد المرات التي يمكن فيها استدعاء getMatchedRules خلال فترة GETMATCHEDRULES_QUOTA_INTERVAL

القيمة

‫20

MAX_NUMBER_OF_DYNAMIC_RULES

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

القيمة

30000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

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

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

القيمة

‫50

MAX_NUMBER_OF_REGEX_RULES

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

القيمة

‫1000

MAX_NUMBER_OF_SESSION_RULES

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

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

القيمة

5000

MAX_NUMBER_OF_STATIC_RULESETS

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

القيمة

‫100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

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

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

القيمة

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

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

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

القيمة

5000

SESSION_RULESET_ID

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

رقم تعريف مجموعة القواعد التي تمّت إضافتها من خلال الإضافة والتي تنطبق على مستوى الجلسة.

القيمة

"_session"

الطُرق

getAvailableStaticRuleCount()

الإصدار 89 من Chrome والإصدارات الأحدث 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(): Promise<number>

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

المرتجعات

  • Promise<number>

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

getDisabledRuleIds()

الإصدار 111 من Chrome والإصدارات الأحدث 
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
): Promise<number[]>

تعرض هذه الطريقة قائمة بالقواعد الثابتة في Ruleset المحدّد التي تكون غير مفعّلة حاليًا.

المعلمات

  • الخيارات

    GetDisabledRuleIdsOptions

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

المرتجعات

  • Promise<number[]>

getDynamicRules()

chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
): Promise<Rule[]>

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

المعلمات

  • تصفية

    GetRulesFilter اختياري

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

    عنصر لفلترة قائمة القواعد التي تم استرجاعها

المرتجعات

  • Promise<Rule[]>

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

getEnabledRulesets()

chrome.declarativeNetRequest.getEnabledRulesets(): Promise<string[]>

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

المرتجعات

  • Promise<string[]>

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

getMatchedRules()

chrome.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
): Promise<RulesMatchedDetails>

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

المعلمات

  • تصفية

    MatchedRulesFilter اختياري

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

المرتجعات

getSessionRules()

Chrome 90 والإصدارات الأحدث 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
): Promise<Rule[]>

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

المعلمات

  • تصفية

    GetRulesFilter اختياري

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

    عنصر لفلترة قائمة القواعد التي تم استرجاعها

المرتجعات

  • Promise<Rule[]>

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

isRegexSupported()

الإصدار 87 من Chrome والإصدارات الأحدث 
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
): Promise<IsRegexSupportedResult>

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

المعلمات

  • regexOptions

    RegexOptions

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

المرتجعات

setExtensionActionOptions()

الإصدار 88 من Chrome والإصدارات الأحدث 
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
): Promise<void>

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

المعلمات

المرتجعات

  • Promise<void>

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

testMatchOutcome()

الإصدار 103 من Chrome والإصدارات الأحدث 
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
): Promise<TestMatchOutcomeResult>

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

المعلمات

المرتجعات

updateDynamicRules()

chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
): Promise<void>

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

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

المعلمات

  • الخيارات

    UpdateRuleOptions

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

المرتجعات

  • Promise<void>

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

updateEnabledRulesets()

chrome.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
): Promise<void>

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

المعلمات

  • الخيارات

    UpdateRulesetOptions

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

المرتجعات

  • Promise<void>

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

updateSessionRules()

Chrome 90 والإصدارات الأحدث 
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
): Promise<void>

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

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

المعلمات

المرتجعات

  • Promise<void>

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

updateStaticRules()

الإصدار 111 من Chrome والإصدارات الأحدث 
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
): Promise<void>

يؤدي هذا الإجراء إلى إيقاف وتفعيل قواعد ثابتة فردية في Ruleset. سيتم تطبيق التغييرات على القواعد التابعة Ruleset غير مفعَّل في المرة التالية التي يتم فيها تفعيله.

المعلمات

المرتجعات

  • Promise<void>

الفعاليات

onRuleMatchedDebug

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

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

المعلمات