REST API & công cụ CLI

Làm chủ REST API của VergeOS, script trợ giúp yb-api và vrg CLI cho quản lý hạ tầng theo chương trình và tự động hóa.

Mọi thao tác bạn thực hiện trong giao diện VergeOS đều ánh xạ trực tiếp thành một lời gọi REST API. Điều này thiết kế ưu tiên API có nghĩa là bất cứ thứ gì bạn có thể nhấp trong bảng điều khiển — tạo VM, cấu hình mạng, quản lý tenant — đều có thể được tự động hóa thông qua các điểm cuối HTTP. Phần này bao gồm ba giao diện chính để truy cập theo chương trình: REST API bản thân, script trợ giúp yb-api để tự động hóa trên máy cục bộ, và CLI vrg để quản lý từ xa.

Tổng quan REST API

API VergeOS tuân theo các quy ước REST tiêu chuẩn với các payload JSON, hỗ trợ toàn bộ vòng đời của mọi tài nguyên trong nền tảng.

Các phương thức HTTP

Phương thức

Mục đích

Ví dụ

GET

Truy xuất tài nguyên

GET /api/v4/vms?fields=most

POST

Tạo tài nguyên hoặc kích hoạt hành động

POST /api/v4/vms

PUT

Cập nhật tài nguyên hiện có

PUT /api/v4/vms/36

DELETE

Xóa tài nguyên

DELETE /api/v4/vms/36

Tham số truy vấn

Mọi yêu cầu GET đều hỗ trợ lọc và chọn trường theo kiểu OData:

các trường — Chỉ định những trường cần trả về (ví dụ, fields=name,$key,ram hoặc fields=most cho tất cả các trường thông dụng)
filter — Biểu thức lọc kiểu OData (ví dụ, filter=is_snapshot eq false)
sort — Sắp xếp kết quả theo trường (ví dụ, sort=name)
limit / offset — Điều khiển phân trang cho các tập kết quả lớn

Định dạng dữ liệu

Tất cả phản hồi API đều được trả về ở định dạng JSON. Phần thân yêu cầu cho các thao tác POST và PUT cũng phải là JSON với tiêu đề Content-Type: application/json .

Giới hạn tốc độ

API hỗ trợ tối đa 1.000 yêu cầu mỗi giờ cho mỗi khóa API. Với tự động hóa khối lượng lớn, hãy gom lô khi có thể và triển khai logic thử lại với backoff theo cấp số nhân.

Xác thực

VergeOS hỗ trợ hai phương thức xác thực — xác thực HTTP Basic và xác thực dựa trên token — mỗi phương thức phù hợp với các trường hợp sử dụng khác nhau. Khóa API dài hạn là một biến thể của phương thức token, được trình bày dưới dạng Bearer token thay vì token phiên:

1. Xác thực HTTP Basic

Phương thức đơn giản nhất — truyền trực tiếp thông tin xác thực với mỗi yêu cầu. Mọi lưu lượng API đều yêu cầu HTTPS.

curl -X GET "https://vergeos.example.com/api/v4/vms?fields=most" \
  --basic --user "admin:password" \
  -H "Accept: application/json"

2. Xác thực dựa trên token (Token phiên)

Yêu cầu token phiên bằng cách POST thông tin xác thực tới /sys/tokens. Sử dụng token trả về trong các yêu cầu tiếp theo thông qua tiêu đề x-yottabyte-token tiêu đề:

# Bước 1: Lấy token
curl --basic \
  --data-ascii '{"login": "admin", "password": "secret"}' \
  --request "POST" \
  --header "Content-Type: application/json" \
  "https://vergeos.example.com/api/sys/tokens"

# Phản hồi bao gồm khóa token:
# {"location":"/sys/tokens/3a334...","$key":"3a334..."}

# Bước 2: Sử dụng token trong các yêu cầu tiếp theo
curl -X GET "https://vergeos.example.com/api/v4/vms?fields=most" \
  -H "x-yottabyte-token: 3a334..." \
  -H "Accept: application/json"

# Bước 3: Đăng xuất khi hoàn tất
curl -X DELETE "https://vergeos.example.com/api/sys/tokens/3a334..."

Biến thể Bearer-Token: khóa API dài hạn

Đối với tự động hóa trong môi trường sản xuất, hãy tạo các khóa API bền vững thông qua System → Users → [User] → API Keys. Các khóa này là một biến thể Bearer-token của xác thực token — chúng hoạt động như Bearer token và vẫn hợp lệ cho đến khi hết hạn hoặc bị xóa:

curl -X GET "https://vergeos.example.com/api/v4/vms?fields=most" \
  -H "Authorization: Bearer your-api-key-string" \
  -H "Content-Type: application/json"

Khóa API hỗ trợ danh sách cho phép/từ chối IP để bảo mật và có thể cấu hình ngày hết hạn. Hãy lưu chúng trong biến môi trường thay vì mã hóa cứng:

export VERGEOS_API_KEY="your-api-key-string"
curl -X GET "https://vergeos.example.com/api/v4/system" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}"

Khóa API chỉ được hiển thị một lần tại thời điểm tạo. Nếu bị mất, bạn phải xóa khóa đó và tạo khóa mới.

API Explorer (Swagger)

VergeOS bao gồm sẵn một trang tài liệu Swagger được tạo động từ hệ thống đang chạy, hiển thị mọi bảng và thao tác hiện có.

Để truy cập:

Đăng nhập vào giao diện VergeOS
Đi tới Hệ thống → Tài liệu API
Duyệt các điểm cuối khả dụng, xem schema và kiểm thử các lời gọi API trực tiếp

Giao diện Swagger cho phép bạn thực thi các lời gọi API ngay trong trình duyệt và xem curl lệnh, phần thân phản hồi và các tiêu đề — khiến nó trở thành một công cụ tuyệt vời để tạo mẫu các script tự động hóa.

Các điểm cuối API chính

API tổ chức các tài nguyên thành các bảng. Dưới đây là những điểm cuối được dùng phổ biến nhất:

Điểm cuối

Mục đích

/api/v4/vms

Các thao tác CRUD máy ảo

/api/v4/vm_actions

Các thao tác nguồn máy ảo, clone, snapshot

/api/v4/machine_drives

Gắn/kết nối và quản lý ổ đĩa lưu trữ VM

/api/v4/machine_nics

Cấu hình giao diện mạng của VM

/api/v4/machine_devices

Passthrough thiết bị GPU/PCI

/api/v4/machine_status/{id}

Trạng thái nguồn và trạng thái lúc chạy

/api/v4/vnets

Quản lý mạng ảo

/api/v4/vnet_rules

Quy tắc tường lửa và NAT

/api/v4/tenants

Quản lý tenant (VDC)

/api/v4/nodes

Thông tin nút vật lý

/api/v4/clusters

Cấu hình cụm

/api/sys/tokens

Quản lý token phiên

Kiểm tra schema

Thêm hậu tố /$table vào bất kỳ điểm cuối nào để truy xuất toàn bộ schema cơ sở dữ liệu của nó, bao gồm tất cả các trường và kiểu khả dụng:

# Lấy schema của bảng VM
curl -X GET "https://vergeos.example.com/api/v4/vms/\$table" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}"

Hướng dẫn API vòng đời VM

Quy trình tự động hóa phổ biến nhất là cấp phát một VM hoàn chỉnh thông qua API. Quy trình bốn bước này phản ánh những gì giao diện người dùng thực hiện ở phía sau:

Bước 1: Tạo VM

curl -X POST "https://vergeos.example.com/api/v4/vms" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-server-01",
    "description": "Máy chủ web sản xuất",
    "machine_type": "pc-q35-9.0",
    "cpu_cores": 4,
    "cpu_type": "Cascadelake-Server",
    "ram": 8192,
    "os_family": "linux",
    "boot_order": "cd",
    "uefi": true,
    "allow_hotplug": true
  }'

# Phản hồi: {"location":"/v4/vms/42","$key":"42"}

Bước 2: Thêm ổ đĩa lưu trữ

curl -X POST "https://vergeos.example.com/api/v4/machine_drives" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "machine": 42,
    "name": "boot-disk",
    "media": "disk",
    "interface": "virtio-scsi",
    "disksize": 107374182400,
    "preferred_tier": "1"
  }'

Bước 3: Thêm giao diện mạng

curl -X POST "https://vergeos.example.com/api/v4/machine_nics" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "machine": 42,
    "vnet": 6,
    "interface": "virtio"
  }'

Bước 4: Bật nguồn

curl -X POST "https://vergeos.example.com/api/v4/vm_actions" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "vm": 42,
    "action": "poweron"
  }'

Các hành động bổ sung

Khi VM đã tồn tại, bạn có thể kích hoạt các thao tác nâng cao thông qua cùng một vm_actions điểm cuối:

# Nhân bản VM
curl -X POST ".../api/v4/vm_actions" \
  -d '{"vm": 42, "action": "clone", "params": {"name": "web-server-clone", "quiesce": "true"}}'

# Chụp snapshot
curl -X POST ".../api/v4/vm_actions" \
  -d '{"vm": 42, "action": "snapshot", "params": {"name": "pre-upgrade"}}'

# Tắt nguồn một cách an toàn
curl -X POST ".../api/v4/vm_actions" \
  -d '{"vm": 42, "action": "poweroff"}'

Script trợ giúp yb-api

Tính năng yb-api script là một bộ bao bọc dòng lệnh tích hợp sẵn, có trên mọi nút VergeOS qua SSH. Nó đơn giản hóa các lời gọi API bằng cách xử lý xác thực, tiêu đề, dựng URL, mã hóa truy vấn và xử lý tải lên cho bạn.

Cú pháp cơ bản

yb-api --get|--post|--put|--delete [options] /v4/<endpoint>

Tùy chọn phổ biến

Cờ

Mục đích

--get

Truy xuất tài nguyên

--post='JSON'

Tạo một tài nguyên với payload JSON

--put='JSON'

Cập nhật một tài nguyên với payload JSON

--delete

Xóa một tài nguyên

--server=IP

Nhắm tới một hệ thống VergeOS cụ thể

--user=NAME

Xác thực với tư cách một người dùng cụ thể

--fields='...'

Chọn các trường sẽ trả về

--filter='...'

Biểu thức lọc OData

Ví dụ sử dụng

# Liệt kê tất cả VM (loại trừ snapshot) kèm trạng thái
yb-api --get --user=admin --server=10.0.0.100 \
  --fields='name,$key,ram,machine#status#status as machine_status' \
  --filter='is_snapshot eq false' /v4/vms

# Lấy thông tin VM chi tiết bao gồm ổ đĩa và NIC
yb-api --get --fields='most,machine[most,drives[most],nics[most]]' /v4/vms/1

# Tạo một VM mới
yb-api --post='{"name":"api-vm","enabled":true,"os_family":"linux",
  "cpu_cores":4,"ram":"8192"}' --user=admin --server=10.0.0.100 /v4/vms

# Đổi tên một VM
yb-api --put='{"name":"new-name"}' --user=admin --server=10.0.0.100 /v4/vms/1

# Bật nguồn VM
yb-api --post='{"vm":1, "action": "poweron"}' /v4/vm_actions

# Lấy schema bảng cho VM
yb-api --get '/v4/vms/$table'

Tính năng yb-api script lý tưởng cho các truy vấn ad-hoc nhanh và viết script trực tiếp trên các nút VergeOS. Đối với tự động hóa từ xa từ máy trạm, hãy dùng CLI vrg hoặc các SDK Python/PowerShell.

CLI vrg

Tính năng vrg công cụ dòng lệnh cung cấp giao diện quản lý từ xa đầy đủ tính năng cho VergeOS, được xây dựng bằng Python với hơn 200 lệnh bao phủ VM, mạng, lưu trữ, tenant và quản trị hệ thống.

Cài đặt

CLI vrg được phân phối qua nhiều kênh — hãy chọn kênh phù hợp với môi trường của bạn. Không kênh nào bị giới hạn theo hệ điều hành; pipx là đường dẫn được khuyến nghị trên mọi hệ điều hành được hỗ trợ.

# pipx (khuyến nghị — môi trường Python cô lập, mọi hệ điều hành)
pipx install vrg

# pip (mọi hệ điều hành)
pip install vrg

# uv (mọi hệ điều hành)
uv tool install vrg

# Homebrew (mọi hệ điều hành chạy Homebrew)
brew install verge-io/tap/vrg

Cũng có sẵn một binary độc lập (không cần Python) cho Linux x86_64, macOS ARM64, và Windows x86_64 — hữu ích cho các máy chủ Windows không có bộ công cụ Python.

Khả năng chính

Quản lý VM

Tạo, liệt kê, khởi động, dừng, snapshot, nhân bản và xóa máy ảo bằng các lệnh đơn giản.

Thao tác mạng

Quản lý mạng ảo, quy tắc tường lửa, cài đặt DHCP và cấu hình VPN.

Kiểm soát lưu trữ

Quản trị các volume NAS, chia sẻ CIFS/NFS và giám sát các tầng vSAN.

Quản lý tenant

Cấp phát tenant, phân bổ tài nguyên và quản lý môi trường đa tenant.

CLI vrg bao bọc cùng REST API đã được tài liệu hóa ở trên, cung cấp tự động hoàn thành tab, đầu ra được định dạng và giao diện thân thiện hơn cho các thao tác hằng ngày từ máy trạm của bạn.

Xử lý lỗi API

Khi các lời gọi API thất bại, VergeOS trả về các mã trạng thái HTTP tiêu chuẩn cùng phần thân lỗi JSON mô tả:

Mã trạng thái

Ý nghĩa

Nguyên nhân phổ biến

401

Không được ủy quyền

Thông tin xác thực không hợp lệ hoặc token đã hết hạn

403

Bị cấm

Không đủ quyền cho thao tác

404

Không tìm thấy

Tài nguyên không tồn tại hoặc điểm cuối không hợp lệ

409

Xung đột

Xung đột trạng thái tài nguyên (ví dụ: VM đã chạy)

422

Lỗi xác thực

Tham số không hợp lệ hoặc thiếu trường bắt buộc

429

Bị giới hạn tốc độ

Vượt quá giới hạn 1.000 yêu cầu/giờ

500

Lỗi máy chủ

Lỗi nội bộ — kiểm tra nhật ký hệ thống

Bạn đang chuyển từ VMware hay Nutanix?

VergeOS cung cấp một /api/v4/ giao diện được phiên bản hóa duy nhất cho mọi thao tác — bản thân giao diện người dùng chỉ là một client của API đó. Trình khám phá Swagger tích hợp sẵn được tạo động từ schema trực tiếp của hệ thống đang chạy, vì vậy tài liệu luôn khớp với những gì API hiện chấp nhận.

Các thực hành tốt nhất cho tự động hóa API

Dùng khóa API cho tự động hóa sản xuất thay vì token phiên — chúng không hết hạn khi không hoạt động
Áp dụng các hạn chế IP trên khóa API để giới hạn nơi chúng có thể được dùng
Chọn các trường cụ thể (fields=name,$key,ram) thay vì fields=most để giảm kích thước tải trọng
Triển khai phân trang với limit và offset cho các tập kết quả lớn
Xử lý các thao tác không đồng bộ — các hành động như clone và snapshot trả về ngay; thăm dò machine_status để hoàn tất
Lưu thông tin xác thực trong biến môi trường — đừng bao giờ mã hóa cứng token trong script
Sử dụng kiểm tra schema (/$table) để khám phá các trường khả dụng trước khi viết tự động hóa

Tiếp theo là gì

Giờ bạn đã hiểu API thô, các trang sau sẽ đề cập đến các công cụ cấp cao hơn bọc API này thành các giao diện bản địa theo ngôn ngữ:

Python SDK (pyvergeos) — bộ bao bọc kiểu Python, có chú thích kiểu, với trình quản lý tài nguyên và trình tạo bộ lọc OData
Mô-đun PowerShell (PSVergeOS) — hơn 200 cmdlet với hỗ trợ pipeline cho tự động hóa bản địa Windows

TrướcTổng quan

Tiếp theoPhòng lab: Tự động hóa hạ tầng

Cập nhật lần cuối 2 tháng trước

Nội dung này có hữu ích không?