chrome.proxy

תיאור

צריך להשתמש ב-API chrome.proxy כדי לנהל את ההגדרות של Chrome לשרת ה-proxy. ה-API הזה מסתמך על אב הטיפוס ChromeSetting של סוג ה-API כדי לקבל את ההגדרות של שרת ה-proxy ולהגדיר אותן.

הרשאות

proxy

מניפסט

עליך להצהיר על "שרת proxy" במניפסט של התוסף לשימוש בהגדרות לשרת ה-proxy API. לדוגמה:

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

אובייקטים ומאפיינים

ההגדרות לשרת proxy מוגדרות באובייקט proxy.ProxyConfig. בהתאם להגדרות של Chrome לשרת ה-proxy, ההגדרות עשויות להכיל proxy.ProxyRules או proxy.PacScript.

מצבי שרת proxy

המאפיין mode של אובייקט ProxyConfig קובע את ההתנהגות הכוללת של Chrome ביחס שימוש בשרת proxy. הוא יכול לקבל את הערכים הבאים:

direct
במצב direct, כל החיבורים נוצרים ישירות, ללא צורך בשרת proxy. המצב הזה מאפשר אין פרמטרים נוספים באובייקט ProxyConfig.
auto_detect
במצב auto_detect, ההגדרה של שרת ה-proxy נקבעת באמצעות סקריפט PAC שניתן להוריד בכתובת http://wpad/wpad.dat. במצב הזה לא ניתן להוסיף פרמטרים נוספים באובייקט ProxyConfig.
pac_script
במצב pac_script, ההגדרה של שרת ה-proxy נקבעת על ידי סקריפט PAC שמאוחזר מכתובת ה-URL שצוינה באובייקט proxy.PacScript או שנלקחה פשוט מהרכיב data שמצוינים באובייקט proxy.PacScript. מלבד זאת, המצב הזה לא מאפשר פרמטרים נוספים באובייקט ProxyConfig.
fixed_servers
במצב fixed_servers, ההגדרות של שרת ה-proxy מקודדות באובייקט proxy.ProxyRules. שלו מתואר בכללים לשרת proxy. מלבד זאת, מצב fixed_servers לא מאפשר באובייקט ProxyConfig.
system
במצב system, ההגדרה של שרת ה-proxy נלקחת ממערכת ההפעלה. במצב הזה לא ניתן פרמטרים נוספים באובייקט ProxyConfig. חשוב לזכור שהמצב system שונה מהמצב הזה אין הגדרה של שרת proxy. במקרה השני, Chrome חוזר להגדרות המערכת רק אם אף אפשרויות של שורת פקודה לא משפיעות על התצורה של שרת ה-proxy.

כללים לשרת proxy

האובייקט proxy.ProxyRules יכול להכיל מאפיין singleProxy או קבוצת משנה של proxyForHttp, proxyForHttps, proxyForFtp וגם fallbackProxy.

במקרה הראשון, תעבורת הנתונים ב-HTTP, ב-HTTPS וב-FTP מועברת דרך שרת proxy דרך שרת ה-proxy שצוין. המלצות אחרות התנועה נשלחת ישירות. במקרה השני, ההתנהגות קצת יותר עדינה: אם שרת proxy מוגדר לפרוטוקול HTTP, HTTPS או FTP, התעבורה המתאימה עוברת דרך שרת proxy השרת שצוין. אם לא צוין שרת proxy כזה, או שהתנועה משתמשת בפרוטוקול שונה מ- HTTP, HTTPS או FTP, נעשה שימוש בfallbackProxy. אם לא מציינים ערך של fallbackProxy, התנועה נשלחת ישירות ללא שרת proxy.

אובייקטים של שרת ה-proxy

שרת proxy מוגדר באובייקט proxy.ProxyServer. החיבור לשרת ה-proxy (מוגדר על ידי המאפיין host) משתמש בפרוטוקול המוגדר במאפיין scheme. אם לא צוין scheme. ברירת המחדל של החיבור לשרת ה-Proxy היא http.

אם לא מוגדר port באובייקט proxy.ProxyServer, היציאה נגזרת מסכימה. יציאות ברירת המחדל הן:

Schemeיציאה
http‏80
https443
socks41080
socks51080

רשימת העקיפה

יכול להיות ששרתים ספציפיים לא ייכללו בשרת proxy עם 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>"

דוגמאות

הקוד הבא מגדיר שרת proxy 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() {}
);

קטע הקוד הבא שולח שאילתה על ההגדרות האפקטיביות כרגע של שרת proxy. ההגדרות האפקטיביות של שרת proxy יכולות שנקבעת באמצעות הרחבה אחרת או באמצעות מדיניות. פרטים נוספים זמינים במסמכים בנושא Types API.

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

חשוב לשים לב שהאובייקט value שמועבר אל set() לא זהה לאובייקט value שמועבר אל פונקציית קריאה חוזרת של get(). המסנן הזה יכיל רכיב rules.proxyForHttp.port.

סוגים

Mode

Chrome 54+

Enum

"direct"

"auto_detect"

"pac_script"

"fixed_servers"

"מערכת"

PacScript

אובייקט שמכיל פרטי הגדרה אוטומטית של שרת proxy. בדיוק אחד מהשדות לא יכול להיות ריק.

מאפיינים

  • נתונים

    מחרוזת אופציונלי

    סקריפט PAC.

  • חובה

    ערך בוליאני אופציונלי

    אם הערך הוא True, סקריפט PAC לא תקין ימנע ממקבץ הרשת לחזור לחיבורים ישירים. ברירת המחדל היא False.

  • כתובת אתר

    מחרוזת אופציונלי

    כתובת ה-URL של קובץ ה-PAC לשימוש.

ProxyConfig

אובייקט שמכסה הגדרה מלאה של שרת proxy.

מאפיינים

  • מצב

    'ישיר' = לעולם לא להשתמש בשרת proxy 'auto_detect' = זיהוי אוטומטי של הגדרות לשרת proxy 'pac_script' = השתמש בסקריפט ה-PAC שצוין 'fixed_servers' = ציון שרתי proxy באופן ידני 'מערכת' = שימוש בהגדרות שרת proxy של המערכת

  • pacScript

    PacScript אופציונלי

    סקריפט התצורה האוטומטית של שרת ה-proxy (PAC) להגדרה הזו. יש להשתמש בשדה הזה עבור 'pac_script' במצב תצוגה.

  • כללים

    ProxyRules אופציונלי

    הכללים לשרתי proxy שמתארים את ההגדרה הזו. משתמשים בשדה הזה עבור 'fixed_servers' במצב תצוגה.

ProxyRules

אובייקט שמכסה את קבוצת הכללים של שרת proxy לכל הפרוטוקולים. יש להשתמש ב-'singleProxy' או (קבוצת משנה של) 'proxyForHttp', 'proxyForHttps', 'proxyForFtp' ו-'fallbackProxy'.

מאפיינים

  • bypassList

    string[] אופציונלי

    רשימת שרתים שצריך להתחבר אליהם ללא שרת proxy.

  • fallbackProxy

    ProxyServer אופציונלי

    שרת ה-proxy שישמש לכל דבר אחר או אם לא צוין שרת proxy ספציפי ל....

  • proxyForFtp

    ProxyServer אופציונלי

    שרת ה-proxy שישמש לבקשות FTP.

  • proxyForHttp

    ProxyServer אופציונלי

    שרת ה-proxy שישמש לבקשות HTTP.

  • proxyForHttps

    ProxyServer אופציונלי

    שרת ה-proxy שישמש לבקשות HTTPS.

  • singleProxy

    ProxyServer אופציונלי

    שרת ה-proxy שישמש לכל הבקשות לכתובת URL (כלומר http, https ו-ftp).

ProxyServer

אובייקט שמקיף את המפרט של שרת proxy יחיד.

מאפיינים

  • מארח

    מחרוזת

    שם המארח או כתובת ה-IP של שרת ה-proxy. שמות המארחים חייבים להיות בפורמט ASCII (בפורמט Funycode). עדיין אין תמיכה ב-IDNA.

  • יציאה

    מספר אופציונלי

    היציאה של שרת ה-Proxy. ברירת המחדל היא יציאה שתלויה בסכמה.

  • סכמה

    סכמה אופציונלי

    הסכימה (פרוטוקול) של שרת ה-proxy עצמו. ברירת המחדל היא 'http'.

Scheme

Chrome 54+

Enum

"http"

"https"

"quic"

"socks4"

"socks5"

מאפיינים

settings

הגדרות לשרת proxy שבהן יש להשתמש. הערך של ההגדרה הזו הוא אובייקט ProxyConfig.

אירועים

onProxyError

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

מתקבלת התראה על שגיאות בשרת proxy.

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

    הפרמטר callback נראה כך:

    (details: object) => void

    • פרטים

      אובייקט

      • פרטים

        מחרוזת

        פרטים נוספים על השגיאה, כמו שגיאת זמן ריצה של JavaScript.

      • error

        מחרוזת

        תיאור השגיאה.

      • fatal

        בוליאני

        אם הערך הוא True, השגיאה הייתה חמורה והעסקה ברשת בוטלה. אחרת, צריך להשתמש בחיבור ישיר.