1、接入信息

1.1 请求地址

接口请求地址：subPath替换为每个接口地址。

节点	地址	请求示例
国内中央节点	https://castack-gncenter.cheersucloud.com/openapi/	https://castack-gncenter.cheersucloud.com/openapi/{subPath}
海外中央节点	https://castack-hwcenter.cheersucloud.com/openapi/	https://castack-hwcenter.cheersucloud.com/openapi/{subPath}

1.2 签名算法

请求头携带：X-ak:AK
URL必须系带时间戳和签名
示例：/openapi/v2/instance/page/list?time=1640494526&sign=*
time：单位秒，参与 sign 值的计算
sign：使用 AK、SK 和 time 配合对应加密算法计算而来
平台提供 AK 和 SK 给用户
加密算法：sha256，key=SK，加密代码示例如下

public static String ak = "f2fcddffd0de46da811414216c5b225c";
public static String sk = "a01d33f69000405cb3eb44143fa9cd11";

public static void main(String[] args) throws NoSuchAlgorithmException, InvalidKeyException {
    String url = "http://127.0.0.1:1800/openapi/v2/instance/page/list";
    LocalDateTime now = LocalDateTime.now();
    long data = now.toEpochSecond(ZoneOffset.UTC);
    String hmacSHA256 = BaseTest.hmacSHA256(sk, String.valueOf(data));
    String requestUrl = url + "?time=" + data + "&sign=" + hmacSHA256;

    HttpRequest request = HttpUtil.createPost(requestUrl)
        .header("Content-Type", "application/json")
        .header("cache-control", "no-cache")
        .header("X-ak", ak);

    Map<String, Object> map = new HashMap<>();
    map.put("pageNum", 1);
    map.put("pageSize", 10);
    request.body(JSON.toJSONString(map));

    // 发送请求并获取响应
    HttpResponse response = request.execute();
    System.out.println(response.body());
}


public static String hmacSHA256(String key, String data) throws NoSuchAlgorithmException, InvalidKeyException {
    // 获取一个 HMAC SHA-256 的 Mac 实例
    Mac mac = Mac.getInstance("HmacSHA256");

    // 创建一个 SecretKeySpec 实例
    SecretKeySpec secretKeySpec = new SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), "HmacSHA256");

    // 初始化 Mac 实例
    mac.init(secretKeySpec);

    // 执行 HMAC SHA-256 运算
    byte[] rawHmac = mac.doFinal(data.getBytes(StandardCharsets.UTF_8));

    // 将原始字节数组转换为十六进制字符串
    StringBuilder hexString = new StringBuilder();
    for (byte b : rawHmac) {
        String hex = Integer.toHexString(0xff & b);
        if (hex.length() == 1) {
            hexString.append('0');
        }
        hexString.append(hex);
    }

    return hexString.toString();
}

1.3 响应规范

响应格式:

参数名称	参数说明	是否返回	数据类型	描述
code	返回代码	是	interger(int32)	200表示响应成功
message	返回处理消息	是	string
timestamp	时间戳	可选	integer(int64)
traceId	请求处理ID	可选	string
result	返回数据对象，封装响应的具体的数据	是	object

http状态码:

状态码	说明	描述
200	OK	Result
201	Created
401	Unauthorized
403	Forbidden
404	Not Found

1.4 调用须知

以下所有请求调用需要在请求头中加上 X-ak和wrap, 并在url地址上加上时间 time 和验签值 sign

curl -X POST -H 'X-ak:3d17155dec2a4076ac8dbe500d53765c' -H 'wrap:false' -H 'Content-Type: application/json' http://192.168.130.241:1800/openapi/v2/instance/page/list?time=1720774436&sign=3bbf04e6c524bc028d543148ea55447cad066f896431980e01d80488d1212807 -d '{"pageNum":1,"pageSize":10,"projectId":"project_admin"}'

1.5 数据结构

默认返回：

{
    "body": {
        "result": {/*返回根据接口功能的数据*/
            ...
        },
        "traceId": "C91320230805160421278",
        "code": 200,
        "message": "操作成功",
        "timestamp": 1691222661324
    },
    "ret": {
        "code": 200, /*200表示成功，非200表示错误*/
        "msg": "操作成功"
    }
}

请求HEADER的wrap参数值为false时返回：

{
    "code":200, /*200表示成功，非200表示错误*/
    "message":"操作成功",
    "timestamp":1691222661324,
    "traceId":"C91320230805160421278",   
    "result":{/*返回根据接口功能的数据*/
        ...
    }
}