chrome.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 โดยหลักการแล้ว กรณีนี้คล้ายกับกรณีแรก แต่มีกรณีพิเศษในการรับมือกับการกำหนดหน้า 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 ที่ส่งไปยังฟังก์ชันเรียกกลับของ get() องค์ประกอบหลังจะมีองค์ประกอบ rules.proxyForHttp.port

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