Beschreibung
Mit der chrome.proxy
API können Sie die Proxyeinstellungen von Chrome verwalten. Diese API basiert auf dem ChromeSetting-Prototyp des Typs API zum Abrufen und Festlegen der Proxykonfiguration.
Berechtigungen
proxy
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 imProxyConfig
-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 imProxyConfig
-Objekt zulässig. pac_script
- Im
pac_script
-Modus wird die Proxykonfiguration durch ein PAC-Skript bestimmt, das entweder aus der improxy.PacScript
-Objekt angegebenen URL abgerufen oder buchstäblich aus demdata
-Element, das improxy.PacScript
-Objekt angegeben ist, übernommen wird. Außerdem lässt dieser Modus keine weiteren Parameter imProxyConfig
-Objekt zu. fixed_servers
- Im
fixed_servers
-Modus wird die Proxykonfiguration in einemproxy.ProxyRules
-Objekt codiert. Seine Struktur wird unter Proxyregeln beschrieben. Außerdem lässt derfixed_servers
-Modus keine weiteren Parameter imProxyConfig
-Objekt zu. system
- Im
system
-Modus wird die Proxykonfiguration aus dem Betriebssystem übernommen. In diesem Modus sind keine weiteren Parameter imProxyConfig
-Objekt zulässig. Der Modussystem
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:
Schema | Port |
---|---|
http | 80 |
https | 443 |
socks4 | 1080 |
socks5 | 1080 |
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 sindexample
undlocalhost
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.
Typen
Mode
Enum
"pac_script"
"system"
PacScript
Ein Objekt mit Informationen zur automatischen Konfiguration von Proxys. Genau eines der Felder darf nicht leer sein.
Attribute
-
Daten
String optional
Ein PAC-Script.
-
obligatorisch
Boolescher Wert optional
Ist der Wert „true“, verhindert ein ungültiges PAC-Script, dass der Netzwerkstack auf direkte Verbindungen zurückgreift. Die Standardeinstellung ist "false".
-
url
String optional
URL der PAC-Datei, die verwendet werden soll.
ProxyConfig
Ein Objekt, das eine vollständige Proxykonfiguration einschließt.
Attribute
-
Modus
'direct' = Nie einen Proxy verwenden 'auto_detection' = Proxy-Einstellungen automatisch erkennen 'pac_script' = angegebenes PAC-Skript verwenden 'Fixed_servers' = Proxyserver manuell angeben 'system' = Proxy-Einstellungen des Systems verwenden
-
pacScript
PacScript optional
Das PAC-Skript (Proxy Auto-Config) für diese Konfiguration. Verwenden Sie dies für den Modus „pac_script“.
-
Regeln
ProxyRules optional
Die Proxy-Regeln, die diese Konfiguration beschreiben. Verwenden Sie diesen Wert für den Modus „Fixed_servers“.
ProxyRules
Ein Objekt, das den Satz von Proxyregeln für alle Protokolle einschließt. Verwenden Sie entweder „singleProxy“ oder (eine Teilmenge von) „proxyForHttp“, „proxyForHttps“, „proxyForFtp“ und „fallbackProxy“.
Attribute
-
bypassList
string[] optional
Liste der Server, zu denen ohne Proxyserver eine Verbindung hergestellt werden soll.
-
fallbackProxy
ProxyServer optional
Der Proxy-Server, der für alle anderen Aktionen verwendet werden soll oder für den Fall, dass einer der spezifischen proxyFor... nicht angegeben ist.
-
proxyForFtp
ProxyServer optional
Der Proxyserver, der für FTP-Anfragen verwendet werden soll.
-
proxyForHttp
ProxyServer optional
Der Proxyserver, der für HTTP-Anfragen verwendet werden soll.
-
proxyForHttps
ProxyServer optional
Der Proxyserver, der für HTTPS-Anfragen verwendet werden soll.
-
singleProxy
ProxyServer optional
Der Proxyserver, der für alle Anfragen pro URL (HTTP, HTTPS und FTP) verwendet werden soll.
ProxyServer
Ein Objekt, das die Spezifikation eines einzelnen Proxyservers einschließt.
Attribute
-
Gastgeber
String
Der Hostname oder die IP-Adresse des Proxyservers. Hostnamen müssen im ASCII-Format (Punycode-Format) vorliegen. IDNA wird noch nicht unterstützt.
-
Port
Nummer optional
Port des Proxyservers. Die Standardeinstellung ist ein Port, der vom Schema abhängt.
-
Schema
Schema optional
Das Schema (Protokoll) des Proxyservers selbst. Die Standardeinstellung ist „http“.
Scheme
Enum
"http"
"quic"
"socks4"
"socks5"
Attribute
settings
Zu verwendende Proxy-Einstellungen. Der Wert dieser Einstellung ist ein ProxyConfig-Objekt.
Veranstaltungen
onProxyError
chrome.proxy.onProxyError.addListener(
callback: function,
)
Benachrichtigt über Proxyfehler
Parameters
-
callback
Funktion
Der Parameter
callback
sieht so aus:(details: object) => void
-
Details
Objekt
-
Details
String
Zusätzliche Details zum Fehler, z. B. ein JavaScript-Laufzeitfehler.
-
error
String
Die Fehlerbeschreibung.
-
fatal
boolean
Wenn „true“ festgelegt ist, war der Fehler schwerwiegend und die Netzwerktransaktion wurde abgebrochen. Andernfalls wird eine direkte Verbindung verwendet.
-
-