chrome.proxy

Description

Autorisations

Fichier manifeste

Vous devez déclarer l'autorisation "proxy" dans le fichier manifeste de l'extension pour utiliser l'API des paramètres proxy. Exemple :

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

Objets et propriétés

Les paramètres proxy sont définis dans un objet proxy.ProxyConfig. En fonction des paramètres proxy de Chrome, les paramètres peuvent contenir proxy.ProxyRules ou proxy.PacScript.

Modes proxy

L'attribut mode d'un objet ProxyConfig détermine le comportement général de Chrome en ce qui concerne l'utilisation du proxy. Il peut prendre les valeurs suivantes :

direct

En mode direct, toutes les connexions sont créées directement, sans aucun proxy. Ce mode n'autorise aucun autre paramètre dans l'objet ProxyConfig.

auto_detect

En mode auto_detect, la configuration du proxy est déterminée par un script PAC qui peut être téléchargé à l'adresse http://wpad/wpad.dat.

Ce mode n'autorise aucun autre paramètre dans l'objet ProxyConfig.

pac_script

En mode pac_script, la configuration du proxy est déterminée par un script PAC qui est récupéré à partir de l'URL spécifiée dans l'objet proxy.PacScript ou pris littéralement à partir de l'élément data spécifié dans l'objet proxy.PacScript. De plus, ce mode n'autorise aucun autre paramètre dans l'objet ProxyConfig.

fixed_servers

 En mode fixed_servers, la configuration du proxy est codifiée dans un objet proxy.ProxyRules. Sa structure est décrite dans Règles de proxy. De plus, le mode fixed_servers n'autorise aucun autre paramètre dans l'objet ProxyConfig.

system

 : en mode system, la configuration du proxy est extraite du système d'exploitation. Ce mode n'autorise aucun autre paramètre dans l'objet ProxyConfig. Notez que le mode system est différent de la configuration sans proxy. Dans ce dernier cas, Chrome revient aux paramètres système uniquement si aucune option de ligne de commande n'influence la configuration du proxy.

Règles de proxy

L'objet proxy.ProxyRules peut contenir un attribut singleProxy ou un sous-ensemble de proxyForHttp, proxyForHttps, proxyForFtp et fallbackProxy.

Dans le premier cas, le trafic HTTP, HTTPS et FTP est transféré par proxy via le serveur proxy spécifié. Les autres types de trafic sont envoyés directement. Dans ce dernier cas, le comportement est légèrement plus subtil : si un serveur proxy est configuré pour le protocole HTTP, HTTPS ou FTP, le trafic correspondant est transmis par proxy via le serveur spécifié. Si aucun serveur proxy de ce type n'est spécifié ou si le trafic utilise un protocole différent de HTTP, HTTPS ou FTP, fallbackProxy est utilisé. Si aucun fallbackProxy n'est spécifié, le trafic est envoyé directement sans serveur proxy.

Objets de serveur proxy

Un serveur proxy est configuré dans un objet proxy.ProxyServer. La connexion au serveur proxy (défini par l'attribut host) utilise le protocole défini dans l'attribut scheme. Si aucun scheme n'est spécifié, la connexion proxy est définie par défaut sur http.

Si aucun port n'est défini dans un objet proxy.ProxyServer, le port est dérivé du schéma. Les ports par défaut sont les suivants :

Liste d'exemption

Il est possible d'exclure des serveurs individuels du proxy à l'aide de bypassList. Cette liste peut contenir les entrées suivantes :

[SCHEME://]HOST_PATTERN[:PORT]

Mettre en correspondance tous les noms d'hôte correspondant au modèle HOST_PATTERN. Un "." en début de chaîne est interprété comme un "*.".

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

Schéma	Correspond à	Ne correspond pas
".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]

Faites correspondre les URL qui sont des littéraux d'adresse IP. Conceptuellement, cela ressemble au premier cas, mais avec des cas particuliers pour gérer la canonisation des littéraux IP. Par exemple, la correspondance avec « [0:0:0::1] » est identique à celle avec « [::1] », car la canonisation IPv6 est effectuée en interne.

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

IP_LITERAL/PREFIX_LENGTH_IN_BITS

Correspond à toute URL contenant un littéral IP (IP_LITERAL) dans la plage donnée. La plage d'adresses IP (PREFIX_LENGTH_IN_BITS) est spécifiée à l'aide de la notation CIDR.

Correspond à toute URL contenant un littéral IP dans la plage donnée. La plage d'adresses IP est spécifiée au format CIDR. Exemples : "192.168.1.1/16", "fefe:13::abc/33"

<local>

La chaîne littérale <local> correspond aux noms d'hôte simples. Un nom d'hôte simple est un nom qui ne contient aucun point et n'est pas un littéral d'adresse IP. Par exemple, example et localhost sont des noms d'hôte simples, contrairement à example.com, example. et [::1].

Exemple : "<local>"

Exemples

Le code suivant définit un proxy SOCKS 5 pour les connexions HTTP à tous les serveurs, à l'exception de foobar.com, et utilise des connexions directes pour tous les autres protocoles. Les paramètres s'appliquent aux fenêtres standards et de navigation privée, car les fenêtres de navigation privée héritent des paramètres des fenêtres standards. Veuillez également consulter la documentation de l'API Types.

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

Le code suivant définit un script PAC personnalisé.

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

L'extrait de code suivant interroge les paramètres proxy actuellement en vigueur. Les paramètres proxy effectifs peuvent être déterminés par une autre extension ou par une règle. Pour en savoir plus, consultez la documentation de l'API Types.

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

Notez que l'objet value transmis à set() n'est pas identique à l'objet value transmis à la fonction de rappel de get(). Ce dernier contiendra un élément rules.proxyForHttp.port.

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