Tích hợp proxy với khách hàng REST API: cấu hình Postman, Insomnia, cURL và HTTPie

Khi phát triển và kiểm tra API, thường có nhu cầu gửi yêu cầu qua các máy chủ proxy. Điều này có thể cần thiết để vượt qua các hạn chế địa lý, kiểm tra hành vi của API từ các khu vực khác nhau, đảm bảo tính ẩn danh hoặc làm việc với các dịch vụ chặn IP của các trung tâm dữ liệu. Trong hướng dẫn này, chúng ta sẽ xem xét cách cấu hình proxy đúng cách trong các khách hàng REST API phổ biến và tránh những lỗi thường gặp.

Chúng ta sẽ xem xét bốn công cụ phổ biến nhất để làm việc với API: Postman (giao diện đồ họa cho hầu hết các nhà phát triển), Insomnia (thay thế hiện đại với giao diện người dùng thân thiện), cURL (công cụ dòng lệnh cổ điển) và HTTPie (khách hàng CLI hiện đại với cú pháp dễ đọc). Đối với từng công cụ, chúng tôi sẽ cung cấp ví dụ mã và xem xét các đặc điểm cấu hình.

Các loại proxy nào phù hợp để làm việc với API

Trước khi cấu hình proxy trong các khách hàng API, điều quan trọng là phải hiểu loại proxy nào phù hợp với nhiệm vụ của bạn. Các khách hàng REST API hỗ trợ hai giao thức chính: HTTP/HTTPS và SOCKS5. Sự lựa chọn phụ thuộc vào yêu cầu của API cụ thể và mức độ bảo mật mà bạn cần.

Proxy HTTP/HTTPS hoạt động ở cấp độ giao thức HTTP và rất phù hợp cho hầu hết các yêu cầu REST API. Chúng hiểu cấu trúc lưu lượng HTTP, có thể lưu trữ các phản hồi và sửa đổi các tiêu đề. Proxy HTTPS thêm mã hóa kết nối giữa khách hàng và máy chủ proxy, điều này quan trọng khi truyền tải dữ liệu nhạy cảm như khóa API hoặc mã thông báo xác thực.

Proxy SOCKS5 hoạt động ở cấp độ thấp hơn và truyền tải bất kỳ loại lưu lượng nào mà không sửa đổi. Chúng chậm hơn proxy HTTP nhưng cung cấp tính ẩn danh tốt hơn và phù hợp cho các trường hợp khi API sử dụng các giao thức không chuẩn hoặc yêu cầu tính minh bạch hoàn toàn của kết nối. SOCKS5 cũng hỗ trợ lưu lượng UDP, mặc dù điều này hiếm khi cần thiết cho REST API.

Cấu hình proxy trong Postman: cài đặt toàn cầu và cục bộ

Postman là công cụ đồ họa phổ biến nhất để làm việc với REST API, được sử dụng bởi hàng triệu nhà phát triển. Nó hỗ trợ hai cách cấu hình proxy: cài đặt toàn cầu (áp dụng cho tất cả các yêu cầu) và cài đặt ở mức môi trường (environment). Chúng ta sẽ xem xét cả hai tùy chọn một cách chi tiết.

Cài đặt toàn cầu proxy trong Postman

Các cài đặt toàn cầu proxy nằm trong menu Cài đặt (biểu tượng bánh răng ở góc trên bên phải). Cách này thuận tiện khi bạn muốn tất cả các yêu cầu từ Postman luôn đi qua cùng một máy chủ proxy. Hướng dẫn từng bước:

1. Mở Postman và nhấp vào biểu tượng bánh răng (Cài đặt) ở góc trên bên phải
2. Chuyển đến tab "Proxy"
3. Bật tùy chọn "Thêm cấu hình proxy tùy chỉnh"
4. Chọn loại proxy: HTTP, HTTPS hoặc SOCKS5
5. Nhập địa chỉ máy chủ proxy (ví dụ: proxy.example.com)
6. Chỉ định cổng (thường là 8080 cho HTTP, 1080 cho SOCKS5)
7. Nếu proxy yêu cầu xác thực, hãy bật "Proxy Auth" và nhập tên đăng nhập/mật khẩu
8. Nhấn "Lưu" và đóng cửa sổ cài đặt

Sau đó, tất cả các yêu cầu từ Postman sẽ tự động đi qua proxy đã chỉ định. Một đặc điểm quan trọng: Postman cũng gửi telemetry và kiểm tra các bản cập nhật qua proxy, điều này có thể tạo ra lưu lượng bổ sung. Nếu bạn đang sử dụng proxy với lưu lượng hạn chế, điều này cần được xem xét.

Cấu hình proxy qua biến môi trường

Một cách linh hoạt hơn là sử dụng các biến môi trường (Environments). Điều này cho phép bạn nhanh chóng chuyển đổi giữa các proxy khác nhau cho các dự án hoặc API khác nhau. Tạo một môi trường mới và thêm các biến sau:

PROXY_HOST = proxy.example.com
PROXY_PORT = 8080
PROXY_USER = your_username
PROXY_PASS = your_password

Sau đó, trong các cài đặt toàn cầu proxy, hãy sử dụng các biến này thay vì các giá trị cụ thể: {{PROXY_HOST}} và {{PROXY_PORT}}. Bây giờ bạn có thể tạo nhiều môi trường (ví dụ: "Proxy Sản xuất", "Proxy Kiểm tra", "Proxy Mỹ") và chuyển đổi giữa chúng chỉ bằng một cú nhấp chuột.

Sử dụng proxy hệ thống

Postman cũng có thể sử dụng các cài đặt proxy hệ thống của hệ điều hành của bạn. Để làm điều này, trong cài đặt Proxy, hãy chọn tùy chọn "Sử dụng Proxy Hệ thống". Điều này thuận tiện nếu bạn đã cấu hình proxy ở cấp độ hệ điều hành (ví dụ: qua cài đặt Windows hoặc macOS) và muốn Postman sử dụng cùng một cài đặt như trình duyệt.

Cấu hình proxy trong Insomnia

Insomnia là một thay thế hiện đại cho Postman với giao diện sạch sẽ và mã nguồn mở. Cấu hình proxy trong Insomnia hơi khác so với Postman và yêu cầu chỉnh sửa tệp cấu hình hoặc sử dụng các biến môi trường. Chúng ta sẽ xem xét cả hai cách.

Cấu hình qua biến môi trường

Cách đơn giản nhất để cấu hình proxy trong Insomnia là sử dụng các biến môi trường tiêu chuẩn HTTP_PROXY và HTTPS_PROXY. Insomnia tự động đọc các biến này từ hệ thống. Đặt chúng trước khi khởi động Insomnia:

Linux/macOS:

export HTTP_PROXY="http://username:password@proxy.example.com:8080"
export HTTPS_PROXY="http://username:password@proxy.example.com:8080"
insomnia

Windows (PowerShell):

$env:HTTP_PROXY = "http://username:password@proxy.example.com:8080"
$env:HTTPS_PROXY = "http://username:password@proxy.example.com:8080"
insomnia

Lưu ý về định dạng URL: ngay cả đối với proxy HTTPS, sử dụng sơ đồ http://, không phải https://. Đây là quy ước tiêu chuẩn cho các biến môi trường proxy. Nếu proxy không yêu cầu xác thực, URL sẽ ngắn hơn: http://proxy.example.com:8080.

Cấu hình proxy SOCKS5

Đối với proxy SOCKS5, hãy sử dụng biến môi trường ALL_PROXY:

export ALL_PROXY="socks5://username:password@proxy.example.com:1080"

Insomnia hỗ trợ SOCKS5, nhưng không phải tất cả các phiên bản đều xử lý xác thực SOCKS5 một cách chính xác. Nếu bạn gặp sự cố với SOCKS5 đã xác thực, hãy thử sử dụng proxy HTTP hoặc nâng cấp Insomnia lên phiên bản mới nhất.

Cấu hình qua tệp cấu hình

Để cấu hình proxy vĩnh viễn, bạn có thể chỉnh sửa tệp cấu hình của Insomnia. Vị trí của tệp phụ thuộc vào hệ điều hành:

• Windows: %APPDATA%\Insomnia\config.json
• macOS: ~/Library/Application Support/Insomnia/config.json
• Linux: ~/.config/Insomnia/config.json

Mở tệp trong trình soạn thảo văn bản và thêm phần proxy:

{
  "proxy": {
    "http": "http://username:password@proxy.example.com:8080",
    "https": "http://username:password@proxy.example.com:8080"
  }
}

Sau khi chỉnh sửa, hãy khởi động lại Insomnia. Các cài đặt proxy sẽ tự động áp dụng cho tất cả các yêu cầu.

Sử dụng proxy trong cURL: ví dụ lệnh

cURL là công cụ dòng lệnh cổ điển để làm việc với HTTP, được cài đặt trên hầu hết các hệ thống tương tự Unix và Windows 10+. Nó hỗ trợ proxy thông qua tham số -x hoặc --proxy. Chúng ta sẽ xem xét các kịch bản sử dụng khác nhau.

Sử dụng cơ bản proxy HTTP

Ví dụ đơn giản nhất về việc sử dụng proxy HTTP mà không cần xác thực:

curl -x http://proxy.example.com:8080 https://api.example.com/users

Tham số -x chỉ định địa chỉ và cổng của máy chủ proxy. cURL sẽ tự động xác định rằng đây là proxy HTTP và cấu hình kết nối. Nếu bạn muốn chỉ định rõ ràng giao thức, hãy sử dụng URL đầy đủ:

curl --proxy http://proxy.example.com:8080 https://api.example.com/users

Proxy có xác thực

Nếu proxy yêu cầu xác thực bằng tên đăng nhập và mật khẩu, hãy thêm chúng vào URL của proxy hoặc sử dụng tham số -U:

# Cách 1: tên đăng nhập và mật khẩu trong URL
curl -x http://username:password@proxy.example.com:8080 https://api.example.com/users

# Cách 2: tham số -U (an toàn hơn, không lưu trong lịch sử lệnh)
curl -x http://proxy.example.com:8080 -U username:password https://api.example.com/users

Cách thứ hai là ưu tiên, vì tên đăng nhập và mật khẩu sẽ không bị lưu trong lịch sử lệnh shell. Để tăng cường bảo mật, bạn có thể chỉ định tên đăng nhập, và cURL sẽ yêu cầu mật khẩu một cách tương tác:

curl -x http://proxy.example.com:8080 -U username https://api.example.com/users
# cURL sẽ yêu cầu mật khẩu: Nhập mật khẩu proxy cho người dùng 'username':

Sử dụng proxy SOCKS5

Đối với proxy SOCKS5, hãy chỉ định rõ ràng giao thức trong URL:

# SOCKS5 không có xác thực
curl -x socks5://proxy.example.com:1080 https://api.example.com/users

# SOCKS5 có xác thực
curl -x socks5://username:password@proxy.example.com:1080 https://api.example.com/users

# SOCKS5h (giải quyết DNS qua proxy)
curl -x socks5h://proxy.example.com:1080 https://api.example.com/users

Sự khác biệt giữa socks5:// và socks5h://: trong trường hợp đầu tiên, giải quyết DNS xảy ra cục bộ (trên máy của bạn), trong trường hợp thứ hai — qua máy chủ proxy. Sử dụng socks5h:// nếu bạn muốn hoàn toàn ẩn các yêu cầu DNS khỏi nhà cung cấp của bạn.

Yêu cầu POST qua proxy

Proxy hoạt động giống nhau cho tất cả các phương thức HTTP. Ví dụ về yêu cầu POST với dữ liệu JSON qua proxy:

curl -x http://proxy.example.com:8080 \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"name":"John","email":"john@example.com"}' \
  https://api.example.com/users

Để gửi tệp, hãy sử dụng tham số -F:

curl -x http://proxy.example.com:8080 \
  -X POST \
  -F "file=@document.pdf" \
  -F "description=Important document" \
  https://api.example.com/upload

Sử dụng biến môi trường

Thay vì chỉ định proxy trong mỗi lệnh, bạn có thể sử dụng các biến môi trường. cURL tự động đọc http_proxy, https_proxy và all_proxy:

# Đặt các biến môi trường
export http_proxy="http://username:password@proxy.example.com:8080"
export https_proxy="http://username:password@proxy.example.com:8080"

# Bây giờ tất cả các lệnh cURL sẽ tự động sử dụng proxy
curl https://api.example.com/users

# Tắt proxy cho một lệnh cụ thể
curl --noproxy "*" https://api.example.com/users

Tham số --noproxy cho phép loại trừ các miền cụ thể khỏi việc sử dụng proxy. Ví dụ, để không sử dụng proxy cho localhost và các miền nội bộ:

export no_proxy="localhost,127.0.0.1,.internal.company.com"

Cấu hình proxy trong HTTPie

HTTPie là một thay thế hiện đại cho cURL với cú pháp dễ đọc và đầu ra màu. Nó đặc biệt thuận tiện cho việc tương tác với API trong terminal. HTTPie hỗ trợ proxy thông qua tham số --proxy hoặc các biến môi trường.

Sử dụng cơ bản proxy

Cú pháp HTTPie cho proxy hơi khác so với cURL. Bạn cần chỉ định giao thức và URL của proxy riêng biệt:

# Proxy HTTP
http --proxy=http:http://proxy.example.com:8080 \
     --proxy=https:http://proxy.example.com:8080 \
     GET https://api.example.com/users

# Dạng rút gọn (nếu proxy giống nhau cho HTTP và HTTPS)
http --proxy=all:http://proxy.example.com:8080 GET https://api.example.com/users

Định dạng: --proxy=protocol:proxy_url. Đối với các yêu cầu HTTPS, thường sử dụng proxy HTTP (không phải HTTPS), đây là hành vi tiêu chuẩn.

Proxy có xác thực

Để xác thực, hãy thêm tên đăng nhập và mật khẩu vào URL của proxy:

http --proxy=all:http://username:password@proxy.example.com:8080 \
     GET https://api.example.com/users

HTTPie cũng hỗ trợ tham số --proxy-auth để chỉ định rõ ràng thông tin xác thực, nhưng trong các phiên bản gần đây, tham số này được coi là lỗi thời, và khuyến nghị là bao gồm xác thực trong URL.

Proxy SOCKS5 trong HTTPie

HTTPie hỗ trợ proxy SOCKS5 bắt đầu từ phiên bản 2.0.0. Hãy đảm bảo rằng bạn đã cài đặt phiên bản mới nhất:

# Kiểm tra phiên bản HTTPie
http --version

# Cập nhật HTTPie qua pip
pip install --upgrade httpie

# Sử dụng proxy SOCKS5
http --proxy=all:socks5://proxy.example.com:1080 GET https://api.example.com/users

Đối với SOCKS5 có xác thực, bạn sẽ cần cài đặt thư viện bổ sung pysocks:

pip install pysocks
http --proxy=all:socks5://username:password@proxy.example.com:1080 \
     GET https://api.example.com/users

Yêu cầu POST và gửi dữ liệu

HTTPie có cú pháp thuận tiện cho các yêu cầu POST. Ví dụ gửi JSON qua proxy:

# POST với JSON (HTTPie tự động xác định Content-Type)
http --proxy=all:http://proxy.example.com:8080 \
     POST https://api.example.com/users \
     name="John Doe" \
     email="john@example.com" \
     age:=30

# Gửi tệp
http --proxy=all:http://proxy.example.com:8080 \
     POST https://api.example.com/upload \
     file@document.pdf \
     description="Important document"

Lưu ý về cú pháp: key=value cho chuỗi, key:=value cho số và giá trị boolean, key@file cho tệp.

Sử dụng biến môi trường

Giống như cURL, HTTPie đọc các biến môi trường tiêu chuẩn http_proxy và https_proxy:

export http_proxy="http://username:password@proxy.example.com:8080"
export https_proxy="http://username:password@proxy.example.com:8080"

# Bây giờ tất cả các lệnh tự động sử dụng proxy
http GET https://api.example.com/users

Để tạm thời tắt proxy, hãy sử dụng tham số --proxy= (giá trị trống):

http --proxy= GET https://api.example.com/users

Xác thực proxy: tên đăng nhập và mật khẩu

Hầu hết các dịch vụ proxy thương mại yêu cầu xác thực để bảo vệ khỏi việc sử dụng trái phép. Có hai phương pháp xác thực chính: Xác thực Cơ bản (tên đăng nhập/mật khẩu) và Danh sách trắng IP (ràng buộc theo địa chỉ IP). Chúng ta sẽ xem xét các đặc điểm của mỗi phương pháp và cách cấu hình chúng đúng cách trong các khách hàng API.

Xác thực Cơ bản (tên đăng nhập và mật khẩu)

Xác thực Cơ bản là phương pháp phổ biến nhất. Máy chủ proxy yêu cầu tên đăng nhập và mật khẩu mỗi khi kết nối. Thông tin xác thực được truyền trong tiêu đề Proxy-Authorization ở định dạng Base64. Tất cả các khách hàng API hiện đại tự động tạo tiêu đề này nếu bạn chỉ định tên đăng nhập và mật khẩu trong URL proxy.

Định dạng URL với xác thực:

protocol://username:password@proxy_host:proxy_port

Ví dụ cho các giao thức khác nhau:

# Proxy HTTP
http://user123:pass456@proxy.example.com:8080

# Proxy HTTPS (sử dụng cùng một định dạng)
http://user123:pass456@proxy.example.com:8080

# Proxy SOCKS5
socks5://user123:pass456@proxy.example.com:1080

Danh sách trắng IP (ràng buộc theo IP)

Một số nhà cung cấp proxy cung cấp xác thực theo địa chỉ IP. Trong trường hợp này, bạn thêm IP của mình vào danh sách trắng trong bảng điều khiển proxy, và máy chủ chỉ cho phép kết nối từ IP đó mà không cần tên đăng nhập và mật khẩu. Điều này thuận tiện hơn và an toàn hơn, vì không cần truyền thông tin xác thực trong mỗi yêu cầu.

Khi sử dụng danh sách trắng IP, định dạng URL proxy đơn giản hơn:

# Không có tên đăng nhập và mật khẩu
http://proxy.example.com:8080

# Ví dụ trong cURL
curl -x http://proxy.example.com:8080 https://api.example.com/users

Nhược điểm của phương pháp này là nếu IP của bạn là động (thay đổi khi kết nối lại với internet), bạn sẽ phải cập nhật danh sách trắng mỗi lần. Đối với các máy chủ có IP tĩnh, đây là lựa chọn lý tưởng.

Ký tự đặc biệt trong mật khẩu

Nếu mật khẩu proxy chứa các ký tự đặc biệt (@, :, /, ?), chúng cần được mã hóa theo định dạng mã hóa URL (percent encoding). Ví dụ:

Ví dụ về việc sử dụng mật khẩu với ký tự đặc biệt:

# Mật khẩu gốc: P@ss:w0rd/123
# Mật khẩu đã mã hóa: P%40ss%3Aw0rd%2F123

curl -x http://username:P%40ss%3Aw0rd%2F123@proxy.example.com:8080 \
     https://api.example.com/users

Để tự động mã hóa, bạn có thể sử dụng các công cụ trực tuyến mã hóa URL hoặc lệnh trong Python:

python3 -c "import urllib.parse; print(urllib.parse.quote('P@ss:w0rd/123'))"
# Đầu ra: P%40ss%3Aw0rd%2F123

Giải quyết các vấn đề và lỗi thường gặp

Khi làm việc với proxy trong các khách hàng API, thường xảy ra các lỗi phổ biến. Chúng ta sẽ xem xét những vấn đề thường gặp nhất và cách giải quyết chúng.

Lỗi "407 Proxy Authentication Required"

Lỗi này có nghĩa là máy chủ proxy yêu cầu xác thực, nhưng thông tin xác thực không được cung cấp hoặc không chính xác. Các giải pháp:

• Kiểm tra tính chính xác của tên đăng nhập và mật khẩu trong bảng điều khiển của nhà cung cấp proxy
• Đảm bảo rằng các ký tự đặc biệt trong mật khẩu đã được mã hóa (xem phần trên)
• Kiểm tra định dạng URL: http://username:password@host:port
• Nếu sử dụng danh sách trắng IP, hãy đảm bảo rằng IP hiện tại của bạn đã được thêm vào danh sách trắng

Ví dụ về chẩn đoán trong cURL với đầu ra chi tiết:

curl -v -x http://username:password@proxy.example.com:8080 https://api.example.com/users
# Cờ -v (verbose) sẽ hiển thị tất cả các tiêu đề và quá trình xác thực

Lỗi "Connection timeout" hoặc "Failed to connect"

Lỗi này xảy ra khi khách hàng API không thể thiết lập kết nối với máy chủ proxy. Các nguyên nhân có thể:

• Địa chỉ hoặc cổng của máy chủ proxy không chính xác — kiểm tra cài đặt với nhà cung cấp
• Máy chủ proxy không khả dụng hoặc quá tải — hãy thử một máy chủ khác trong danh sách
• Tường lửa của bạn đang chặn các kết nối ra ngoài đến cổng proxy
• Nhà cung cấp proxy đã chặn IP của bạn vì vượt quá giới hạn

Để chẩn đoán, hãy thử kết nối trực tiếp đến proxy qua telnet hoặc nc:

# Kiểm tra khả năng truy cập proxy
telnet proxy.example.com 8080
# hoặc
nc -zv proxy.example.com 8080

# Nếu không thể thiết lập kết nối, vấn đề nằm ở mạng hoặc máy chủ proxy không khả dụng

Lỗi "SSL certificate problem"

Khi sử dụng proxy HTTPS, có thể xảy ra vấn đề với việc kiểm tra chứng chỉ SSL. Điều này đặc biệt đúng với các proxy MITM (Man-in-the-Middle), những người chặn và giải mã lưu lượng HTTPS. Các giải pháp:

• Trong cURL, sử dụng cờ -k hoặc --insecure để tắt kiểm tra chứng chỉ (chỉ để thử nghiệm!)
• Trong Postman, tắt "Xác minh chứng chỉ SSL" trong Cài đặt → Chung
• Cài đặt chứng chỉ gốc của proxy vào hệ thống (cho môi trường sản xuất)

# Tắt kiểm tra chứng chỉ SSL
curl -k -x http://username:password@proxy.example.com:8080 https://api.example.com/users