chrome.proxy

説明

権限

マニフェスト

プロキシ設定 API を使用するには、拡張機能のマニフェストで「proxy」権限を宣言する必要があります。次に例を示します。

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

オブジェクトとプロパティ

プロキシ設定は proxy.ProxyConfig オブジェクトで定義されます。Chrome のプロキシ設定によっては、設定に proxy.ProxyRules または proxy.PacScript が含まれることがあります。

プロキシモード

ProxyConfig オブジェクトの mode 属性は、プロキシの使用に関する Chrome の全体的な動作を決定します。次のいずれかの値を取ります。

direct

direct モードでは、プロキシを使用せずにすべての接続が直接作成されます。このモードでは、ProxyConfig オブジェクトにパラメータを追加できません。

auto_detect

auto_detect モードでは、プロキシ構成は http://wpad/wpad.dat でダウンロードできる PAC スクリプトによって決定されます。このモードでは、ProxyConfig オブジェクトにパラメータを追加することはできません。

pac_script

pac_script モードでは、プロキシ構成は、proxy.PacScript オブジェクトで指定された URL から取得されるか、proxy.PacScript オブジェクトで指定された data 要素からリテラルで取得される PAC スクリプトによって決定されます。このモードでは、ProxyConfig オブジェクトに他のパラメータを指定することはできません。

fixed_servers

fixed_servers モードでは、プロキシ構成は proxy.ProxyRules オブジェクトにコード化されます。その構造については、プロキシルールをご覧ください。このほか、fixed_servers モードでは ProxyConfig オブジェクトにパラメータを追加できません。

system

system モードでは、プロキシ構成はオペレーティング システムから取得されます。このモードでは、ProxyConfig オブジェクトにパラメータを追加できません。system モードは、プロキシ構成を設定しないこととは異なります。後者の場合、コマンドライン オプションがプロキシ構成に影響しない場合にのみ、Chrome はシステム設定にフォールバックします。

プロキシルール

proxy.ProxyRules オブジェクトには、singleProxy 属性または proxyForHttp、proxyForHttps、proxyForFtp、fallbackProxy のサブセットのいずれかを含めることができます。

最初のケースでは、HTTP、HTTPS、FTP のトラフィックは指定されたプロキシ サーバーを介してプロキシされます。他のトラフィックは直接送信されます。後者の場合、動作はやや複雑になります。HTTP、HTTPS、FTP プロトコル用にプロキシ サーバーが構成されている場合、それぞれのトラフィックは指定されたサーバーを介してプロキシされます。このようなプロキシ サーバーが指定されていない場合、またはトラフィックが HTTP、HTTPS、FTP とは異なるプロトコルを使用している場合は、fallbackProxy が使用されます。fallbackProxy が指定されていない場合、トラフィックはプロキシ サーバーなしで直接送信されます。

プロキシ サーバー オブジェクト

プロキシ サーバーは proxy.ProxyServer オブジェクトで構成されます。プロキシ サーバーへの接続（host 属性で定義）では、scheme 属性で定義されたプロトコルが使用されます。scheme が指定されていない場合、プロキシ接続はデフォルトで http になります。

proxy.ProxyServer オブジェクトで port が定義されていない場合、ポートはスキームから取得されます。デフォルトのポートは次のとおりです。

バイパスリスト

個々のサーバーは bypassList を使用してプロキシから除外できます。このリストには次のエントリが含まれる場合があります。

[SCHEME://]HOST_PATTERN[:PORT]

パターン HOST_PATTERN に一致するすべてのホスト名を照合します。先頭の "." は "*." として解釈されます。

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

パターン	一致する	一致しない
".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]

IP アドレス リテラルである URL を照合します。概念的には最初のケースと似ていますが、IP リテラルの正規化を処理する特殊なケースがあります。たとえば、IPv6 の正規化は内部で行われるため、「[0:0:0::1]」との照合は「[::1]」との照合と同じです。

例: 127.0.1、[0:0::1]、[::1]:80、https://[::1]:443

IP_LITERAL/PREFIX_LENGTH_IN_BITS

指定された範囲内の IP リテラル（IP_LITERAL）を含む URL を検索します。IP 範囲（PREFIX_LENGTH_IN_BITS）は、CIDR 表記を使用して指定します。

指定された範囲内の IP リテラルを含む URL に一致します。IP 範囲は CIDR 表記を使用して指定します。例: "192.168.1.1/16", "fefe:13::abc/33"

<local>

リテラル文字列 <local> は、単純なホスト名と一致します。単純なホスト名とは、ドットを含まず、IP リテラルではないホスト名です。たとえば、example と localhost は単純なホスト名ですが、example.com、example.、[::1] は単純なホスト名ではありません。

例: "<local>"

例

次のコードは、すべてのサーバー（foobar.com を除く）への HTTP 接続に SOCKS 5 プロキシを設定し、他のすべてのプロトコルに直接接続を使用します。シークレット ウィンドウは通常のウィンドウの設定を継承するため、この設定は通常のウィンドウとシークレット ウィンドウの両方に適用されます。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() {}
);

次のコードは、カスタム PAC スクリプトを設定します。

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

次のスニペットは、現在有効なプロキシ設定をクエリします。有効なプロキシ設定は、別の拡張機能またはポリシーによって決定されることがあります。詳しくは、Types API ドキュメントをご覧ください。

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

set() に渡される value オブジェクトは、get() のコールバック関数に渡される value オブジェクトと同一ではありません。後者には rules.proxyForHttp.port 要素が含まれます。

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