browser.proxy

Beschreibung

Berechtigungen

Sie müssen die Berechtigung „proxy“ im Erweiterungsmanifest deklarieren, um die API für Proxy-Einstellungen zu verwenden. Beispiel:

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

Konzepte und Verwendung

Proxy-Einstellungen werden in einem proxy.ProxyConfig-Objekt definiert. Je nach den Proxy-Einstellungen von Chrome können die Einstellungen proxy.ProxyRules oder eine proxy.PacScript enthalten.

Proxy-Modi

Das Attribut mode eines ProxyConfig-Objekts bestimmt das allgemeine Verhalten von Chrome in Bezug auf die Proxynutzung. Er kann die folgenden Werte annehmen:

direct

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

auto_detect

Im Modus auto_detect wird die Proxykonfiguration durch ein PAC-Skript 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 Modus pac_script wird die Proxy-Konfiguration durch ein PAC-Script bestimmt, das entweder von der im Objekt proxy.PacScript angegebenen URL abgerufen oder wörtlich aus dem im Objekt proxy.PacScript angegebenen Element data übernommen wird. Darüber hinaus sind in diesem Modus keine weiteren Parameter im ProxyConfig-Objekt zulässig.

fixed_servers

Im fixed_servers-Modus wird die Proxykonfiguration in einem proxy.ProxyRules-Objekt codiert. Die Struktur wird unter Proxyregeln beschrieben. Darüber hinaus sind im fixed_servers-Modus keine weiteren Parameter im ProxyConfig-Objekt zulässig.

system

Im system-Modus wird die Proxy-Konfiguration vom Betriebssystem übernommen. In diesem Modus sind keine weiteren Parameter im ProxyConfig-Objekt zulässig. Beachten Sie, dass sich der Modus system von der Einstellung ohne Proxy-Konfiguration unterscheidet. Im letzteren Fall greift Chrome nur dann auf die Systemeinstellungen zurück, wenn keine Befehlszeilenoptionen die Proxy-Konfiguration 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 der 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 weitergeleitet. Wenn kein solcher Proxyserver angegeben ist oder der Traffic ein anderes Protokoll als HTTP, HTTPS oder FTP verwendet, wird die fallbackProxy verwendet. Wenn kein fallbackProxy angegeben ist, wird der Traffic direkt ohne Proxyserver gesendet.

Proxyserverobjekte

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

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

Umgehungsliste

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

[SCHEME://]HOST_PATTERN[:PORT]

Alle Hostnamen abgleichen, die dem Muster HOST_PATTERN entsprechen. Ein führendes "." wird als "*." interpretiert.

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

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

URLs abgleichen, die IP-Adressliterale sind. Konzeptionell ist dies ähnlich wie im ersten Fall, aber mit Sonderfällen für die Kanonisierung von IP-Literalen. Beispielsweise entspricht der Abgleich mit „[0:0:0::1]“ dem Abgleich mit „[::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

Übereinstimmung mit 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.

Entspricht jeder URL, die ein IP-Literal innerhalb des angegebenen Bereichs 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] jedoch 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 für alle anderen Protokolle werden direkte Verbindungen verwendet. Die 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"]
  }
};
browser.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" +
          "}"
  }
};
browser.proxy.settings.set(
  {value: config, scope: 'regular'},
  function() {}
);

Mit dem nächsten Snippet werden die aktuellen effektiven Proxy-Einstellungen abgefragt. Die effektiven Proxy-Einstellungen können durch eine andere Erweiterung oder eine Richtlinie bestimmt werden. Weitere Informationen finden Sie in der Dokumentation zur Types API.

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

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

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