chrome.proxy

Beschreibung

Berechtigungen

Sie müssen die Berechtigung „Proxy“ im Erweiterungsmanifest deklarieren, um die Proxy Settings API zu verwenden. Beispiel:

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

Konzepte und Nutzung

Proxy-Einstellungen werden in einem proxy.ProxyConfig-Objekt definiert. Abhängig von den Proxyeinstellungen von Chrome können diese Einstellungen proxy.ProxyRules oder proxy.PacScript enthalten.

Proxy-Modi

Das Attribut mode eines ProxyConfig-Objekts bestimmt das Gesamtverhalten von Chrome in Bezug auf die Proxy-Nutzung. Folgende Werte sind möglich:

direct

Im direct-Modus werden alle Verbindungen direkt und ohne Proxy erstellt. In diesem Modus sind keine weiteren Parameter im ProxyConfig-Objekt zulässig.

auto_detect

Im auto_detect-Modus wird die Proxykonfiguration durch ein PAC-Script bestimmt, das unter http://wpad/wpad.dat heruntergeladen werden kann. In diesem Modus sind keine weiteren Parameter im ProxyConfig-Objekt zulässig.

pac_script

Im pac_script-Modus wird die Proxykonfiguration durch ein PAC-Skript bestimmt, das entweder aus der im proxy.PacScript-Objekt angegebenen URL abgerufen oder buchstäblich aus dem data-Element, das im proxy.PacScript-Objekt angegeben ist, übernommen wird. Außerdem lässt dieser Modus keine weiteren Parameter im ProxyConfig-Objekt zu.

fixed_servers

Im fixed_servers-Modus wird die Proxykonfiguration in einem proxy.ProxyRules-Objekt codiert. Seine Struktur wird unter Proxyregeln beschrieben. Außerdem lässt der fixed_servers-Modus keine weiteren Parameter im ProxyConfig-Objekt zu.

system

Im system-Modus wird die Proxykonfiguration aus dem Betriebssystem übernommen. In diesem Modus sind keine weiteren Parameter im ProxyConfig-Objekt zulässig. Der Modus system unterscheidet sich von der Einstellung ohne Proxykonfiguration. In letzterem Fall greift Chrome nur dann auf die Systemeinstellungen zurück, wenn keine Befehlszeilenoptionen die Proxykonfiguration beeinflussen.

Proxyregeln

Das Objekt proxy.ProxyRules kann entweder ein singleProxy-Attribut oder eine Teilmenge von proxyForHttp, proxyForHttps, proxyForFtp und fallbackProxy enthalten.

Im ersten Fall wird HTTP-, HTTPS- und FTP-Traffic über den angegebenen Proxyserver geleitet. Anderer Traffic wird direkt gesendet. Im letzteren Fall ist das Verhalten etwas subtiler: Wenn ein Proxyserver für das HTTP-, HTTPS- oder FTP-Protokoll konfiguriert ist, wird der entsprechende Traffic über den angegebenen Server geleitet. Wenn kein solcher Proxyserver angegeben ist oder der Traffic ein anderes Protokoll als HTTP, HTTPS oder FTP verwendet, wird fallbackProxy verwendet. Wenn kein fallbackProxy angegeben ist, wird der Traffic direkt ohne Proxyserver gesendet.

Proxyserver-Objekte

Ein Proxyserver wird in einem proxy.ProxyServer-Objekt konfiguriert. Für die Verbindung zum Proxyserver (definiert durch das Attribut host) wird das Protokoll verwendet, das im Attribut scheme definiert ist. Wenn kein scheme angegeben ist, wird die Proxyverbindung standardmäßig auf http gesetzt.

Wenn in einem proxy.ProxyServer-Objekt kein port definiert ist, wird der Port aus dem Schema abgeleitet. Die Standardports sind:

Umgehungsliste

Einzelne Server können vom Proxy bypassList ausgeschlossen werden. Diese Liste kann folgende Einträge enthalten:

[SCHEME://]HOST_PATTERN[:PORT]

Findet alle Hostnamen, die dem Muster HOST_PATTERN entsprechen. Ein führender "." wird als "*." interpretiert.

Beispiele: "foobar.com", "*foobar.com", "*.foobar.com", "*foobar.com:99", "https://x.*.y.com:99".

Muster	Übereinstimmungen	Stimmt nicht überein mit
".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]

Findet URLs, die IP-Adressliterale sind. Das Konzept ähnelt dem ersten Fall, es gibt jedoch Sonderfälle für die Kanonisierung des IP-Literals. Zum Beispiel ist der Abgleich bei "[0:0:0::1]" dasselbe wie der Abgleich bei "[::1]", da die IPv6-Kanonisierung intern erfolgt.

Beispiele: 127.0.1, [0:0::1], [::1]:80, https://[::1]:443

IP_LITERAL/PREFIX_LENGTH_IN_BITS

Sie suchen nach jeder URL, die ein IP-Literal (IP_LITERAL) im angegebenen Bereich enthält. Der IP-Bereich (PREFIX_LENGTH_IN_BITS) wird in der CIDR-Notation angegeben.

Sie suchen nach einer beliebigen URL, die ein IP-Literal im angegebenen Bereich enthält. Der IP-Bereich wird in CIDR-Notation angegeben. Beispiele: "192.168.1.1/16", "fefe:13::abc/33"

<local>

Der Literalstring <local> stimmt mit einfachen Hostnamen überein. Ein einfacher Hostname enthält keine Punkte und ist kein IP-Literal. Beispielsweise sind example und localhost einfache Hostnamen, example.com, example. und [::1] hingegen nicht.

Beispiel: "<local>"

Beispiele

Mit dem folgenden Code wird ein SOCKS 5-Proxy für HTTP-Verbindungen zu allen Servern außer foobar.com festgelegt und direkte Verbindungen für alle anderen Protokolle verwendet. Diese Einstellungen gelten für normale und Inkognitofenster, da Inkognitofenster die Einstellungen von normalen Fenstern übernehmen. Weitere Informationen finden Sie in der Dokumentation zur 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() {}
);

Mit dem folgenden Code wird ein benutzerdefiniertes PAC-Skript festgelegt.

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() {}
);

Das nächste Snippet fragt die aktuellen effektiven Proxy-Einstellungen ab. Die gültigen Proxy-Einstellungen können durch eine andere Erweiterung oder durch eine Richtlinie bestimmt werden. Weitere Informationen finden Sie in der Dokumentation zur Types API.

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

Das an set() übergebene value-Objekt ist nicht identisch mit dem value-Objekt, das an die Callback-Funktion von get() übergeben wird. Letztere enthält ein rules.proxyForHttp.port-Element.

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