chrome.declarativeNetRequest

توضیحات

مجوزها

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

"declarativeNetRequest"

در زمان نصب، یک هشدار مجوز ایجاد می‌کند، اما دسترسی ضمنی به قوانین allow ، allowAllRequests و block را فراهم می‌کند. در صورت امکان از این مورد استفاده کنید تا از نیاز به درخواست دسترسی کامل به میزبان‌ها جلوگیری شود.

"declarativeNetRequestFeedback"

ویژگی‌های اشکال‌زدایی را برای افزونه‌های باز نشده ، به‌ویژه getMatchedRules() و onRuleMatchedDebug ، فعال می‌کند.

"declarativeNetRequestWithHostAccess"

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

در دسترس بودن

مانیفست

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

درخواست اعلانی شبکه (Declarative Net Request) امکان تطبیق URLها را با استفاده از سینتکس تطبیق الگو یا عبارات منظم فراهم می‌کند.

سینتکس فیلتر URL

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

عبارات منظم

شرط‌ها همچنین می‌توانند از عبارات منظم استفاده کنند. به کلید "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 هستند بعداً (زمانی که هدرهای پاسخ در دسترس باشند) در نظر گرفته می‌شوند و در اینجا گنجانده نشده‌اند.

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

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

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

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

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

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

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

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

به محض دریافت پاسخ

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

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

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

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

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

قوانین ایمن

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

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

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

قوانین ایستا

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

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

قوانین جلسه

یک افزونه می‌تواند تا ۵۰۰۰ قانون جلسه داشته باشد. این به صورت MAX_NUMBER_OF_SESSION_RULES نمایش داده می‌شود.

قبل از کروم ۱۲۰، محدودیت ۵۰۰۰ قانون ترکیبی پویا و جلسه‌ای وجود داشت.

قوانین پویا

یک افزونه می‌تواند حداقل ۵۰۰۰ قانون پویا داشته باشد. این به صورت MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES نمایش داده می‌شود.

با شروع از کروم ۱۲۱، محدودیت بیشتری به تعداد ۳۰۰۰۰ قانون برای قوانین پویای ایمن وجود دارد که به صورت MAX_NUMBER_OF_DYNAMIC_RULES نمایش داده می‌شود. هر قانون ناامنی که در محدوده ۵۰۰۰ اضافه شود، نیز جزو این محدودیت محسوب می‌شود.

قبل از کروم ۱۲۰، محدودیت ۵۰۰۰ قانون پویا و جلسه‌ای ترکیبی وجود داشت.

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

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

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

rules_1.json: Rule with id 1 specified a more complex 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" در مانیفست استفاده کنید.

اصلاح هدر

عملیات افزودن فقط برای هدرهای درخواست زیر پشتیبانی می‌شود: 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);
}

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

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

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

این مثال‌ها نیاز به مجوز میزبان برای *://*.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"] }
}

chrome.declarativeNetRequest.getAvailableStaticRuleCount(): Promise<number>

chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
): Promise<number[]>

chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
): Promise<Rule[]>

chrome.declarativeNetRequest.getEnabledRulesets(): Promise<string[]>

chrome.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
): Promise<RulesMatchedDetails>

chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
): Promise<Rule[]>

chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
): Promise<IsRegexSupportedResult>

chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
): Promise<void>

chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
): Promise<TestMatchOutcomeResult>

chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
): Promise<void>

chrome.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
): Promise<void>

chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
): Promise<void>

chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
): Promise<void>

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