# 使用管理 API：从只读查询开始

API 密钥通常具有管理实例的能力，应像服务器密码一样保护。第三方手机工具或脚本接入前，要确认它会保存和传输哪些信息。

更新日期：2026-09-16

规范地址：https://stock.iftalking.com/guides/kiwivm-api/

## 1. API 适合做什么，先从只读查询开始

KiwiVM API 可用于读取实例信息、统计流量和管理实例任务。它管理的是 VPS，不是网站账户的普通登录接口。API 密钥可能拥有停止、重装或恢复磁盘等高权限，不能放进网页前端、公开代码仓库或在线调试网站。

先在服务商账户中进入**目标实例**的 KiwiVM，再打开 API 菜单。核对实例编号 VEID、密钥显示入口、接口地址和该页当前文档。每台实例的凭据应分开保存，避免把 A 实例的 VEID 与 B 实例的密钥配在一起。

![从实例面板进入 API 菜单，先核对所选实例](https://stock.iftalking.com/tutorial-media/provider-kiwivm-overview.jpg)

*图示说明：服务商官方知识库公开截图（旧版界面），用于对照功能名称；当前菜单位置可能调整。图中的套餐、IP、端口和日期仅为示例。*

## 2. 复制接口文档，不复制带密钥的网址

面板通常列出 `getServiceInfo`、`getLiveServiceInfo` 等查询方法，以及启动、停止、快照等写操作。首次只选查询方法，核对当前文档允许的请求方式和参数。

不要把包含 API Key 的 GET 地址收藏到浏览器，URL 可能进入历史记录或代理日志。若文档支持 POST 表单，可把参数放在请求体中；这仍需要 HTTPS，并不意味着可以随意打印请求内容。

## 3. 用 Python 发起一次受控查询

把以下代码保存为本机的 `query_vps.py`。它会交互读取面板给出的只读接口地址、VEID 和密钥，不把密钥写进源文件；先确认接口属于服务商，再输入凭据。示例按常见的 `veid`、`api_key` 表单参数和 `error` 返回字段编写，使用前与自己的 API 页面核对。

```python
import getpass
import json
import urllib.parse
import urllib.request

endpoint = input('粘贴面板中的 HTTPS 只读查询接口：').strip()
url = urllib.parse.urlsplit(endpoint)
if url.scheme != 'https' or url.hostname != 'api.64clouds.com':
    raise SystemExit('请核对服务商接口域名，不向其他地址发送密钥')
if url.path != '/v1/getServiceInfo' or url.query:
    raise SystemExit('本示例只允许 getServiceInfo，且地址不带查询参数')
veid = input('VEID：').strip()
key = getpass.getpass('API Key：')
body = urllib.parse.urlencode({'veid': veid, 'api_key': key}).encode()
request = urllib.request.Request(endpoint, data=body, method='POST')
with urllib.request.urlopen(request, timeout=30) as response:
    result = json.load(response)
if result.get('error') != 0:
    raise SystemExit('接口未成功，请核对凭据、权限和面板中的错误说明')
print('查询成功')
for name in ('hostname', 'vm_type', 'plan_ram', 'plan_disk'):
    if name in result:
        print(name, result[name])
```

不要把完整返回数据公开粘贴；其中可能包含 IP、实例配置和其他运维信息。网络异常应显示失败，不能用上一条成功记录冒充刚刚查询结果。

## 4. 自动化时保存时间并控制请求频率

轮询程序应有超时、有限重试和失败退避，遵守面板当前的速率限制。分别保存“最后成功查询时间”和“本次尝试时间”，接口失败时保留旧值并标记时间，避免误导使用者。

流量字段的单位和重置时间格式以文档为准；字节与 GB/GiB 的换算要一致。不要每秒查询所有实例，也不要用重启接口验证密钥是否正确。

## 5. 导出与撤销密钥

账户中的“导出全部服务及私有 API Key”文件可能包含所有实例的高权限凭据。只在确有批量管理需求时导出，存放在加密位置，限制文件权限，不能上传到聊天群或普通表格分享链接。

更换密钥后逐个更新任务并做只读验证，再撤销旧密钥。第三方手机管理工具需要输入 API Key 时，先了解其保存和同步方式。重装、停止、恢复快照等操作应有单独确认和审计，不与普通状态查询按钮混在一起。


## 完成后检查

本文不固定接口名称和参数。按官方面板当时提供的 API 文档调用，避免沿用失效示例。

## 参考资料

- [服务商官方说明](https://bandwagonhost.com/knowledgebase.php)
- [服务商官方说明](https://bandwagonhost.com/kb.php?action=displayarticle&id=30)