説明
chrome.proxy
API を使用して、Chrome のプロキシ設定を管理します。この API は、プロキシ構成の取得と設定に ChromeSetting プロトタイプ タイプ API を使用します。
権限
proxy
プロキシ設定 API を使用するには、拡張機能のマニフェストで「プロキシ」権限を宣言する必要があります。次に例を示します。
{
"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
モードでは、プロキシ構成は PAC スクリプトによって決定されます。PAC スクリプトは、proxy.PacScript
オブジェクトで指定された URL から取得されるか、proxy.PacScript
オブジェクトで指定されたdata
要素から取得されます。また、このモードでは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
が定義されていない場合、ポートはスキームから導出されます。デフォルトのポートは次のとおりです。
Scheme | ポート |
---|---|
http | 80 |
https | 443 |
socks4 | 1080 |
socks5 | 1080 |
バイパスリスト
個々のサーバーを 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
要素が含まれます。
型
Mode
Enum
"auto_detect"
"fixed_servers"
PacScript
プロキシの自動設定情報を保持するオブジェクト。いずれか 1 つのフィールドを空にすることはできません。
プロパティ
-
data
string(省略可)
PAC スクリプト。
-
必須
ブール値(省略可)
true の場合、無効な PAC スクリプトがあると、ネットワーク スタックを直接接続にフォールバックできません。デフォルトは false です。
-
URL
string(省略可)
使用する PAC ファイルの URL。
ProxyConfig
完全なプロキシ構成をカプセル化するオブジェクト。
プロパティ
-
モード
'direct' = プロキシを使用しない 'auto_detect' = プロキシ設定を自動検出する 'pac_script' = 指定された PAC スクリプトを使用する 'fixed_servers' = プロキシ サーバーを手動で指定 'system' = システムのプロキシ設定を使用
-
pacScript
PacScript 省略可
この構成のプロキシ自動設定(PAC)スクリプト。「pac_script」モードに使用します。
-
ルール
ProxyRules 省略可
この構成を記述するプロキシルール。「fixed_servers」モードに使用します。
ProxyRules
すべてのプロトコルのプロキシルールのセットをカプセル化するオブジェクト。「singleProxy」または「proxyForHttp」、「proxyForHttps」、「proxyForFtp」、「fallbackProxy」のサブセットのいずれかを使用します。
プロパティ
-
bypassList
string[] 省略可
プロキシ サーバーを使用せずに接続するサーバーのリスト。
-
fallbackProxy
ProxyServer 省略可
他のすべてに使用されるか、または特定の proxyFor... のいずれかが指定されていない場合に使用されるプロキシ サーバー。
-
proxyForFtp
ProxyServer 省略可
FTP リクエストに使用するプロキシ サーバー。
-
proxyForHttp
ProxyServer 省略可
HTTP リクエストに使用されるプロキシ サーバー。
-
proxyForHttps
ProxyServer 省略可
HTTPS リクエストに使用するプロキシ サーバー。
-
singleProxy
ProxyServer 省略可
URL ごとのすべてのリクエスト(http、https、ftp)に使用するプロキシ サーバーです。
ProxyServer
単一のプロキシ サーバーの仕様をカプセル化するオブジェクト。
プロパティ
-
主催者
文字列
プロキシ サーバーのホスト名または IP アドレス。ホスト名は ASCII(Punycode 形式)でなければなりません。IDNA はまだサポートされていません。
-
ポート
number(省略可)
プロキシ サーバーのポート。デフォルトは、スキームに応じたポートになります。
-
scheme
スキーム 省略可
プロキシ サーバー自体のスキーム(プロトコル)。デフォルトは「http」です。
Scheme
Enum
"http"
"quic"
"socks4"
"socks5"
プロパティ
settings
使用するプロキシ設定。この設定の値は ProxyConfig オブジェクトです。
イベント
onProxyError
chrome.proxy.onProxyError.addListener(
callback: function,
)
プロキシエラーを通知します。
パラメータ
-
callback
機能
callback
パラメータは次のようになります。(details: object) => void
-
詳細
オブジェクト
-
詳細
文字列
JavaScript ランタイム エラーなど、エラーに関する追加情報。
-
error
文字列
エラーの説明。
-
fatal
boolean
true の場合、エラーは致命的であり、ネットワーク トランザクションは中止されました。それ以外の場合は、直接接続が使用されます。
-
-