chrome.proxy

توضیحات

از API chrome.proxy برای مدیریت تنظیمات پروکسی کروم استفاده کنید. این API برای دریافت و تنظیم پیکربندی پروکسی به نمونه اولیه ChromeSetting از نوع API متکی است.

مجوزها

proxy

مانیفست

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

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

اشیاء و ویژگی‌ها

تنظیمات پروکسی در شیء proxy.ProxyConfig تعریف می‌شوند. بسته به تنظیمات پروکسی کروم، این تنظیمات ممکن است حاوی 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 تعیین می‌شود که یا از URL مشخص شده در شیء proxy.PacScript بازیابی می‌شود یا به معنای واقعی کلمه از عنصر data مشخص شده در شیء proxy.PacScript گرفته می‌شود. علاوه بر این، این حالت هیچ پارامتر دیگری را در شیء ProxyConfig مجاز نمی‌داند.
fixed_servers
در حالت fixed_servers پیکربندی پروکسی در یک شیء proxy.ProxyRules کدگذاری می‌شود. ساختار آن در قوانین پروکسی شرح داده شده است. علاوه بر این، حالت fixed_servers هیچ پارامتر دیگری را در شیء ProxyConfig مجاز نمی‌داند.
system
در حالت system ، پیکربندی پروکسی از سیستم عامل گرفته می‌شود. این حالت هیچ پارامتر دیگری را در شیء ProxyConfig مجاز نمی‌داند. توجه داشته باشید که حالت system با تنظیم بدون پیکربندی پروکسی متفاوت است. در حالت دوم، کروم فقط در صورتی به تنظیمات سیستم برمی‌گردد که هیچ گزینه خط فرمانی بر پیکربندی پروکسی تأثیر نگذارد.

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

شیء 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 تعریف نشده باشد، پورت از این طرح مشتق می‌شود. پورت‌های پیش‌فرض عبارتند از:

طرح بندر
اچ‌تی‌پی ۸۰
https ۴۴۳
جوراب4 ۱۰۸۰
جوراب5 ۱۰۸۰

لیست بای پس

ممکن است سرورهای منفرد از پروکسی شدن با 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]

URLهایی را که به صورت تحت‌اللفظی آدرس 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

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

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

<local>

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

مثال: "<local>"

مثال‌ها

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

var config = {
  mode: "fixed_servers",
  rules: {
    proxyForHttp: {
      scheme: "socks5",
      host: "1.2.3.4"
    },
    bypassList: ["foobar.com"]
  }
};
chrome.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" +
          "}"
  }
};
chrome.proxy.settings.set(
  {value: config, scope: 'regular'},
  function() {}
);

قطعه کد بعدی تنظیمات پروکسی فعال فعلی را بررسی می‌کند. تنظیمات پروکسی فعال می‌تواند توسط یک افزونه دیگر یا توسط یک سیاست تعیین شود. برای جزئیات بیشتر به مستندات API مربوط به انواع مراجعه کنید.

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

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

انواع

Mode

کروم ۵۴+

شمارشی

"مستقیم"

"تشخیص_خودکار"

"pac_script"

"سرورهای_ثابت"

«سیستم»

PacScript

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

خواص

  • داده‌ها

    رشته اختیاری

    یک اسکریپت PAC.

  • اجباری

    بولی اختیاری

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

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

    رشته اختیاری

    آدرس اینترنتی (URL) فایل PAC مورد استفاده.

ProxyConfig

یک شیء که پیکربندی کامل پروکسی را در بر می‌گیرد.

خواص

  • حالت

    حالت

    'direct' = هرگز از پروکسی استفاده نکنید 'auto_detect' = تنظیمات پروکسی را به صورت خودکار شناسایی کنید 'pac_script' = از اسکریپت PAC مشخص شده استفاده کنید 'fixed_servers' = سرورهای پروکسی را به صورت دستی مشخص کنید 'system' = از تنظیمات پروکسی سیستم استفاده کنید

  • پک‌اسکریپت

    PacScript اختیاری

    اسکریپت پیکربندی خودکار پروکسی (PAC) برای این پیکربندی. از این برای حالت 'pac_script' استفاده کنید.

  • قوانین

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

    قوانین پروکسی که این پیکربندی را توصیف می‌کنند. از این برای حالت 'fixed_servers' استفاده کنید.

ProxyRules

یک شیء که مجموعه قوانین پروکسی را برای همه پروتکل‌ها در خود جای می‌دهد. از 'singleProxy' یا (زیرمجموعه‌ای از) 'proxyForHttp'، 'proxyForHttps'، 'proxyForFtp' و 'fallbackProxy' استفاده کنید.

خواص

  • بای‌پس‌لیست

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

    لیست سرورهایی که بدون پروکسی سرور می‌توان به آنها متصل شد.

  • پروکسی پشتیبان

    پروکسی سرور اختیاری

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

  • proxyForFtp

    پروکسی سرور اختیاری

    سرور پروکسی که برای درخواست‌های FTP استفاده می‌شود.

  • پروکسی برای HTTP

    پروکسی سرور اختیاری

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

  • proxyForHttps

    پروکسی سرور اختیاری

    سرور پروکسی که برای درخواست‌های HTTPS استفاده می‌شود.

  • تک پروکسی

    پروکسی سرور اختیاری

    سرور پروکسی که برای همه درخواست‌های مربوط به هر URL (یعنی http، https و ftp) استفاده می‌شود.

ProxyServer

یک شیء که مشخصات یک پروکسی سرور واحد را در خود جای داده است.

خواص

  • میزبان

    رشته

    نام میزبان یا آدرس IP سرور پروکسی. نام‌های میزبان باید به صورت ASCII (با فرمت Punycode) باشند. IDNA هنوز پشتیبانی نمی‌شود.

  • بندر

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

    پورت سرور پروکسی. به طور پیش‌فرض روی پورتی است که به طرح بستگی دارد.

  • طرح

    طرح اختیاری

    طرح (پروتکل) خود سرور پروکسی. پیش‌فرض روی 'http' است.

Scheme

کروم ۵۴+

شمارشی

"http"

"https"

"سریع"

«جوراب ۴»

«جوراب ۵»

خواص

settings

تنظیمات پروکسی مورد استفاده. مقدار این تنظیم یک شیء ProxyConfig است.

نوع

type.ChromeSetting < ProxyConfig >

رویدادها

onProxyError

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

در مورد خطاهای پروکسی اطلاع می‌دهد.

پارامترها

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

    (details: object) => void

    • جزئیات

      شیء

      • جزئیات

        رشته

        جزئیات بیشتر در مورد خطا، مانند خطای زمان اجرای جاوا اسکریپت.

      • خطا

        رشته

        شرح خطا.

      • کشنده

        بولی

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