文档中心开发者

OpenAPI 快速上手

OpenAPI 供脚本与服务器间调用,无需登录态。主账户在「账号安全 → OpenAPI 密钥」可自助签发只读密钥(上限 5 把); 需要全功能密钥(含实例电源操作)请提交工单申请,由管理员签发。

密钥由两部分组成:AccessKey(uak_ 前缀,请求时明文携带)和 Secret(仅签发时展示一次, 只存在你手里,平台无法找回)。认证方式为 HMAC-SHA256 请求签名。

基础地址

https://heyiwei.com.cn/api/v1/openapi

认证请求头

X-Access-KeyAccessKey(uak_ 前缀)
X-TimestampUnix 秒级时间戳,须在服务器时间 ±300 秒内
X-Nonce8~64 位随机串,同一时间窗内不可重复(防重放)
X-SignatureHMAC-SHA256 签名结果,HEX 小写

签名串构造

以下五部分用换行符 \n 拼接后,以 Secret 为密钥计算 HMAC-SHA256,HEX 小写编码即签名:

timestamp + "\n" + nonce + "\n" + METHOD + "\n" + path_with_query + "\n" + HEX(SHA256(body))
  • METHOD 为大写 HTTP 方法(GET / POST);
  • path_with_query 为 URL 路径,带查询参数时追加 ?原始查询串,如 /api/v1/openapi/instances?page=1;
  • body 为原始请求体;GET 请求无 body,取空字节的 SHA256(e3b0c442…);
  • JSON 请求体须与实际发送的字节完全一致(建议固定 json.dumps 序列化后再签名与发送)。

Python 示例

# 依赖:Python 3.8+,pip install -U requests
import hashlib, hmac, json, time, uuid

import requests

BASE = "https://heyiwei.com.cn"
ACCESS_KEY = "uak_xxxxxxxx"     # 账号安全 → OpenAPI 密钥页签发
SECRET = "签发时展示的 Secret"   # 仅签发时展示一次,妥善保管

def call(method, path, body=None):
    """签名并发起一次调用:HTTP 层失败抛 HTTPError,业务失败抛 RuntimeError,
    成功返回响应里的 data 字段(dict / list)。"""
    raw = json.dumps(body).encode() if body is not None else b""
    ts = str(int(time.time()))                    # 秒级时间戳,±300 秒内有效
    nonce = uuid.uuid4().hex                      # 每次请求唯一的随机串(防重放)
    body_hash = hashlib.sha256(raw).hexdigest()   # GET 无 body 时是空串的哈希
    payload = "\n".join([ts, nonce, method, path, body_hash])
    sign = hmac.new(SECRET.encode(), payload.encode(), hashlib.sha256).hexdigest()
    headers = {
        "X-Access-Key": ACCESS_KEY,
        "X-Timestamp": ts,
        "X-Nonce": nonce,
        "X-Signature": sign,                      # HMAC-SHA256 结果,HEX 小写
    }
    if body is not None:
        headers["Content-Type"] = "application/json"
    resp = requests.request(method, BASE + path, data=raw, headers=headers, timeout=15)
    resp.raise_for_status()                       # 429 限流、5xx 在此抛出
    result = resp.json()
    if result.get("code") != 0:                   # 401:签名/时间窗/Nonce 问题
        raise RuntimeError(f"调用失败:{result.get('message')}")
    return result["data"]

# 查询示例:解析后按需取字段输出,不要整包打印
account = call("GET", "/api/v1/openapi/account")
print(f"账户 {account['username']} 余额 {account['balance']:.2f} 元")

for ins in call("GET", "/api/v1/openapi/instances"):
    # memory 单位是 MB,disk 单位是 GB
    print(f"{ins['name']}  {ins['status']}  {ins['ip_address']}  "
          f"{ins['cpu']}C / {ins['memory'] // 1024}G / {ins['disk']}G")

限流与错误

  • 每把密钥 120 次/分钟,超限返回 429;
  • 成功响应:{"code": 0, "message": "ok", "data": …};失败响应:{"code": <HTTP状态码>, "message": "原因"};
  • 常见 401 原因:缺少认证头、时间戳超窗(校准时钟)、Nonce 重复(疑似重放)、签名不匹配(对照签名串逐段核对,注意 body 序列化一致)。
Secret 泄露请立即在「账号安全 → OpenAPI 密钥」吊销该密钥并重新签发。
这篇文章没有解决你的问题?提交工单,客服会尽快回复你。
提交工单