chrome.proxy

الوصف

استخدِم chrome.proxy API لإدارة إعدادات الخادم الوكيل في Chrome. تعتمد واجهة برمجة التطبيقات هذه على النموذج الأوّلي لإعداد Chrome لنوع واجهة برمجة التطبيقات للحصول على إعدادات الخادم الوكيل وضبطها.

الأذونات

proxy

يجب تعريف "الخادم الوكيل" إذن في بيان الإضافة لاستخدام إعدادات الخادم الوكيل واجهة برمجة التطبيقات. مثلاً:

{
  "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) يتم استرداده من عنوان URL المحدد في الكائن 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 و"بروتوكول نقل الملفات" عبر الخادم الوكيل المحدد. غير ذلك إرسال حركة البيانات مباشرة. في الحالة الثانية، يكون السلوك أكثر دقة إلى حد ما: إذا كان هناك خادم وكيل مع بروتوكول HTTP أو HTTPS أو FTP، يتم إنشاء حركة البيانات ذات الصلة من خلال خادم وكيل الخادم المحدد. إذا لم يتم تحديد أي خادم وكيل هذا أو كانت الزيارات تستخدم بروتوكولاً مختلفًا عن يتم استخدام fallbackProxy أو HTTP أو HTTPS أو FTP. إذا لم يتم تحديد fallbackProxy، سيتم إرسال الزيارات مباشرةً بدون خادم وكيل.

كائنات الخادم الوكيل

تم إعداد خادم وكيل في عنصر proxy.ProxyServer. الاتصال بالخادم الوكيل (التعريف من خلال السمة host) يستخدم البروتوكول المحدّد في السمة scheme. إذا كانت الإجابة "لا" تم تحديد scheme، يتم ضبط اتصال الخادم الوكيل تلقائيًا على http.

إذا لم يتم تحديد port في كائن proxy.ProxyServer، سيكون المنفذ مشتقًا من المخطط. المنافذ التلقائية هي:

المخططالمنفذ
http80
https443
socks41080
socks51080

قائمة الاستثناءات

قد يتم استبعاد الخوادم الفردية من إنشاء خادم وكيل باستخدام 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]" لأنّ تحديد عنوان URL الأساسي لـ 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 ويستخدمه الاتصالات المباشرة لجميع البروتوكولات الأخرى. تسري الإعدادات على النوافذ العادية ونوافذ التصفح المتخفي، نظرًا تكتسب نوافذ التصفح المتخفي الإعدادات من النوافذ العادية. راجِع أيضًا Types 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() {}
);

يستفسر المقتطف التالي عن إعدادات الخادم الوكيل الحالية الفعالة. يمكن أن تكون إعدادات الوكيل الفعالة محددة بواسطة إضافة أخرى أو سياسة. راجِع وثائق Types API للحصول على التفاصيل.

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

تجدر الإشارة إلى أنّ الكائن value الذي تم تمريره إلى set() لا يتطابق مع عنصر value الذي تم تمريره إلى دالّة رد الاتصال get(). وسيتضمن الاسم الأخير العنصر rules.proxyForHttp.port.

الأنواع

Mode

الإصدار 54 من Chrome أو الإصدارات الأحدث

Enum

"مباشر"

"auto_detect"

"pac_script"

"fixed_servers"

"النظام"

PacScript

كائن يحتوي على معلومات الإعداد التلقائي للخادم الوكيل يجب أن يكون أحد الحقول بالضبط غير فارغ.

أماكن إقامة

  • البيانات

    سلسلة اختيارية

    نص PAC البرمجي

  • إلزامي

    قيمة منطقية اختيارية

    في حال ضبط السياسة على "صحيح"، سيؤدي البرنامج النصي PAC غير الصالح إلى منع تكديس الشبكة من العودة إلى الاتصالات المباشرة. وتكون القيمة التلقائية على "خطأ".

  • url

    سلسلة اختيارية

    عنوان URL لملف PAC المراد استخدامه.

ProxyConfig

يشير ذلك المصطلح إلى كائن يغلف إعدادات كاملة للخادم الوكيل.

أماكن إقامة

  • الوضع

    الوضع

    "مباشر" = عدم استخدام الخادم الوكيل مطلقًا "auto_detect" (الاكتشاف التلقائي) = اكتشاف إعدادات الخادم الوكيل تلقائيًا "pac_script" = استخدام نص PAC المحدد "fixed_servers" = تحديد الخوادم الوكيلة يدويًا "نظام" = استخدام إعدادات الخادم الوكيل للنظام

  • pacScript

    PacScript اختيارية

    النص البرمجي للضبط التلقائي للخادم الوكيل (PAC) لهذه الإعدادات. استخدِم هذا العمود لـ 'pac_script' الحالي.

  • القواعد

    ProxyRules اختياري

    قواعد الخادم الوكيل التي تصف هذه الإعدادات. استخدِم هذا الخيار لـ 'fixed_servers' الحالي.

ProxyRules

يشير هذا المصطلح إلى كائن يغلف مجموعة قواعد الخادم الوكيل لجميع البروتوكولات. استخدِم إما "singleProxy" أو (مجموعة فرعية من) "proxyForHttp" أو "proxyForHttps" أو "proxyForFtp" و"fallbackProxy".

أماكن إقامة

  • bypassList

    string[] اختيارية

    قائمة بالخوادم المطلوب الاتصال بها بدون خادم وكيل.

  • fallbackProxy

    ProxyServer اختياري

    الخادم الوكيل المراد استخدامه لأي شيء آخر أو إذا لم يتم تحديد أي من خوادمproxyFor... المحددة.

  • proxyForFtp

    ProxyServer اختياري

    الخادم الوكيل المراد استخدامه لطلبات FTP.

  • proxyForHttp

    ProxyServer اختياري

    الخادم الوكيل المراد استخدامه لطلبات HTTP.

  • proxyForHttps

    ProxyServer اختياري

    الخادم الوكيل المراد استخدامه لطلبات HTTPS.

  • singleProxy

    ProxyServer اختياري

    الخادم الوكيل المراد استخدامه لجميع الطلبات حسب عنوان URL (أي http وhttps وftp).

ProxyServer

يشير هذا المصطلح إلى كائن يغلف مواصفات خادم وكيل واحد.

أماكن إقامة

  • مضيف

    سلسلة

    اسم المضيف أو عنوان IP للخادم الوكيل. يجب أن تكون أسماء المضيفين بتنسيق ASCII (بتنسيق Punycode). لا يمكن استخدام رقم التعريف الوطني (IDNA) بعد.

  • المنفذ

    الرقم اختياري

    منفذ الخادم الوكيل. يتم ضبط الإعدادات التلقائية على منفذ يعتمد على النظام.

  • المخطط

    المخطط اختياري

    مخطط (بروتوكول) الخادم الوكيل نفسه. الإعداد التلقائي هو "http".

Scheme

الإصدار 54 من Chrome أو الإصدارات الأحدث

Enum

"http"

"https"

"quic"

"socks4"

"socks5"

أماكن إقامة

settings

إعدادات الخادم الوكيل التي سيتم استخدامها. قيمة هذا الإعداد هي كائن ProxyConfig.

النوع

types.ChromeSetting&lt;ProxyConfig&gt;

فعاليات

onProxyError

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

يتم إشعارك بأخطاء الخادم الوكيل.

المعلمات

  • رد الاتصال

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (details: object) => void

    • التفاصيل

      كائن

      • التفاصيل

        سلسلة

        تفاصيل إضافية عن الخطأ، مثل خطأ في وقت تشغيل JavaScript

      • خطأ

        سلسلة

        وصف الخطأ.

      • fatal

        منطقي

        إذا كانت القيمة هي true، هذا يعني أنّ الخطأ فادح وتم إلغاء معاملة الشبكة. وبخلاف ذلك، يتم استخدام اتصال مباشر بدلاً من ذلك.