chrome.declarativeNetRequest

توضیحات

chrome.declarativeNetRequest API برای مسدود کردن یا اصلاح درخواست‌های شبکه با تعیین قوانین اعلامی استفاده می‌شود. این به برنامه‌های افزودنی اجازه می‌دهد تا درخواست‌های شبکه را بدون رهگیری و مشاهده محتوای آن‌ها اصلاح کنند، بنابراین حریم خصوصی بیشتری را فراهم می‌کنند.

مجوزها

declarativeNetRequest
declarativeNetRequestWithHostAccess

declarativeNetRequestFeedback
host_permissions

در دسترس بودن

Chrome 84+

آشکار

علاوه بر مجوزهایی که در بالا توضیح داده شد، انواع خاصی از مجموعه قوانین، به طور خاص مجموعه قوانین ثابت، نیاز به اعلام کلید مانیفست "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/*"
  ],
  ...
}

مفاهیم و کاربرد

برای استفاده از این API، یک یا چند مجموعه قوانین را مشخص کنید. یک مجموعه قوانین شامل آرایه ای از قوانین است. یک قانون واحد یکی از موارد زیر را انجام می دهد:

  • مسدود کردن درخواست شبکه
  • طرحواره (http به https) را ارتقا دهید.
  • با نفی قوانین مسدود شده منطبق، از مسدود شدن درخواست جلوگیری کنید.
  • تغییر مسیر درخواست شبکه
  • هدر درخواست یا پاسخ را اصلاح کنید.

سه نوع مجموعه قوانین وجود دارد که به روش های کمی متفاوت مدیریت می شوند.

پویا
در طول جلسات مرورگر و ارتقاء برنامه‌های افزودنی ادامه داشته باشد و با استفاده از جاوا اسکریپت در زمانی که یک برنامه افزودنی در حال استفاده است مدیریت می‌شود.
جلسه
وقتی مرورگر خاموش می شود و نسخه جدیدی از برنامه افزودنی نصب می شود پاک می شود. قوانین جلسه با استفاده از جاوا اسکریپت مدیریت می شوند در حالی که یک برنامه افزودنی در حال استفاده است.
استاتیک
بسته بندی، نصب و به روز رسانی در هنگام نصب یا ارتقاء یک برنامه افزودنی. قوانین استاتیک در فایل‌های قانون با فرمت JSON ذخیره می‌شوند و در فایل مانیفست فهرست می‌شوند.

چند بخش بعدی انواع قوانین را با جزئیات توضیح می دهد.

مجموعه قوانین پویا و با محدوده جلسه

قواعد پویا و جلسه با استفاده از جاوا اسکریپت در حالی که یک برنامه افزودنی در حال استفاده است مدیریت می شوند.

  • قوانین پویا در طول جلسات مرورگر و ارتقاء برنامه‌های افزودنی پابرجا هستند.
  • زمانی که مرورگر خاموش می شود و نسخه جدیدی از برنامه افزودنی نصب می شود، قوانین جلسه پاک می شوند.

هر یک از این نوع مجموعه قوانین فقط یکی وجود دارد. یک برنامه افزودنی می تواند با فراخوانی 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 تعریف می شوند.

برای فعال یا غیرفعال کردن قواعد ثابت، 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://baexample.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. اگر بیش از یک قانون مطابقت داشته باشد، افزونه اخیراً نصب شده در اولویت قرار می گیرد.

محدودیت های قوانین

برای بارگذاری و ارزیابی قوانین در مرورگر، هزینه ای سربار عملکرد وجود دارد، بنابراین برخی از محدودیت ها هنگام استفاده از API اعمال می شود. محدودیت ها به نوع قاعده ای که استفاده می کنید بستگی دارد.

قوانین ایستا

قوانین ایستا آنهایی هستند که در فایل های قوانین اعلام شده در فایل مانیفست مشخص شده اند. یک برنامه افزودنی می تواند حداکثر 50 مجموعه قوانین ثابت را به عنوان بخشی از کلید مانیفست "rule_resources" مشخص کند، اما تنها 10 مورد از این مجموعه قوانین را می توان در یک زمان فعال کرد. دومی MAX_NUMBER_OF_ENABLED_STATIC_RULESETS نامیده می شود. در مجموع، این مجموعه قوانین حداقل 30000 قانون را تضمین می کند. این GUARANTEED_MINIMUM_STATIC_RULES نامیده می شود.

تعداد قوانین موجود پس از آن بستگی به تعداد قوانینی دارد که توسط همه برنامه های افزودنی نصب شده در مرورگر کاربر فعال شده است. می توانید این شماره را در زمان اجرا با فراخوانی getAvailableStaticRuleCount() بیابید. می توانید نمونه ای از این را در زیر نمونه های کد مشاهده کنید.

قوانین پویا و جلسه

محدودیت های اعمال شده برای قوانین پویا و جلسات ساده تر از قوانین ایستا هستند. تعداد کل هر دو نمی تواند از 5000 تجاوز کند. این MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES نامیده می شود.

قوانینی که از regex استفاده می کنند

همه انواع قوانین می توانند از عبارات منظم استفاده کنند. با این حال، تعداد کل قوانین regex در هر نوع نمی تواند از 1000 تجاوز کند. این MAX_NUMBER_OF_REGEX_RULES نامیده می شود.

علاوه بر این، پس از کامپایل، هر قانون باید کمتر از 2 کیلوبایت باشد. این تقریباً با پیچیدگی قانون مرتبط است. اگر بخواهید قانونی را بارگذاری کنید که از این حد فراتر رود، هشداری مانند تصویر زیر خواهید دید و قانون نادیده گرفته می شود. 

rules_1.json: Rule with id 1 specified a more complext 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) با فریمی باشد که درخواست از آن منشا گرفته است، طرف اول است.

Enum

"فرست پارتی"
درخواست شبکه اولین طرف فریمی است که در آن ایجاد شده است.

"شخص ثالث"
درخواست شبکه شخص ثالثی در چارچوبی است که در آن منشا گرفته است.

ExtensionActionOptions

Chrome 88+

خواص

  • displayActionCountAsBadgeText

    بولی اختیاری

    نمایش خودکار تعداد کنش برای یک صفحه به عنوان متن نشان برنامه افزودنی. این اولویت در تمام جلسات ادامه دارد.

  • تب به روز رسانی

    TabActionCountUpdate اختیاری است

    Chrome 89+

    جزئیات نحوه تنظیم تعداد کنش برگه باید تنظیم شود.

GetDisabledRuleIdsOptions

Chrome 111+

خواص

  • شناسه قوانین

    رشته

    شناسه مربوط به یک Ruleset ثابت.

GetRulesFilter

Chrome 111+

خواص

  • شناسه قوانین

    شماره[] اختیاری

    اگر مشخص شده باشد، فقط قوانینی با شناسه‌های منطبق گنجانده می‌شوند.

HeaderInfo

Chrome 128+

خواص

  • مقادیر استثنا شده

    رشته[] اختیاری است

    اگر مشخص شده باشد، اگر سرصفحه وجود داشته باشد، این شرط مطابقت ندارد اما مقدار آن حداقل یک عنصر در این لیست داشته باشد. این از همان نحو الگوی مطابقت به عنوان values استفاده می کند.

  • هدر

    رشته

    نام سربرگ. این شرط تنها در صورتی با نام مطابقت دارد که هر دو values و excludedValues ​​مشخص نشده باشند.

  • ارزش ها

    رشته[] اختیاری است

    اگر مشخص شده باشد، اگر مقدار سرصفحه حداقل با یک الگوی این لیست مطابقت داشته باشد، این شرط مطابقت دارد. این از تطبیق مقدار سرصفحه حساس به حروف بزرگ و کوچک به علاوه ساختارهای زیر پشتیبانی می‌کند:

    '*' : با هر تعداد کاراکتر مطابقت دارد.

    "؟" : با صفر یا یک کاراکتر مطابقت دارد.

    '*' و '؟' می توان با یک اسلش برگشت، به عنوان مثال '\*' و '\?'

HeaderOperation

Chrome 86+

این عملیات ممکن برای یک قانون "modifyHeaders" را توصیف می کند.

Enum

"ضمیمه"
یک ورودی جدید برای هدر مشخص شده اضافه می کند. این عملیات برای سرصفحه های درخواست پشتیبانی نمی شود.

"تنظیم"
مقدار جدیدی را برای هدر مشخص شده تنظیم می کند و هر سرصفحه موجود با همان نام را حذف می کند.

"حذف"
تمام ورودی های هدر مشخص شده را حذف می کند.

IsRegexSupportedResult

Chrome 87+

خواص

  • پشتیبانی می شود

    بولی

  • دلیل

    UnsupportedRegexReason اختیاری است

    دلیل پشتیبانی نشدن عبارت منظم را مشخص می کند. فقط در صورتی ارائه می شود که isSupported نادرست باشد.

MatchedRule

خواص

  • قانون شناسه

    شماره

    شناسه قانون منطبق

  • شناسه قوانین

    رشته

    شناسه Ruleset این قانون به آن تعلق دارد. برای قاعده ای که از مجموعه قوانین پویا نشات می گیرد، این برابر با DYNAMIC_RULESET_ID خواهد بود.

MatchedRuleInfo

خواص

  • حکومت کند

    MatchedRule

  • tabId

    شماره

    در صورتی که برگه هنوز فعال باشد، tabId برگه ای که درخواست از آن شروع شده است. در غیر این صورت -1.

  • مهر زمان

    شماره

    زمانی که قانون مطابقت داشت. مهرهای زمانی با قرارداد جاوا اسکریپت برای زمان ها مطابقت دارند، یعنی تعداد میلی ثانیه از زمان.

MatchedRuleInfoDebug

خواص

MatchedRulesFilter

خواص

  • minTimeStamp

    شماره اختیاری

    اگر مشخص شده باشد، فقط با قوانین پس از مهر زمانی مشخص مطابقت دارد.

  • tabId

    شماره اختیاری

    اگر مشخص شده باشد، فقط با قوانین برگه داده شده مطابقت دارد. اگر روی -1 تنظیم شود، قوانینی را که با هیچ برگه فعال مرتبط نیستند مطابقت می دهد.

ModifyHeaderInfo

Chrome 86+

خواص

  • هدر

    رشته

    نام هدر که باید اصلاح شود.

  • عملیات

    HeaderOperation

    عملیاتی که باید روی هدر انجام شود.

  • ارزش

    رشته اختیاری

    مقدار جدید برای هدر. باید برای عملیات append و set مشخص شود.

QueryKeyValue

خواص

  • کلید

    رشته

  • جایگزین فقط

    بولی اختیاری

    Chrome 94+

    اگر درست باشد، کلید پرس و جو تنها در صورتی جایگزین می شود که از قبل موجود باشد. در غیر این صورت، در صورت مفقود شدن کلید نیز اضافه می شود. پیش فرض به نادرست.

  • ارزش

    رشته

QueryTransform

خواص

  • addOrReplaceParams

    QueryKeyValue [] اختیاری است

    فهرست جفت‌های کلید-مقدار پرس و جو که باید اضافه یا جایگزین شوند.

  • حذف پارامز

    رشته[] اختیاری است

    فهرست کلیدهای پرس و جو که باید حذف شوند.

Redirect

خواص

  • extensionPath

    رشته اختیاری

    مسیر نسبت به دایرکتوری افزونه. باید با '/' شروع شود.

  • جایگزینی regex

    رشته اختیاری

    الگوی جایگزینی برای قوانینی که یک regexFilter مشخص می کنند. اولین تطابق regexFilter در آدرس اینترنتی با این الگو جایگزین خواهد شد. در regexSubstitution ، ارقام بک اسلش (\1 تا \9) را می توان برای درج گروه های ضبط مربوطه استفاده کرد. \ 0 به کل متن منطبق اشاره دارد.

  • تبدیل کنید

    URLTransform اختیاری است

    تبدیل URL برای انجام.

  • آدرس اینترنتی

    رشته اختیاری

    آدرس تغییر مسیر. تغییر مسیر به آدرس های اینترنتی جاوا اسکریپت مجاز نیست.

RegexOptions

Chrome 87+

خواص

  • isCaseSensitive است

    بولی اختیاری

    اینکه regex مشخص شده به حروف کوچک و بزرگ حساس است یا خیر. پیش فرض درست است.

  • regex

    رشته

    بیان منظم برای بررسی.

  • نیاز به گرفتن

    بولی اختیاری

    آیا regex مشخص شده نیاز به گرفتن دارد یا خیر. گرفتن تنها برای قوانین تغییر مسیر که یک عمل regexSubstition را مشخص می‌کنند لازم است. پیش فرض نادرست است.

RequestDetails

خواص

  • شناسه سند

    رشته اختیاری

    Chrome 106+

    اگر این درخواست برای یک فریم باشد، شناسه منحصربه‌فرد برای سند فریم.

  • documentLifecycle

    DocumentLifecycle اختیاری است

    Chrome 106+

    چرخه عمر سند فریم، اگر این درخواست برای یک فریم باشد.

  • frameId

    شماره

    مقدار 0 نشان می دهد که درخواست در فریم اصلی اتفاق می افتد. یک مقدار مثبت نشان دهنده شناسه زیرفریمی است که درخواست در آن انجام می شود. اگر سند یک قاب (زیر) بارگذاری شود ( type main_frame یا sub_frame است)، frameId نشان دهنده شناسه این قاب است، نه شناسه قاب بیرونی. شناسه‌های فریم در یک برگه منحصربه‌فرد هستند.

  • نوع قاب

    FrameType اختیاری است

    Chrome 106+

    نوع قاب، اگر این درخواست برای قاب باشد.

  • آغازگر

    رشته اختیاری

    مبدایی که در آن درخواست آغاز شد. این از طریق تغییر مسیر تغییر نمی کند. اگر منشا مات باشد، از رشته «تهی» استفاده خواهد شد.

  • روش

    رشته

    روش استاندارد HTTP

  • parentDocumentId

    رشته اختیاری

    Chrome 106+

    شناسه منحصربه‌فرد برای سند والد فریم، اگر این درخواست برای یک فریم باشد و یک والد داشته باشد.

  • parentFrameId

    شماره

    شناسه فریمی که فریمی را که درخواست ارسال کرده است می‌پیچد. اگر فریم والد وجود نداشته باشد، روی -1 تنظیم کنید.

  • درخواست شناسه

    رشته

    شناسه درخواست شناسه های درخواست در یک جلسه مرورگر منحصر به فرد هستند.

  • tabId

    شماره

    شناسه برگه ای که درخواست در آن انجام می شود. اگر درخواست مربوط به یک برگه نیست، روی -1 تنظیم کنید.

  • نوع منبع درخواست

  • آدرس اینترنتی

    رشته

    آدرس اینترنتی درخواست

RequestMethod

Chrome 91+

این روش درخواست HTTP درخواست شبکه را توصیف می کند.

Enum

"اتصال"

"حذف"

"دریافت"

"سر"

"گزینه ها"

"پچ"

"پست"

"قرار دادن"

"دیگر"

ResourceType

این نوع منبع درخواست شبکه را توصیف می کند.

Enum

"فریم_اصلی"

"sub_frame"

"شیوه نامه"

"اسکریپت"

"تصویر"

"فونت"

"شیء"

"xmlhttpدرخواست"

"پینگ"

"csp_report"

"رسانه"

"وب سوکت"

"انتقال وب"

"وبندل"

"دیگر"

Rule

خواص

  • اقدام

    RuleAction

    اقدامی که در صورت مطابقت با این قانون انجام می شود.

  • وضعیت

    RuleCondition

    شرایطی که تحت آن این قانون راه اندازی می شود.

  • شناسه

    شماره

    شناسه ای که به طور منحصر به فرد یک قانون را مشخص می کند. اجباری است و باید >= 1 باشد.

  • اولویت

    شماره اختیاری

    اولویت قانون پیش‌فرض 1 است. وقتی مشخص شد، باید >= 1 باشد.

RuleAction

خواص

  • تغییر مسیر

    تغییر مسیر اختیاری است

    توضیح می دهد که چگونه تغییر مسیر باید انجام شود. فقط برای قوانین تغییر مسیر معتبر است.

  • درخواست سرصفحه ها

    ModifyHeaderInfo [] اختیاری است

    Chrome 86+

    هدرهای درخواست برای تغییر درخواست. فقط در صورتی معتبر است که RuleActionType "modifyHeaders" باشد.

  • پاسخ سرصفحه ها

    ModifyHeaderInfo [] اختیاری است

    Chrome 86+

    هدرهای پاسخ برای تغییر درخواست. فقط زمانی معتبر است که RuleActionType "modifyHeaders" باشد.

  • نوع عمل برای انجام.

RuleActionType

نوع اقدامی را که در صورت مطابقت یک RuleCondition انجام می شود، شرح می دهد.

Enum

"بلاک کردن"
درخواست شبکه را مسدود کنید.

"تغییر مسیر"
درخواست شبکه را تغییر مسیر دهید.

"اجازه دادن"
درخواست شبکه را مجاز کنید. اگر یک قانون اجازه وجود داشته باشد که با آن مطابقت داشته باشد، درخواست رهگیری نخواهد شد.

"upgradeScheme"
اگر درخواست http یا ftp است، طرح URL درخواست شبکه را به https ارتقا دهید.

"modifyHeaders"
هدرهای درخواست/پاسخ را از درخواست شبکه تغییر دهید.

"AllowAllRequests"
اجازه دادن به تمام درخواست‌ها در یک سلسله مراتب فریم، از جمله خود درخواست فریم.

RuleCondition

خواص

  • نوع دامنه

    DomainType اختیاری است

    مشخص می کند که درخواست شبکه شخص اول باشد یا شخص ثالث به دامنه ای که از آن منشا گرفته است. در صورت حذف تمامی درخواست ها پذیرفته می شود.

  • دامنه ها

    رشته[] اختیاری است

    از Chrome 101 منسوخ شده است

    به جای آن از initiatorDomains استفاده کنید

    این قانون فقط با درخواست های شبکه که از لیست domains منشا می گیرند مطابقت دارد.

  • دامنه های حذف شده

    رشته[] اختیاری است

    از Chrome 101 منسوخ شده است

    به جای آن از excludedInitiatorDomains استفاده کنید

    این قانون با درخواست‌های شبکه که از لیست excludedDomains منشا می‌گیرند مطابقت نخواهد داشت.

  • excludedInitiatorDomains

    رشته[] اختیاری است

    Chrome 101+

    این قانون با درخواست های شبکه که از لیست excludedInitiatorDomains منشا می گیرند مطابقت نخواهد داشت. اگر لیست خالی یا حذف شده باشد، هیچ دامنه ای مستثنی نمی شود. این بر initiatorDomains اولویت دارد.

    یادداشت ها:

    • دامنه های فرعی مانند "a.example.com" نیز مجاز هستند.
    • ورودی ها باید فقط شامل کاراکترهای ascii باشند.
    • از کدگذاری punycode برای دامنه های بین المللی استفاده کنید.
    • این با آغازگر درخواست مطابقت دارد و نه با آدرس اینترنتی درخواست.
    • دامنه های فرعی دامنه های فهرست شده نیز مستثنی هستند.
  • excludedRequestDomains

    رشته[] اختیاری است

    Chrome 101+

    این قانون با درخواست‌های شبکه مطابقت نخواهد داشت وقتی دامنه‌ها با یکی از لیست excludedRequestDomains مطابقت داشته باشند. اگر لیست خالی یا حذف شده باشد، هیچ دامنه ای مستثنی نمی شود. این نسبت به requestDomains اولویت دارد.

    یادداشت ها:

    • دامنه های فرعی مانند "a.example.com" نیز مجاز هستند.
    • ورودی ها باید فقط شامل کاراکترهای ascii باشند.
    • از کدگذاری punycode برای دامنه های بین المللی استفاده کنید.
    • دامنه های فرعی دامنه های فهرست شده نیز مستثنی هستند.
  • excludedRequestMethods

    RequestMethod [] اختیاری است

    Chrome 91+

    فهرست روش‌های درخواستی که این قانون مطابقت ندارد. فقط یکی از requestMethods و excludedRequestMethods باید مشخص شود. اگر هیچ یک از آنها مشخص نشده باشد، همه روش های درخواست مطابقت دارند.

  • excludedResourceTypes

    نوع منبع [] اختیاری است

    فهرست انواع منابعی که این قانون مطابقت ندارد. فقط یکی از resourceTypes و excludedResourceTypes باید مشخص شود. اگر هیچ یک از آنها مشخص نشده باشد، همه انواع منابع به جز "main_frame" مسدود می شوند.

  • excludedResponseHeaders

    HeaderInfo [] اختیاری است

    Chrome 128+

    اگر درخواست با شرایط سرصفحه پاسخ در این لیست مطابقت داشته باشد (در صورت مشخص شدن) قانون مطابقت ندارد. اگر هر دو excludedResponseHeaders و responseHeaders مشخص شده باشند، ویژگی excludedResponseHeaders اولویت دارد.

  • excludedTabIds

    شماره[] اختیاری

    Chrome 92+

    فهرست tabs.Tab.id که قانون نباید مطابقت داشته باشد. شناسه tabs.TAB_ID_NONE درخواست‌هایی را که از یک برگه نشات نمی‌گیرند مستثنی می‌کند. فقط برای قوانین مربوط به جلسه پشتیبانی می شود.

  • InitiatorDomains

    رشته[] اختیاری است

    Chrome 101+

    این قانون فقط با درخواست‌های شبکه که از لیست initiatorDomains منشا می‌گیرند مطابقت دارد. اگر لیست حذف شود، این قانون برای درخواست های همه دامنه ها اعمال می شود. لیست خالی مجاز نیست.

    یادداشت ها:

    • دامنه های فرعی مانند "a.example.com" نیز مجاز هستند.
    • ورودی ها باید فقط شامل کاراکترهای ascii باشند.
    • از کدگذاری punycode برای دامنه های بین المللی استفاده کنید.
    • این با آغازگر درخواست مطابقت دارد و نه با آدرس اینترنتی درخواست.
    • دامنه های فرعی دامنه های فهرست شده نیز مطابقت دارند.
  • isUrlFilterCaseSensitive

    بولی اختیاری

    urlFilter یا regexFilter (هر کدام که مشخص شده است) به حروف کوچک و بزرگ حساس است. پیش فرض نادرست است.

  • regexFilter

    رشته اختیاری

    عبارت منظم برای مطابقت با URL درخواست شبکه. این از نحو RE2 پیروی می کند.

    توجه: فقط یکی از urlFilter یا regexFilter را می توان مشخص کرد.

    توجه: regexFilter باید فقط از کاراکترهای ASCII تشکیل شده باشد. این با url مطابقت دارد که میزبان در قالب punycode (در مورد دامنه‌های بین‌المللی شده) و سایر نویسه‌های غیر ascii در utf-8 کدگذاری شده است.

  • درخواست دامنه ها

    رشته[] اختیاری است

    Chrome 101+

    این قانون تنها زمانی با درخواست‌های شبکه مطابقت می‌کند که دامنه با یکی از فهرست requestDomains دامنه مطابقت داشته باشد. اگر لیست حذف شود، این قانون برای درخواست های همه دامنه ها اعمال می شود. لیست خالی مجاز نیست.

    یادداشت ها:

    • دامنه های فرعی مانند "a.example.com" نیز مجاز هستند.
    • ورودی ها باید فقط شامل کاراکترهای ascii باشند.
    • از کدگذاری punycode برای دامنه های بین المللی استفاده کنید.
    • دامنه های فرعی دامنه های فهرست شده نیز مطابقت دارند.
  • درخواست روشها

    RequestMethod [] اختیاری است

    Chrome 91+

    فهرست روش‌های درخواست HTTP که این قانون می‌تواند مطابقت داشته باشد. لیست خالی مجاز نیست.

    توجه: تعیین یک شرط قانون requestMethods درخواست‌های غیر HTTP را نیز حذف می‌کند، در حالی که تعیین excludedRequestMethods نمی‌تواند.

  • انواع منابع

    نوع منبع [] اختیاری است

    فهرست انواع منابعی که این قانون می تواند مطابقت داشته باشد. لیست خالی مجاز نیست.

    توجه: این باید برای قوانین allowAllRequests مشخص شود و ممکن است فقط شامل انواع منابع sub_frame و main_frame باشد.

  • پاسخ سرصفحه ها

    HeaderInfo [] اختیاری است

    Chrome 128+

    اگر درخواست با شرایط سرصفحه پاسخ در این لیست مطابقت داشته باشد (در صورت مشخص شدن) قانون مطابقت دارد.

  • tabIds

    شماره[] اختیاری

    Chrome 92+

    فهرست tabs.Tab.id که قانون باید مطابقت داشته باشد. شناسه tabs.TAB_ID_NONE با درخواست‌هایی مطابقت دارد که از یک برگه منشا نمی‌گیرند. لیست خالی مجاز نیست. فقط برای قوانین مربوط به جلسه پشتیبانی می شود.

  • urlFilter

    رشته اختیاری

    الگویی که با URL درخواست شبکه مطابقت دارد. سازه های پشتیبانی شده:

    '*' : Wildcard: با هر تعداد کاراکتر مطابقت دارد.

    '|' : لنگر چپ/راست: اگر در هر دو انتهای الگو استفاده شود، به ترتیب ابتدا/پایان url را مشخص می کند.

    '||' : لنگر نام دامنه: اگر در ابتدای الگو استفاده شود، شروع یک (زیر) دامنه URL را مشخص می کند.

    '^' : کاراکتر جداکننده: با هر چیزی به جز یک حرف، یک رقم یا یکی از موارد زیر مطابقت دارد: _ , - , . , یا % . این همچنین با انتهای URL مطابقت دارد.

    بنابراین urlFilter از بخش‌های زیر تشکیل شده است: (اختیاری لنگر سمت چپ/نام دامنه) + الگو + (لنگر راست اختیاری).

    اگر حذف شود، همه url ها مطابقت دارند. رشته خالی مجاز نیست.

    الگویی که با ||* شروع می شود مجاز نیست. به جای آن از * استفاده کنید.

    توجه: فقط یکی از urlFilter یا regexFilter را می توان مشخص کرد.

    توجه: urlFilter باید فقط از کاراکترهای ASCII تشکیل شده باشد. این با url مطابقت دارد که میزبان در قالب punycode (در مورد دامنه‌های بین‌المللی شده) و سایر نویسه‌های غیر ascii در utf-8 کدگذاری شده است. به عنوان مثال، وقتی آدرس درخواست http://abc.рф?q=ф باشد، urlFilter با آدرس http://abc.xn--p1ai/?q=%D1%84 مطابقت داده می شود.

Ruleset

خواص

  • فعال شد

    بولی

    اینکه آیا مجموعه قوانین به طور پیش فرض فعال است یا خیر.

  • شناسه

    رشته

    یک رشته غیر خالی که به طور منحصر به فرد مجموعه قوانین را شناسایی می کند. شناسه هایی که با '_' شروع می شوند برای استفاده داخلی رزرو شده اند.

  • مسیر

    رشته

    مسیر مجموعه قوانین JSON نسبت به فهرست برنامه افزودنی.

RulesMatchedDetails

خواص

  • rulesMatchedInfo

    MatchedRuleInfo []

    قوانین مطابق با فیلتر داده شده

TabActionCountUpdate

Chrome 89+

خواص

  • افزایش

    شماره

    مقداری که باید عمل برگه را افزایش دهید حساب می شود. مقادیر منفی تعداد را کاهش می دهد.

  • tabId

    شماره

    برگه ای که برای آن تعداد کنش ها به روز می شود.

TestMatchOutcomeResult

Chrome 103+

خواص

  • مطابق قوانین

    MatchedRule []

    قوانین (در صورت وجود) که با درخواست فرضی مطابقت دارد.

TestMatchRequestDetails

Chrome 103+

خواص

  • آغازگر

    رشته اختیاری

    URL آغازگر (در صورت وجود) برای درخواست فرضی.

  • روش

    RequestMethod اختیاری است

    روش استاندارد HTTP درخواست فرضی. برای درخواست های HTTP به طور پیش فرض "دریافت" است و برای درخواست های غیر HTTP نادیده گرفته می شود.

  • پاسخ سرصفحه ها

    شی اختیاری

    Chrome 129+

    اگر درخواست قبل از ارسال مسدود یا هدایت نشود، هدرها توسط یک پاسخ فرضی ارائه می‌شوند. به عنوان یک شی نشان داده می شود که نام سرصفحه را به لیستی از مقادیر رشته نگاشت می کند. اگر مشخص نشود، پاسخ فرضی سرصفحه‌های پاسخ خالی را برمی‌گرداند، که می‌تواند با قوانینی مطابقت داشته باشد که با عدم وجود هدر مطابقت دارند. به عنوان مثال {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}

  • tabId

    شماره اختیاری

    شناسه برگه ای که درخواست فرضی در آن انجام می شود. نیازی به مطابقت با شناسه برگه واقعی ندارد. پیش فرض -1 است، به این معنی که درخواست مربوط به یک برگه نیست.

  • نوع منبع درخواست فرضی.

  • آدرس اینترنتی

    رشته

    URL درخواست فرضی.

UnsupportedRegexReason

Chrome 87+

دلیل پشتیبانی نشدن یک عبارت منظم داده شده را توضیح می دهد.

Enum

"Error syntax"
عبارت منظم از نظر نحوی نادرست است یا از ویژگی هایی استفاده می کند که در نحو RE2 موجود نیست.

"MemoryLimitExceeded"
عبارت منظم بیش از حد حافظه است.

UpdateRuleOptions

Chrome 87+

خواص

  • addRules

    قانون [] اختیاری است

    قوانین برای اضافه کردن

  • removeRuleIds

    شماره[] اختیاری

    شناسه قوانین برای حذف. هر شناسه نامعتبر نادیده گرفته می شود.

UpdateRulesetOptions

Chrome 87+

خواص

  • disableRulesetIds

    رشته[] اختیاری است

    مجموعه ای از شناسه های مربوط به یک Ruleset ثابت که باید غیرفعال شود.

  • enableRulesetIds

    رشته[] اختیاری است

    مجموعه ای از شناسه های مربوط به یک Ruleset ثابت که باید فعال شود.

UpdateStaticRulesOptions

Chrome 111+

خواص

  • disableRuleIds

    شماره[] اختیاری

    مجموعه ای از شناسه های مربوط به قوانین موجود در Ruleset برای غیرفعال کردن.

  • enableRuleIds

    شماره[] اختیاری

    مجموعه ای از شناسه های مربوط به قوانین موجود در Ruleset برای فعال کردن.

  • شناسه قوانین

    رشته

    شناسه مربوط به یک Ruleset ثابت.

URLTransform

خواص

  • قطعه

    رشته اختیاری

    قطعه جدید برای درخواست. باید خالی باشد، در این صورت قطعه موجود پاک می شود. یا باید با "#" شروع شود.

  • میزبان

    رشته اختیاری

    میزبان جدید برای درخواست.

  • رمز عبور

    رشته اختیاری

    رمز عبور جدید برای درخواست

  • مسیر

    رشته اختیاری

    مسیر جدید برای درخواست اگر خالی باشد، مسیر موجود پاک می شود.

  • بندر

    رشته اختیاری

    پورت جدید برای درخواست اگر خالی باشد، پورت موجود پاک می شود.

  • پرس و جو

    رشته اختیاری

    درخواست جدید برای درخواست. باید خالی باشد، در این صورت کوئری موجود پاک می شود. یا باید با "؟" شروع شود.

  • query Transform

    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

Chrome 89+

حداقل تعداد قوانین ثابت تضمین شده برای یک برنامه افزودنی در سراسر مجموعه قوانین ثابت فعال آن. هر قاعده ای بالاتر از این حد به عنوان محدودیت جهانی ایستا به حساب می آید.

ارزش

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

تعداد دفعاتی که getMatchedRules را می توان در یک دوره GETMATCHEDRULES_QUOTA_INTERVAL فراخوانی کرد.

ارزش

20

MAX_NUMBER_OF_DYNAMIC_RULES

حداکثر تعداد قوانین پویا که یک برنامه افزودنی می تواند اضافه کند.

ارزش

30000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94+

حداکثر تعداد Rulesets ثابتی که یک برنامه افزودنی می تواند در هر زمان فعال کند.

ارزش

50

MAX_NUMBER_OF_REGEX_RULES

حداکثر تعداد قوانین عبارت منظم که یک برنامه افزودنی می تواند اضافه کند. این محدودیت به طور جداگانه برای مجموعه قوانین پویا و آنهایی که در فایل منابع قانون مشخص شده اند ارزیابی می شود.

ارزش

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120+

حداکثر تعداد قوانین محدوده جلسه که یک برنامه افزودنی می تواند اضافه کند.

ارزش

5000

MAX_NUMBER_OF_STATIC_RULESETS

حداکثر تعداد Rulesets ثابتی که یک برنامه افزودنی می تواند به عنوان بخشی از کلید مانیفست "rule_resources" تعیین کند.

ارزش

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120+

حداکثر تعداد قوانین پویا "ناامن" که یک برنامه افزودنی می تواند اضافه کند.

ارزش

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120+

حداکثر تعداد قوانین محدوده جلسه "ناامن" که یک برنامه افزودنی می تواند اضافه کند.

ارزش

5000

SESSION_RULESET_ID

Chrome 90+

شناسه مجموعه قواعد برای قوانین مربوط به جلسه اضافه شده توسط برنامه افزودنی.

ارزش

"_session"

روش ها

getAvailableStaticRuleCount()

Promise Chrome 89+
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
)

تعداد قوانین ثابتی را که یک برنامه افزودنی می‌تواند قبل از رسیدن به محدودیت جهانی قانون استاتیک فعال کند، برمی‌گرداند.

پارامترها

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (count: number) => void

    • شمارش

      شماره

برمی گرداند

  • قول <تعداد>

    Chrome 91+

    Promises فقط برای Manifest V3 و نسخه‌های جدیدتر پشتیبانی می‌شود، پلتفرم‌های دیگر باید از callback استفاده کنند.

getDisabledRuleIds()

Promise Chrome 111+
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
  callback?: function,
)

لیست قوانین استاتیک را در Ruleset داده شده که در حال حاضر غیرفعال هستند ، برمی گرداند.

پارامترها

  • گزینه ها

    getDisabledRuleIdSoptions

    قوانین مربوط به پرس و جو را مشخص می کند.

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (disabledRuleIds: number[]) => void

    • ناتوانی

      شماره []

برمی گرداند

  • وعده <شماره []>

    وعده ها فقط برای مانیفست V3 و بعد از آن پشتیبانی می شوند ، سایر سیستم عامل ها نیاز به استفاده از تماس تلفنی دارند.

getDynamicRules()

قول بده
chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
  callback?: function,
)

مجموعه فعلی قوانین پویا را برای پسوند برمی گرداند. تماس گیرندگان می توانند با مشخص کردن filter ، لیست قوانین واکشی را به صورت اختیاری فیلتر کنند.

پارامترها

  • فیلتر

    getrulesfilter اختیاری

    Chrome 111+

    یک شی برای فیلتر کردن لیست قوانین واکشی.

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (rules: Rule[]) => void

برمی گرداند

  • وعده < قانون []>

    Chrome 91+

    وعده ها فقط برای مانیفست V3 و بعد از آن پشتیبانی می شوند ، سایر سیستم عامل ها نیاز به استفاده از تماس تلفنی دارند.

getEnabledRulesets()

قول بده
chrome.declarativeNetRequest.getEnabledRulesets(
  callback?: function,
)

شناسه ها را برای مجموعه فعلی قوانین استاتیک فعال باز می گرداند.

پارامترها

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (rulesetIds: string[]) => void

    • قوانین قانونگذاری

      رشته []

برمی گرداند

  • وعده <رشته []>

    Chrome 91+

    وعده ها فقط برای مانیفست V3 و بعد از آن پشتیبانی می شوند ، سایر سیستم عامل ها نیاز به استفاده از تماس تلفنی دارند.

getMatchedRules()

قول بده
chrome.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
  callback?: function,
)

تمام قوانین مطابق با پسوند را برمی گرداند. تماس گیرندگان می توانند با مشخص کردن filter ، لیست قوانین همسان را فیلتر کنند. این روش فقط با مجوز "declarativeNetRequestFeedback" یا داشتن مجوز "activeTab" برای tabId مشخص شده در filter در دسترس است. توجه: قوانینی که با یک سند فعال که بیش از پنج دقیقه پیش با آن مطابقت داشته باشد ، همراه نخواهد بود.

پارامترها

  • فیلتر

    MatchedrulesFilter اختیاری

    یک شیء برای فیلتر کردن لیست قوانین همسان.

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (details: RulesMatchedDetails) => void

برمی گرداند

  • Chrome 91+

    وعده ها فقط برای مانیفست V3 و بعد از آن پشتیبانی می شوند ، سایر سیستم عامل ها نیاز به استفاده از تماس تلفنی دارند.

getSessionRules()

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

مجموعه فعلی قوانین scoped جلسه را برای پسوند برمی گرداند. تماس گیرندگان می توانند با مشخص کردن filter ، لیست قوانین واکشی را به صورت اختیاری فیلتر کنند.

پارامترها

  • فیلتر

    getrulesfilter اختیاری

    Chrome 111+

    یک شی برای فیلتر کردن لیست قوانین واکشی.

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (rules: Rule[]) => void

برمی گرداند

  • وعده < قانون []>

    Chrome 91+

    وعده ها فقط برای مانیفست V3 و بعد از آن پشتیبانی می شوند ، سایر سیستم عامل ها نیاز به استفاده از تماس تلفنی دارند.

isRegexSupported()

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

بررسی می کند که آیا بیان منظم داده شده به عنوان یک قانون regexFilter پشتیبانی می شود.

پارامترها

برمی گرداند

  • Chrome 91+

    وعده ها فقط برای مانیفست V3 و بعد از آن پشتیبانی می شوند ، سایر سیستم عامل ها نیاز به استفاده از تماس تلفنی دارند.

setExtensionActionOptions()

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

پیکربندی می کند اگر تعداد اقدامات مربوط به زبانه ها به عنوان متن نشان Action Action نمایش داده شود و راهی را برای افزایش تعداد عمل فراهم می کند.

پارامترها

  • گزینه ها

    ژنتیک

  • پاسخ به تماس

    عملکرد اختیاری

    Chrome 89+

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول <void>

    Chrome 91+

    وعده ها فقط برای مانیفست V3 و بعد از آن پشتیبانی می شوند ، سایر سیستم عامل ها نیاز به استفاده از تماس تلفنی دارند.

testMatchOutcome()

قول Chrome 103+
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
)

بررسی می کند که اگر هر یک از قوانین DelemarativenevetRequest با یک درخواست فرضی مطابقت داشته باشد. توجه: فقط برای پسوندهای بسته بندی نشده در دسترس است زیرا این تنها در زمان توسعه پسوند مورد استفاده قرار می گیرد.

پارامترها

برمی گرداند

  • وعده ها فقط برای مانیفست V3 و بعد از آن پشتیبانی می شوند ، سایر سیستم عامل ها نیاز به استفاده از تماس تلفنی دارند.

updateDynamicRules()

قول بده
chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
  callback?: function,
)

مجموعه فعلی قوانین پویا را برای پسوند اصلاح می کند. قوانین با شناسه های ذکر شده در options.removeRuleIds RemoveruleIds ابتدا حذف می شوند ، و سپس قوانینی که در options.addRules ارائه شده است. افزودنی ها اضافه می شوند. یادداشت ها:

  • این به روزرسانی به عنوان یک عمل اتمی واحد اتفاق می افتد: یا تمام قوانین مشخص شده اضافه می شوند و حذف می شوند ، یا خطایی بازگردانده می شود.
  • این قوانین در جلسات مرورگر و به روزرسانی های پسوند ادامه دارد.
  • قوانین استاتیک که به عنوان بخشی از بسته پسوند مشخص شده است با استفاده از این عملکرد قابل حذف نیست.
  • MAX_NUMBER_OF_DYNAMIC_RULES حداکثر تعداد قوانین پویا است که یک پسوند می تواند اضافه کند. تعداد قوانین ناامن نباید از MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES تجاوز کند.

پارامترها

  • گزینه ها

    به روزرسانی

    Chrome 87+
  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول <void>

    Chrome 91+

    وعده ها فقط برای مانیفست V3 و بعد از آن پشتیبانی می شوند ، سایر سیستم عامل ها نیاز به استفاده از تماس تلفنی دارند.

updateEnabledRulesets()

قول بده
chrome.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
  callback?: function,
)

مجموعه ای از قوانین استاتیک فعال را برای پسوند به روز می کند. قوانین با شناسه های ذکر شده در options.disableRulesetIds Disablerulesetids ابتدا حذف می شوند و سپس قوانین ذکر شده در options.enableRulesetIds enablerulesetids اضافه می شوند. توجه داشته باشید که مجموعه ای از قوانین استاتیک فعال در جلسات ادامه دارد اما در مورد به روزرسانی های پسوند ، یعنی rule_resources Manifely مجموعه ای از قوانین استاتیک فعال شده در هر به روزرسانی پسوند را تعیین می کند.

پارامترها

  • گزینه ها

    به روزرسانی

    Chrome 87+
  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول <void>

    Chrome 91+

    وعده ها فقط برای مانیفست V3 و بعد از آن پشتیبانی می شوند ، سایر سیستم عامل ها نیاز به استفاده از تماس تلفنی دارند.

updateSessionRules()

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

مجموعه فعلی قوانین scoped جلسه را برای پسوند اصلاح می کند. قوانین با شناسه های ذکر شده در options.removeRuleIds RemoveruleIds ابتدا حذف می شوند ، و سپس قوانینی که در options.addRules ارائه شده است. افزودنی ها اضافه می شوند. یادداشت ها:

  • این به روزرسانی به عنوان یک عمل اتمی واحد اتفاق می افتد: یا تمام قوانین مشخص شده اضافه می شوند و حذف می شوند ، یا خطایی بازگردانده می شود.
  • این قوانین در جلسات ادامه نمی یابد و از حافظه حمایت می شود.
  • MAX_NUMBER_OF_SESSION_RULES حداکثر تعداد قوانین جلسه است که یک برنامه افزودنی می تواند اضافه کند.

پارامترها

  • گزینه ها

    به روزرسانی

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول <void>

    Chrome 91+

    وعده ها فقط برای مانیفست V3 و بعد از آن پشتیبانی می شوند ، سایر سیستم عامل ها نیاز به استفاده از تماس تلفنی دارند.

updateStaticRules()

قول Chrome 111+
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
  callback?: function,
)

قوانین استاتیک فردی را در یک Ruleset غیرفعال و امکان پذیر می کند. تغییرات در قوانین متعلق به یک Ruleset معلول ، دفعه بعد که فعال می شود ، عملی می شود.

پارامترها

  • گزینه ها

    updatustaticrulesoptions

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول <void>

    وعده ها فقط برای مانیفست V3 و بعد از آن پشتیبانی می شوند ، سایر سیستم عامل ها نیاز به استفاده از تماس تلفنی دارند.

رویدادها

onRuleMatchedDebug

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

هنگامی که یک قاعده با یک درخواست مطابقت دارد ، اخراج شد. فقط برای پسوندهای بسته بندی نشده با مجوز "declarativeNetRequestFeedback" در دسترس است زیرا این مورد فقط برای اهداف اشکال زدایی مورد استفاده قرار می گیرد.

پارامترها