> 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/02-python-sdk.md). # Python SDK (pyvergeos) Tính năng **pyvergeos** SDK cung cấp một giao diện kiểu Python, có chú thích kiểu cho toàn bộ VergeOS REST API. Thay vì tạo các yêu cầu HTTP thô, bạn làm việc với **các trình quản lý tài nguyên** — `client.vms`, `client.networks`, `client.tenants` — ánh xạ trực tiếp đến các đối tượng VergeOS. SDK xử lý xác thực, phân trang, thử lại và thăm dò tác vụ bất đồng bộ để các script tự động hóa của bạn luôn gọn gàng và tập trung vào logic nghiệp vụ. ## Yêu cầu & Cài đặt **Điều kiện tiên quyết:** * **Python 3.9** hoặc mới hơn * **VergeOS 26.0** hoặc mới hơn * Hoạt động trên **Windows, macOS và Linux** **Cài đặt từ PyPI (khuyến nghị):** ```bash pip install pyvergeos ``` **Hoặc với uv (lựa chọn nhanh hơn):** ```bash uv add pyvergeos ``` **Từ mã nguồn (phát triển):** ```bash git clone https://github.com/verge-io/pyvergeos.git cd pyvergeos pip install . ``` ## Xác thực SDK hỗ trợ ba phương thức xác thực, mỗi phương thức phù hợp với các môi trường khác nhau. ### Tên người dùng & Mật khẩu Cách đơn giản nhất cho script tương tác và phát triển: ```python from pyvergeos import VergeClient client = VergeClient( host="192.168.1.100", username="admin", password="secret", verify_ssl=False # Chỉ dùng cho chứng chỉ tự ký ) ``` ### API Token Cho tự động hóa sản xuất khi bạn có sẵn một API key đã tạo trước: ```python client = VergeClient( host="192.168.1.100", token="your-api-token" ) ``` ### Biến môi trường Cách được khuyến nghị cho môi trường sản xuất — giữ thông tin xác thực ngoài mã nguồn: ```bash export VERGE_HOST=192.168.1.100 export VERGE_USERNAME=admin export VERGE_PASSWORD=secret export VERGE_VERIFY_SSL=false # Tùy chọn export VERGE_TIMEOUT=30 # Tùy chọn export VERGE_RETRY_TOTAL=3 # Tùy chọn export VERGE_RETRY_BACKOFF=1 # Tùy chọn ``` ```python client = VergeClient.from_env() ``` ### Trình quản lý ngữ cảnh Luôn dùng trình quản lý ngữ cảnh trong mã sản xuất để đảm bảo kết nối được đóng đúng cách, ngay cả khi có ngoại lệ xảy ra: ```python with VergeClient(host="192.168.1.100", token="api-token") as client: vms = client.vms.list() for vm in vms: print(f"{vm.name}: {vm.ram}MB RAM") # Kết nối sẽ tự động đóng ở đây ``` ## Trình quản lý tài nguyên Mỗi loại tài nguyên VergeOS đều được hiển thị thông qua một **trình quản lý tài nguyên** trên đối tượng client. Mỗi trình quản lý cung cấp `list()`, `get()`, `create()`và các phương thức hành động. ### Máy ảo `client.vms` — Tạo, cấu hình, điều khiển nguồn, nhân bản, snapshot và quản lý ổ đĩa/NIC cho VM. ### Mạng `client.networks` — Mạng ảo, quy tắc tường lửa, DHCP, DNS và quản lý nguồn mạng. ### Tenants `client.tenants` — Cấp phát đa thuê bao, cô lập tài nguyên, snapshot, khối lưu trữ và khối mạng. ### NAS & Lưu trữ `client.nas` — Dịch vụ NAS, volume, chia sẻ CIFS/NFS và đồng bộ volume. ### Khôi phục sau thảm họa `client.dr` — Snapshot đám mây, đồng bộ site và quy trình khôi phục. ### Người dùng & Nhóm `client.users` — Tài khoản người dùng, nhóm, quyền và quản lý khóa API. ### Tác vụ & Giám sát `client.tasks` — Theo dõi tác vụ bất đồng bộ, chờ đợi, thời gian chờ. Ngoài ra: cảnh báo và nhật ký. ### Hệ thống & GPU `client.clusters`, `client.nodes`, `client.gpu` — Thông tin cụm/nút, các tầng lưu trữ, quản lý thiết bị GPU. ### Bảng tài nguyên đầy đủ | Danh mục | Tài nguyên khả dụng | | --------------------- | ----------------------------------------------------- | | **Máy ảo** | VM, ổ đĩa, NIC, snapshot | | **Mạng** | Mạng, quy tắc tường lửa, 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ụ NAS, volume, chia sẻ CIFS/NFS, đồng bộ volume | | **Tenants** | Quản lý tenant, snapshot, khối 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, các 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 | ## Lọc tài nguyên SDK cung cấp ba cách để lọc tài nguyên, từ các tham số từ khóa đơn giản đến một trình tạo bộ lọc OData đầy đủ. ### Tham số từ khóa Cách đơn giản nhất cho các bộ lọc cơ bản — truyền trực tiếp tên trường: ```python # Tìm tất cả VM Linux đang chạy vms = client.vms.list(status="running", os_family="linux") # Khớp ký tự đại diện vms = client.vms.list(name="prod-*") ``` ### Chuỗi lọc OData Đối với các truy vấn phức tạp, hãy truyền trực tiếp biểu thức lọc OData: ```python # Kết hợp điều kiện bằng toán tử vms = client.vms.list(filter="os_family eq 'linux' and ram gt 2048") ``` ### Trình tạo bộ lọc (Fluent API) Xây dựng bộ lọc bằng lập trình với an toàn kiểu và tự động hoàn thành: ```python from pyvergeos import Filter # Chuỗi fluent với các phương thức toán tử f = Filter().eq("os_family", "linux").and_().gt("ram", 2048) vms = client.vms.list(filter=str(f)) ``` **Các toán tử lọc khả dụng:** | Phương thức | Toán tử OData | Ví dụ | | ----------- | ------------- | ------------------------------------- | | `.eq()` | `eq` | `Filter().eq("status", "running")` | | `.ne()` | `ne` | `Filter().ne("os_family", "windows")` | | `.gt()` | `gt` | `Filter().gt("ram", 4096)` | | `.lt()` | `lt` | `Filter().lt("cpu_cores", 8)` | | `.ge()` | `ge` | `Filter().ge("ram", 2048)` | | `.le()` | `le` | `Filter().le("ram", 8192)` | | `.and_()` | `và` | Nối nhiều điều kiện | | `.or_()` | `hoặc` | Kết hợp các điều kiện thay thế | ## Xử lý tác vụ bất đồng bộ Nhiều thao tác VergeOS — snapshot, nhân bản, di chuyển — chạy **bất đồng bộ** và trả về ngay một task ID. SDK cung cấp trình quản lý tác vụ để thăm dò trạng thái hoàn thành: ```python # Snapshot trả về một tham chiếu tác vụ result = vm.snapshot(retention=86400, quiesce=True) # Chờ snapshot hoàn tất (chặn tối đa 300 giây) task = client.tasks.wait(result["task"], timeout=300) print(f"Snapshot hoàn tất: {task}") ``` Nếu tác vụ không hoàn thành trong thời gian chờ, `TaskTimeoutError` sẽ được ném ra cùng với thuộc tính `task_id` để bạn có thể kiểm tra trạng thái sau: ```python from pyvergeos import TaskTimeoutError try: task = client.tasks.wait(task_id, timeout=60) except TaskTimeoutError as e: print(f"Tác vụ {e.task_id} vẫn đang chạy — hãy kiểm tra lại sau") ``` ## Xử lý lỗi SDK cung cấp một hệ thống ngoại lệ có cấu trúc để bạn có thể bắt các chế độ lỗi cụ thể: | 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 thành trong thời gian chờ | | `TaskError` | Tác vụ thất bại trong quá trình thực thi | ```python from pyvergeos import NotFoundError, AuthenticationError try: vm = client.vms.get(name="nonexistent-vm") except NotFoundError: print("Không tìm thấy VM — hãy kiểm tra tên") except AuthenticationError: print("Xác thực thất bại — hãy kiểm tra thông tin đăng nhập") ``` ## Cấu hình thử lại SDK tự động thử lại các lỗi tạm thời (HTTP 429, 500, 502, 503, 504) với cơ chế backoff lũy tiến: ```python client = VergeClient( host="192.168.1.100", token="api-token", retry_total=5, # Số lần thử lại tối đa (mặc định: 3) retry_backoff_factor=2, # Hệ số backoff (mặc định: 1) ) ``` Đặt `retry_total=0` để tắt hoàn toàn việc thử lại cho các thao tác nhạy cảm về thời gian. ## Chuyển đổi ngữ cảnh Tenant pyvergeos có thể **kết nối vào các ngữ cảnh tenant** từ hệ thống host, cho phép các script tự động hóa tập trung quản lý tài nguyên trên nhiều tenant: ```python # Lấy một tenant từ hệ thống host tenant = client.tenants.get(name="customer-a") # Kết nối vào ngữ cảnh của tenant tenant_client = tenant.connect() # Bây giờ quản lý tài nguyên BÊN TRONG tenant tenant_vms = tenant_client.vms.list() for vm in tenant_vms: print(f"VM của tenant: {vm.name}") # Tạo một mạng bên trong tenant tenant_client.networks.create( name="tenant-app-net", network_address="10.50.1.0/24", ip_address="10.50.1.1", dhcp_enabled=True ) ``` Điều này đặc biệt hữu ích cho **Các MSP và nhà cung cấp dịch vụ** cần tự động hóa việc cấp phát trên hàng chục hoặc hàng trăm môi trường tenant từ một script duy nhất. ## Ví dụ thực tế ### Quản lý vòng đời VM ```python with VergeClient.from_env() as client: # Tạo một VM mới vm = client.vms.create( name="web-server-01", ram=4096, cpu_cores=2, os_family="linux" ) # Thêm một ổ dữ liệu 50 GB vm.drives.add(name="data", size=50 * 1024 * 1024 * 1024) # Gắn vào một mạng network = client.networks.get(name="app-network") vm.nics.add(network=network.key) # Bật nguồn vm.power_on() print(f"VM {vm.name} đang chạy") ``` ### Mạng với quy tắc tường lửa ```python with VergeClient.from_env() as client: # Tạo một mạng network = client.networks.create( name="web-tier", network_address="10.20.1.0/24", ip_address="10.20.1.1", dhcp_enabled=True ) network.power_on() # Thêm các quy tắc tường lửa network.rules.create( name="Cho phép HTTPS", action="accept", protocol="tcp", dest_port=443 ) network.rules.create( name="Cho phép SSH", action="accept", protocol="tcp", dest_port=22 ) network.apply_rules() ``` ### Thao tác hàng loạt với lọc ```python with VergeClient.from_env() as client: # Snapshot tất cả VM sản xuất đang chạy prod_vms = client.vms.list(name="prod-*", status="running") for vm in prod_vms: result = vm.snapshot(retention=86400, quiesce=True) task = client.tasks.wait(result["task"], timeout=300) print(f"Đã tạo snapshot cho {vm.name}") ``` ### Báo cáo kiểm kê đa tenant ```python with VergeClient.from_env() as client: for tenant in client.tenants.list(): tenant_client = tenant.connect() vms = tenant_client.vms.list() print(f"\n--- {tenant.name} ---") for vm in vms: print(f" {vm.name}: {vm.ram}MB RAM, {vm.cpu_cores} lõi") ``` ## Ghi chú quan trọng {% hint style="warning" %} **An toàn luồng** Client pyvergeos **không an toàn luồng**. Nếu bạn cần các thao tác đồng thời, hãy tạo các `VergeClient` riêng biệt cho từng luồng. Với các khối lượng công việc thực sự song song, hãy cân nhắc **govergeos** Go SDK được thiết kế để sử dụng đồng thời với goroutine. {% endhint %} {% hint style="info" %} **Bạn đang chuyển từ VMware hay Nutanix?** pyvergeos cung cấp ba mẫu sử dụng đáng biết ngay từ đầu: * **Lọc** — một `Filter()` fluent tạo ra các biểu thức kiểu OData (`.eq()`, `.gt()`, `.and_()`, `.or_()`), hoặc bạn có thể truyền một chuỗi OData thô vào `list(filter=...)`. * **Thăm dò tác vụ** — các thao tác bất đồng bộ trả về một tham chiếu tác vụ; `client.tasks.wait(task_id, timeout=...)` chặn cho đến khi hoàn tất và ném `TaskTimeoutError` khi hết thời gian chờ. * **Ngữ cảnh tenant** — `tenant.connect()` trả về một client nằm trong phạm vi tenant, vì vậy cùng một script có thể điều khiển hệ thống host và bất kỳ tenant con nào mà không cần kết nối lại tới một endpoint khác. {% endhint %} ## Tài nguyên bổ sung * [Kho lưu trữ GitHub](https://github.com/verge-io/pyvergeos) — Mã nguồn, vấn đề và đóng góp * [Gói PyPI](https://pypi.org/project/pyvergeos/) — Bản phát hành mới nhất và lịch sử phiên bản * [Tài liệu VergeOS API](/knowledge-base/vi/automation-api/verge-api-guide.md) --- # 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/02-python-sdk.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.