创蓝OM2.0 通用请求头与返回码定义

通用请求头

所有的API均需鉴权，即在Header中携带以下信息：

参数名称	类型	必填	描述
Content-Type	String	是	请求体的数据类型。例如 application/json、charset=utf-8。
AppID	String	是	通过控制台->账号中心->API Key 获取
Nonce	String	是	随机数（最大长度 128 个字符）。
CurTime	String	是	当前 UTC 时间戳，从 1970 年 1 月 1 日 0 时 0 分 0 秒开始到 现在 的秒数。该时间用于计算 CheckSum 的有效期，请确保与标准时间同步。
CheckSum	String	是	SHA1(AppSecret + Nonce + CurTime)，将该三个参数拼接的字符串进行 SHA1 哈希计算从而生成 16 进制字符（小写）。 - 出于安全性考虑，每个 CheckSum 的 有效期 为 5 分钟，即服务端接收到请求的时间与请求中的 CurTime 相差不能超过 5 分钟，建议每次请求都生成新的 CheckSum，同时 请确认 发起请求的服务器是与标准时间同步的。 - CheckSum 检验失败时会code返回 "120001" 错误码。
X-Custom-TraceId	String	否	开发者填入的自定义标识，用于与开发者业务服务器中的请求中的上下游请求关联，该由用户自定义和使用

签名生成案例（java代码）：

复制成功
package com.chuanglan.gateway.utils;

import org.apache.commons.codec.digest.DigestUtils;
import org.apache.commons.lang3.StringUtils;
import org.apache.commons.lang3.math.NumberUtils;

import java.util.HashMap;
import java.util.Map;
import java.util.UUID;

public class SignUtils {

    private static final long *DEFAULT_EXPIRE_MILLIS *= 5 * 60 * 1000L;

    public static Map<String, String> generateSign(String appSecret) {
        String nonce = UUID.*randomUUID*().toString();
        String curTime = String.*valueOf*(System.*currentTimeMillis*());
        *validateParams*(appSecret, nonce, curTime);
        String signStr = appSecret + nonce + curTime;
        String sign = DigestUtils.*sha1Hex*(signStr).toUpperCase();
        Map<String, String> map = new HashMap<>();
        map.put("sign", sign);
        map.put("nonce", nonce);
        map.put("curTime", curTime);
        return map;
    }

    public static String generateSign(String appSecret, String nonce, String curTime) {
        *validateParams*(appSecret, nonce, curTime);
        String signStr = appSecret + nonce + curTime;
        return DigestUtils.*sha1Hex*(signStr).toUpperCase();
    }

    public static String generateSign(String appSecret, String nonce, long curTime) {
        return *generateSign*(appSecret, nonce, String.*valueOf*(curTime));
    }

    public static boolean verifySign(String appSecret, String nonce, String curTime, String sign) {
        return *verifySign*(appSecret, nonce, curTime, sign, *DEFAULT_EXPIRE_MILLIS*);
    }

    public static boolean verifySign(String appSecret, String nonce, String curTime, String sign, long expireMillis) {
        if (StringUtils.*isBlank*(sign)) {
            return false;
        }
        try {
            *validateParams*(appSecret, nonce, curTime);
        } catch (IllegalArgumentException e) {
            return false;
        }
        if (!*isCurTimeValid*(curTime, expireMillis)) {
            return false;
        }
        String generateSign = *generateSign*(appSecret, nonce, curTime);
        return generateSign.equalsIgnoreCase(sign);
    }

    private static boolean isCurTimeValid(String curTime, long expireMillis) {
        if (!NumberUtils.*isDigits*(curTime)) {
            return false;
        }
        long curTimeLong;
        try {
            curTimeLong = Long.*parseLong*(curTime);
        } catch (NumberFormatException e) {
            return false;
        }
        long now = System.*currentTimeMillis*();
        return (curTimeLong >= now - expireMillis) && (curTimeLong <= now + expireMillis);
    }

    private static void validateParams(String appSecret, String nonce, String curTime) {
        if (StringUtils.*isBlank*(appSecret)) {
            throw new IllegalArgumentException("AppSecret不能为空");
        }
        if (StringUtils.*isBlank*(nonce)) {
            throw new IllegalArgumentException("Nonce不能为空");
        }
        if (StringUtils.*isBlank*(curTime)) {
            throw new IllegalArgumentException("CurTime不能为空");
        }
    }

    public static void main(String[] args) {
        String appId     = "your_app_id";
        String appSecret = "your_app_secret";

        Map<String, String> result = *generateSign*(appSecret);

        System.*out*.println("AppID:    " + appId);
        System.*out*.println("Nonce:    " + result.get("nonce"));
        System.*out*.println("CurTime:  " + result.get("curTime"));
        System.*out*.println("CheckSum: " + result.get("sign"));
    }
}

通用code码

状态码 (code)	描述 (msg)	解决方案 (solution)
000000	success
120001	signature verification failed	验签失败
120401	invalid token	token过期，请联系客服人员
120301	request header is missing AppID or incorrect	AppID有误，请联系客服人员
120302	missing parameters in message header	请检查请求头参数是否缺失
120403	insufficient allocated permissions	权限不足，请联系客服人员
120504	signature expired	签名失效，请核对签名有效时间5分钟
190001	request failed	请求失败，请联系客服人员
190004	invalid parameter	参数错误
190403	forbidden	添加IP白名单