> 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/knowledge-base/vi/automation-api/verge-api-guide.md). # Hướng dẫn API ## Tổng quan API VergeOS cho phép các nhà phát triển tương tác với hệ thống VergeOS theo chương trình. Nó cung cấp quyền truy cập vào các thao tác hệ thống như tạo máy ảo, quản lý tài nguyên, và tương tác với các kho lưu trữ thanh toán và danh mục. API sử dụng các quy ước chuẩn kiểu REST và hỗ trợ nhiều phương thức xác thực. Hướng dẫn này cung cấp tổng quan về API VergeOS, tài liệu endpoint, các yêu cầu ví dụ và xử lý lỗi. Tài liệu này phác thảo cách sử dụng API. Thông tin chi tiết về API có thể được tìm thấy trong giao diện người dùng VergeOS dưới dạng một trang tài liệu Swagger, được tạo động và hiển thị danh sách đầy đủ các bảng và thao tác API hiện có. ### Giao diện Swagger Để truy cập tài liệu Swagger trong giao diện người dùng VergeOS: 1. **Đăng nhập** vào hệ thống VergeOS bằng thông tin xác thực hợp lệ. 2. Chọn **Hệ thống** từ menu trên cùng. 3. Chọn **API Documentation**. 4. Trang tài liệu Swagger sẽ mở ra. Trang này cung cấp các ví dụ chi tiết cho từng thao tác API, bao gồm khả năng kiểm thử trực tiếp API. ![Ví dụ tài liệu Swagger](/files/a5000b49b64e5634265e92616f35bec6fc97bf9a) 5. Chọn một bảng riêng lẻ và chọn một trong các **GET/POST/DELETE/PUT** tùy chọn có sẵn để xem và kiểm thử các hành động API. 6. Chỉ định các tham số và nhấp vào **Nút Execute** để chạy lệnh API. Điều này sẽ trả về phản hồi, bao gồm nội dung phản hồi, tiêu đề và một ví dụ curl. ## Cơ bản về API ### Phương thức HTTP API VergeOS sử dụng các phương thức HTTP chuẩn như GET, POST, PUT và DELETE để thao tác tài nguyên. ### Tham số GET * **fields**: Chỉ định những trường nào sẽ được trả về trong tập kết quả. * **filter**: Lọc tập kết quả dựa trên các tiêu chí nhất định. * **sort**: Sắp xếp kết quả theo một trường được chỉ định. * **limit**: Giới hạn số lượng kết quả trả về. ### Xác thực Tất cả các yêu cầu API phải được thực hiện qua HTTPS và yêu cầu xác thực bằng xác thực truy cập cơ bản hoặc mã thông báo phiên. ## Ghi chú bổ sung * **Giới hạn tốc độ**: API hỗ trợ tối đa 1000 yêu cầu mỗi giờ cho mỗi khóa API. * **Định dạng dữ liệu**: Tất cả phản hồi được trả về ở định dạng JSON. * **Phân trang**: Các endpoint trả về lượng dữ liệu lớn hỗ trợ phân trang bằng `offset` và `limit` tham số truy vấn. *** ## Xác thực VergeOS hỗ trợ hai phương thức xác thực: 1. **Xác thực HTTP cơ bản**\ API chỉ khả dụng thông qua SSL. 2. **Xác thực dựa trên mã thông báo**\ Các nhà phát triển phải yêu cầu mã thông báo từ API bằng cách gửi POST tới `/sys/tokens` endpoint. Sau đó, mã thông báo được truyền trong các yêu cầu API tiếp theo trong tiêu đề `x-yottabyte-token` . ### Ví dụ yêu cầu xác thực Để lấy mã thông báo: ```bash curl --header "X-JSON-Non-Compact: 1" --basic --data-ascii '{"login": "USERNAME", "password": "PASSWORD"}' --insecure --request "POST" --header 'Content-Type: application/json' 'https://your-verge-instance.com/api/sys/tokens' ``` Ví dụ phản hồi: ```json { "location":"\\/sys\\/tokens\\/3a334563456378845634563b7b82d2efcadce9", "dbpath":"tokens\\/3a334563456378845634563b7b82d2efcadce9", "$row":1, "$key":"3a334563456378845634563b7b82d2efcadce9" } ``` Sử dụng mã thông báo từ trường `"$key"` trong tất cả các yêu cầu tiếp theo: ```bash x-yottabyte-token: 3a334563456378845634563b7b82d2efcadce9 ``` Để đăng xuất, gửi một yêu cầu DELETE tới `/sys/tokens/{token}` endpoint. ### Ví dụ yêu cầu đăng xuất ```bash DELETE /sys/tokens/3a334563456378845634563b7b82d2efcadce9 ``` *** ### Ví dụ máy ảo Tham số **VMs** phần của API VergeOS cho phép người dùng quản lý máy ảo theo chương trình. Nó bao gồm các endpoint để liệt kê, tạo, sửa đổi và xóa VM. ### Lấy danh sách máy ảo **Endpoint**:\ `GET /v4/vms?fields=most` **Mô tả**: Truy xuất danh sách tất cả VM trong hệ thống với các chi tiết như số lõi CPU, RAM, loại máy và thông tin cấu hình. **Yêu cầu ví dụ**: ```bash curl -X 'GET' \\ 'https://your-verge-instance.com/api/v4/vms?fields=most' \\ -H 'accept: application/json' \\ -H 'x-yottabyte-token: ' ``` **Phản hồi ví dụ**: ```json [ { "$key": 1, "name": "CentOS 7 (Latest) 1.0-7", "machine": 7, "cpu_cores": 2, "cpu_type": "Cascadelake-Server", "ram": 2048, "os_family": "linux", "is_snapshot": true, "boot_order": "cd", "rtc_base": "utc", "console": "vnc", "uefi": false, "secure_boot": false, "serial_port": true, "uuid": "d3914756-4ec5-9dfe-5c45-b28af2fd3d73", "created": 1724435418, "modified": 1724435418 } ] ``` **Tổng quan về dữ liệu trả về**: * **$key**: Mã định danh duy nhất của VM. * **name**: Tên của máy ảo. * **machine**: ID máy liên kết với VM. * **cpu\_cores**: Số lõi CPU được cấp cho VM. * **ram**: Lượng RAM được cấp phát (tính bằng MB). * **os\_family**: Loại hệ điều hành. * **uuid**: Mã định danh duy nhất toàn cầu (UUID) của VM. * **created**: Dấu thời gian tạo. * **modified**: Dấu thời gian sửa đổi gần nhất. *** ### Tạo một máy ảo mới **Endpoint**:\ `POST /v4/vms` **Mô tả**: Tạo một máy ảo mới với các chi tiết cấu hình cụ thể, chẳng hạn như số lõi CPU, RAM, loại máy, thứ tự khởi động, v.v. **Yêu cầu ví dụ**: ```bash curl -X 'POST' \\ 'https://your-verge-instance.com/api/v4/vms' \\ -H 'accept: application/json' \\ -H 'x-yottabyte-token: ' \\ -H 'Content-Type: application/json' \\ -d '{ "name": "rest", "description": "test", "machine_type": "pc-q35-9.0", "allow_hotplug": true, "cpu_cores": 1, "cpu_type": "Broadwell", "ram": 1024, "os_family": "linux", "boot_order": "cd", "uefi": false, "note": "test vm" }' ``` **Phản hồi ví dụ**: ```json { "location": "/v4/vms/36", "dbpath": "vms/36", "$row": 36, "$key": "36" } ``` **Tổng quan về dữ liệu trả về**: * **location**: Vị trí của tài nguyên VM mới được tạo. * **dbpath**: Đường dẫn cơ sở dữ liệu của VM mới. * **$row**: ID hàng của VM. * **$key**: Khóa duy nhất của VM. *** ### Ví dụ mạng ảo (Vnets) Tham số **Vnets** phần của API VergeOS cho phép người dùng quản lý mạng ảo (Vnets) theo chương trình. Nó bao gồm các endpoint để truy xuất, tạo và quản lý tài nguyên mạng, bao gồm mạng nội bộ và bên ngoài, đồng thời cho phép các tùy chọn nâng cao như giới hạn tốc độ. ### Truy xuất chi tiết Vnet **Endpoint**:\ `GET /v4/vnets?fields=most` **Mô tả**: Truy xuất danh sách tất cả Vnets trong hệ thống với các chi tiết như loại mạng, MTU, cài đặt DHCP và cấu hình DNS. **Yêu cầu ví dụ**: ```bash curl -X 'GET' \\ 'https://your-verge-instance.com/api/v4/vnets?fields=most' \\ -H 'accept: application/json' \\ -H 'x-yottabyte-token: ' ``` **Phản hồi ví dụ**: ```json [ { "$key": 6, "name": "Internal Test 1", "advanced_options": { "dnsmasq": [ "--dhcp-boot=netboot.xyz.kpxe,,192.168.10.20", "--dhcp-match=set:efi-x86,option:client-arch,6", "--dhcp-boot=tag:efi-x86,netboot.xyz.efi,,192.168.10.20", "--dhcp-match=set:efi-x86_64,option:client-arch,7", "--dhcp-boot=tag:efi-x86_64,netboot.xyz.efi,,192.168.10.20", "--dhcp-match=set:efi-x86_64,option:client-arch,9", "--dhcp-boot=tag:efi-x86_64,netboot.xyz.efi,,192.168.10.20" ] }, "type": "internal", "layer2_type": "vxlan", "network": "192.168.100.0/24", "mtu": 9000, "dhcp_enabled": true, "dhcp_start": "192.168.100.100", "dhcp_stop": "192.168.100.200", "rate_limit": 0, "rate_limit_type": "mbytes/second", "gateway": "" } ] ``` **Tổng quan về dữ liệu trả về**: * **$key**: Mã định danh duy nhất của Vnet. * **name**: Tên của mạng ảo. * **advanced\_options**: Các tùy chọn nâng cao sẽ được truyền tới các dịch vụ chạy bên trong mạng, trong ví dụ này là các cờ netboot cho dnsmasq * **type**: Loại mạng (ví dụ: "internal"). * **layer2\_type**: Loại mạng Layer 2, chẳng hạn như VXLAN. * **network**: Khối CIDR của mạng. * **mtu**: Kích thước Đơn vị Truyền Tối đa (MTU). * **dhcp\_enabled**: Cho biết DHCP có được bật cho mạng này hay không. * **dhcp\_start**: Địa chỉ IP bắt đầu cho phạm vi DHCP. * **dhcp\_stop**: Địa chỉ IP kết thúc cho phạm vi DHCP. * **rate\_limit**: Giới hạn tốc độ của mạng (tính bằng mbytes/second). * **gateway**: Cổng mặc định của mạng. *** ### Tạo một mạng nội bộ với giới hạn tốc độ **Endpoint**:\ `POST /v4/vnets` **Mô tả**: Tạo một mạng ảo nội bộ mới với giới hạn tốc độ và cài đặt DHCP. **Yêu cầu ví dụ**: ```bash curl -X 'POST' \\ 'https://your-verge-instance.com/api/v4/vnets' \\ -H 'accept: application/json' \\ -H 'x-yottabyte-token: ' \\ -H 'Content-Type: application/json' \\ -d '{ "name":"int1", "description":"workloads", "type":"internal", "mtu":"9000", "network":"192.168.80.0/24", "gateway":"192.168.80.1", "dnslist":"1.1.1.1", "dhcp_enabled": true, "rate_limit": 100, "rate_limit_burst": 500, "dhcp_start":"192.168.80.100", "dhcp_stop":"192.168.80.200" }' ``` **Phản hồi ví dụ**: ```json { "location": "/v4/vnets/8", "dbpath": "vnets/8", "$row": 8, "$key": "8" } ``` **Tổng quan về dữ liệu trả về**: * **location**: Vị trí của tài nguyên Vnet mới được tạo. * **dbpath**: Đường dẫn cơ sở dữ liệu của Vnet mới. * **$row**: ID hàng của Vnet. * **$key**: Khóa duy nhất của Vnet. *** ## Tài nguyên Dưới đây là một URL ví dụ được dùng để truy vấn danh sách máy. *Ví dụ: * | | | | | | | | | | | | --------- | -------------- | - | ------------------- | - | ------------------------------- | ---- | ----------------------- | - | ------------------------------------ | | https\:// | user | : | password | @ | server | /api | /v4/machines | ? | filter=\&fields=all\&sort=\&limit= | | | Tên người dùng | | Mật khẩu người dùng | | Tên máy chủ hoặc IP của máy chủ | | Vị trí tài nguyên (URI) | | Các tùy chọn này được mô tả bên dưới | ### Tùy chọn GET #### Trường * **Chỉ định những trường nào sẽ được trả về trong tập kết quả (cũng có thể là một view nếu có một view được định nghĩa cho lược đồ bảng)**. * **all** trả về mọi trường. * **most** trả về hầu hết các trường ngoại trừ các trường đối số và hàng. * **summary** trả về các trường được đánh dấu là 'summary' trong lược đồ của chúng. * Ví dụ: `fields=name,email,enabled,groups[all] as all_groups,collapse(groups[name]) as first_groups_name` Các hàm trường: * **collapse** * **datetime** * **upper** * **lower** * **count** * **diskspace** * **display** * **hex** * **sha1** * **sum** * **avg** * **min** * **max** #### Lọc * Lọc các tập kết quả theo tiêu chí được chỉ định. * Tương tự như [OData](https://msdn.microsoft.com/en-us/library/gg309461\(v=crm.7\).aspx#BKMK_filter). * Ví dụ: `filter=enabled eq true and size gt 1048576`. * Ví dụ: `filter=cputype eq 'qemu' or cputype eq 'kvm'`. | Toán tử | Mô tả | | ------- | ------------------------------------------------- | | *eq* | Bằng | | *ne* | Không bằng | | *gt* | Lớn hơn | | *ge* | Lớn hơn hoặc bằng | | *lt* | Nhỏ hơn | | *le* | Nhỏ hơn hoặc bằng | | *bw* | Bắt đầu bằng | | *ew* | Kết thúc bằng | | *và* | Và logic | | *hoặc* | Hoặc logic | | *cs* | Chứa chuỗi (phân biệt chữ hoa chữ thường) | | *ct* | Chứa văn bản (không phân biệt chữ hoa chữ thường) | | *rx* | Khớp biểu thức chính quy | #### Sắp xếp * Sắp xếp kết quả theo trường được chỉ định. * Ví dụ: `sort=+name`. * Ví dụ: `sort=-id`. #### Giới hạn * **limit** (số nguyên) giới hạn tập kết quả ở một số mục được chỉ định. Giá trị 0 có nghĩa là không giới hạn. * Ví dụ: `limit=1`. ### Mã phản hồi HTTP chung * **400 - Yêu cầu không hợp lệ**: Yêu cầu không hợp lệ. * **401 - Đăng nhập thất bại / Cần đăng nhập**: Xác thực thất bại hoặc là bắt buộc. * **403 - Từ chối quyền truy cập**: Bạn không có các quyền cần thiết. * **404 - Không tìm thấy tài nguyên**: Hàng hoặc API được yêu cầu không tồn tại. * **405 - Không được phép**: Thao tác không được cho phép. * **409 - Hàng đã tồn tại**: Tài nguyên đã tồn tại. * **422 - Xác thực thất bại / Tham số không hợp lệ**: Xác thực không thành công. * **500 - Lỗi máy chủ nội bộ**: Đã xảy ra lỗi chưa được xử lý. #### Dành riêng cho POST * **201 - Đã tạo**: Một hàng/tài nguyên mới đã được tạo thành công. #### Dành riêng cho WebSocket (dùng cho VNC/SPICE) * **101 - Chuyển đổi giao thức**: Giao thức đã được chuyển đổi thành công. #### PUT/GET/DELETE * **200 - Thành công**: Thao tác đã hoàn tất thành công. *** ### Định nghĩa bảng lược đồ #### Kiểu trường * **bool** * **text** * **chuỗi** * **num** * **uint8** * **uint16** * **uint32** * **uint64** * **int8** * **int16** * **int32** * **int64** * **đã bật** * **created** * **created\_ms** * **created\_us** * **modified** * **modified\_ms** * **modified\_us** * **tên tệp** * **kích thước tệp** * **dùng tệp** * **tệp đã cấp phát** * **tệp đã sửa đổi** * **json** * **hàng** * **các hàng** #### Chủ sở hữu lược đồ / Trường cha * **Trường chủ sở hữu**: Nếu trường chủ sở hữu là null, các quyền thông thường sẽ được áp dụng. Nếu trường chủ sở hữu có giá trị, các quyền sẽ được thay thế bằng một kiểm tra quyền đối với chủ sở hữu. * **Trường cha**: Kiểm tra quyền được áp dụng cho chính hàng đó, và nếu kiểm tra quyền thất bại, quyền cũng sẽ được kiểm tra trên hàng cha. *** ### Lược đồ toàn bộ bảng Để truy xuất lược đồ của một bảng, thêm **$table** vào URI: **/api/v4/machines/$table** (thay "machines" bằng tên bảng). Bạn sẽ được yêu cầu nhập thông tin xác thực; điều này đòi hỏi thông tin xác thực quản trị VergeOS. Đầu ra sẽ ở định dạng JSON. Firefox hiển thị nội dung này ở định dạng dễ đọc theo mặc định, nhưng các trình duyệt khác có thể yêu cầu xuất JSON sang một chương trình bên ngoài để dễ đọc hơn. *** ### Ví dụ về lỗi #### Ví dụ lỗi (Mã HTTP 422) ```json { "err": "Lỗi xác thực trên trường: 'dhcp_start' - 'không vượt qua bài kiểm tra xác thực'" } ``` VergeOS sử dụng các mã trạng thái HTTP tiêu chuẩn để biểu thị kết quả của một yêu cầu API. * **400 Yêu cầu không hợp lệ**: Yêu cầu không hợp lệ hoặc không thể được xử lý. * **401 Không được phép**: Khóa API bị thiếu hoặc không hợp lệ. * **403 Bị cấm**: Khóa API không có các quyền cần thiết. * **404 Không tìm thấy**: Tài nguyên không tồn tại. * **500 Lỗi máy chủ nội bộ**: Đã xảy ra lỗi máy chủ. *** {% hint style="info" %} **Thông tin tài liệu** * Cập nhật lần cuối: 2024-11-14 * Phiên bản vergeOS: 4.12.6 {% endhint %} --- # 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/knowledge-base/vi/automation-api/verge-api-guide.md?ask=&goal= ``` `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.