Open API 使用文档

1. 概述

1.1 什么是 Open API

共绩算力 Open API 是一套 RESTful 接口，用于以编程方式管理算力资源与弹性部署任务，支持自动化运维与第三方系统集成。

典型应用场景：

• CI/CD 流水线中自动创建、启停弹性服务服务
• 批量查询任务状态与节点信息
• 查询租户账单

1.2 基础信息

项目	说明
API 基址	https://openapi.suanli.cn
协议	HTTPS
数据格式	JSON（Content-Type: application/json）
字符编码	UTF-8
接口版本	各接口独立版本，当前多为 1.0.0，以 Apifox 文档为准

1.3 版本说明

版本类型	示例	说明
API 接口版本	1.0.0	请求头 version 字段值，按接口文档填写
时间戳	毫秒级 Unix 时间戳	如 1770194570564

注意：请求头 version 请使用接口文档中的版本号（通常为 1.0.0），而非平台功能版本号。

1.4 统一响应格式

所有接口返回统一的 JSON 结构：

{
  "code": 0000,
  "msg": "success",
  "data": { }
}

字段	类型	说明
code	number	0000 表示成功，非 0000 表示失败
msg	string	结果描述信息
data	object	业务数据，结构因接口而异

---

2. 快速开始

以下流程可在约 5 分钟内完成首次 API 调用验证。

步骤 1：获取 API 密钥

1. 登录 共绩算力控制台
2. 进入 API 密钥管理
3. 点击「新建密钥」，选择 Token 模式（适合首次调试）
4. 填写备注后生成，立即复制并妥善保存 Token

⚠️ 密钥仅在创建时展示一次，丢失后需重新创建。

步骤 2：在线调试验证

1. 打开 Open API 接口文档
2. 选择任意接口（如「资源列表查询」），点击「调试」
3. 在 Header 中配置：

Header	值	说明
token	您的 API 密钥	步骤 1 获取
version	1.0.0	接口版本，使用调试页默认值
timestamp	当前毫秒时间戳	使用调试页自动生成值

1. 点击「发送」，确认返回 code: 0000

步骤 3：代码调用（可选）

参见 第 6 节代码集成示例。

---

3. API 密钥管理

3.1 密钥模式对比

对比项	Token 模式	RSA 签名模式
别名	快速模式	RSA 模式
创建要求	仅需填写备注	需填写备注 + RSA 公钥
调用方式	Header 携带 Token	Header 携带 Token + RSA 签名
安全等级	中等	高
适用场景	开发调试、内部简单集成	生产环境、高安全要求场景
签名算法	无需签名	RSA-SHA256 + Base64

3.2 模式选择建议

开发/测试环境  →  Token 模式（快速验证）
生产环境       →  RSA 签名模式（防篡改、防重放）

3.3 密钥创建流程

Token 模式：

1. 控制台 → API 密钥管理 → 新建密钥
2. 选择「Token 模式」
3. 填写备注 → 生成 → 立即复制 Token

RSA 签名模式：

1. 本地生成 RSA 密钥对（见 RSA 模式使用指南）
2. 控制台 → 新建密钥 → 选择「RSA 加验签模式」
3. 粘贴公钥内容（-----BEGIN PUBLIC KEY----- 至 -----END PUBLIC KEY-----）
4. 生成后妥善保管私钥

3.4 团队账号与权限

使用团队账号时，仅 团队主账号 和 团队管理员 拥有密钥管理权限。开发者角色可调用 API，但无法在控制台创建或删除密钥。详见 团队账号常见问题。

---

4. 鉴权机制

所有 API 请求均需在 HTTP Header 中携带鉴权参数。

4.1 Token 模式鉴权

适用于开发调试，无需签名。

必需 Header：

Header	类型	必填	说明
token	string	是	API 密钥
version	string	是	接口版本，如 1.0.0
timestamp	string	是	毫秒级 Unix 时间戳

请求示例：

GET /api/deployment/resource/search HTTP/1.1
Host: openapi.suanli.cn
Content-Type: application/json
token: your-api-token-here
version: 1.0.0
timestamp: 1770194570564

4.2 RSA 签名模式鉴权

适用于生产环境，需在 Token 模式基础上增加签名。

必需 Header：

Header	类型	必填	说明
token	string	是	API 密钥
version	string	是	接口版本
timestamp	string	是	毫秒级时间戳
sign_str	string	是	RSA-SHA256 签名（Base64 编码）

签名规则摘要：

1. 构建待签名字符串（字段以换行符 \n 连接）：

{uri}\n{version}\n{timestamp}\n{token}\n{body}

字段	说明
uri	接口路径，如 /api/deployment/task/search
version	接口版本，如 1.0.0
timestamp	毫秒级时间戳
token	API 密钥
body	请求体 JSON 字符串；GET 请求或无 Body 时为空字符串 ""

1. 使用 RSA 私钥 + SHA-256 + PKCS1v15 填充进行签名
2. 对签名结果进行 Base64 编码，写入 Header sign_str

完整签名规则、密钥生成及 Python 示例代码，请参阅 Open API RSA 模式使用指南。

4.3 接口加密说明

部分接口支持请求体 RSA 加密（创建任务等敏感操作）。是否加密以 Apifox 接口文档中的「是否需要加密」字段为准。加密后的 Body 同样参与签名计算。

---

5. 在线调试

5.1 调试入口

资源	链接
在线接口文档	https://s.apifox.cn/6aa360d3-d8f2-471e-b841-3a35c33a7b7c
API 密钥管理	https://console.suanli.cn/settings/key

5.2 调试步骤

1. 打开 Apifox 文档，选择目标接口
2. 点击「调试」进入在线调试面板
3. 配置 Header 鉴权参数（token、version、timestamp）
4. 如需 RSA 签名，按 RSA 指南生成 sign_str 并填入
5. 填写 Query / Body 参数
6. 点击「发送」，查看响应

5.3 调试建议

• 首次集成建议从 GET 类查询接口 开始（如资源列表、任务列表）
• 使用 Apifox 的「自动生成代码」功能导出 curl、Python、Go 等语言示例
• 鉴权失败时，优先核对 timestamp 是否为毫秒级、服务器时间是否同步

---

6. 代码集成示例

6.1 cURL 示例（Token 模式）

curl -X GET "https://openapi.suanli.cn/api/deployment/resource/search" \
  -H "Content-Type: application/json" \
  -H "token: your-api-token-here" \
  -H "version: 1.0.0" \
  -H "timestamp: $(date +%s000)"

6.2 Python 示例（Token 模式）

import time
import requests

BASE_URL = "https://openapi.suanli.cn"
API_TOKEN = "your-api-token-here"

headers = {
    "Content-Type": "application/json",
    "token": API_TOKEN,
    "version": "1.0.0",
    "timestamp": str(int(time.time() * 1000)),
}

response = requests.get(
    f"{BASE_URL}/api/deployment/resource/search",
    headers=headers,
)

print(response.json())

6.3 Java 示例（Token 模式）

需要 Java 11 及以上版本（使用 java.net.http.HttpClient）。

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class OpenApiExample {

    private static final String BASE_URL = "https://openapi.suanli.cn";
    private static final String API_TOKEN = "your-api-token-here";
    private static final String API_VERSION = "1.0.0";

    public static void main(String[] args) throws Exception {
        String timestamp = String.valueOf(System.currentTimeMillis());
        String url = BASE_URL + "/api/deployment/resource/search";

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("Content-Type", "application/json")
                .header("token", API_TOKEN)
                .header("version", API_VERSION)
                .header("timestamp", timestamp)
                .GET()
                .build();

        HttpResponse<String> response = client.send(
                request, HttpResponse.BodyHandlers.ofString());

        System.out.println("Status: " + response.statusCode());
        System.out.println("Body: " + response.body());
    }
}

6.4 Go 示例（Token 模式）

package main

import (
    "fmt"
    "io"
    "net/http"
    "time"
)

const (
    baseURL    = "https://openapi.suanli.cn"
    apiToken   = "your-api-token-here"
    apiVersion = "1.0.0"
)

func main() {
    url := baseURL + "/api/deployment/resource/search"
    timestamp := fmt.Sprintf("%d", time.Now().UnixMilli())

    req, err := http.NewRequest(http.MethodGet, url, nil)
    if err != nil {
        panic(err)
    }

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("token", apiToken)
    req.Header.Set("version", apiVersion)
    req.Header.Set("timestamp", timestamp)

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println("Status:", resp.StatusCode)
    fmt.Println("Body:", string(body))
}

6.5 RSA 签名模式

RSA 模式需实现签名逻辑、完整代码与说明见 Open API RSA 模式使用指南。

---

7. 安全最佳实践

7.1 密钥管理

实践	说明
立即保存	密钥创建后仅展示一次，请立即复制至密钥管理系统
环境隔离	开发、测试、生产使用不同密钥，禁止混用
最小权限	团队场景下，仅授权必要角色管理密钥
定期轮换	建议每 90 天轮换生产环境密钥
禁止硬编码	密钥通过环境变量或密钥管理服务注入，勿写入代码仓库

7.2 密钥泄露处置

1. 立即在控制台删除泄露的密钥
2. 创建新密钥并更新应用配置
3. 排查访问日志，确认是否有异常调用
4. 如涉及生产环境，评估是否需要轮换关联资源

7.3 传输安全

• 所有 API 调用必须使用 HTTPS
• 生产环境建议使用 RSA 签名模式
• 确保服务器时间与 NTP 同步，避免时间戳校验失败

---

8. 常见问题

Q1：鉴权失败，返回签名错误？

请按以下顺序排查：

1. timestamp 是否为毫秒级（13 位数字）
2. version 是否与接口文档一致（通常为 1.0.0）
3. 待签名字符串字段顺序是否为 uri → version → timestamp → token → body
4. RSA 模式下，body 为空时是否使用空字符串 "" 参与签名
5. 服务器时间是否与标准时间同步（偏差建议 < 5 分钟）

Q2：Token 模式和 RSA 模式可以混用吗？

不可以。创建密钥时选定模式后，调用方式需与该模式一致。RSA 模式密钥必须使用签名；Token 模式密钥无需签名。

Q3：密钥丢失怎么办？

平台不保存 Token 明文，私钥由用户自行保管。丢失后只能在控制台删除旧密钥并重新创建，同时更新所有集成方的配置。

Q4：团队开发者能否创建 API 密钥？

不能。仅团队主账号和团队管理员拥有密钥管理权限。开发者可使用已有密钥进行 API 调用。

Q5：接口是否有调用频率限制？

具体限流策略以平台当前政策为准。如遇 429 或限流相关错误，请实现指数退避重试，或联系技术支持提升配额。

---

9. 相关文档

文档	说明	链接
Open API RSA 模式使用指南	密钥生成、签名算法、Python 示例	Open API RSA 模式使用指南
Open API 接口文档	接口参数、在线调试、代码生成	https://s.apifox.cn/6aa360d3-d8f2-471e-b841-3a35c33a7b7c
团队账号常见问题	角色权限、密钥管理权限	https://suanli.cn/docs/platform/team-account/bpcxwi8vviqxylk677tcpfwqnkf/
平台使用常见问题	通用平台问题	https://suanli.cn/docs/platform/faq/