> 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/automate-protect-and-extend/vi/tich-hop-va-api/python-sdk.md).

# VergeOS Python SDK (pyvergeos)

## Tổng quan

pyvergeos là một SDK Python để quản lý hạ tầng VergeOS thông qua REST API. Nó cung cấp một giao diện theo phong cách Python, có chú thích kiểu, để tự động hóa vòng đời VM, mạng, lưu trữ, thao tác đa thuê bao và quy trình khôi phục sau thảm họa, khiến nó lý tưởng cho các script tự động hóa, phát triển công cụ và tích hợp.

## Tính năng chính

* **Quản lý VM**: Tạo, cấu hình, điều khiển nguồn, sao chép và snapshot
* **Mạng nâng cao**: Mạng ảo, quy tắc tường lửa, DHCP, DNS, VPN IPSec và WireGuard
* **NAS & Lưu trữ**: Quản lý volume, chia sẻ CIFS/NFS và đồng bộ hóa
* **Đa thuê bao**: Cấp phát tenant với cách ly tài nguyên
* **Khôi phục sau thảm họa**: Snapshot đám mây, đồng bộ hóa site và quy trình khôi phục
* **Lọc**: Hỗ trợ bộ lọc OData với API xây dựng bộ lọc linh hoạt
* **Chú thích kiểu**: Đầy đủ gợi ý kiểu cho tự động hoàn thành IDE và phân tích tĩnh
* **Đa nền tảng**: Hỗ trợ Windows, macOS và Linux

## Yêu cầu

* Python 3.9 trở lên
* VergeOS 26.0 trở lên

## Cài đặt

### Từ PyPI (Khuyến nghị)

```bash
pip install pyvergeos
```

### Sử dụng uv

```bash
uv add pyvergeos
```

### Từ mã nguồn

```bash
git clone https://github.com/verge-io/pyvergeos.git
cd pyvergeos
pip install .
```

## Xác thực

SDK hỗ trợ nhiều phương thức xác thực:

### Tên người dùng/Mật khẩu

```python
from pyvergeos import VergeClient

client = VergeClient(
    host="192.168.1.100",
    username="admin",
    password="secret",
    verify_ssl=False  # Dành cho chứng chỉ tự ký
)
```

{% hint style="info" %}
**Xác minh chứng chỉ SSL**

Đặt `verify_ssl=False` chỉ cho các môi trường có chứng chỉ tự ký. Với môi trường sản xuất có chứng chỉ hợp lệ, hãy bỏ qua tham số này hoặc đặt nó thành `True`.
{% endhint %}

### Mã thông báo API

```python
client = VergeClient(
    host="192.168.1.100",
    token="your-api-token"
)
```

### Biến môi trường

```bash
export VERGE_HOST=192.168.1.100
export VERGE_USERNAME=admin
export VERGE_PASSWORD=secret
```

```python
client = VergeClient.from_env()
```

{% hint style="success" %}
**Khuyến nghị cho môi trường sản xuất**

Sử dụng biến môi trường giúp giữ thông tin xác thực ra khỏi mã nguồn của bạn và dễ dàng dùng các thông tin xác thực khác nhau giữa các môi trường.
{% endhint %}

### Trình quản lý ngữ cảnh

```python
with VergeClient(host="192.168.1.100", token="api-token") as client:
    vms = client.vms.list()
```

{% hint style="success" %}
**Dọn dẹp tự động**

Sử dụng trình quản lý ngữ cảnh (`with` câu lệnh) đảm bảo kết nối được đóng đúng cách, ngay cả khi xảy ra ngoại lệ.
{% endhint %}

## Tài nguyên có sẵn

SDK cung cấp quyền truy cập vào các tài nguyên VergeOS sau:

| Danh mục          | Tài nguyên                                           |
| ----------------- | ---------------------------------------------------- |
| Máy ảo            | VM, ổ đĩa, NIC, snapshot                             |
| Mạng              | Mạng, quy tắc, DNS, DHCP, bí danh, máy chủ           |
| VPN               | Kết nối IPSec, giao diện và peer WireGuard           |
| NAS/Lưu trữ       | Dịch vụ, volume, chia sẻ CIFS/NFS, đồng bộ volume    |
| Tenant            | Quản lý tenant, snapshot, lưu trữ, khối mạng         |
| Người dùng & Nhóm | Người dùng, nhóm, quyền, khóa API                    |
| Hệ thống          | Cụm, nút, tầng lưu trữ, chứng chỉ                    |
| Giám sát          | Cảnh báo, nhật ký, tác vụ                            |
| Sao lưu & DR      | Hồ sơ snapshot, snapshot đám mây, site, đồng bộ site |

## Ví dụ sử dụng

### Quản lý máy ảo

```python
from pyvergeos import VergeClient

client = VergeClient(host="192.168.1.100", username="admin", password="secret")

# Liệt kê tất cả VM
for vm in client.vms.list():
    print(f"{vm.name}: {vm.ram}MB RAM, {vm.cpu_cores} nhân")

# Lấy một VM cụ thể
vm = client.vms.get(name="web-server")

# Tạo một VM
new_vm = client.vms.create(
    name="test-vm",
    ram=2048,
    cpu_cores=2,
    os_family="linux"
)

# Thao tác nguồn
vm.power_on()
vm.power_off()
vm.reset()

# Snapshot
vm.snapshot(retention=86400, quiesce=True)

# Nhân bản VM
clone = vm.clone(name="test-clone")

# Thêm ổ đĩa và NIC
vm.drives.add(name="data", size=50*1024*1024*1024)
vm.nics.add(network=network.key)

client.disconnect()
```

### Tạo và quản lý mạng

```python
# Tạo mạng ảo
network = client.networks.create(
    name="app-network",
    network_address="10.10.1.0/24",
    ip_address="10.10.1.1",
    dhcp_enabled=True
)

network.power_on()
network.apply_rules()

# Thêm quy tắc tường lửa
network.rules.create(
    name="Cho phép SSH",
    action="accept",
    protocol="tcp",
    dest_port=22
)
```

### Lọc tài nguyên

SDK hỗ trợ nhiều cách tiếp cận lọc:

{% tabs %}
{% tab title="Tham số từ khóa" %}

```python
# Đơn giản và dễ đọc cho các bộ lọc cơ bản
vms = client.vms.list(status="running", name="prod-*")
```

{% endtab %}

{% tab title="Chuỗi bộ lọc OData" %}

```python
# Cú pháp bộ lọc OData đầy đủ cho các truy vấn phức tạp
vms = client.vms.list(filter="os_family eq 'linux' and ram gt 2048")
```

{% endtab %}

{% tab title="Trình xây dựng bộ lọc" %}

```python
# API linh hoạt để xây dựng bộ lọc bằng chương trình
from pyvergeos import Filter

f = Filter().eq("os_family", "linux").and_().gt("ram", 2048)
vms = client.vms.list(filter=str(f))
```

{% endtab %}
{% endtabs %}

### Chờ tác vụ

Nhiều thao tác trong VergeOS chạy không đồng bộ. Hãy dùng trình quản lý tác vụ để chờ hoàn tất:

```python
result = vm.snapshot()
task = client.tasks.wait(result["task"], timeout=300)
```

{% hint style="info" %}
**Thao tác không đồng bộ**

Các thao tác như snapshot, nhân bản và di chuyển sẽ trả về ngay với một task ID. Hãy dùng `client.tasks.wait()` để chặn cho đến khi thao tác hoàn tất.
{% endhint %}

## Xử lý lỗi

SDK cung cấp các loại ngoại lệ cụ thể cho các điều kiện lỗi khác nhau:

```python
from pyvergeos import NotFoundError, AuthenticationError, TaskTimeoutError

try:
    vm = client.vms.get(name="nonexistent")
except NotFoundError:
    print("Không tìm thấy VM")

try:
    task = client.tasks.wait(task_id, timeout=60)
except TaskTimeoutError as e:
    print(f"Tác vụ {e.task_id} đã hết thời gian chờ")
```

{% hint style="info" %}
**Các loại ngoại lệ có sẵn**
{% endhint %}

| Ngoại lệ              | Mô tả                                                 |
| --------------------- | ----------------------------------------------------- |
| `VergeError`          | Ngoại lệ cơ sở cho mọi lỗi của SDK                    |
| `AuthenticationError` | Thông tin xác thực không hợp lệ hoặc token đã hết hạn |
| `NotFoundError`       | Tài nguyên được yêu cầu không tồn tại                 |
| `ConflictError`       | Xung đột trạng thái tài nguyên (ví dụ: VM đã chạy)    |
| `ValidationError`     | Giá trị tham số không hợp lệ                          |
| `TaskTimeoutError`    | Tác vụ không hoàn tất trong thời gian chờ             |
| `TaskError`           | Tác vụ thất bại trong khi thực thi                    |

## Các trường hợp sử dụng phổ biến

* **Tự động hóa hạ tầng**: Cấp phát VM, mạng và lưu trữ bằng chương trình
* **Tích hợp CI/CD**: Tạo và hủy môi trường thử nghiệm trong pipeline
* **Giám sát và báo cáo**: Truy vấn trạng thái tài nguyên và tạo báo cáo kiểm kê
* **Tự động hóa sao lưu**: Lên lịch và quản lý snapshot cùng bản sao lưu đám mây
* **Cấp phát đa thuê bao**: Tự động hóa việc tạo tenant và phân bổ tài nguyên

## Tài liệu và tài nguyên

Để có tài liệu đầy đủ, bao gồm tất cả các phương thức có sẵn và ví dụ sử dụng chi tiết, hãy truy cập kho lưu trữ chính thức:

* [Kho lưu trữ GitHub](https://github.com/verge-io/pyvergeos)
* [Gói PyPI](https://pypi.org/project/pyvergeos/)

## Hỗ trợ

Nếu bạn gặp sự cố hoặc có yêu cầu tính năng, vui lòng mở một issue trên kho lưu trữ GitHub:

<https://github.com/verge-io/pyvergeos/issues>

## Tài nguyên bổ sung

* [Tài liệu Python](https://docs.python.org/3/)
* [Tài liệu API VergeOS](/knowledge-base/vi/automation-api/verge-api-guide.md)
* [Mô-đun PowerShell PSVergeOS](/automate-protect-and-extend/vi/tich-hop-va-api/powershell-module.md) - Giải pháp thay thế PowerShell
* [Nhà cung cấp Terraform](/automate-protect-and-extend/vi/tich-hop-va-api/terraform-provider.md) - Hạ tầng dưới dạng mã


---

# 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/automate-protect-and-extend/vi/tich-hop-va-api/python-sdk.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.