chrome.proxy

คำอธิบาย

สิทธิ์

ไฟล์ Manifest

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

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

ออบเจ็กต์และพร็อพเพอร์ตี้

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

โหมดพร็อกซี

แอตทริบิวต์ 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 ระบบจะอนุมานพอร์ตจากสคีม พอร์ตเริ่มต้นมีดังนี้

รายการที่ข้าม

คุณสามารถยกเว้นเซิร์ฟเวอร์แต่ละรายการไม่ให้ผ่านพร็อกซีได้ด้วย 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 ในเชิงแนวคิดแล้ว URL นี้คล้ายกับกรณีแรก แต่มีกรณีพิเศษเพื่อจัดการการกำหนดค่า Canonical ของค่าคงที่ IP เช่น การจับคู่ "[0:0:0::1]" จะเหมือนกับการจับคู่ "[::1]" เนื่องจากระบบจะดำเนินการกำหนดค่า Canonical ของ 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

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