chrome.proxy

คำอธิบาย

ใช้ chrome.proxy API เพื่อจัดการการตั้งค่าพร็อกซีของ Chrome API นี้ใช้ต้นแบบ ChromeSetting ของประเภท API ในการรับและตั้งค่าการกำหนดค่าพร็อกซี

สิทธิ์

proxy

คุณต้องประกาศ "พร็อกซี" สิทธิ์ในไฟล์ Manifest ของส่วนขยายเพื่อใช้การตั้งค่าพร็อกซี API เช่น

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

แนวคิดและการใช้งาน

การตั้งค่าพร็อกซีจะกำหนดไว้ในออบเจ็กต์ proxy.ProxyConfig ทั้งนี้ขึ้นอยู่กับการตั้งค่าพร็อกซีของ Chrome การตั้งค่าอาจมี proxy.ProxyRules หรือ proxy.PacScript

โหมดพร็อกซี

แอตทริบิวต์ mode ของออบเจ็กต์ ProxyConfig จะกำหนดลักษณะการทำงานโดยรวมของ Chrome เกี่ยวกับ การใช้พร็อกซี โดยสามารถรับค่าต่อไปนี้

direct

ระบบจะสร้างการเชื่อมต่อทั้งหมดในโหมด direct โดยตรงโดยไม่มีพร็อกซีที่เกี่ยวข้อง โหมดนี้ช่วยให้ ไม่มีพารามิเตอร์เพิ่มเติมในออบเจ็กต์ ProxyConfig

auto_detect

ในโหมด auto_detect การกำหนดค่าพร็อกซีจะกำหนดโดยสคริปต์ PAC ที่ดาวน์โหลดได้ ที่ http://wpad/wpad.dat โหมดนี้จะทำให้ไม่มีพารามิเตอร์เพิ่มเติมในออบเจ็กต์ ProxyConfig อีก

pac_script

ในโหมด pac_script การกำหนดค่าพร็อกซีจะกำหนดโดยสคริปต์ PAC ที่ดึงมา จาก URL ที่ระบุในออบเจ็กต์ proxy.PacScript หรือนำมาจากองค์ประกอบ data จริงๆ ที่ระบุในออบเจ็กต์ proxy.PacScript นอกจากนี้ โหมดนี้ไม่อนุญาตพารามิเตอร์เพิ่มเติม ในออบเจ็กต์ 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

หากไม่ได้กำหนด port ในออบเจ็กต์ proxy.ProxyServer พอร์ตนั้นจะมาจากรูปแบบดังกล่าว พอร์ตเริ่มต้นคือ

แบบแผน	พอร์ต
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]

จับคู่ URL ที่เป็นลิเทอรัลของที่อยู่ IP โดยหลักการแล้ว กรณีนี้คล้ายกับกรณีแรก ที่มีกรณีพิเศษในการจัดการการกำหนดหน้า Canonical ของ IP ตัวอย่างเช่น การจับคู่ใน "[0:0:0::1]" จะเหมือนกับการจับคู่ใน "[::1]" เนื่องจากการกำหนดหน้า Canonical6 ของ IPv6 ดำเนินการภายใน

เช่น 127.0.1, [0:0::1], [::1]:80, https://[::1]:443

IP_LITERAL/PREFIX_LENGTH_IN_BITS

จับคู่ URL ที่มีลิเทอรัล IP (IP_LITERAL) ภายใน ระบุช่วง IP (PREFIX_LENGTH_IN_BITS) โดยใช้ CIDR

จับคู่ URL ที่มีลิเทอรัล IP ภายในช่วงที่กำหนด ระบุช่วง IP โดยใช้ CIDR ตัวอย่าง: "192.168.1.1/16", "fefe:13::abc/33"

<local>

สตริงตัวอักษร <local> ตรงกับชื่อโฮสต์พื้นฐาน ชื่อโฮสต์แบบง่ายคือชื่อโฮสต์ที่ไม่มี จุด และไม่ใช่ลิเทอรัล IP ตัวอย่างเช่น example และ localhost เป็นชื่อโฮสต์ที่เรียบง่าย ขณะที่ example.com, example. และ [::1] ไม่ใช่

เช่น "<local>"

ตัวอย่าง

รหัสต่อไปนี้ตั้งค่าพร็อกซี SOCKS 5 สำหรับการเชื่อมต่อ HTTP กับเซิร์ฟเวอร์ทั้งหมด แต่ใช้ foobar.com ทั้งหมด การเชื่อมต่อโดยตรงสำหรับโปรโตคอลอื่นๆ ทั้งหมด การตั้งค่าจะมีผลกับหน้าต่างปกติและหน้าต่างที่ไม่ระบุตัวตน เนื่องจาก หน้าต่างที่ไม่ระบุตัวตนจะรับการตั้งค่าจากหน้าต่างปกติ โปรดดู 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));
  }
);

โปรดทราบว่าออบเจ็กต์ value ที่ส่งไปยัง set() ไม่เหมือนกับออบเจ็กต์ value ที่ส่งไปยัง ฟังก์ชัน Callback ของ get() รายการหลังจะมีองค์ประกอบ rules.proxyForHttp.port

ประเภท

Mode

Chrome 54 ขึ้นไป

ค่าแจกแจง

"โดยตรง"

"auto_detect"

"pac_script"

"fixed_servers"

"ระบบ"

PacScript

ออบเจ็กต์ที่มีข้อมูลการกำหนดค่าพร็อกซีอัตโนมัติ มีช่องใดช่องหนึ่งที่ไม่ควรว่างเปล่า

พร็อพเพอร์ตี้

• ข้อมูล

  string ไม่บังคับ

  สคริปต์ PAC

• บังคับ

  บูลีน ไม่บังคับ

  หากเป็นจริง สคริปต์ PAC ที่ไม่ถูกต้องจะป้องกันไม่ให้สแต็กเครือข่ายกลับไปใช้การเชื่อมต่อโดยตรง ค่าเริ่มต้นคือ "เท็จ"

• URL

  string ไม่บังคับ

  URL ของไฟล์ PAC ที่จะใช้

ProxyConfig

ออบเจ็กต์ที่รวมการกำหนดค่าพร็อกซีที่สมบูรณ์

พร็อพเพอร์ตี้

• โหมด

  โหมด

  "โดยตรง" = ไม่ใช้พร็อกซี "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 ไม่บังคับ

  พร็อกซีเซิร์ฟเวอร์ที่จะใช้เพื่อวัตถุประสงค์อื่น หรือไม่มีการระบุพร็อกซีสำหรับ... โดยเฉพาะ

• proxyForFtp

  ProxyServer ไม่บังคับ

  พร็อกซีเซิร์ฟเวอร์ที่จะใช้สำหรับคำขอ FTP

• proxyForHttp

  ProxyServer ไม่บังคับ

  พร็อกซีเซิร์ฟเวอร์ที่จะใช้สำหรับคำขอ HTTP

• proxyForHttps

  ProxyServer ไม่บังคับ

  พร็อกซีเซิร์ฟเวอร์ที่จะใช้สำหรับคำขอ HTTPS

• singleProxy

  ProxyServer ไม่บังคับ

  พร็อกซีเซิร์ฟเวอร์ที่จะใช้สำหรับคำขอ URL แต่ละรายการทั้งหมด (ซึ่งก็คือ http, https และ ftp)

ProxyServer

ออบเจ็กต์ที่รวมข้อกำหนดของพร็อกซีเซิร์ฟเวอร์เดียว

พร็อพเพอร์ตี้

• ผู้จัด

  สตริง

  ชื่อโฮสต์หรือที่อยู่ IP ของพร็อกซีเซิร์ฟเวอร์ ชื่อโฮสต์ต้องเป็น ASCII (ในรูปแบบ Puycode) ยังไม่รองรับ IDNA

• พอร์ต

  หมายเลข ไม่บังคับ

  พอร์ตของพร็อกซีเซิร์ฟเวอร์ ค่าเริ่มต้นเป็นพอร์ตที่ขึ้นอยู่กับรูปแบบ

• สคีม

  รูปแบบ ไม่บังคับ

  รูปแบบ (โปรโตคอล) ของพร็อกซีเซิร์ฟเวอร์ ค่าเริ่มต้นคือ "http"

Scheme

Chrome 54 ขึ้นไป

ค่าแจกแจง

"http"

"https"

"quic"

"socks4"

"socks5"

พร็อพเพอร์ตี้

settings

การตั้งค่าพร็อกซีที่จะใช้ ค่าของการตั้งค่านี้คือออบเจ็กต์ ProxyConfig

ประเภท

types.ChromeSetting<ProxyConfig>

กิจกรรม

onProxyError

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

แจ้งเตือนเกี่ยวกับข้อผิดพลาดของพร็อกซี

พารามิเตอร์

• Callback

  ฟังก์ชัน

  พารามิเตอร์ callback มีลักษณะดังนี้

  (details: object) => void

  • รายละเอียด

    ออบเจ็กต์

    • รายละเอียด

      สตริง

      รายละเอียดเพิ่มเติมเกี่ยวกับข้อผิดพลาด เช่น ข้อผิดพลาดรันไทม์ของ JavaScript

    • ข้อผิดพลาด

      สตริง

      คำอธิบายข้อผิดพลาด

    • fatal

      boolean

      หากเป็นจริง แสดงว่าข้อผิดพลาดร้ายแรงและล้มเลิกธุรกรรมของเครือข่าย มิเช่นนั้นจะใช้การเชื่อมต่อโดยตรงแทน