browser.proxy

شرح

اجازه‌ها

برای استفاده از API تنظیمات پراکسی، باید اجازه «پراکسی» را در مانیفست افزونه تعریف کنید. برای مثال:

{
  "name": "My extension",
  ...
  "permissions": [
    "proxy"
  ],
  ...
}

مفاهیم و استفاده

تنظیمات پراکسی در شیء proxy.ProxyConfig تعریف شده است. بسته به تنظیمات پراکسی Chrome، تنظیمات ممکن است حاوی proxy.ProxyRules یا proxy.PacScript باشد.

حالت‌های پراکسی

مشخصه mode شیء ProxyConfig رفتار کلی Chrome را درخصوص استفاده از پراکسی تعیین می‌کند. می‌تواند مقادیر زیر را داشته باشد:

direct

در حالت direct، همه اتصال‌ها مستقیماً و بدون دخالت هیچ پراکسی‌ای ایجاد می‌شوند. این حالت اجازه نمی‌دهد پارامترهای بیشتری در شیء ProxyConfig وجود داشته باشد.

auto_detect

در حالت auto_detect، پیکربندی پراکسی توسط دستورگان PAC تعیین می‌شود که می‌تواند در http://wpad/wpad.dat بارگیری شود. این حالت اجازه نمی‌دهد پارامترهای بیشتری در شیء ProxyConfig اضافه شود.

pac_script

در حالت pac_script، پیکربندی پراکسی با دستورگان PAC تعیین می‌شود که یا از نشانی وب مشخص‌شده در شیء proxy.PacScript بازیابی می‌شود یا به‌صورت تحت‌اللفظی از عنصر data مشخص‌شده در شیء proxy.PacScript گرفته می‌شود. علاوه‌براین، این حالت اجازه نمی‌دهد پارامترهای بیشتری در شیء ProxyConfig اضافه شود.

fixed_servers

در حالت fixed_servers، پیکربندی پراکسی در شیء proxy.ProxyRules کدبندی می‌شود. ساختار آن در قوانین پراکسی توضیح داده شده است. علاوه‌براین، حالت fixed_servers اجازه نمی‌دهد پارامترهای بیشتری در شیء ProxyConfig وجود داشته باشد.

system

در حالت system، پیکربندی پراکسی از سیستم‌عامل گرفته می‌شود. این حالت اجازه نمی‌دهد پارامترهای بیشتری در شیء ProxyConfig وجود داشته باشد. توجه داشته باشید که حالت system با تنظیم پیکربندی بدون پراکسی متفاوت است. در حالت دوم، Chrome فقط درصورتی به تنظیمات سیستم برمی‌گردد که هیچ گزینه خط فرمانی بر پیکربندی پراکسی تأثیر نگذارد.

قوانین پراکسی

شیء proxy.ProxyRules می‌تواند حاوی مشخصه singleProxy یا زیرمجموعه‌ای از proxyForHttp، proxyForHttps، proxyForFtp، و fallbackProxy باشد.

در حالت اول، ترافیک HTTP،‏ HTTPS، و FTP ازطریق سرور پراکسی مشخص‌شده پراکسی می‌شود. ترافیک دیگر مستقیماً ارسال می‌شود. در حالت دوم، رفتار کمی ظریف‌تر است: اگر سرور پراکسی برای پروتکل HTTP،‏ HTTPS، یا FTP پیکربندی شده باشد، ترافیک مربوطه ازطریق سرور مشخص‌شده پراکسی می‌شود. اگر چنین سرور پراکسی‌ای مشخص نشده باشد یا ترافیک از پروتکل دیگری به‌جز HTTP،‏ HTTPS، یا FTP استفاده کند، از fallbackProxy استفاده می‌شود. اگر fallbackProxy مشخص نشده باشد، ترافیک بدون پراکسی سرور به‌طور مستقیم ارسال می‌شود.

اشیاء سرور پراکسی

سرور پروکسی در شیء proxy.ProxyServer پیکربندی شده است. اتصال به سرور پراکسی (تعریف‌شده توسط مشخصه host) از پروتکل تعریف‌شده در مشخصه scheme استفاده می‌کند. اگر scheme مشخص نشده باشد، اتصال پراکسی به‌طور پیش‌فرض روی http تنظیم می‌شود.

اگر هیچ port در شیء proxy.ProxyServer تعریف نشده باشد، درگاه از طرح مشتق می‌شود. درگاه‌های پیش‌فرض عبارت‌اند از:

فهرست فرعی

سرورهای تکی ممکن است با bypassList از استفاده از پراکسی مستثنا شوند. این فهرست ممکن است شامل ورودی‌های زیر باشد:

[SCHEME://]HOST_PATTERN[:PORT]

همه نام‌های میزبانی را که با الگوی HOST_PATTERN مطابقت دارند مطابقت دهید. ‫"." پیشرو به‌عنوان "*." تفسیر می‌شود.

مثال‌ها: "foobar.com", "*foobar.com", "*.foobar.com", "*foobar.com:99", "https://x.*.y.com:99".

الگو	موارد منطبق	نامنطبق
".foobar.com"	"www.foobar.com"	"foobar.com"
"*.foobar.com"	"www.foobar.com"	"foobar.com"
"foobar.com"	"foobar.com"	"www.foobar.com"
"*foobar.com"	"foobar.com"، "www.foobar.com"، "foofoobar.com"

[SCHEME://]IP_LITERAL[:PORT]

با نشانی‌های وبی که نشانی IP حرفی هستند مطابقت دارد. ازنظر مفهومی این مورد مشابه مورد اول است، اما با موارد خاص برای مدیریت استانداردسازی نشانی‌های وب IP. برای مثال، مطابقت با «[0:0:0::1]» با مطابقت با «[::1]» یکسان است زیرا استانداردسازی IPv6 به‌صورت داخلی انجام می‌شود.

مثال‌ها: 127.0.1، [0:0::1]، [::1]:80، https://[::1]:443

IP_LITERAL/PREFIX_LENGTH_IN_BITS

با هر نشانی وبی که حاوی نشانی IP تحت‌اللفظی (IP_LITERAL) در محدوده داده‌شده باشد مطابقت دارد. محدوده IP (PREFIX_LENGTH_IN_BITS) بااستفاده از نشانه‌گذاری CIDR مشخص شده است.

با هر نشانی وبی که حاوی نشانی IP تحت‌اللفظی در محدوده داده‌شده باشد مطابقت دارد. محدوده IP بااستفاده از نماد CIDR مشخص می‌شود. مثال‌ها: "192.168.1.1/16", "fefe:13::abc/33"

<local>

رشته تحت‌اللفظی <local> با نام‌های میزبان ساده مطابقت دارد. نام میزبان ساده نامی است که نقطه ندارد و یک IP literal نیست. برای نمونه، example و localhost نام‌های میزبان ساده هستند، درحالی‌که example.com، example.، و [::1] نام‌های میزبان ساده نیستند.

مثال: "<local>"

مثال‌ها

کد زیر پراکسی SOCKS 5 را برای اتصالات HTTP به همه سرورها به‌جز foobar.com تنظیم می‌کند و برای همه پروتکل‌های دیگر از اتصالات مستقیم استفاده می‌کند. این تنظیمات برای پنجره‌های عادی و ناشناس اعمال می‌شود، زیرا پنجره‌های ناشناس تنظیمات را از پنجره‌های عادی به‌ارث می‌برند. همچنین Types API مستندات را ببینید.

var config = {
  mode: "fixed_servers",
  rules: {
    proxyForHttp: {
      scheme: "socks5",
      host: "1.2.3.4"
    },
    bypassList: ["foobar.com"]
  }
};
browser.proxy.settings.set(
  {value: config, scope: 'regular'},
  function() {}
);

کد زیر یک دستورگان PAC سفارشی تنظیم می‌کند.

var config = {
  mode: "pac_script",
  pacScript: {
    data: "function FindProxyForURL(url, host) {\n" +
          "  if (host == 'foobar.com')\n" +
          "    return 'PROXY blackhole:80';\n" +
          "  return 'DIRECT';\n" +
          "}"
  }
};
browser.proxy.settings.set(
  {value: config, scope: 'regular'},
  function() {}
);

تکه‌کد بعدی تنظیمات پراکسی مؤثر کنونی را پُرسمان می‌کند. تنظیمات پراکسی مؤثر را می‌توان با افزونه‌ای دیگر یا با خط‌مشی تعیین کرد. برای جزئیات بیشتر، به مستندات Types API مراجعه کنید.

browser.proxy.settings.get(
  {'incognito': false},
  function(config) {
    console.log(JSON.stringify(config));
  }
);

توجه داشته باشید که شیء value که به set() ارسال شده است با شیء value که به تابع برگشتی get() ارسال شده است یکسان نیست. مورد دوم حاوی عنصر rules.proxyForHttp.port خواهد بود.

chrome.proxy.onProxyError.addListener(
  callback: function,
)