chrome.declarativeNetRequest

توضیحات

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

مجوزها

declarativeNetRequest
declarativeNetRequestWithHostAccess

declarativeNetRequestFeedback
host_permissions

در دسترس بودن

کروم ۸۴+

مانیفست

علاوه بر مجوزهایی که در بالا توضیح داده شد، انواع خاصی از مجموعه قوانین، به طور خاص مجموعه قوانین استاتیک، نیاز به اعلام کلید مانیفست "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).
  • با نفی هرگونه قانون مسدود شده‌ی منطبق، از مسدود شدن یک درخواست جلوگیری کنید.
  • تغییر مسیر یک درخواست شبکه.
  • هدرهای درخواست یا پاسخ را تغییر دهید.

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

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

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

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

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

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

فقط یکی از این انواع مجموعه قوانین وجود دارد. یک افزونه می‌تواند با فراخوانی updateDynamicRules() و updateSessionRules() به صورت پویا قوانین را به آنها اضافه یا حذف کند، مشروط بر اینکه از محدودیت‌های قوانین تجاوز نشود. برای اطلاعات در مورد محدودیت‌های قوانین، به Rule limits مراجعه کنید. می‌توانید مثالی از این مورد را در زیر مثال‌های کد مشاهده کنید.

مجموعه قوانین ایستا

برخلاف قوانین پویا و جلسه‌ای، قوانین ایستا هنگام نصب یا ارتقاء یک افزونه، بسته‌بندی، نصب و به‌روزرسانی می‌شوند. آن‌ها در فایل‌های قوانین با فرمت JSON ذخیره می‌شوند که با استفاده از کلیدهای "declarative_net_request" و "rule_resources" همانطور که در بالا توضیح داده شد ، و همچنین یک یا چند دیکشنری Ruleset به افزونه نشان داده می‌شوند. یک دیکشنری Ruleset شامل مسیری به فایل قوانین، یک شناسه برای مجموعه قوانین موجود در فایل و اینکه آیا مجموعه قوانین فعال یا غیرفعال است، می‌باشد. دو مورد آخر هنگام فعال یا غیرفعال کردن یک مجموعه قوانین به صورت برنامه‌نویسی مهم هستند.

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

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

فعال و غیرفعال کردن قوانین و مجموعه قوانین ایستا

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

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

به دلایل عملکردی، محدودیت‌هایی نیز برای تعداد قوانین و مجموعه قوانینی که می‌توانند همزمان فعال شوند، وجود دارد. برای بررسی تعداد قوانین اضافی که ممکن است فعال شوند، تابع getAvailableStaticRuleCount() را فراخوانی کنید. برای اطلاعات بیشتر در مورد محدودیت‌های قوانین، به Rule limits مراجعه کنید.

برای فعال یا غیرفعال کردن قوانین استاتیک، تابع 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"]
  }
}

فیلتر url کاراکترهای منطبق

کلید "condition" یک قانون، به کلید "urlFilter" اجازه می‌دهد تا روی URLهای تحت یک دامنه مشخص عمل کند. شما با استفاده از توکن‌های تطبیق الگو، الگوها را ایجاد می‌کنید. چند مثال در زیر نشان داده شده است.

urlFilter مسابقات مطابقت ندارد
"abc" https://abcd.com
https://example.com/abcd		 https://ab.com
"abc*d" https://abcd.com
https://example.com/abcxyzd		 https://abc.com
"||a.example.com" https://a.example.com/
https://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" تعریف‌شده توسط توسعه‌دهنده و توسط عملیات مشخص‌شده تعیین می‌شود.

    • اگر یک قانون به یک سرصفحه (header) اضافه شود، قوانین با اولویت پایین‌تر فقط می‌توانند به آن سرصفحه اضافه شوند. عملیات تنظیم (set) و حذف (remove) مجاز نیستند.
    • اگر یک قانون یک سرصفحه (header) تنظیم کند، آنگاه قوانین با اولویت پایین‌تر فقط می‌توانند به آن سرصفحه اضافه شوند. هیچ تغییر دیگری مجاز نیست.
    • اگر یک قانون، یک سرصفحه (header) را حذف کند، آنگاه قوانین با اولویت پایین‌تر نمی‌توانند سرصفحه را بیشتر تغییر دهند.

اولویت‌بندی قوانین بین افزونه‌ها

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

  1. قوانین با استفاده از فیلد "action" و به ترتیب زیر اولویت‌بندی می‌شوند:

    1. block
    2. redirect یا upgradeScheme
    3. allow یا allowAllRequests

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

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

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

قوانین ایستا

قوانین ایستا، آن‌هایی هستند که در فایل‌های قوانین اعلام‌شده در فایل مانیفست مشخص شده‌اند. یک افزونه می‌تواند تا ۵۰ مجموعه قوانین ایستا را به عنوان بخشی از کلید مانیفست "rule_resources" مشخص کند، اما فقط ۱۰ مورد از این مجموعه قوانین می‌توانند همزمان فعال شوند. مورد دوم MAX_NUMBER_OF_ENABLED_STATIC_RULESETS نامیده می‌شود. در مجموع، این مجموعه قوانین حداقل ۳۰،۰۰۰ قانون را تضمین می‌کنند. به این GUARANTEED_MINIMUM_STATIC_RULES می‌گویند.

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

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

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

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

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

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

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

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

یک declarativeNetRequest فقط برای درخواست‌هایی که به پشته شبکه می‌رسند اعمال می‌شود. این شامل پاسخ‌هایی از حافظه پنهان HTTP می‌شود، اما ممکن است شامل پاسخ‌هایی که از طریق کنترل‌کننده onfetch یک service worker عبور می‌کنند، نباشد. declarativeNetRequest بر پاسخ‌های تولید شده توسط service worker یا بازیابی شده از CacheStorage تأثیری نخواهد گذاشت، اما بر فراخوانی‌های fetch() که در یک service worker انجام می‌شود، تأثیر می‌گذارد.

منابع قابل دسترسی در وب

یک قانون 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);
}

مثال‌های قاعده

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

کلید «اولویت»

این مثال‌ها نیاز به مجوز میزبان برای *://*.example.com/* دارند.

برای تعیین اولویت یک URL خاص، به کلید "priority" (تعریف شده توسط توسعه‌دهنده)، کلید "action" و کلید "urlFilter" نگاه کنید. این مثال‌ها به فایل قانون نمونه‌ای که در زیر آنها نشان داده شده است، اشاره دارند.

پیمایش به https://google.com
دو قانون این URL را پوشش می‌دهند: قوانینی با شناسه‌های ۱ و ۴. قانون با شناسه ۱ اعمال می‌شود زیرا اقدامات "block" اولویت بالاتری نسبت به اقدامات "redirect" دارند. قوانین باقی‌مانده اعمال نمی‌شوند زیرا برای URLهای طولانی‌تر هستند.
پیمایش به https://google.com/1234
به دلیل طولانی‌تر شدن URL، اکنون علاوه بر قوانین با شناسه‌های ۱ و ۴، قانون با شناسه ۲ نیز مطابقت دارد. قانون با شناسه ۲ اعمال می‌شود زیرا "allow" اولویت بالاتری نسبت به "block" و "redirect" دارد.
پیمایش به https://google.com/12345
هر چهار قانون با این URL مطابقت دارند. قانون با شناسه ۳ اعمال می‌شود زیرا اولویت تعریف‌شده توسط توسعه‌دهنده آن بالاترین اولویت در گروه است. 
[
  {
    "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

کروم ۸۸+

خواص

  • نمایش تعداد اقدام به عنوان نشان متن

    بولی اختیاری

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

  • به‌روزرسانی برگه

    TabActionCountUpdate اختیاری است

    کروم ۸۹+

    جزئیات نحوه تنظیم تعداد اقدامات تب.

GetDisabledRuleIdsOptions

کروم ۱۱۱+

خواص

  • شناسه مجموعه قوانین

    رشته

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

GetRulesFilter

کروم ۱۱۱+

خواص

  • شناسه‌های قاعده

    عدد[] اختیاری

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

HeaderInfo

کروم ۱۲۸+

خواص

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

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

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

  • سربرگ

    رشته

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

  • ارزش‌ها

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

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

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

    '?' : با صفر یا یک کاراکتر مطابقت دارد.

    می‌توان از '*' و '?' با یک بک‌اسلش صرف نظر کرد، مثلاً '\*' و '\?'

HeaderOperation

کروم ۸۶+

این، عملیات ممکن برای یک قانون "modifyHeaders" را شرح می‌دهد.

شمارشی

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

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

"حذف کردن"
تمام ورودی‌های مربوط به سرآیند مشخص‌شده را حذف می‌کند.

IsRegexSupportedResult

کروم ۸۷+

خواص

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

    بولی

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

MatchedRule

خواص

  • شناسه قاعده

    شماره

    شناسه‌ی یک قانون منطبق.

  • شناسه مجموعه قوانین

    رشته

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

MatchedRuleInfo

خواص

  • شناسه برگه

    شماره

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

  • مهر زمانی

    شماره

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

MatchedRuleInfoDebug

خواص

MatchedRulesFilter

خواص

  • minTimeStamp

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

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

  • شناسه برگه

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

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

ModifyHeaderInfo

کروم ۸۶+

خواص

  • سربرگ

    رشته

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

  • عملیات

    عملیات هدر

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

  • ارزش

    رشته اختیاری

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

QueryKeyValue

خواص

  • کلید

    رشته

  • فقط جایگزین

    بولی اختیاری

    کروم ۹۴+

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

  • ارزش

    رشته

QueryTransform

خواص

  • پارامترهای addOrReplace

    مقدار کلید پرس‌وجو [] اختیاری

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

  • حذف پارامترها

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

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

Redirect

خواص

  • مسیر افزونه

    رشته اختیاری

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

  • جایگزینی regex

    رشته اختیاری

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

  • تبدیل کردن

    تبدیل URL اختیاری

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

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

    رشته اختیاری

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

RegexOptions

کروم ۸۷+

خواص

  • حساس به حروف بزرگ و کوچک

    بولی اختیاری

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

  • عبارت منظم

    رشته

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

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

    بولی اختیاری

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

RequestDetails

خواص

  • شناسه سند

    رشته اختیاری

    کروم ۱۰۶+

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

  • چرخه عمر سند

    چرخه عمر سند (اختیاری)

    کروم ۱۰۶+

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

  • شناسه قاب

    شماره

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

  • نوع قاب

    نوع قاب اختیاری

    کروم ۱۰۶+

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

  • آغازگر

    رشته اختیاری

    مبدایی که درخواست از آنجا آغاز شده است. این مورد از طریق تغییر مسیرها تغییر نمی‌کند. اگر این یک مبدا مبهم باشد، از رشته 'null' استفاده خواهد شد.

  • روش

    رشته

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

  • شناسه سند والد

    رشته اختیاری

    کروم ۱۰۶+

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

  • شناسه والدفریم

    شماره

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

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

    رشته

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

  • شناسه برگه

    شماره

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

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

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

    رشته

    آدرس اینترنتی (URL) درخواست.

RequestMethod

کروم ۹۱+

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

شمارشی

"وصل کردن"

"حذف"

"دریافت"

"سر"

«گزینه‌ها»

"وصله"

«پست»

"گذاشتن"

«دیگر»

ResourceType

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

شمارشی

"فریم_اصلی"

"زیر_فریم"

"شیوه‌نامه"

«فیلمنامه»

«تصویر»

"فونت"

"شیء"

"درخواست xmlhttp"

"پینگ"

"گزارش csp"

«رسانه»

"سوکت وب"

"حمل و نقل تحت وب"

"بسته وب"

«دیگر»

Rule

خواص

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

  • وضعیت

    شرط قاعده

    شرایطی که تحت آن این قانون فعال می‌شود.

  • شناسه

    شماره

    یک شناسه که به طور منحصر به فرد یک قانون را مشخص می‌کند. اجباری است و باید بزرگتر یا مساوی ۱ باشد.

  • اولویت

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

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

RuleAction

خواص

  • تغییر مسیر

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

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

  • درخواست‌ها

    ModifyHeaderInfo [] اختیاری

    کروم ۸۶+

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

  • هدرهای پاسخ

    ModifyHeaderInfo [] اختیاری

    کروم ۸۶+

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

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

RuleActionType

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

شمارشی

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

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

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

"طرح ارتقا"
اگر درخواست از نوع http یا ftp است، طرح آدرس اینترنتی درخواست شبکه را به https ارتقا دهید.

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

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

RuleCondition

خواص

  • نوع دامنه

    نوع دامنه اختیاری

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

  • دامنه‌ها

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

    از زمان کروم ۱۰۱ منسوخ شده است

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

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

  • دامنه‌های مستثنی‌شده

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

    از زمان کروم ۱۰۱ منسوخ شده است

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

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

  • دامنه‌های آغازگر مستثنی‌شده

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

    کروم ۱۰۱+

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

    یادداشت‌ها:

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

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

    کروم ۱۰۱+

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

    یادداشت‌ها:

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

    RequestMethod [] اختیاری

    کروم ۹۱+

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

  • انواع منابع مستثنی شده

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

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

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

    اطلاعات سربرگ [] اختیاری

    کروم ۱۲۸+

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

  • TabId های حذف شده

    عدد[] اختیاری

    کروم ۹۲+

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

  • دامنه‌های آغازگر

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

    کروم ۱۰۱+

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

    یادداشت‌ها:

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

    بولی اختیاری

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

  • فیلتر منظم

    رشته اختیاری

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

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

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

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

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

    کروم ۱۰۱+

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

    یادداشت‌ها:

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

    RequestMethod [] اختیاری

    کروم ۹۱+

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

    نکته: تعیین شرط قانون requestMethods ، درخواست‌های غیر HTTP(ها) را نیز مستثنی می‌کند، در حالی که تعیین excludedRequestMethods چنین نخواهد کرد.

  • انواع منابع

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

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

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

  • هدرهای پاسخ

    اطلاعات سربرگ [] اختیاری

    کروم ۱۲۸+

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

  • شناسه‌های برگه

    عدد[] اختیاری

    کروم ۹۲+

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

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

    رشته اختیاری

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

    '*' : کاراکتر جایگزین: با هر تعداد کاراکتر مطابقت دارد.

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

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

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

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

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

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

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

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

Ruleset

خواص

  • فعال شده

    بولی

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

  • شناسه

    رشته

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

  • مسیر

    رشته

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

RulesMatchedDetails

خواص

TabActionCountUpdate

کروم ۸۹+

خواص

  • افزایش

    شماره

    مقداری که تعداد اقدامات تب را افزایش می‌دهد. مقادیر منفی تعداد را کاهش می‌دهند.

  • شناسه برگه

    شماره

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

TestMatchOutcomeResult

کروم ۱۰۳+

خواص

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

    MatchedRule []

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

TestMatchRequestDetails

کروم ۱۰۳+

خواص

  • آغازگر

    رشته اختیاری

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

  • روش

    روش درخواست اختیاری است

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

  • هدرهای پاسخ

    شیء اختیاری

    کروم ۱۲۹+

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

  • شناسه برگه

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

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

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

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

    رشته

    آدرس اینترنتی (URL) درخواست فرضی.

UnsupportedRegexReason

کروم ۸۷+

دلیل پشتیبانی نشدن یک عبارت منظم مشخص را شرح می‌دهد.

شمارشی

"خطای نحوی"
عبارت منظم از نظر نحوی نادرست است، یا از ویژگی‌هایی استفاده می‌کند که در نحو RE2 موجود نیست.

"حافظه از حد مجاز فراتر رفت"
عبارت منظم از محدودیت حافظه فراتر می‌رود.

UpdateRuleOptions

کروم ۸۷+

خواص

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

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

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

  • حذف شناسه‌های قوانین

    عدد[] اختیاری

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

UpdateRulesetOptions

کروم ۸۷+

خواص

  • غیرفعال کردن شناسه‌های تنظیم‌کننده‌ی قواعد

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

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

  • enableRulesetIds

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

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

UpdateStaticRulesOptions

کروم ۱۱۱+

خواص

  • غیرفعال کردن شناسه‌های قاعده

    عدد[] اختیاری

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

  • enableRuleIds

    عدد[] اختیاری

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

  • شناسه مجموعه قوانین

    رشته

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

URLTransform

خواص

  • قطعه قطعه

    رشته اختیاری

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

  • میزبان

    رشته اختیاری

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

  • رمز عبور

    رشته اختیاری

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

  • مسیر

    رشته اختیاری

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

  • بندر

    رشته اختیاری

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

  • پرس و جو

    رشته اختیاری

    عبارت جستجوی جدید برای درخواست. یا باید خالی باشد، که در این صورت عبارت جستجوی موجود پاک می‌شود؛ یا باید با '?' شروع شود.

  • پرس و جو تبدیل

    تبدیل پرس و جو اختیاری

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

  • طرح

    رشته اختیاری

    طرح جدید برای درخواست. مقادیر مجاز عبارتند از "http"، "https"، "ftp" و "chrome-extension".

  • نام کاربری

    رشته اختیاری

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

خواص

DYNAMIC_RULESET_ID

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

ارزش

"_پویا"

GETMATCHEDRULES_QUOTA_INTERVAL

Time interval within which MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules calls can be made, specified in minutes. Additional calls will fail immediately and set runtime.lastError . Note: getMatchedRules calls associated with a user gesture are exempt from the quota.

ارزش

۱۰

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89+

The minimum number of static rules guaranteed to an extension across its enabled static rulesets. Any rules above this limit will count towards the global static rule limit .

ارزش

۳۰۰۰۰

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

The number of times getMatchedRules can be called within a period of GETMATCHEDRULES_QUOTA_INTERVAL .

ارزش

۲۰

MAX_NUMBER_OF_DYNAMIC_RULES

The maximum number of dynamic rules that an extension can add.

ارزش

۳۰۰۰۰

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94+

The maximum number of static Rulesets an extension can enable at any one time.

ارزش

۵۰

MAX_NUMBER_OF_REGEX_RULES

The maximum number of regular expression rules that an extension can add. This limit is evaluated separately for the set of dynamic rules and those specified in the rule resources file.

ارزش

۱۰۰۰

MAX_NUMBER_OF_SESSION_RULES

کروم ۱۲۰+

The maximum number of session scoped rules that an extension can add.

ارزش

۵۰۰۰

MAX_NUMBER_OF_STATIC_RULESETS

The maximum number of static Rulesets an extension can specify as part of the "rule_resources" manifest key.

ارزش

۱۰۰

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

کروم ۱۲۰+

The maximum number of "unsafe" dynamic rules that an extension can add.

ارزش

۵۰۰۰

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

کروم ۱۲۰+

The maximum number of "unsafe" session scoped rules that an extension can add.

ارزش

۵۰۰۰

SESSION_RULESET_ID

کروم ۹۰+

Ruleset ID for the session-scoped rules added by the extension.

ارزش

"_session"

روش‌ها

getAvailableStaticRuleCount()

PromiseChrome 89+
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
): Promise<number>

Returns the number of static rules an extension can enable before the global static rule limit is reached.

پارامترها

  • تماس برگشتی

    function optional

    The callback parameter looks like: 

    (count: number) => void

    • بشمار

      شماره

بازگشت‌ها

  • Promise<number>

    Chrome 91+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

getDisabledRuleIds()

PromiseChrome 111+
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
  callback?: function,
): Promise<number[]>

Returns the list of static rules in the given Ruleset that are currently disabled.

پارامترها

  • گزینه‌ها

    GetDisabledRuleIdsOptions

    Specifies the ruleset to query.

  • تماس برگشتی

    function optional

    The callback parameter looks like: 

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      number[]

بازگشت‌ها

  • Promise<number[]>

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

getDynamicRules()

وعده
chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
  callback?: function,
): Promise<Rule[]>

Returns the current set of dynamic rules for the extension. Callers can optionally filter the list of fetched rules by specifying a filter .

پارامترها

  • فیلتر

    GetRulesFilter optional

    Chrome 111+

    An object to filter the list of fetched rules.

  • تماس برگشتی

    function optional

    The callback parameter looks like: 

    (rules: Rule[]) => void

    • قوانین

      Rule []

بازگشت‌ها

  • Promise< Rule []>

    Chrome 91+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

getEnabledRulesets()

وعده
chrome.declarativeNetRequest.getEnabledRulesets(
  callback?: function,
): Promise<string[]>

Returns the ids for the current set of enabled static rulesets.

پارامترها

  • تماس برگشتی

    function optional

    The callback parameter looks like: 

    (rulesetIds: string[]) => void

    • rulesetIds

      رشته[]

بازگشت‌ها

  • Promise<string[]>

    Chrome 91+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

getMatchedRules()

وعده
chrome.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
  callback?: function,
): Promise<RulesMatchedDetails>

Returns all rules matched for the extension. Callers can optionally filter the list of matched rules by specifying a filter . This method is only available to extensions with the "declarativeNetRequestFeedback" permission or having the "activeTab" permission granted for the tabId specified in filter . Note: Rules not associated with an active document that were matched more than five minutes ago will not be returned.

پارامترها

بازگشت‌ها

  • Chrome 91+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

getSessionRules()

PromiseChrome 90+
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
  callback?: function,
): Promise<Rule[]>

Returns the current set of session scoped rules for the extension. Callers can optionally filter the list of fetched rules by specifying a filter .

پارامترها

  • فیلتر

    GetRulesFilter optional

    Chrome 111+

    An object to filter the list of fetched rules.

  • تماس برگشتی

    function optional

    The callback parameter looks like: 

    (rules: Rule[]) => void

    • قوانین

      Rule []

بازگشت‌ها

  • Promise< Rule []>

    Chrome 91+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

isRegexSupported()

PromiseChrome 87+
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
  callback?: function,
): Promise<IsRegexSupportedResult>

Checks if the given regular expression will be supported as a regexFilter rule condition.

پارامترها

بازگشت‌ها

  • Chrome 91+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

setExtensionActionOptions()

PromiseChrome 88+
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
  callback?: function,
): Promise<void>

Configures if the action count for tabs should be displayed as the extension action's badge text and provides a way for that action count to be incremented.

پارامترها

  • گزینه‌ها

    ExtensionActionOptions

  • تماس برگشتی

    function optional

    Chrome 89+

    The callback parameter looks like: 

    () => void

بازگشت‌ها

  • Promise<void>

    Chrome 91+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

testMatchOutcome()

PromiseChrome 103+
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
): Promise<TestMatchOutcomeResult>

Checks if any of the extension's declarativeNetRequest rules would match a hypothetical request. Note: Only available for unpacked extensions as this is only intended to be used during extension development.

پارامترها

بازگشت‌ها

  • Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

updateDynamicRules()

وعده
chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
  callback?: function,
): Promise<void>

Modifies the current set of dynamic rules for the extension. The rules with IDs listed in options.removeRuleIds are first removed, and then the rules given in options.addRules are added. Notes:

  • This update happens as a single atomic operation: either all specified rules are added and removed, or an error is returned.
  • These rules are persisted across browser sessions and across extension updates.
  • Static rules specified as part of the extension package can not be removed using this function.
  • MAX_NUMBER_OF_DYNAMIC_RULES is the maximum number of dynamic rules an extension can add. The number of unsafe rules must not exceed MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES .

پارامترها

  • گزینه‌ها

    UpdateRuleOptions

    Chrome 87+
  • تماس برگشتی

    function optional

    The callback parameter looks like: 

    () => void

بازگشت‌ها

  • Promise<void>

    Chrome 91+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

updateEnabledRulesets()

وعده
chrome.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
  callback?: function,
): Promise<void>

Updates the set of enabled static rulesets for the extension. The rulesets with IDs listed in options.disableRulesetIds are first removed, and then the rulesets listed in options.enableRulesetIds are added. Note that the set of enabled static rulesets is persisted across sessions but not across extension updates, ie the rule_resources manifest key will determine the set of enabled static rulesets on each extension update.

پارامترها

  • گزینه‌ها

    UpdateRulesetOptions

    Chrome 87+
  • تماس برگشتی

    function optional

    The callback parameter looks like: 

    () => void

بازگشت‌ها

  • Promise<void>

    Chrome 91+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

updateSessionRules()

PromiseChrome 90+
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
  callback?: function,
): Promise<void>

Modifies the current set of session scoped rules for the extension. The rules with IDs listed in options.removeRuleIds are first removed, and then the rules given in options.addRules are added. Notes:

  • This update happens as a single atomic operation: either all specified rules are added and removed, or an error is returned.
  • These rules are not persisted across sessions and are backed in memory.
  • MAX_NUMBER_OF_SESSION_RULES is the maximum number of session rules an extension can add.

پارامترها

  • گزینه‌ها

    UpdateRuleOptions

  • تماس برگشتی

    function optional

    The callback parameter looks like: 

    () => void

بازگشت‌ها

  • Promise<void>

    Chrome 91+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

updateStaticRules()

PromiseChrome 111+
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
  callback?: function,
): Promise<void>

Disables and enables individual static rules in a Ruleset . Changes to rules belonging to a disabled Ruleset will take effect the next time that it becomes enabled.

پارامترها

  • گزینه‌ها

    UpdateStaticRulesOptions

  • تماس برگشتی

    function optional

    The callback parameter looks like: 

    () => void

بازگشت‌ها

  • Promise<void>

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

رویدادها

onRuleMatchedDebug

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

Fired when a rule is matched with a request. Only available for unpacked extensions with the "declarativeNetRequestFeedback" permission as this is intended to be used for debugging purposes only.

پارامترها