chrome.proxy

refresh date: 2026-09-25 robots: noindex

תיאור

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

הרשאות

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 כזה או שהתנועה משתמשת בפרוטוקול שונה מ-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"

"system"

PacScript

אובייקט שמכיל מידע על תצורת Proxy אוטומטית (PAC). רק אחד מהשדות יכול להיות ריק.

מאפיינים

  • נתונים

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

    סקריפט PAC.

  • חובה

    בוליאני אופציונלי

    אם המדיניות מוגדרת כ-True, סקריפט PAC לא תקין ימנע ממקבץ הרשת (network stack) לחזור לחיבורים ישירים. ברירת המחדל היא False.

  • url

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

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

ProxyConfig

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

מאפיינים

  • מצב

    המצב

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

  • pacScript

    ‫PacScript אופציונלי

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

  • כללים

    ProxyRules אופציונלי

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

ProxyRules

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

מאפיינים

  • bypassList

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

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

  • fallbackProxy

    ProxyServer אופציונלי

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

  • proxyForFtp

    ProxyServer אופציונלי

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

  • proxyForHttp

    ProxyServer אופציונלי

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

  • proxyForHttps

    ProxyServer אופציונלי

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

  • singleProxy

    ProxyServer אופציונלי

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

ProxyServer

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

מאפיינים

  • מארח

    מחרוזת

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

  • יציאה

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

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

  • סכמה

    ‫Scheme אופציונלי

    הסכימה (הפרוטוקול) של שרת ה-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, השגיאה הייתה חמורה והעסקה ברשת בוטלה. אחרת, נעשה שימוש בחיבור ישיר.