chrome.proxy

說明

使用 chrome.proxy API 管理 Chrome 的 Proxy 設定。這個 API 需要運用 ChromeSetting 類型 API 原型取得及設定 Proxy 設定。

權限

proxy

資訊清單

您必須宣告「proxy」請使用擴充功能資訊清單中的權限,才能使用 Proxy 設定 也能使用 Google Cloud CLI 或 Compute Engine API例如:

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

物件和屬性

Proxy 設定是在 proxy.ProxyConfig 物件中定義。視 Chrome 的 Proxy 設定而定 設定可能包含 proxy.ProxyRulesproxy.PacScript

Proxy 模式

ProxyConfig 物件的 mode 屬性會決定 Chrome 針對 Proxy 用量可能採用的值如下:

direct
direct 模式中,所有連線都會直接建立,不需使用任何 Proxy。這個模式允許 ProxyConfig 物件中沒有其他參數。
auto_detect
auto_detect 模式下,Proxy 設定會由可下載的 PAC 指令碼決定 前往 http://wpad/wpad.dat,這個模式不允許 ProxyConfig 物件中使用其他參數。
pac_script
pac_script 模式下,Proxy 設定會由擷取的 PAC 指令碼決定 來自 proxy.PacScript 物件中指定的網址,或直接從 data 元素取得 在 proxy.PacScript 物件中指定。此外,這個模式無法再提供其他參數 在 ProxyConfig 物件中。
fixed_servers
fixed_servers 模式下,Proxy 設定會編寫在 proxy.ProxyRules 物件中。結果 請參閱「Proxy 規則」一文。除此之外,fixed_servers 模式已無 定義 ProxyConfig 物件。
system
system 模式下,Proxy 設定會從作業系統取得。如果使用這個模式, ProxyConfig 物件中其他的參數。請注意,system 模式與 沒有 Proxy 設定若是後者,只有在符合以下條件時,Chrome 才會改回使用系統設定 沒有任何指令列選項影響 Proxy 設定。

Proxy 規則

proxy.ProxyRules 物件可包含 singleProxy 屬性或子集 proxyForHttpproxyForHttpsproxyForFtpfallbackProxy

在第一個情況下,HTTP、HTTPS 和 FTP 流量會透過指定的 Proxy 伺服器進行 Proxy 處理。其他 流量第二種情況則略有變動:如果 Proxy 伺服器 HTTP、HTTPS 或 FTP 通訊協定設定時,系統會透過 指定的伺服器如果沒有指定這類 Proxy 伺服器,或是流量使用的通訊協定並非 HTTP、HTTPS 或 FTP,會使用 fallbackProxy。如未指定 fallbackProxy,系統會傳送流量 無需 Proxy 伺服器

Proxy 伺服器物件

Proxy 伺服器是在 proxy.ProxyServer 物件中設定。連至 Proxy 伺服器的連線 (由 host 屬性定義) 會使用 scheme 屬性中定義的通訊協定。如果答案為「否」 指定 scheme,Proxy 連線預設為 http

如果 proxy.ProxyServer 物件中未定義任何 port,則通訊埠將衍生自配置。 預設通訊埠如下:

架構通訊埠
http80
https443
socks41080
socks51080

略過清單

使用 bypassList 時,不得將個別伺服器進行 Proxy 處理。這份清單可能包含 下列項目:

[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 位址常值的網址。概念上與第一個例子類似 處理 IP 常值標準化的特殊情況例如比對「[0:0:0::1]」 與「[::1]」上的相符項目相同IPv6 標準化作業是在內部完成

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

IP_LITERAL/PREFIX_LENGTH_IN_BITS

比對指定內包含 IP 常值 (IP_LITERAL) 的任何網址 範圍。IP 範圍 (PREFIX_LENGTH_IN_BITS) 是以 CIDR 指定 標記法

比對指定範圍內任何包含 IP 常值的網址。IP 範圍是以 CIDR 指定 標記法。 範例:"192.168.1.1/16", "fefe:13::abc/33"

<local>

常值字串 <local> 符合簡單的主機名稱。簡單的主機名稱 而且不是 IP 常值。舉例來說,examplelocalhost 是簡單的主機名稱 而 example.comexample.[::1] 則不是。

範例:"<local>"

範例

下列程式碼會為與 foobar.com 外的所有伺服器設定 HTTP 連線的 SOCKS 5 Proxy,並使用 所有其他通訊協定的直接連線。這些設定會套用到一般視窗和無痕式視窗,如 無痕式視窗會沿用一般視窗的設定。另請參閱 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() {}
);

下一段程式碼片段會查詢目前有效的 Proxy 設定。有效的 Proxy 設定 由其他擴充功能或政策決定。詳情請參閱 Types API 說明文件。

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

請注意,傳遞至 set() 物件的 value 物件與傳入 value 物件不同 get() 的回呼函式。後者包含 rules.proxyForHttp.port 元素。

類型

Mode

Chrome 54 以上版本

列舉

"direct"

"auto_detect"

"pac_script"

"fixed_servers"

「系統」

PacScript

保留 Proxy 自動設定資訊的物件。其中一個欄位不能空白。

屬性

  • 資料

    string optional

    PAC 指令碼。

  • 必填

    布林值 選填

    若為 true,無效的 PAC 指令碼將使網路堆疊無法轉回直接連線。預設值為 false。

  • 網址

    string optional

    要使用的 PAC 檔案網址。

ProxyConfig

封裝完整 Proxy 設定的物件。

屬性

  • 模式

    「直接」= 不使用 Proxy 「auto_Detect」= 自動偵測 Proxy 設定 「pac_script」= 使用指定的 PAC 指令碼 「fixed_servers」= 手動指定 Proxy 伺服器 「系統」= 使用系統 Proxy 設定

  • pacScript

    PacScript 選用

    這項設定的 Proxy 自動設定 (PAC) 指令碼。這將用於「pac_script」模式。

  • 規則

    ProxyRules 選用

    說明這項設定的 Proxy 規則。將這個數字用於「fixed_servers」模式。

ProxyRules

這個物件會封裝所有通訊協定的 Proxy 規則組合。使用「singleProxy」或 (子集)「proxyForHttp」、「proxyForHttps」、「proxyForFtp」和「fallbackProxy」

屬性

  • bypassList

    string[] 選填

    不需 Proxy 伺服器即可連線的伺服器清單。

  • fallbackProxy

    ProxyServer 選用

    要使用的 Proxy 伺服器;如果沒有指定 Proxy 伺服器,也未指定任何 ProxyFor...。

  • proxyForFtp

    ProxyServer 選用

    用於 FTP 要求的 Proxy 伺服器。

  • proxyForHttp

    ProxyServer 選用

    用於 HTTP 要求的 Proxy 伺服器。

  • proxyForHttps

    ProxyServer 選用

    用於 HTTPS 要求的 Proxy 伺服器。

  • singleProxy

    ProxyServer 選用

    用於個別網址要求 (http、https 和 ftp) 的 Proxy 伺服器。

ProxyServer

封裝單一 Proxy 伺服器規格的物件。

屬性

  • 主機

    字串

    Proxy 伺服器的主機名稱或 IP 位址。主機名稱必須採用 ASCII 格式 (採用 Punycode 格式)。目前尚不支援 IDNA。

  • 通訊埠

    編號 選填

    Proxy 伺服器的通訊埠。預設為依附於配置的通訊埠。

  • 架構

    配置 選用

    Proxy 伺服器本身的配置 (通訊協定)。預設為「http」。

Scheme

Chrome 54 以上版本

列舉

"http"

"https"

"quic"

"socks4"

"socks5"

屬性

settings

要使用的 Proxy 設定。這項設定的值是 ProxyConfig 物件。

活動

onProxyError

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

通知 Proxy 錯誤。

參數

  • 回呼

    函式

    callback 參數如下所示:

    (details: object) => void

    • 詳細資料

      物件

      • 詳細資料

        字串

        其他錯誤詳細資料,例如 JavaScript 執行階段錯誤。

      • 錯誤

        字串

        錯誤說明。

      • fatal

        布林值

        如為 true,則屬於嚴重錯誤,並取消網路交易。否則,系統會改用直接連線。