chrome.proxy

Beschreibung

Verwenden Sie die chrome.proxy API, um die Proxy-Einstellungen von Chrome zu verwalten. Diese API basiert auf dem ChromeSetting-Prototyp des Typs API zum Abrufen und Festlegen der Proxy-Konfiguration.

Berechtigungen

proxy

Sie müssen den „Proxy“ deklarieren Berechtigung im Erweiterungsmanifest, die Proxy-Einstellungen zu verwenden der API erstellen. 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 proxy.PacScript enthalten.

Proxy-Modi

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

direct
Im direct-Modus werden alle Verbindungen direkt und ohne Beteiligung eines Proxys erstellt. In diesem Modus können keine weiteren Parameter im ProxyConfig-Objekt.
auto_detect
Im auto_detect-Modus wird die Proxykonfiguration durch ein PAC-Skript bestimmt, das heruntergeladen werden kann unter http://wpad/wpad.dat. 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 URL, die im proxy.PacScript-Objekt angegeben ist oder wortwörtlich aus dem data-Element entnommen wird im Objekt proxy.PacScript angegeben. Außerdem können in diesem Modus keine weiteren Parameter im Objekt ProxyConfig.
fixed_servers
Im fixed_servers-Modus wird die Proxykonfiguration in einem proxy.ProxyRules-Objekt kodifiziert. Das wird unter Proxyregeln beschrieben. Außerdem können Sie im fixed_servers-Modus keine weiteren im Objekt ProxyConfig.
system
Im Modus system wird die Proxykonfiguration vom Betriebssystem übernommen. In diesem Modus sind keine weitere Parameter im ProxyConfig-Objekt. Der system-Modus ist nicht dasselbe wie Keine Proxy-Konfiguration festgelegt. In letzterem Fall greift Chrome nur dann auf die Systemeinstellungen zurück, wenn keine Befehlszeilenoptionen die Proxykonfiguration beeinflussen.

Proxy-Regeln

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

Im ersten Fall wird HTTP-, HTTPS- und FTP-Traffic über den angegebenen Proxyserver geleitet. Sonstiges werden die Zugriffe 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 Datenverkehr über das angegebenen Server. Wenn kein derartiger Proxyserver angegeben ist oder der Traffic ein anderes Protokoll als HTTP, HTTPS oder FTP: fallbackProxy wird verwendet. Wenn kein fallbackProxy angegeben ist, wird der Traffic gesendet direkt ohne Proxyserver.

Proxyserver-Objekte

Ein Proxyserver wird in einem proxy.ProxyServer-Objekt konfiguriert. Die Verbindung zum Proxyserver (definiert durch das Attribut host) verwendet das im Attribut scheme definierte Protokoll. Falls nein scheme angegeben ist, ist die Proxyverbindung standardmäßig http.

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

SchemaPort
http80
https443
socks41080
socks51080

Umgehungsliste

Einzelne Server können von der Weiterleitung mit dem bypassList ausgeschlossen werden. Diese Liste kann Folgendes enthalten: die folgenden Einträge:

[SCHEME://]HOST_PATTERN[:PORT]

Alle Hostnamen, die mit dem Muster HOST_PATTERN übereinstimmen, werden gefunden. Ein vorangestelltes "." wird als "*.".

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

MusterÜbereinstimmungenStimmt 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]

Gleicht URLs ab, die IP-Adressliterale sind. Dies ist konzeptionell ähnlich wie im ersten Fall, aber mit Sonderfällen zur Verarbeitung der IP-Literal-Kanonisierung. Beispiel: Übereinstimmungen mit "[0:0:0::1]" entspricht der Übereinstimmung 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

Sie suchen alle URLs, die ein IP-Literal (IP_LITERAL) enthalten, und zwar innerhalb des Bereich. Der IP-Bereich (PREFIX_LENGTH_IN_BITS) wird mit CIDR angegeben Schreibweise.

Sie suchen alle URLs, die ein IP-Literal im angegebenen Bereich enthalten. Der IP-Bereich wird mit CIDR angegeben Notation. Beispiele: "192.168.1.1/16", "fefe:13::abc/33"

<local>

Der literale String <local> stimmt mit einfachen Hostnamen überein. Ein einfacher Hostname enthält keine Punkte und ist kein IP-Literal. example und localhost sind beispielsweise 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 mit Ausnahme von foobar.com festgelegt und verwendet direkte Verbindungen für alle anderen Protokolle. Die Einstellungen gelten sowohl für normale als auch für Inkognitofenster Inkognito-Fenster übernehmen die Einstellungen von normalen Fenstern. Siehe auch die Types API Dokumentation.

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

Mit dem nächsten Snippet werden die aktuellen effektiven Proxy-Einstellungen abgefragt. Die effektiven Proxy-Einstellungen können durch eine andere Erweiterung oder durch eine Richtlinie festgelegt wird. 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 Callback-Funktion von get(). Letzteres enthält ein rules.proxyForHttp.port-Element.

Typen

Mode

Chrome (ab Version 54)

Enum

"direkt"

"auto_Detect"

"pac_script"

"Fixed_servers"

"system"

PacScript

Ein Objekt, das Informationen zur automatischen Proxykonfiguration enthält. Genau eines der Felder darf nicht leer sein.

Attribute

  • Daten

    String optional

    Ein PAC-Skript.

  • obligatorisch

    Boolescher Wert optional

    Ist sie auf „true“ gesetzt, verhindert ein ungültiges PAC-Script, dass der Netzwerkstack nicht auf direkte Verbindungen zurückgreifen kann. Die Standardeinstellung ist "false".

  • URL

    String optional

    URL der zu verwendenden PAC-Datei.

ProxyConfig

Ein Objekt, das eine vollständige Proxykonfiguration einschließt.

Attribute

  • Modus

    'direkt' [direct] = Nie einen Proxy verwenden „auto_ detect“ (Automatisch erkennen) = Proxy-Einstellungen automatisch erkennen „pac_script“ = Angegebenes PAC-Skript verwenden „feste_server“ = Proxyserver manuell angeben „system“ = Proxy-Einstellungen des Systems verwenden

  • pacScript

    PacScript optional

    Das PAC-Script (Proxy Auto-Config) für diese Konfiguration. Verwenden Sie dieses Attribut für "pac_script" .

  • Regeln

    ProxyRules optional

    Die Proxyregeln, die diese Konfiguration beschreiben. Verwenden Sie dieses Attribut für „fixed_servers“ .

ProxyRules

Ein Objekt, das die Gruppe von Proxyregeln für alle Protokolle einschließt. Verwenden Sie entweder „singleProxy“ oder (eine Untergruppe 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 für alles andere zu verwendende Proxyserver oder wenn einer der spezifischen proxyFor... nicht angegeben ist.

  • proxyForFtp

    ProxyServer optional

    Der für FTP-Anfragen zu verwendende Proxyserver.

  • proxyForHttp

    ProxyServer optional

    Der für HTTP-Anfragen zu verwendende Proxyserver.

  • proxyForHttps

    ProxyServer optional

    Der für HTTPS-Anfragen zu verwendende Proxyserver.

  • singleProxy

    ProxyServer optional

    Der für alle URL-Anfragen zu verwendende Proxyserver (d. h. HTTP, HTTPS und FTP).

ProxyServer

Ein Objekt, das die Spezifikation eines einzelnen Proxyservers einschließt.

Attribute

  • Host

    String

    Der Hostname oder die IP-Adresse des Proxyservers. Hostnamen müssen im ASCII-Format (im Punycode-Format) angegeben werden. IDNA wird noch nicht unterstützt.

  • Port

    Zahl optional

    Der 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

Chrome (ab Version 54)

Enum

"http"

„https“

"quic"

„socken4“

"socken5"

Attribute

settings

Zu verwendende Proxy-Einstellungen. Der Wert dieser Einstellung ist ein ProxyConfig-Objekt.

Ereignisse

onProxyError

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

Benachrichtigt über Proxy-Fehler.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus:

    (details: object) => void

    • Details

      Objekt

      • Details

        String

        Weitere Details zum Fehler, z. B. ein JavaScript-Laufzeitfehler.

      • Fehler

        String

        Die Fehlerbeschreibung.

      • fatal

        boolean

        Falls wahr, war der Fehler schwerwiegend und die Netzwerktransaktion wurde abgebrochen. Andernfalls wird eine direkte Verbindung verwendet.