> 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/zh/automation-api/api-helper-script.md).

# API 辅助脚本

该 `yb-api` 辅助脚本为开发人员提供了一种轻松与 VergeOS API 交互的方式。它简化了 API 调用，例如检索虚拟机、更新配置和管理资源。本指南将概述该 `yb-api` 脚本。

## 前提条件

* 可访问 VergeOS 系统。
* 可通过 SSH 或直接连接访问集群。
* **wget** 以及 **curl** 必须安装在系统上，才能执行某些操作。

### 运行辅助脚本

如需获取帮助或查看可用选项，请运行：

```bash
yb-api --help
```

连接到节点并执行此命令，即可开始使用 API 辅助脚本。

![yb-api 示例](/files/aede35717f9c7821bc180a38c9d46f5441dc1299)

## 示例命令

以下是如何使用 `yb-api` 来执行各种虚拟机管理任务的示例。

### 获取虚拟机列表（不包括快照）

检索虚拟机列表并过滤掉快照。

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

### 所有虚拟机的简单导出

该命令会检索所有虚拟机的列表。 `--server`, `--user`, `--filter`，并 `--fields` 在这种情况下，这些标志是可选的。

```bash
yb-api --get /v4/vms
```

### 获取虚拟机详细信息

检索特定虚拟机的大部分字段，包括磁盘和 NIC 信息（此处为 VM 1）。

```bash
yb-api --get --user=admin --server=10.0.0.100 \\
--fields='most,machine[most,drives[most],nics[most]]' /v4/vms/1
```

### 重命名虚拟机

将现有虚拟机（VM 1）的名称更改为“NEWNAME”。

```bash
yb-api --put='{"name":"NEWNAME"}' --user=admin --server=10.0.0.100 /v4/vms/1
```

### 删除虚拟机

删除特定虚拟机（VM 1），使用其 `$key`.

```bash
yb-api --delete --user=admin --server=10.0.0.100 \\
--fields='name,$key,ram' /v4/vms/1
```

### 创建新的虚拟机

使用特定配置（名称、CPU 核心、RAM 等）创建新的虚拟机。

```bash
yb-api --post='{"name":"NEWVM","enabled":true,"description":"test vm",\
"os_family":"linux","cpu_cores":4,"ram":"8192"}' --user=admin \\
--server=10.0.0.100 /v4/vms
```

### 获取虚拟机数据库表结构

检索虚拟机数据库表的结构。

```bash
yb-api --get --user=admin --server=10.0.0.100 '/v4/vms/$table'
```

### 克隆虚拟机

克隆现有虚拟机（VM 1）并为其指定新名称。

```bash
yb-api --get --user=admin --server=10.0.0.100 '/v4/vm_actions' \\
--post='{"vm":1, "action": "clone", "params": {"name": "NEW VM NAME"}}'
```

### 启动虚拟机

启动现有虚拟机（VM 1）。

```bash
yb-api --get --user=admin --server=10.0.0.100 '/v4/vm_actions' \\
--post='{"vm":1, "action": "poweron"}'
```

## 注意事项 `yb-api`

* 该 `yb-api` 脚本依赖于 **wget**，它可能未在 macOS 上默认安装。如有必要，请确保安装它。
* **curl** 在某些 API 调用中用于上传功能，例如在创建新虚拟机时提交数据。

***

辅助脚本，开发人员可以简化与 VergeOS API 的交互，并更高效地管理虚拟机。如果您需要更多命令或选项方面的帮助，请告诉我们。 `yb-api` 辅助脚本，开发人员可以简化与 VergeOS API 的交互，并更高效地管理虚拟机。如果您需要更多命令或选项方面的帮助，请告诉我们。

***

{% hint style="info" %}
**文档信息**

* 最后更新：2024-08-29
* 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/zh/automation-api/api-helper-script.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.