chrome.proxy

תיאור

הרשאות

כדי להשתמש ב-API להגדרות של שרת proxy, עליכם להצהיר על ההרשאה 'שרת proxy' במניפסט התוספים. למשל:

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

מושגים ושימוש

הגדרות שרת proxy נקבעות באובייקט proxy.ProxyConfig. בהתאם להגדרות של שרת ה-proxy ב-Chrome, יכול להיות שההגדרות יכילו 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 מוגדר לפרוטוקול HTTP, HTTPS או FTP, תעבורת הנתונים המתאימה נשלחת דרך שרת ה-proxy דרך השרת שצוין. אם לא צוין שרת proxy כזה או שהתנועה משתמשת בפרוטוקול שונה מ-HTTP, מ-HTTPS או FTP, נעשה שימוש ב-fallbackProxy. אם לא צוין fallbackProxy, תעבורת הנתונים נשלחת ישירות ללא שרת proxy.

אובייקטים של שרת Proxy

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

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

רשימת העקיפה

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

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