Hướng dẫn gọi API của UpSnap từ máy tính, iPhone và Android

2025-10-25

UpSnap là ứng dụng mã nguồn mở giúp bạn điều khiển máy tính trong mạng nội bộ bằng Wake-on-LAN (WOL).
Chỉ với vài thao tác, bạn có thể bật, tắt hoặc khởi động lại máy tính từ xa.
Bài viết này hướng dẫn cách gọi API của UpSnap trên máy tính, iPhone và Android,
sử dụng HTTPie Desktop, HTTPie CLI, hoặc ứng dụng gửi API tương ứng trên di động.

💡 Lưu ý:

Trong bài viết, địa chỉ mặc định là http://localhost:8090 (chạy thử trên máy cá nhân).

Nếu triển khai UpSnap trong mạng LAN, hãy thay localhost bằng địa chỉ IP thực tế, ví dụ http://192.168.1.100:8090.

Khi điều khiển từ xa, bạn có thể sử dụng VPN hoặc reverse proxy (Nginx, Caddy, Cloudflare Tunnel, v.v.) và thay localhost bằng tên miền của bạn.

1. Giới thiệu về UpSnap API

UpSnap cung cấp REST API theo chuẩn HTTP, sử dụng dữ liệu JSON.
Thông qua API, bạn có thể:

Đăng nhập và nhận mã xác thực (JWT)
Liệt kê danh sách thiết bị
Bật, tắt hoặc khởi động lại máy tính
Gửi lệnh cho nhiều thiết bị cùng lúc

Sơ đồ luồng hoạt động của UpSnap API – Client gửi POST để đăng nhập và GET để bật, tắt hoặc khởi động lại máy qua UpSnap Server

Sơ đồ minh họa quá trình Client → UpSnap Server → Máy đích (Wake-on-LAN).
Người dùng gửi POST để đăng nhập và GET để điều khiển thiết bị qua API của UpSnap.

2. Tạo người dùng mới

Sau khi cài đặt, UpSnap mặc định chỉ có tài khoản quản trị (superuser).
Để sử dụng API an toàn hơn, bạn nên tạo người dùng thông thường có quyền hạn giới hạn.

Cách tạo người dùng trong giao diện quản trị

Mở trình duyệt và truy cập:
```
http://localhost:8090
```
Đăng nhập bằng tài khoản quản trị viên (superuser)
Ở góc trên bên trái, chọn Users (Người dùng)
Bên dưới danh sách, bạn sẽ thấy biểu mẫu “Create new user (Tạo người dùng mới)”
Nhập thông tin:
- Email: [email protected]
- Mật khẩu: matkhaucuatoi
Nhấn Add (Thêm) để tạo tài khoản.

⚠️ Không nên dùng tài khoản superuser cho thao tác điều khiển hàng ngày.
Hãy tạo người dùng riêng cho từng người để đảm bảo an toàn và dễ quản lý.

3. Phân quyền người dùng

Bạn có thể giới hạn quyền thao tác của từng người dùng để tăng cường bảo mật.
Trong giao diện Users, chọn người dùng cần chỉnh, sau đó vào phần Device permissions để bật hoặc tắt các quyền:

Read – Xem thông tin thiết bị
Update – Thay đổi cấu hình thiết bị
Delete – Xóa thiết bị
Power – Gửi lệnh bật, tắt, khởi động lại

👉 Nếu chỉ cần điều khiển từ xa, bạn nên chỉ bật quyền Power.

4. Đăng nhập và điều khiển thiết bị qua API

Để điều khiển thiết bị qua API của UpSnap, trước hết bạn cần đăng nhập để lấy mã xác thực (JWT token).
Sau đó, dùng mã này trong tiêu đề (HTTP header) của các yêu cầu (HTTP request) để bật, tắt hoặc khởi động lại máy tính từ xa.

🔍 Hiểu về phương thức GET và POST khi gọi API

Khi gửi yêu cầu đến API, có hai phương thức (HTTP request method) chính bạn cần nắm rõ:

POST – Dùng để gửi dữ liệu đến máy chủ, ví dụ: đăng nhập để nhận token.
GET – Dùng để lấy dữ liệu hoặc kích hoạt hành động, ví dụ: gửi lệnh bật/tắt thiết bị.

Hầu hết các công cụ gửi API (như HTTPie, cURL, Postman, hoặc ứng dụng di động)
đều cho phép bạn chọn phương thức và thêm tiêu đề khi gửi yêu cầu.

🔐 Đăng nhập và lấy mã xác thực

Loại tài khoản	Đường dẫn đăng nhập	Mô tả
Người dùng thường	`/api/collections/users/auth-with-password`	Dành cho tài khoản thông thường
Quản trị viên (superuser)	`/api/collections/_superusers/auth-with-password`	Dành cho người quản trị hệ thống

Chúng ta sử dụng người dùng thường để đăng nhập (sử dụng POST):

POST http://localhost:8090/api/collections/users/auth-with-password
Content-Type: application/json

{
  "identity": "nguoidung1",
  "password": "matkhaucuatoi"
}

Kết quả phản hồi:

{
  "token": "eyJhbGciOi...",
  "record": { "id": "abcd1234", "email": "[email protected]" }
}

Ghi nhớ mã xác thực ở phần token trả về để gửi kèm trong các yêu cầu điều khiển về sau:

<ma_xac_thuc> = eyJhbGciOi...

⚙️ Gửi yêu cầu điều khiển thiết bị

Sau khi đã có mã xác thực, bạn có thể gửi các yêu cầu điều khiển đến API của UpSnap.
Tất cả các yêu cầu này đều cần thêm tiêu đề xác thực:

Authorization: Bearer <ma_xac_thuc>

Các thao tác phổ biến:

Bật máy (Wake-on-LAN)

GET http://localhost:8090/api/upsnap/wake/<ma_thiet_bi>
Authorization: Bearer <ma_xac_thuc>

Tắt máy

GET http://localhost:8090/api/upsnap/shutdown/<ma_thiet_bi>
Authorization: Bearer <ma_xac_thuc>

Khởi động lại máy

GET http://localhost:8090/api/upsnap/reboot/<ma_thiet_bi>
Authorization: Bearer <ma_xac_thuc>

🧩 Ví dụ lệnh GET / POST trên các ứng dụng

🟦 HTTPie CLI

Cài đặt:

pipx install httpie

Đăng nhập (POST):

http POST http://localhost:8090/api/collections/users/auth-with-password \
  identity=nguoidung1 password=matkhaucuatoi

Bật máy (GET):

http GET http://localhost:8090/api/upsnap/wake/<ma_thiet_bi> \
  "Authorization: Bearer <ma_xac_thuc>"

🟦 HTTPie Desktop

Tạo Draft Request
Chọn phương thức POST hoặc GET
Khi đăng nhập, thêm Body -> Text -> JSON: {"identity": "nguoidung1", "password": "matkhaucuatoi" }
Khi điều khiển thiết bị, thêm Auth -> Bearer token: <ma_xac_thuc>
Nhấn Send để gửi yêu cầu.

Đăng nhập để lấy token bằng POST request

Gửi yêu cầu bật máy bằng GET request

🟩 HTTP Request Shortcuts (Android)

Tạo Shortcut mới.
Chọn POST để đăng nhập hoặc GET để bật máy.
Nhập URL API.
Khi đăng nhập thêm header JSON: {"identity": "nguoidung1", "password": "matkhaucuatoi" }
Khi điều khiển thiết bị, bật Bearer Authentication và dán token vào ô Token.

🟦 Phím tắt (Shortcuts – iPhone)

Tạo Phím tắt mới → thêm hành động Lấy nội dung từ URL
Chọn Phương thức: POST (đăng nhập) hoặc GET (bật/tắt máy).
Khi gửi POST, chọn Yêu cầu dạng JSON và nhập thông tin đăng nhập:
```
{"identity": "nguoidung1", "password": "matkhaucuatoi" }
```

Khi gửi GET thêm Header:

Key: Authorization
Value: Bearer <ma_xac_thuc>

Nhấn Chạy (Run) để xem kết quả phản hồi.
📱 Bạn có thể lưu phím tắt này và kích hoạt bằng Siri để bật/tắt máy chỉ bằng giọng nói.

💡 Lưu ý:

Các yêu cầu GET dùng cho hành động như bật, tắt, khởi động lại.

Các yêu cầu POST dùng để đăng nhập hoặc gửi dữ liệu.

Wake-on-LAN chỉ hoạt động khi thiết bị điều khiển và máy đích cùng mạng LAN hoặc Wi-Fi.

Khi điều khiển qua Internet, hãy dùng VPN hoặc reverse proxy để bảo mật kết nối.

Đảm bảo Wake on Magic Packet đã được bật trong BIOS hoặc driver mạng của máy đích.

5. 📘 Tóm tắt nhanh (TL;DR)

1️⃣ Đăng nhập để lấy token

POST http://localhost:8090/api/collections/users/auth-with-password \
  identity=nguoidung1 password=matkhaucuatoi

2️⃣ Bật máy tính từ xa

GET http://localhost:8090/api/upsnap/wake/<ma_thiet_bi> \
  "Authorization: Bearer <ma_xac_thuc>"

3️⃣ Tắt máy tính từ xa

GET http://localhost:8090/api/upsnap/shutdown/<ma_thiet_bi> \
  "Authorization: Bearer <ma_xac_thuc>"

🔑 Chỉ cần 3 lệnh trên — bạn có thể đăng nhập, bật hoặc tắt máy tính từ xa bằng API của UpSnap.

6. Tài liệu tham khảo

👉 UpSnap Wiki – REST API Documentation
https://github.com/seriousm4x/UpSnap/wiki/Rest-API

👉 Xem thêm: UpSnap - Wake-on-LAN tắt mở máy tính từ xa trong mạng nội bộ

#UpSnap #API #Wake on LAN #HTTPie Desktop #Android #iPhone #Điều khiển máy tính từ xa

← Create a Password Hash