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
https	443
socks4	1080
socks5	1080

רשימת העקיפה

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

סוג

types.ChromeSetting<ProxyConfig>

אירועים

onProxyError

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

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

פרמטרים

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

  פונקציה

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

  (details: object) => void

  • פרטים

    אובייקט

    • פרטים

      מחרוזת

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

    • error

      מחרוזת

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

    • fatal

      בוליאני

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