chrome.declarativeNetRequest

الوصف

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

الأذونات

declarativeNetRequest
declarativeNetRequestWithHostAccess

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

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

مدى التوفّر

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

البيان

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

مراجعة سريعة

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

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

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

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

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

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

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

وضع القواعد

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

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

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

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

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

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

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

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

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

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

وفي إضافة واحدة، يتم تحديد الأولويات باستخدام العملية التالية:

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

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

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

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

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

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

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

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

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

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

  2. وفي حال تطابق أكثر من قاعدة، تكون الأولوية للإضافة التي تم تثبيتها مؤخرًا.

القواعد الآمنة

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

حدود القواعد

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

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

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

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

قواعد الجلسة

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

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

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

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

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

قبل الإصدار 120 من Chrome، كان هناك حد أقصى يبلغ 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) الذي تم استخدامه في الإطار الذي نشأ فيه الطلب.

التعداد

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

"الطرف الثالث"
طلب الشبكة هو طرف ثالث في الإطار الذي تم إنشاؤه منه.

ExtensionActionOptions

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

أماكن إقامة

  • displayActionCountAsBadgeText

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

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

  • tabUpdate

    TabActionCountUpdate اختياري

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

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

GetDisabledRuleIdsOptions

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

أماكن إقامة

  • rulesetId

    سلسلة

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

GetRulesFilter

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

أماكن إقامة

  • ruleIds

    number[] اختياري

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

HeaderOperation

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

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

التعداد

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

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

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

IsRegexSupportedResult

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

أماكن إقامة

  • isSupported

    boolean

  • السبب

    UnsupportedRegexReason اختياري

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

MatchedRule

أماكن إقامة

  • ruleId

    الرقم

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

  • rulesetId

    سلسلة

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

MatchedRuleInfo

أماكن إقامة

  • قاعدة

    MatchedRule

  • tabId

    الرقم

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

  • timeStamp

    الرقم

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

MatchedRuleInfoDebug

أماكن إقامة

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

  • قاعدة

    MatchedRule

MatchedRulesFilter

أماكن إقامة

  • minTimeStamp

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

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

  • tabId

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

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

ModifyHeaderInfo

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

أماكن إقامة

  • header

    سلسلة

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

  • عملية

    HeaderOperation

    العملية المطلوب إجراؤها على العنوان.

  • القيمة

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

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

QueryKeyValue

أماكن إقامة

  • مفتاح

    سلسلة

  • replaceOnly

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

    الإصدار 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

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

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

  • تعبير عادي

    سلسلة

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

  • requireCapturing

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

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

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 لأحد طلبات الشبكة.

التعداد

"get"

"put"

"other"

ResourceType

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

التعداد

"sub_frame"

"script"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"other"

Rule

أماكن إقامة

  • إجراء

    RuleAction

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

  • الشرط

    RuleCondition

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

  • id

    الرقم

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

  • الحملة

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

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

RuleAction

أماكن إقامة

  • إعادة توجيه

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

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

  • requestHeaders

    ModifyHeaderInfo[] اختيارية

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

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

  • responseHeaders

    ModifyHeaderInfo[] اختيارية

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

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

  • كتابة

    RuleActionType

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

RuleActionType

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

التعداد

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

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

"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".

  • excludedTabIds

    number[] اختياري

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

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

  • initiatorDomains

    string[] اختيارية

    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

    string[] اختيارية

    Chrome 101 والأحدث

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

    ملاحظات:

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

    RequestMethod[] اختيارية

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

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

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

  • resourceTypes

    ResourceType[] اختياري

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

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

  • 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

أماكن إقامة

  • مفعّلة

    boolean

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

  • id

    سلسلة

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

  • المسار

    سلسلة

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

RulesMatchedDetails

أماكن إقامة

  • rulesMatchedInfo

    MatchedRuleInfo[]

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

TabActionCountUpdate

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

أماكن إقامة

  • زيادة

    الرقم

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

  • tabId

    الرقم

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

TestMatchOutcomeResult

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

أماكن إقامة

  • matchedRules

    MatchedRule[]

    تمثّل هذه السمة القواعد (إن وُجدت) التي تتطابق مع الطلب الافتراضي.

TestMatchRequestDetails

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

أماكن إقامة

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

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

    تمثّل هذه السمة عنوان URL لبادئ التشغيل (إن توفّر) للطلب الافتراضي.

  • method

    RequestMethod اختيارية

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

  • tabId

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

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

  • كتابة

    ResourceType

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

  • url

    سلسلة

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

UnsupportedRegexReason

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

يصف سبب عدم توافق تعبير عادي معين.

التعداد

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

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

UpdateRuleOptions

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

أماكن إقامة

  • addRules

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

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

  • 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

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

القيمة

1,000

MAX_NUMBER_OF_SESSION_RULES

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

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

القيمة

5,000

MAX_NUMBER_OF_STATIC_RULESETS

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

القيمة

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

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

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

القيمة

5,000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

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

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

القيمة

5,000

SESSION_RULESET_ID

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

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

القيمة

"_session"

الطُرق

getAvailableStaticRuleCount()

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

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

المعلمات

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    (count: number) => void

    • العدد

      الرقم

المرتجعات

  • وعد<number>

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

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

getDisabledRuleIds()

التوقعات Chrome 111 والأحدث 
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
  callback?: function,
)

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

المعلمات

  • الخيارات

    GetDisabledRuleIdsOptions

    تُستخدَم لتحديد مجموعة القواعد لطلب البحث.

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      رقم[]

المرتجعات

  • وعد<number[]>

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

getDynamicRules()

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

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

المعلمات

  • filter

    GetRulesFilter اختياري

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

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

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    (rules: Rule[]) => void

المرتجعات

  • الوعد<Rule[]>

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

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

getEnabledRulesets()

وعد بذلك 
chrome.declarativeNetRequest.getEnabledRulesets(
  callback?: function,
)

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

المعلمات

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    (rulesetIds: string[]) => void

    • rulesetIds

      سلسلة[]

المرتجعات

  • وعد<string[]>

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

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

getMatchedRules()

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

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

المعلمات

  • filter

    MatchedRulesFilter اختياري

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

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    (details: RulesMatchedDetails) => void

المرتجعات

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

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

getSessionRules()

التوقعات Chrome 90+ 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
  callback?: function,
)

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

المعلمات

  • filter

    GetRulesFilter اختياري

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

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

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    (rules: Rule[]) => void

المرتجعات

  • الوعد<Rule[]>

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

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

isRegexSupported()

وعود Chrome 87+ 
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
  callback?: function,
)

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

المعلمات

  • regexOptions

    RegexOptions

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

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    (result: IsRegexSupportedResult) => void

المرتجعات

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

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

setExtensionActionOptions()

وعود Chrome 88+ 
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
  callback?: function,
)

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

المعلمات

  • الخيارات

    ExtensionActionOptions

  • رد الاتصال

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

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

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • Promise<void>

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

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

testMatchOutcome()

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

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

المعلمات

المرتجعات

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

updateDynamicRules()

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

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

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

المعلمات

  • الخيارات

    UpdateRuleOptions

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

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

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • Promise<void>

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

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

updateEnabledRulesets()

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

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

المعلمات

  • الخيارات

    UpdateRulesetOptions

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

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

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • Promise<void>

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

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

updateSessionRules()

التوقعات Chrome 90+ 
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
  callback?: function,
)

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

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

المعلمات

  • الخيارات

    UpdateRuleOptions

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • Promise<void>

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

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

updateStaticRules()

التوقعات Chrome 111 والأحدث 
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
  callback?: function,
)

إيقاف قواعد ثابتة فردية وتفعيلها في Ruleset وستدخل التغييرات على القواعد التابعة لـ Ruleset الذي تم إيقافه حيز التنفيذ في المرة التالية التي يتم فيها تفعيلها.

المعلمات

  • الخيارات

    UpdateStaticRulesOptions

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • Promise<void>

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

فعاليات

onRuleMatchedDebug

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

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

المعلمات