chrome.declarativeNetRequest

توضیحات

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

مجوزها

declarativeNetRequest
declarativeNetRequestWithHostAccess

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

"declarativeNetRequest"
در زمان نصب، یک هشدار مجوز را راه‌اندازی می‌کند، اما دسترسی ضمنی برای allow ، allowAllRequests و قوانین block را فراهم می‌کند. در صورت امکان از این مورد استفاده کنید تا نیازی به درخواست دسترسی کامل به هاست نداشته باشید.
"declarativeNetRequestFeedback"
ویژگی‌های اشکال‌زدایی را برای برنامه‌های افزودنی بدون بسته ، به‌ویژه getMatchedRules() و onRuleMatchedDebug فعال می‌کند.
"declarativeNetRequestWithHostAccess"
اخطار مجوز در زمان نصب نشان داده نمی‌شود، اما قبل از اینکه بتوانید هر اقدامی را روی میزبان انجام دهید، باید مجوزهای میزبان را درخواست کنید. این زمانی مناسب است که می‌خواهید از قوانین درخواست خالص اعلامی در برنامه‌های افزودنی استفاده کنید که از قبل دارای مجوزهای میزبان بدون ایجاد هشدارهای اضافی است.

در دسترس بودن

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 تعریف می شوند. حداکثر محدودیت 5000 قانون ثابت غیرفعال وجود دارد.

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

درخواست Net Declarative این امکان را فراهم می کند که URL ها را با یک نحو مطابق الگو یا عبارات منظم مطابقت دهد.

نحو فیلتر URL

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

urlFilter مسابقات مطابقت ندارد
"abc" https://abcd.com
https://example.com/abcd		 https://ab.com
"abc*d" https://abcd.com
https://example.com/abcxyzd		 https://abc.com
"||a.example.com" https://a.example.com/
https://baexample.com/xyz
https://a.example.company		 https://example.com/
"|https*" https://example.com http://example.com/
http://https.com
"example*^123|" https://example.com/123
http://abc.com/example?123		 https://example.com/1234
https://abc.com/example0123

عبارات منظم

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

شرایط URL خوب را بنویسید

هنگام نوشتن قوانین مراقب باشید که همیشه با کل دامنه مطابقت داشته باشد. در غیر این صورت، قانون شما ممکن است در شرایط غیرمنتظره مطابقت داشته باشد. به عنوان مثال، هنگام استفاده از نحو تطبیق الگو:

  • google.com به اشتباه https://example.com/?param=google.com مطابقت دارد
  • ||google.com به اشتباه https://google.company مطابقت دارد
  • https://www.google.com به اشتباه https://example.com/?param=https://www.google.com مطابقت دارد

استفاده را در نظر بگیرید:

  • ||google.com/ که با همه مسیرها و همه زیردامنه ها مطابقت دارد.
  • |https://www.google.com/ که با همه مسیرها و بدون زیردامنه مطابقت دارد.

به طور مشابه، از کاراکترهای ^ و / برای لنگر انداختن یک عبارت منظم استفاده کنید. برای مثال، ^https:\/\/www\.google\.com\/ با هر مسیری در https://www.google.com مطابقت دارد.

ارزیابی قوانین

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

قبل از درخواست

قبل از درخواست، یک برنامه افزودنی می‌تواند آن را با یک قانون منطبق مسدود یا تغییر مسیر دهد (از جمله ارتقای طرح از HTTP به HTTPS).

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

سپس، برای هر برنامه افزودنی، Chrome در هر درخواست حداکثر یک نامزد را انتخاب می‌کند. Chrome با ترتیب دادن همه قوانین منطبق بر اساس اولویت، یک قانون منطبق را پیدا می‌کند. قوانین با اولویت یکسان بر اساس عمل مرتب می شوند ( allow یا allowAllRequests > block > upgradeScheme > redirect ).

اگر نامزد یک قانون allow یا allowAllRequests باشد، یا چارچوبی که درخواست در حال انجام است، قبلاً با قانون allowAllRequests با اولویت بالاتر یا برابر از این پسوند مطابقت داده شده است، درخواست "مجاز" است و برنامه افزودنی هیچ تاثیری بر روی درخواست کنید.

اگر بیش از یک برنامه افزودنی بخواهد این درخواست را مسدود یا تغییر مسیر دهد، یک اقدام واحد برای انجام انتخاب می شود. Chrome این کار را با مرتب‌سازی قوانین در block سفارش > redirect یا upgradeScheme > allow یا allowAllRequests انجام می‌دهد. اگر دو قانون از یک نوع باشند، Chrome قانون را از جدیدترین برنامه افزودنی نصب شده انتخاب می کند.

قبل از ارسال سرصفحه درخواست

قبل از اینکه Chrome سرصفحه‌های درخواست را به سرور ارسال کند، سرصفحه‌ها براساس قوانین مطابق با modifyHeaders به‌روزرسانی می‌شوند.

Chrome در یک برنامه افزودنی، فهرستی از تغییرات را ایجاد می‌کند تا با یافتن همه قوانین مطابق با modifyHeaders انجام شود. مشابه قبل، فقط قوانینی که اولویت بالاتری نسبت به قوانین تطبیق allow یا allowAllRequests دارند گنجانده شده است.

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

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

پس از دریافت پاسخ

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

پس از مرتب‌سازی این قوانین بر اساس action و priority و مستثنی کردن قوانینی که توسط قانون منطبق allow یا allowAllRequests اضافه شده‌اند (این امر دقیقاً مشابه مراحل «قبل از درخواست» اتفاق می‌افتد)، Chrome ممکن است درخواست را از طرف یک برنامه افزودنی مسدود یا تغییر مسیر دهد.

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

در مورد قانون مسدود کردن، صفحه‌ای که درخواست را وادار به دریافت پاسخ مسدود کرده و کروم درخواست را زودتر خاتمه می‌دهد، این کار را انجام می‌دهد. در مورد یک قانون تغییر مسیر، کروم یک درخواست جدید به URL هدایت شده ارسال می کند. حتماً در نظر بگیرید که آیا این رفتارها انتظارات حفظ حریم خصوصی برای برنامه افزودنی شما را برآورده می کند یا خیر.

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

قوانین ایمن

قوانین ایمن به عنوان قوانینی با عملکرد block ، allow ، allowAllRequests یا upgradeScheme تعریف می شوند. این قوانین مشمول افزایش سهمیه قوانین پویا هستند.

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

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

قوانین ایستا

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

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

قوانین جلسه

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

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

قوانین پویا

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

از Chrome 121، محدودیت بزرگتری از 30000 قانون برای قوانین پویا ایمن موجود است که به عنوان MAX_NUMBER_OF_DYNAMIC_RULES در معرض دید قرار می‌گیرند. هر گونه قوانین ناامن اضافه شده در محدوده 5000 نیز جزو این محدودیت محسوب می شود.

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

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

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

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

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

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

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

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

یک قانون declarativeNetRequest نمی تواند از یک درخواست منبع عمومی به منبعی که قابل دسترسی به وب نیست هدایت شود. انجام این کار باعث بروز خطا می شود. این درست است حتی اگر منبع قابل دسترس وب مشخص شده متعلق به پسوند تغییر مسیر باشد. برای اعلام منابع برای declarativeNetRequest، از آرایه "web_accessible_resources" مانیفست استفاده کنید.

اصلاح هدر

عملیات الحاق فقط برای سرصفحه‌های زیر پشتیبانی می‌شود: accept ، accept-encoding ، accept-language ، access-control-request-headers ، cache-control ، connection ، content-language ، cookie ، forwarded ، if-match ، if-none-match , keep-alive , range , te , trailer , transfer-encoding , upgrade , user-agent , via , want-digest , x-forwarded-for .

نمونه ها

نمونه های کد

قوانین پویا را به روز کنید

مثال زیر نحوه فراخوانی updateDynamicRules() را نشان می دهد. رویه updateSessionRules() یکسان است.

// Get arrays containing new and old rules
const newRules = await getNewRules();
const oldRules = await chrome.declarativeNetRequest.getDynamicRules();
const oldRuleIds = oldRules.map(rule => rule.id);

// Use the arrays to update the dynamic rules
await chrome.declarativeNetRequest.updateDynamicRules({
  removeRuleIds: oldRuleIds,
  addRules: newRules
});

به روز رسانی قوانین استاتیک

مثال زیر نحوه فعال و غیرفعال کردن مجموعه قوانین را با در نظر گرفتن تعداد قوانین موجود و حداکثر تعداد قوانین ثابت فعال نشان می دهد. این کار را زمانی انجام می دهید که تعداد قوانین ثابت مورد نیاز شما از تعداد مجاز بیشتر شود. برای این کار، برخی از قوانین شما باید با برخی از قوانین غیرفعال نصب شوند (تنظیم "Enabled" روی false در فایل مانیفست).

async function updateStaticRules(enableRulesetIds, disableCandidateIds) {
  // Create the options structure for the call to updateEnabledRulesets()
  let options = { enableRulesetIds: enableRulesetIds }
  // Get the number of enabled static rules
  const enabledStaticCount = await chrome.declarativeNetRequest.getEnabledRulesets();
  // Compare rule counts to determine if anything needs to be disabled so that
  // new rules can be enabled
  const proposedCount = enableRulesetIds.length;
  if (enabledStaticCount + proposedCount > chrome.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS) {
    options.disableRulesetIds = disableCandidateIds
  }
  // Update the enabled static rules
  await chrome.declarativeNetRequest.updateEnabledRulesets(options);
}

نمونه قوانین

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

کلید "اولویت".

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

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

به https://google.com پیمایش کنید
دو قانون این URL را پوشش می‌دهند: قوانین با شناسه‌های 1 و 4. قانون با شناسه 1 اعمال می‌شود زیرا اقدامات "block" اولویت بیشتری نسبت به اقدامات "redirect" دارند. قوانین باقیمانده اعمال نمی شوند زیرا برای URL های طولانی تر هستند.
به https://google.com/1234 پیمایش کنید
به دلیل طولانی‌تر بودن URL، قانون با شناسه 2 اکنون علاوه بر قوانین با شناسه‌های 1 و 4 مطابقت دارد. قانون با شناسه 2 اعمال می‌شود زیرا "allow" اولویت بیشتری نسبت به "block" و "redirect" دارد.
به https://google.com/12345 پیمایش کنید
هر چهار قانون با این URL مطابقت دارند. قانون با شناسه 3 اعمال می شود زیرا اولویت تعریف شده توسط توسعه دهنده بالاترین اولویت گروه است. 
[
  {
    "id": 1,
    "priority": 1,
    "action": { "type": "block" },
    "condition": {"urlFilter": "||google.com/", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 2,
    "priority": 1,
    "action": { "type": "allow" },
    "condition": { "urlFilter": "||google.com/123", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 3,
    "priority": 2,
    "action": { "type": "block" },
    "condition": { "urlFilter": "||google.com/12345", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 4,
    "priority": 1,
    "action": { "type": "redirect", "redirect": { "url": "https://example.com" } },
    "condition": { "urlFilter": "||google.com/", "resourceTypes": ["main_frame"] }
  },
]

تغییر مسیرها

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

مثال زیر نشان می دهد که چگونه یک درخواست از example.com را به صفحه ای در خود پسوند هدایت کنید. مسیر برنامه افزودنی /a.jpg به chrome-extension://EXTENSION_ID/a.jpg تغییر می کند، جایی که EXTENSION_ID شناسه برنامه افزودنی شما است. برای این کار، مانیفست باید /a.jpg به عنوان یک منبع قابل دسترسی وب اعلام کند.

{
  "id": 1,
  "priority": 1,
  "action": { "type": "redirect", "redirect": { "extensionPath": "/a.jpg" } },
  "condition": {
    "urlFilter": "||https://www.example.com/",
    "resourceTypes": ["main_frame"]
  }
}

در زیر از کلید "transform" برای تغییر مسیر به یک زیر دامنه از example.com استفاده می شود. از یک لنگر نام دامنه ("||") برای رهگیری درخواست ها با هر طرحی از example.com استفاده می کند. کلید "scheme" در "transform" مشخص می کند که تغییر مسیرها به زیر دامنه همیشه از "https" استفاده می کنند.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": {
      "transform": { "scheme": "https", "host": "new.example.com" }
    }
  },
  "condition": {
    "urlFilter": "||example.com/",
    "resourceTypes": ["main_frame"]
  }
}

مثال زیر از عبارات منظم برای تغییر مسیر از https://www.abc.xyz.com/path به https://abc.xyz.com/path استفاده می کند. در کلید "regexFilter" ، توجه کنید که چگونه از نقطه ها فرار می شود و گروه عکسبرداری "abc" یا "def" را انتخاب می کند. کلید "regexSubstitution" اولین تطابق بازگشتی عبارت منظم را با استفاده از "\1" مشخص می کند. در این مورد، "abc" از URL هدایت شده گرفته می شود و در جایگزینی قرار می گیرد. 

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": {
      "regexSubstitution": "https://\\1.xyz.com/"
    }
  },
  "condition": {
    "regexFilter": "^https://www\\.(abc|def)\\.xyz\\.com/",
    "resourceTypes": [
      "main_frame"
    ]
  }
}

سرصفحه ها

مثال زیر همه کوکی‌ها را هم از فریم اصلی و هم از فریم‌های فرعی حذف می‌کند. 

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "modifyHeaders",
    "requestHeaders": [{ "header": "cookie", "operation": "remove" }]
  },
  "condition": { "resourceTypes": ["main_frame", "sub_frame"] }
}

انواع

DomainType

این نشان می دهد که آیا درخواست شخص اول یا شخص ثالث در چارچوبی است که در آن منشا گرفته است. در صورتی که یک درخواست دارای همان دامنه (eTLD+1) با فریمی باشد که درخواست از آن منشا گرفته است، طرف اول است.

Enum

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

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

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 کدگذاری شده است. به عنوان مثال ، هنگامی که URL درخواست http: //abc.р؟ q = ф است ، urlFilter با url http: //abc.xn-p1ai/؟ q = ٪ d1 ٪ 84 مطابقت خواهد داشت.

Ruleset

خواص

  • فعال شد

    بولی

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

  • شناسه

    رشته

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

  • مسیر

    رشته

    مسیر قوانین JSON نسبت به فهرست پسوند.

RulesMatchedDetails

خواص

  • RulesmatchedInfo

    MatchedruleInfo []

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

TabActionCountUpdate

Chrome 89+

خواص

  • افزایش

    شماره

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

  • زبانه

    شماره

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

TestMatchOutcomeResult

Chrome 103+

خواص

  • ماتروس

    Matchedrule []

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

TestMatchRequestDetails

Chrome 103+

خواص

  • آغازگر

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

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

  • روش

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

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

  • سرپرستان

    شیء اختیاری

    Chrome 129+

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

  • زبانه

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

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

  • نوع

    منبع

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

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

    رشته

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

UnsupportedRegexReason

Chrome 87+

دلیل پشتیبانی از بیان منظم خاص را توصیف می کند.

Enum

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

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

UpdateRuleOptions

Chrome 87+

خواص

  • حیاط

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

    قوانینی برای افزودن.

  • بازپرداخت

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

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

UpdateRulesetOptions

Chrome 87+

خواص

  • ناتوانی

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

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

  • Enablerulesetids

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

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

UpdateStaticRulesOptions

Chrome 111+

خواص

  • نابسامانی

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

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

  • EnableruleIds

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

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

  • قاطع

    رشته

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

URLTransform

خواص

  • قطعه

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

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

  • میزبان

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

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

  • رمز عبور

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

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

  • مسیر

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

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

  • بندر

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

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

  • پرس و جو

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

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

  • ترجمه

    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+

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

ارزش

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()

قول Chrome 89+
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
)

تعداد قوانین استاتیک را که پس از رسیدن به حد قانون جهانی استاتیک امکان پذیر است ، باز می گرداند.

پارامترها

  • پاسخ به تماس

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

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

    (count: number) => void

    • شمارش

      شماره

برمی گرداند

  • قول <شماره>

    Chrome 91+

    وعده ها در مانیفست V3 و بعد از آن پشتیبانی می شوند ، اما تماس های برگشتی برای سازگاری عقب مانده ارائه می شود. شما نمی توانید از هر دو در یک تماس عملکردی استفاده کنید. این وعده با همان نوع که به پاسخ به تماس منتقل می شود ، حل می شود.

getDisabledRuleIds()

قول 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" در دسترس است زیرا این مورد فقط برای اهداف اشکال زدایی مورد استفاده قرار می گیرد.

پارامترها