> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/learn-the-platform/vi/module-8-nha-phat-trien-and-devops/01-api-cli.md).

# Công cụ REST API & CLI

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.

```bash
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 đề:

```bash
# 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:

```bash
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:

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

{% hint style="warning" %}
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.
{% endhint %}

## 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:**

1. Đăng nhập vào giao diện VergeOS
2. Đi tới **Hệ thống → Tài liệu API**
3. 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:

```bash
# 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:

```mermaid
graph LR
    A["1. Tạo VM"] --> B["2. Thêm ổ đĩa"]
    B --> C["3. Thêm NIC"]
    C --> D["4. Bật nguồn"]
    style A fill:#e8f5e9,stroke:#2e7d32
    style B fill:#e3f2fd,stroke:#1565c0
    style C fill:#fff3e0,stroke:#ef6c00
    style D fill:#fce4ec,stroke:#c62828
```

### Bước 1: Tạo VM

```bash
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ữ

```bash
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

```bash
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

```bash
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:

```bash
# 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

```bash
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

```bash
# 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'
```

{% hint style="success" %}
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.
{% endhint %}

## 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ợ.

```bash
# 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                |

{% hint style="info" %}
**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.
{% endhint %}

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

1. **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
2. **Á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
3. **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
4. **Triển khai phân trang** với `limit` và `offset` cho các tập kết quả lớn
5. **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
6. **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
7. **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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verge.io/learn-the-platform/vi/module-8-nha-phat-trien-and-devops/01-api-cli.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.