Cette traduction est incomplète. Aidez à traduire cet article depuis l'anglais.

Utilisez l'API proxy pour enregistrer un fichier Proxy Auto-Configuration (PAC) étendu, qui implémente une stratégie de proxy pour les requêtes Web. Cette implémentation diffère de la conception PAC standard de plusieurs manières parce que la spécification de facto pour les fichiers PAC n'a pas changé depuis sa mise en œuvre initiale vers 1995. Il n'y a pas d'organisme de normalisation maintenant la spécification.

Notez que Google Chrome fournit une API extension appelée aussi "proxy" qui est fonctionnellement similaire à cette API, dans la mesure où les extensions peuvent l'utiliser pour implémenter une stratégie de proxy. Cependant, la conception de l'API Chrome est complètement différente de cette API. Avec l'API de Chrome, une extension peut enregistrer un fichier PAC, mais elle peut également définir des règles de proxy explicites. Comme cela est également possible en utilisant les fichiers PAC étendus, cette API ne supporte que l'approche du fichier PAC. Parce que cette API est incompatible avec l'API proxy de Chrome, cette API est uniquement disponible via l'espace de noms du browser.

Pour utiliser cette API, vous devez disposer de la permission "proxy"

Communicating with PAC files

You can exchange messages between the PAC file and your extension's background page (or any other privileged pages, like popup pages) using runtime.sendMessage() and runtime.onMessage.

To send a message to the PAC file, you must set the toProxyScript option:

// background.js

// Log any messages from the proxy.
browser.runtime.onMessage.addListener((message, sender) => {
  if (sender.url === browser.extension.getURL(proxyScriptURL)) {
    console.log(message);
  }
});

let messageToProxy = {
  enabled: true,
  foo: "A string",
  bar: 1234
};

browser.runtime.sendMessage(messageToProxy, {toProxyScript: true});
// pac.js

browser.runtime.onMessage.addListener((message) => {
  if (message.enabled) {
    browser.runtime.sendMessage("I'm enabled!");
  }
});

PAC file specification

The basic PAC file syntax is described in the PAC documentation, but the implementation used by the proxy API differs from standard PAC design in several ways, which are described in this section.

FindProxyForURL() return value

The standard FindProxyForURL() returns a string. In Firefox 55 and 56, the PAC file used with the proxy API also returns a string. In Firefox 55 only, you must pass an argument to the "DIRECT" return value, even though it doesn't need an argument.

From Firefox 57 onwards, FindProxyForURL() may still return a string, but may alternatively (and preferably) return an array of objects. Each object has the following properties:

type
String. This must be one of: "http"|"https|"socks5"|"socks4"|"socks"|"direct"|"ignore". "socks" is a synonym for socks5. "ignore" means the browser should handle this URI through its global proxy settings.
host
String. Hostname for the proxy to use.
port
String. Port for the proxy.
username Facultatif
String. Username for the proxy. This is usable with "socks"/"socks5". For HTTP proxy authorizations, use webRequest.onAuthRequired.
password Facultatif
String. Password for the proxy. This is usable with "socks"/"socks5". For HTTP proxy authorizations, use webRequest.onAuthRequired.
proxyDNS Facultatif
Boolean. If true, the proxy server is used to resolve certain DNS queries. Defaults to false.
failoverTimeout Facultatif
Integer. Number of seconds before timing out and trying the next proxy in the array. Defaults to 1.

For example:

const proxySpecification = [
  {
    type: "socks",
    host: "foo.com",
    port: 1080,
    proxyDNS: true,
    failoverTimeout: 5
  },
  {
    type: "socks",
    host: "bar.com",
    port: 1060,
  }
];

The first proxy in the array will be tried first. If it does not respond in failoverTimeout seconds, the next will be tried, until the end of the array is reached.

PAC file environment

The global helper functions usually available for PAC files (isPlainHostName(), dnsDomainIs(), and so on) are not available.

Code running in the PAC file does not get access to:

//  pac.js

// send the log message to the background script
browser.runtime.sendMessage(`Proxy-blocker: blocked ${url}`);
// background-script.js

function handleMessage(message, sender) {
  // only handle messages from the proxy script
  if (sender.url != browser.extension.getURL(proxyScriptURL)) {
    return;
  }
  console.log(message);
}

browser.runtime.onMessage.addListener(handleMessage);

Functions

proxy.register()
Registers the given proxy script.
proxy.unregister()
Unregisters the proxy script.

Events

proxy.onProxyError
Fired when the system encounters an error running the proxy script.

Compatibilité du navigateur

ChromeEdgeFirefoxFirefox for AndroidOpera
onProxyError Non Non5555 Non
register Non Non

56

55 *

55 Non
unregister Non Non5656 Non

Example extensions

Remerciements :

Les données de compatibilité relatives à Microsoft Edge sont fournies par Microsoft Corporation et incluses ici sous la licence Creative Commons Attribution 3.0 pour les États-Unis.

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : hellosct1
 Dernière mise à jour par : hellosct1,