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 调用验证。

获取 API 密钥

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

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

在线调试验证

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

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

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

代码调用（可选）

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

3. API 密钥管理

3.1 密钥模式对比

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

3.2 模式选择建议

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

3.3 密钥创建流程

Token 模式：

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

RSA 签名模式：

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

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 编码）

签名规则摘要：

构建待签名字符串（字段以换行符 \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 时为空字符串 `""`

使用 RSA 私钥 + SHA-256 + PKCS1v15 填充进行签名
对签名结果进行 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 调试步骤

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

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 密钥泄露处置

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

7.3 传输安全

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

8. 常见问题

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

请按以下顺序排查：

timestamp 是否为毫秒级（13 位数字）
version 是否与接口文档一致（通常为 1.0.0）
待签名字符串字段顺序是否为 uri → version → timestamp → token → body
RSA 模式下，body 为空时是否使用空字符串 "" 参与签名
服务器时间是否与标准时间同步（偏差建议 < 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
团队账号	角色权限、密钥管理权限	团队账号
弹性部署常见问题	计费、扩缩容、无状态部署	弹性部署常见问题