الوصف
تُستخدَم واجهة برمجة التطبيقات chrome.declarativeNetRequest
لحظر طلبات الشبكة أو تعديلها من خلال تحديد قواعد الإفصاح. ويتيح ذلك للإضافات تعديل طلبات الشبكة بدون اعتراضها وعرض محتواها، ما يوفّر المزيد من الخصوصية.
الأذونات
declarativeNetRequest
declarativeNetRequestWithHostAccess
يقدّم الإذنان "declarativeNetRequest
" و "declarativeNetRequestWithHostAccess
"
الإمكانات نفسها. يكمن الاختلاف بينهما في وقت طلب
الأذونات أو منحها.
"declarativeNetRequest"
- يؤدي هذا الإجراء إلى إصدار تحذير بشأن الإذن عند التثبيت مع توفير إمكانية الوصول الضمني إلى
قواعد
allow
وallowAllRequests
وblock
. يمكنك استخدام ذلك متى أمكن لتجنب الحاجة إلى طلب الوصول الكامل إلى المضيفين. "declarativeNetRequestFeedback"
- تفعيل ميزات تصحيح الأخطاء للإضافات التي تم فك ضغطها، وتحديدًا
getMatchedRules()
وonRuleMatchedDebug
. "declarativeNetRequestWithHostAccess"
- لا يظهر تحذير بشأن الإذن أثناء التثبيت، ولكن يجب طلب أذونات المضيف قبل أن تتمكّن من تنفيذ أي إجراء على المضيف. ويكون هذا مناسبًا عندما تريد استخدام قواعد بيانية لطلب الشراء في إحدى الإضافات التي تتضمن أذونات المضيف بدون إنشاء تحذيرات إضافية.
مدى توفّر الخدمة
البيان
بالإضافة إلى الأذونات الموضّحة سابقًا، تتطلّب أنواع معيّنة من مجموعات القواعد، تحديدًا مجموعات القواعد الثابتة، الإفصاح عن مفتاح بيان "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 |
تحديد أولوية القواعد
يتم تفعيل القواعد من خلال طلبات مُرسَلة من صفحات الويب. وفي حال تطابق عدة قواعد مع طلب معيَّن، يجب إعطاء الأولوية للقواعد. يوضّح هذا القسم كيفية ترتيبها حسب الأولوية. يتم تحديد الأولويات على مرحلتين.
- ويتم تحديد أولوية القواعد داخل الإضافة.
- وإذا كان بإمكان أكثر من إضافة واحدة تطبيق قاعدة على أحد الطلبات، سيتم تحديد أولوية جميع الإضافات التي تتطابق مع طلب معيَّن.
نفكر في المطابقة بهذه الطريقة: ستُمنح أي قاعدة تمنحها إضافة معيّنة الأولوية مقابل قواعد من إضافات أخرى.
تحديد أولوية القواعد داخل الإضافة
يتم تحديد الأولويات ضمن عملية إضافة واحدة باتّباع العملية التالية:
- يتم عرض القاعدة ذات أعلى أولوية من تحديد المطوّر (بمعنى آخر، الحقل
"priority"
). إذا كانت هناك أكثر من قاعدة ذات الأولوية القصوى التي يحدِّدها المطوِّر، سيتم منح الأولوية للقواعد باستخدام الحقل
"action"
، بالترتيب التالي:allow
allowAllRequests
block
upgradeScheme
redirect
إذا لم يكن نوع الإجراء
block
أوredirect
، يتم تقييم أي قواعدmodifyHeaders
مطابقة. ويُرجى العلم بأنّه في حال توفُّر أي قواعد ذات أولوية يحددها المطوّر أقل من الأولوية المحدّدة لكل منallow
وallowAllRequests
، سيتم تجاهل هذه القواعد.إذا عدَّلت عدة قواعد العنوان نفسه، يتم تحديد التعديل من خلال حقل
"priority"
الذي حدّده المطوّر ومن خلال العمليات المحدّدة.- إذا تم إلحاق قاعدة برأس، فإن القواعد ذات الأولوية الأقل لا يمكن إلحاقها إلا بهذا العنوان. لا يُسمح بعمليات الضبط والإزالة.
- إذا ضبطت قاعدة عنوانًا، يمكن أن تلحق القواعد ذات الأولوية الأقل بهذا العنوان فقط. ولا يُسمح بإجراء أي تعديلات أخرى.
- إذا أزالت إحدى القواعد عنوانًا، لا يمكن لقواعد الأولوية المنخفضة تعديل ذلك العنوان.
تحديد أولوية القواعد بين الإضافات
وفي حال توفُّر إضافة واحدة فقط تتطابق مع طلب معيَّن، يتم تطبيق هذه القاعدة. ولكن في حال تطابق أكثر من إضافة مع أحد الطلبات، يتم استخدام العملية التالية:
ويتم تحديد أولوية القواعد باستخدام الحقل
"action"
بالترتيب التالي:block
-
redirect
أوupgradeScheme
-
allow
أوallowAllRequests
وفي حال تطابق أكثر من قاعدة، تُمنَح الأولوية لآخر إضافة مثبَّتة.
حدود القواعد
يتم فرض عبء زائد على الأداء في ما يتعلق بتحميل قواعد التحميل وتقييمها في المتصفّح، وبالتالي، يتم تطبيق بعض القيود عند استخدام واجهة برمجة التطبيقات. تعتمد الحدود على نوع القاعدة التي تستخدمها.
القواعد الثابتة
القواعد الثابتة هي تلك المحدَّدة في ملفات القواعد المعرَّفة في ملف البيان. يمكن أن تحدد الإضافة ما يصل إلى 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
أماكن إقامة
-
displayActionCountAsBadgeText
منطقية اختيارية
ما إذا كان سيتم عرض عدد الإجراءات لإحدى الصفحات تلقائيًا كنص لشارة الإضافة. ويستمر هذا الخيار المفضّل على مستوى الجلسات.
-
tabUpdate
TabActionCountUpdate اختيارية
الإصدار 89 من Chrome والإصدارات الأحدثتفاصيل حول كيفية تعديل عدد الإجراءات في علامة التبويب
GetDisabledRuleIdsOptions
أماكن إقامة
-
rulesetId
سلسلة
رقم التعريف المتجاوب مع
Ruleset
ثابتة.
GetRulesFilter
أماكن إقامة
-
ruleIds
number[] اختيارية
وفي حال تحديدها، لا يتم تضمين سوى القواعد ذات أرقام التعريف المطابقة.
HeaderOperation
يصف هذا العمليات المحتملة لقاعدة "modifyHeaders".
التعداد
"append"
لإضافة إدخال جديد للعنوان المحدّد. هذه العملية غير متاحة لعناوين الطلبات.
"set"
يضبط هذا الحقل قيمة جديدة للعنوان المحدَّد، مع إزالة أي عناوين حالية تحمل الاسم نفسه.
"remove"
لإزالة جميع الإدخالات الخاصة بالعنوان المحدَّد
IsRegexSupportedResult
أماكن إقامة
-
isSupported
boolean
-
السبب
UnsupportedRegexReason اختيارية
تحدّد سبب عدم توافق التعبير العادي. يتم تقديمه فقط إذا كانت قيمة
isSupported
خطأ.
MatchedRule
أماكن إقامة
-
ruleId
الرقم
رقم تعريف القاعدة المُطابِقة.
-
rulesetId
سلسلة
رقم تعريف
Ruleset
التي تنتمي إليها هذه القاعدة. بالنسبة إلى أي قاعدة تنشأ من مجموعة القواعد الديناميكية، سيكون ذلك مساويًا لـDYNAMIC_RULESET_ID
.
MatchedRuleInfo
أماكن إقامة
-
قاعدة
-
tabId
الرقم
TabId لعلامة التبويب التي نشأ منها الطلب، إذا كانت علامة التبويب لا تزال نشطة. غير ذلك -1.
-
timeStamp
الرقم
وقت مطابقة القاعدة. ستتوافق الطوابع الزمنية مع اصطلاح JavaScript في الأوقات، أي عدد المللي ثانية منذ الفترة.
MatchedRuleInfoDebug
أماكن إقامة
-
طلب
تفاصيل حول الطلب الذي تمت مطابقة القاعدة له.
-
قاعدة
MatchedRulesFilter
أماكن إقامة
-
minTimeStamp
الرقم اختياري
وفي حال تحديدها، تتم مطابقة القواعد بعد الطابع الزمني المحدّد فقط.
-
tabId
الرقم اختياري
وفي حال تحديدها، ستتم مطابقة قواعد علامة التبويب المحدّدة فقط. يطابق القواعد غير المرتبطة بأي علامة تبويب نشطة في حال ضبطها على -1.
ModifyHeaderInfo
أماكن إقامة
-
header
سلسلة
تمثّل هذه السمة اسم العنوان الذي سيتم تعديله.
-
عملية
العملية التي سيتم تنفيذها على عنوان.
-
القيمة
سلسلة اختيارية
القيمة الجديدة للعنوان. يجب أن تكون محددة لعمليات
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
أماكن إقامة
-
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 إذا لم يكن الطلب مرتبطًا بعلامة تبويب.
-
كتابة
نوع مورد الطلب.
-
url
سلسلة
عنوان URL للطلب.
RequestMethod
يصف هذا طريقة طلب HTTP لطلب الشبكة.
التعداد
"connect"
"get"
"head"
"options"
"put"
ResourceType
يصف هذا نوع المورد الخاص بطلب الشبكة.
التعداد
"main_frame"
"sub_frame"
"script"
"xmlhttprequest"
"ping"
"csp_report"
"media"
"websocket"
"webtransport"
Rule
أماكن إقامة
-
إجراء
الإجراء الذي يتم اتخاذه في حال مطابقة هذه القاعدة.
-
الشرط
الشرط الذي يتم تفعيل هذه القاعدة بموجبه.
-
id
الرقم
معرّف يعرّف القاعدة بشكل فريد. إلزامية ويجب أن تكون >= 1.
-
الحملة
الرقم اختياري
أولوية القاعدة يكون الإعداد التلقائي بالقيمة 1. عند تحديدها، يجب أن تكون >= 1.
RuleAction
أماكن إقامة
-
إعادة توجيه
إعادة التوجيه اختيارية
تصف هذه السمة كيف يجب تنفيذ إعادة التوجيه. صالح فقط لقواعد إعادة التوجيه.
-
requestHeaders
ModifyHeaderInfo[] اختيارية
Chrome 86 والإصدارات الأحدثعناوين الطلب المطلوب تعديلها لا يكون هذا الحقل صالحًا إلا إذا كانت قيمة RuleActionType هي "modifyHeaders".
-
responseHeaders
ModifyHeaderInfo[] اختيارية
Chrome 86 والإصدارات الأحدثعناوين الاستجابة المطلوب تعديلها للطلب. لا يكون هذا الحقل صالحًا إلا إذا كانت قيمة RuleActionType هي "modifyHeaders".
-
كتابة
نوع الإجراء المطلوب تنفيذه.
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
قواعد تتطابق مع الفلتر المحدّد.
TabActionCountUpdate
أماكن إقامة
-
زيادة
الرقم
المبلغ المطلوب زيادة عدد الإجراءات لعلامة التبويب به. وستؤدي القيم السالبة إلى تقليل العدد.
-
tabId
الرقم
علامة التبويب التي يتم تعديل عدد الإجراءات لها
TestMatchOutcomeResult
أماكن إقامة
-
matchedRules
القواعد (إن وجدت) التي تتطابق مع الطلب الافتراضي.
TestMatchRequestDetails
أماكن إقامة
-
بادئ تشغيل
سلسلة اختيارية
عنوان URL الذي بدأ الطلب (إن وجد) للطلب الافتراضي
-
method
RequestMethod اختيارية
طريقة HTTP عادية للطلب الافتراضي. يتم ضبط الإعداد التلقائي على "get" لطلبات HTTP، ويتم تجاهله للطلبات التي لا تستخدم HTTP.
-
tabId
الرقم اختياري
رقم تعريف علامة التبويب التي يحدث فيها الطلب الافتراضي. لا يجب أن يتطابق مع معرّف علامة تبويب حقيقي. القيمة التلقائية هي -1، ما يعني أنّ الطلب غير مرتبط بعلامة تبويب.
-
كتابة
نوع مرجع الطلب الافتراضي
-
url
سلسلة
تمثّل هذه السمة عنوان URL للطلب الافتراضي.
UnsupportedRegexReason
تصف هذه السمة سبب عدم توافق تعبير عادي معيّن.
التعداد
"syntaxError"
التعبير العادي غير صحيح من ناحية البنية أو يستخدم ميزات غير متاحة في بنية RE2.
"memorylimitExceeded"
يتجاوز التعبير العادي الحد المسموح به للذاكرة.
UpdateRuleOptions
أماكن إقامة
-
addRules
القاعدة[] اختيارية
القواعد التي يجب إضافتها.
-
removeRuleIds
number[] اختيارية
معرّفات القواعد المطلوب إزالتها. وسيتم تجاهل أي معرّفات غير صالحة.
UpdateRulesetOptions
أماكن إقامة
UpdateStaticRulesOptions
أماكن إقامة
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
الحد الأدنى لعدد القواعد الثابتة المضمونة لإحدى الإضافات على مستوى مجموعات القواعد الثابتة المفعَّلة فيها. سيتم احتساب أي قواعد أعلى من هذا الحد ضمن حد القواعد الثابتة الشاملة.
القيمة
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
الحد الأقصى لعدد Rulesets
الثابتة التي يمكن للإضافة تفعيلها في أي وقت.
القيمة
50
MAX_NUMBER_OF_REGEX_RULES
الحدّ الأقصى لعدد قواعد التعبير العادي التي يمكن للإضافة إدراجها. يتم تقييم هذا الحد بشكل منفصل لمجموعة القواعد الديناميكية وتلك المحددة في ملف موارد القاعدة.
القيمة
1,000
MAX_NUMBER_OF_SESSION_RULES
الحدّ الأقصى لعدد القواعد على مستوى الجلسة التي يمكن لأي إضافة إدراجها.
القيمة
5,000
MAX_NUMBER_OF_STATIC_RULESETS
الحد الأقصى لعدد Rulesets
الثابتة التي يمكن للإضافة تحديدها كجزء من مفتاح بيان "rule_resources"
القيمة
100
MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES
الحدّ الأقصى لعدد القواعد الديناميكية "غير الآمنة" التي يمكن أن تدرجها إحدى الإضافات.
القيمة
5,000
MAX_NUMBER_OF_UNSAFE_SESSION_RULES
الحدّ الأقصى لعدد القواعد "غير الآمنة" على مستوى الجلسة التي يمكن للإضافة إدراجها.
القيمة
5,000
SESSION_RULESET_ID
رقم تعريف مجموعة القواعد للقواعد على مستوى الجلسة التي أضافتها الإضافة.
القيمة
"_session"
الطُرق
getAvailableStaticRuleCount()
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
callback?: function,
)
تعرض عدد القواعد الثابتة التي يمكن للإضافة تفعيلها قبل الوصول إلى الحد الأقصى للقواعد الثابتة الشاملة.
المَعلمات
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(count: number)=>void
-
العدد
الرقم
-
المرتجعات
-
وعد<الرقم>
Chrome 91 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
getDisabledRuleIds()
chrome.declarativeNetRequest.getDisabledRuleIds(
options: GetDisabledRuleIdsOptions,
callback?: function,
)
لعرض قائمة القواعد الثابتة غير المفعَّلة حاليًا في Ruleset
.
المَعلمات
-
الخيارات
تحدّد هذه السمة مجموعة القواعد المطلوب طلبها.
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
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
-
التفاصيل
-
المرتجعات
-
Promise<RulesMatchedDetails>
Chrome 91 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
getSessionRules()
chrome.declarativeNetRequest.getSessionRules(
filter?: GetRulesFilter,
callback?: function,
)
تعرِض المجموعة الحالية من القواعد على مستوى الجلسة للإضافة. يمكن للمتصلين اختياريًا فلترة قائمة القواعد التي تم جلبها من خلال تحديد filter
.
المَعلمات
-
filter
GetRulesFilter اختيارية
Chrome 111 والإصدارات الأحدثكائن لفلترة قائمة القواعد التي تم جلبها.
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(rules: Rule[])=>void
-
القواعد
القاعدة[]
-
المرتجعات
-
وعد<قاعدة[]>
Chrome 91 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
isRegexSupported()
chrome.declarativeNetRequest.isRegexSupported(
regexOptions: RegexOptions,
callback?: function,
)
للتحقّق مما إذا كان التعبير العادي المحدّد سيصبح متاحًا كشرط للقاعدة regexFilter
.
المَعلمات
-
regexOptions
التعبير العادي المطلوب التحقّق منه.
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(result: IsRegexSupportedResult)=>void
-
نتيجة
-
المرتجعات
-
Promise<IsRegexSupportedResult>
Chrome 91 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
setExtensionActionOptions()
chrome.declarativeNetRequest.setExtensionActionOptions(
options: ExtensionActionOptions,
callback?: function,
)
تحدِّد هذه السياسة ما إذا كان يجب عرض عدد الإجراءات لعلامات التبويب كنص لشارة إجراء الإضافة، وتوفّر طريقة لزيادة عدد هذا الإجراءات.
المَعلمات
-
الخيارات
-
معاودة الاتصال
الدالة اختيارية
الإصدار 89 من Chrome والإصدارات الأحدثتبدو معلَمة
callback
على النحو التالي:()=>void
المرتجعات
-
Promise<void>
Chrome 91 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
testMatchOutcome()
chrome.declarativeNetRequest.testMatchOutcome(
request: TestMatchRequestDetails,
callback?: function,
)
تتحقّق مما إذا كانت أي من قواعد deflarativeNetRequest للإضافة تتطابق مع طلب افتراضي. ملاحظة: لا تتوفّر هذه الميزة إلا للإضافات التي تم فك ضغطها، وذلك لأنّه يتم استخدامها فقط أثناء تطوير الإضافات.
المَعلمات
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(result: TestMatchOutcomeResult)=>void
-
نتيجة
-
المرتجعات
-
Promise<TestMatchOutcomeResult>
تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
updateDynamicRules()
chrome.declarativeNetRequest.updateDynamicRules(
options: UpdateRuleOptions,
callback?: function,
)
لتعديل المجموعة الحالية من القواعد الديناميكية للإضافة. تتم أولاً إزالة القواعد التي لها أرقام تعريف مُدرَجة في options.removeRuleIds
، ثم تُضاف القواعد المقدَّمة في options.addRules
. ملاحظات:
- يتم هذا التعديل من خلال عملية شاملة واحدة: إمّا إضافة جميع القواعد المحدَّدة وإزالتها أو عرض خطأ.
- تظل هذه القواعد سارية في جميع جلسات المتصفِّح وفي جميع تحديثات الإضافات.
- لا يمكن إزالة القواعد الثابتة المحدّدة كجزء من حزمة الإضافة باستخدام هذه الدالة.
MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES
هو الحد الأقصى لعدد القواعد الديناميكية المجمّعة وقواعد الجلسات التي يمكن لأي إضافة إدراجها.
المَعلمات
-
الخياراتالإصدار 87 من Chrome والإصدارات الأحدث
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:()=>void
المرتجعات
-
Promise<void>
Chrome 91 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
updateEnabledRulesets()
chrome.declarativeNetRequest.updateEnabledRulesets(
options: UpdateRulesetOptions,
callback?: function,
)
تُعدِّل مجموعة القواعد الثابتة المفعَّلة للإضافة. تتم أولاً إزالة مجموعات القواعد التي لها أرقام تعريف مُدرَجة في options.disableRulesetIds
، ثم تتم إضافة مجموعات القواعد المدرَجة في options.enableRulesetIds
.
تجدر الإشارة إلى أنّ مجموعة القواعد الثابتة المفعّلة تظلّ في جميع الجلسات وليس على مستوى تحديثات الإضافات، أي أنّ مفتاح البيان rule_resources
سيحدِّد مجموعة القواعد الثابتة المفعَّلة في كل تحديث للإضافة.
المَعلمات
-
الخياراتالإصدار 87 من Chrome والإصدارات الأحدث
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:()=>void
المرتجعات
-
Promise<void>
Chrome 91 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
updateSessionRules()
chrome.declarativeNetRequest.updateSessionRules(
options: UpdateRuleOptions,
callback?: function,
)
يُعدّل المجموعة الحالية من القواعد على مستوى الجلسة للإضافة. تتم أولاً إزالة القواعد التي لها أرقام تعريف مُدرَجة في options.removeRuleIds
، ثم تُضاف القواعد المقدَّمة في options.addRules
. ملاحظات:
- يتم هذا التعديل من خلال عملية شاملة واحدة: إمّا إضافة جميع القواعد المحدَّدة وإزالتها أو عرض خطأ.
- لا يتم الاحتفاظ بهذه القواعد في جميع الجلسات ويتم الاحتفاظ بنسخة احتياطية منها في الذاكرة.
MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES
هو الحد الأقصى لعدد القواعد الديناميكية المجمّعة وقواعد الجلسات التي يمكن لأي إضافة إدراجها.
المَعلمات
-
الخيارات
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:()=>void
المرتجعات
-
Promise<void>
Chrome 91 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
updateStaticRules()
chrome.declarativeNetRequest.updateStaticRules(
options: UpdateStaticRulesOptions,
callback?: function,
)
لإيقاف القواعد الثابتة الفردية وتفعيلها في Ruleset
وتصبح التغييرات التي تطرأ على القواعد التي تخص Ruleset
غير مفعَّلة في المرة التالية التي يتم فيها تفعيل هذه الميزة.
المَعلمات
-
الخيارات
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:()=>void
المرتجعات
-
Promise<void>
تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
فعاليات
onRuleMatchedDebug
chrome.declarativeNetRequest.onRuleMatchedDebug.addListener(
callback: function,
)
يتم تنشيطها عند مطابقة قاعدة مع طلب. لا تتوفّر هذه الميزة إلا للإضافات التي تم فك ضغطها والتي لديها إذن "declarativeNetRequestFeedback"
، لأنّ هذه الميزة مخصّصة للاستخدام لأغراض تصحيح الأخطاء فقط.
المَعلمات
-
معاودة الاتصال
الوظيفة
تبدو معلَمة
callback
على النحو التالي:(info: MatchedRuleInfoDebug)=>void
-
معلومات
-