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

במצב

, הגדרת ה-Proxy מקודדת באובייקט proxy.ProxyRules.fixed_servers התיאור של המבנה שלו מופיע במאמר בנושא כללי פרוקסי. בנוסף, במצב 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,
)