chrome.proxy

Nội dung mô tả

Sử dụng API chrome.proxy để quản lý chế độ cài đặt proxy của Chrome. API này dựa trên nguyên mẫu Cài đặt Chrome của loại API để nhận và đặt cấu hình proxy.

Quyền

proxy

Bạn phải khai báo quyền "proxy" trong tệp kê khai tiện ích để sử dụng API cài đặt proxy. Ví dụ:

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

Khái niệm và cách sử dụng

Chế độ cài đặt proxy được xác định trong đối tượng proxy.ProxyConfig. Tuỳ thuộc vào chế độ cài đặt proxy của Chrome, chế độ cài đặt này có thể chứa proxy.ProxyRules hoặc proxy.PacScript.

Chế độ proxy

Thuộc tính mode của đối tượng ProxyConfig xác định hành vi chung của Chrome liên quan đến việc sử dụng proxy. Hàm này có thể nhận các giá trị sau:

direct
Trong chế độ direct, tất cả các kết nối được tạo trực tiếp mà không cần proxy nào. Chế độ này không cho phép thêm tham số trong đối tượng ProxyConfig.
auto_detect
Ở chế độ auto_detect, cấu hình proxy được xác định bằng một tập lệnh PAC. Bạn có thể tải tập lệnh này xuống tại http://wpad/wpad.dat. Chế độ này không cho phép thêm tham số trong đối tượng ProxyConfig.
pac_script
Ở chế độ pac_script, cấu hình proxy được xác định bằng một tập lệnh PAC. Tập lệnh này được truy xuất từ URL được chỉ định trong đối tượng proxy.PacScript hoặc được lấy từ phần tử data được chỉ định trong đối tượng proxy.PacScript. Ngoài ra, chế độ này không cho phép thêm tham số trong đối tượng ProxyConfig.
fixed_servers
Ở chế độ fixed_servers, cấu hình proxy được mã hoá trong một đối tượng proxy.ProxyRules. Cấu trúc của cấu trúc này được mô tả trong phần Quy tắc proxy. Ngoài ra, chế độ fixed_servers không cho phép tham số nào khác trong đối tượng ProxyConfig.
system
Ở chế độ system, cấu hình proxy sẽ được lấy từ hệ điều hành. Chế độ này không cho phép tham số khác trong đối tượng ProxyConfig. Lưu ý rằng chế độ system khác với việc không đặt cấu hình proxy. Trong trường hợp sau, Chrome chỉ quay lại chế độ cài đặt hệ thống nếu không có tuỳ chọn dòng lệnh nào ảnh hưởng đến cấu hình proxy.

Quy tắc proxy

Đối tượng proxy.ProxyRules có thể chứa thuộc tính singleProxy hoặc tập hợp con của proxyForHttp, proxyForHttps, proxyForFtp và fallbackProxy.

Trong trường hợp đầu tiên, lưu lượng truy cập HTTP, HTTPS và FTP sẽ được xử lý qua máy chủ proxy đã chỉ định. Lưu lượng truy cập khác sẽ được gửi trực tiếp. Trong trường hợp sau, hành vi sẽ tinh vi hơn một chút: Nếu một máy chủ proxy được định cấu hình cho giao thức HTTP, HTTPS hoặc FTP, thì lưu lượng truy cập tương ứng sẽ được xử lý qua máy chủ được chỉ định. Nếu không có máy chủ proxy nào như vậy được chỉ định hoặc lưu lượng truy cập sử dụng một giao thức khác với HTTP, HTTPS hoặc FTP, thì fallbackProxy sẽ được sử dụng. Nếu bạn không chỉ định fallbackProxy, thì lưu lượng truy cập sẽ được gửi trực tiếp mà không cần máy chủ proxy.

Đối tượng máy chủ proxy

Máy chủ proxy được định cấu hình trong đối tượng proxy.ProxyServer. Kết nối đến máy chủ proxy (do thuộc tính host xác định) sử dụng giao thức được xác định trong thuộc tính scheme. Nếu không có scheme được chỉ định, kết nối proxy sẽ mặc định là http.

Nếu không có port nào được xác định trong đối tượng proxy.ProxyServer, thì cổng sẽ được lấy từ lược đồ. Các cổng mặc định là:

Lược đồCổng
http80
https443
socks41080
socks51080

Danh sách bỏ qua

Có thể loại trừ máy chủ riêng lẻ khỏi máy chủ proxy bằng bypassList. Danh sách này có thể chứa các mục sau:

[SCHEME://]HOST_PATTERN[:PORT]

So khớp tất cả tên máy chủ khớp với mẫu HOST_PATTERN. "." ở đầu được hiểu là "*.".

Ví dụ: "foobar.com", "*foobar.com", "*.foobar.com", "*foobar.com:99", "https://x.*.y.com:99".

MẫuKhớp vớiKhông khớp
".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]

So khớp các URL là giá trị cố định địa chỉ IP. Về mặt lý thuyết, trường hợp này tương tự như trường hợp đầu tiên, nhưng với các trường hợp đặc biệt để xử lý việc chuẩn hoá giá trị cố định IP. Ví dụ: việc so khớp trên "[0:0:0::1]" sẽ giống như việc so khớp trên "[::1]" vì quá trình chuẩn hoá IPv6 được thực hiện nội bộ.

Ví dụ: 127.0.1, [0:0::1], [::1]:80, https://[::1]:443

IP_LITERAL/PREFIX_LENGTH_IN_BITS

So khớp bất kỳ URL nào chứa giá trị cố định IP (IP_LITERAL) trong dải ô đã cho. Dải IP (PREFIX_LENGTH_IN_BITS) được chỉ định bằng ký hiệu CIDR.

Khớp với bất kỳ URL nào chứa giá trị cố định IP trong dải ô đã cho. Dải IP được chỉ định bằng ký hiệu CIDR. Ví dụ: "192.168.1.1/16", "fefe:13::abc/33"

<local>

Chuỗi giá trị cố định <local> khớp với các tên máy chủ đơn giản. Tên máy chủ đơn giản là tên không chứa dấu chấm và không phải là giá trị cố định IP. Ví dụ: example và localhost là các tên máy chủ đơn giản, trong khi example.com, example. và [::1] thì không.

Ví dụ: "<local>"

Ví dụ

Mã sau đây đặt proxy SOCKS 5 cho các kết nối HTTP đến tất cả máy chủ ngoại trừ foobar.com và sử dụng kết nối trực tiếp cho tất cả các giao thức khác. Chế độ cài đặt áp dụng cho cửa sổ thông thường và cửa sổ ẩn danh, vì cửa sổ ẩn danh kế thừa các chế độ cài đặt từ cửa sổ thông thường. Xem thêm tài liệu về API Loại.

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() {}
);

Đoạn mã sau đây đặt một tập lệnh PAC tuỳ chỉnh.

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() {}
);

Đoạn mã tiếp theo truy vấn các chế độ cài đặt proxy hiệu quả hiện tại. Chế độ cài đặt proxy hiệu quả có thể được xác định bằng một tiện ích khác hoặc bằng chính sách. Xem tài liệu về API Loại để biết thông tin chi tiết.

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

Xin lưu ý rằng đối tượng value được truyền đến set() không giống với đối tượng value được truyền vào hàm callback của get(). Phần tử thứ hai sẽ chứa phần tử rules.proxyForHttp.port.

Loại

Mode

Chrome 54 trở lên

Liệt kê

"direct"

"auto_detect"

"pac_script"

PacScript

Một đối tượng đang giữ thông tin tự động định cấu hình proxy. Không được để trống chính xác một trong các trường.

Thuộc tính

  • data

    chuỗi không bắt buộc

    Tập lệnh PAC.

  • bắt buộc

    boolean không bắt buộc

    Nếu đúng, tập lệnh PAC không hợp lệ sẽ ngăn ngăn xếp mạng quay trở lại kết nối trực tiếp. Giá trị mặc định là false.

  • url

    chuỗi không bắt buộc

    URL của tệp PAC sẽ được sử dụng.

ProxyConfig

Một đối tượng đóng gói cấu hình proxy hoàn chỉnh.

Thuộc tính

  • chế độ

    Chế độ

    'direct' = Không bao giờ sử dụng proxy 'auto_detect' = Tự động phát hiện các tùy chọn cài đặt proxy 'pac_script' = Sử dụng tập lệnh PAC đã chỉ định 'Fixed_servers' = Chỉ định máy chủ proxy theo cách thủ công 'system' = Sử dụng các tùy chọn cài đặt proxy hệ thống

  • pacScript

    PacScript không bắt buộc

    Tập lệnh cấu hình tự động proxy (PAC) cho cấu hình này. Dùng tuỳ chọn này cho chế độ "pac_script".

  • quy tắc

    ProxyRules không bắt buộc

    Các quy tắc proxy mô tả cấu hình này. Sử dụng thuộc tính này cho chế độ "Fixed_servers".

ProxyRules

Một đối tượng đóng gói bộ quy tắc proxy cho tất cả các giao thức. Sử dụng 'singleProxy' hoặc (một nhóm nhỏ) 'proxyForHttp', 'proxyForHttps', 'proxyForFtp' và 'fallbackProxy'.

Thuộc tính

  • bypassList

    string[] không bắt buộc

    Danh sách máy chủ cần kết nối mà không cần máy chủ proxy.

  • fallbackProxy

    ProxyServer không bắt buộc

    Máy chủ proxy được sử dụng cho mọi thứ khác hoặc nếu bất kỳ proxy cụ thể nào cho... chưa được chỉ định.

  • proxyForFtp

    ProxyServer không bắt buộc

    Máy chủ proxy được sử dụng cho các yêu cầu FTP.

  • proxyForHttp

    ProxyServer không bắt buộc

    Máy chủ proxy được sử dụng cho các yêu cầu HTTP.

  • proxyForHttps

    ProxyServer không bắt buộc

    Máy chủ proxy được sử dụng cho các yêu cầu HTTPS.

  • singleProxy

    ProxyServer không bắt buộc

    Máy chủ proxy được sử dụng cho tất cả các yêu cầu mỗi URL (tức là http, https và ftp).

ProxyServer

Một đối tượng đóng gói thông số của một máy chủ proxy.

Thuộc tính

  • người tổ chức

    string

    Tên máy chủ hoặc địa chỉ IP của máy chủ proxy. Tên máy chủ phải theo ASCII (ở định dạng Punycode). IDNA chưa được hỗ trợ.

  • cổng

    số không bắt buộc

    Cổng của máy chủ proxy. Mặc định là một cổng phụ thuộc vào lược đồ.

  • lược đồ

    Lược đồ không bắt buộc

    Lược đồ (giao thức) của chính máy chủ proxy. Giá trị mặc định là "http".

Scheme

Chrome 54 trở lên

Liệt kê

"http"

"https"

"quic"

"socks4"

"socks5"

Thuộc tính

settings

Chế độ cài đặt proxy sẽ được sử dụng. Giá trị của chế độ cài đặt này là một đối tượng ProxyConfig.

Loại

types.ChromeSetting<ProxyConfig>

Sự kiện

onProxyError

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

Thông báo về lỗi proxy.

Tham số

  • số gọi lại

    hàm

    Tham số callback sẽ có dạng như sau: 

    (details: object)=>void

    • chi tiết

      đối tượng

      • chi tiết

        string

        Thông tin bổ sung về lỗi này, chẳng hạn như lỗi thời gian chạy JavaScript.

      • error

        string

        Nội dung mô tả lỗi.

      • fatal

        boolean

        Nếu đúng, lỗi này đã nghiêm trọng và giao dịch mạng đã bị huỷ. Nếu không, kết nối trực tiếp sẽ được sử dụng.