EasyOpenAPI产品作为所有子服务开放API的统一管理服务,对于子服务开放的API进行统一管理和调用,达到用户使用同一套标准可以调用不同子服务的API,提升开发效率,满足更多元化的业务场景需要。

该文档为调用接口时的通用规范,对所有OpenAPI都适用,必读!OpenAPI列表与详情请查看OpenAPI目录下各个子产品的OpenAPI文档说明。

一、调用相关

1.1 支持协议与请求

所有OpenAPI仅支持HTTP协议,支持的请求为GET、POST。

1.2 请求地址

请求地址由三个部分组成,分别是openapi统一入口域名、子产品调用前缀、子产品功能URI。例如:

http://easy-openapi.bdms.service.163.org/openapi/easydataservice/api/v1/app/get

其中http://easy-openapi.bdms.service.163.org 为统一入口域名,/openapi/必写,easydataservice为需要调用的子产品名,/api/v1/app/get为子产品功能URI。其中子产品调用前缀部分里的子产品名称参考1.2.2响应码中的子产品对照表,子产品功能URI请参考每个子产品详细调用文档。

PS: easyops环境中的统一入口域名获取方式,可打开easyops界面,找到EasyOpenAPI项目打开url,新开页面的地址前缀即为统一入口域名。

OpenAPI通用规范说明 - 图1

OpenAPI通用规范说明 - 图2

1.3 请求参数

  • GET请求:

当调用的接口为GET方法时,请求参数只能放置在调用地址的URL中。


http://easy-openapi.bdms.service.163.org/openapi/easydataservice/app/v1/app/get?user=user@163.com&product=product1&appName=app1&authType=AKSK&timestamp=xxxxx&accessKey=yyyyy&sig=zzzzzz
  • POST请求:

当调用的接口为POST方法时,请求参数只能以json格式(请求头中需要指定Content-Type: application/json)放置在Request Body。


http://easy-openapi.bdms.service.163.org/openapi/easydataservice/api/v1/app/add -d '{"user": "user@163.com", "product": "product1", "appName": "app1", "appDesc":"xxxxxxxxxxxx", "authType":"AKSK", "timestamp":1232423123, "accessKey":"yyyyy", "sig":"zzzzzz"}'
{
    "参数1""值1"
    "参数2""值2"
}

1.4 鉴权

目前支持的鉴权方式有:AK/SK。

  • AS/SK鉴权: 系统为调用者分别应用身份,每个应用都有唯一的accessKey和secretKey。在使用aksk鉴权方式时,需要在入参中携带authType(值为AKSK)、timestamp(5分钟内的毫秒时间戳)、accessKey、sig(由secretKey计算出)。

GET方法时,以上参数放在uri中,例如:


&authType=AKSK&timestamp=1646813499000&accessKey=
2709c24f97ce463c84b7ce9ee7a92212&sig=818dc0bb904cc75fa935cb96e0fc9473

POST方法时,以上参数放在request body里,例如:


{
    "authType":"AKSK",
    "timestamp":1646813499000,
    "accessKey":"2709c24f97ce463c84b7ce9ee7a92212",
    "sig":"818dc0bb904cc75fa935cb96e0fc9473"
}

其中sig的计算方法为:


sig = md5(secretKey+timestamp) 其中+号表示拼接操作,sig为小32

Java代码工具类:


public class MD5MsgDigest {

    /**
     * notice:认为raw string是utf8编码
     */
    public static String digest(String rawString) {
        return digest(rawString, "utf-8");
    }

    public static String digest(String rawString, String charset) {
        Charset cs = Charset.forName(charset);
        try {
            return compute(rawString, cs);
        } catch (Exception e) {
            return "";
        }
    }

    /**
     * Computes the MD5 fingerprint of a string.
     * 
     * @return the MD5 digest of the input <code>String</code>
     */
    private static String compute(String inStr, Charset charset) throws Exception {
        MessageDigest md5 = MessageDigest.getInstance("MD5");
        byte[] md5Bytes = md5.digest(inStr.getBytes(charset));
        return toHexString(md5Bytes);
    }

    public static String toHexString(byte[] bytes) {
        StringBuffer hexValue = new StringBuffer();
        for (int i = 0; i < bytes.length; i++) {
            int val = ((int) bytes[i]) & 0xff;
            if (val < 16) {
                hexValue.append("0");
            }
            hexValue.append(Integer.toHexString(val));
        }
        return hexValue.toString();
    }
}

//计算sig
Long timestamp = System.currentTimeMillis();
String sig = MD5MsgDigest.digest(secretKey+timestamp);

其他编程语言也有类似md5工具类,请自行查找。

1.5 文件上传接口

涉及到文件上传的openAPI,请求路径前缀上稍有区别,需在统一前缀openapi后加file-upload,如下所示:


http://{openapi域名}}/openapi/file-upload/{子产品调用前缀}/子产品功能URI}

文件上传接口的入参为multipart/form-data格式,不支持application/json。

1.6 文件下载接口

涉及到文件下载的openAPI,请求路径前缀上稍有区别,需在统一前缀openapi后加file-download,如下所示:


http://{openapi域名}}/openapi/file-download/{子产品调用前缀}/子产品功能URI}

文件流通过HttpServletResponse获取。

二、响应相关

2.1 响应格式

名称 类型 描述
code Number 响应码
reqId String 请求ID
cost Number 耗时,单位:ms
msg String 响应消息
result Object 响应结果

2.2 响应码

响应码 说明
0 请求成功
-1 服务器错误,空指针、数组越界等非业务逻辑抛出异常。
-2 非法请求,参数异常、参数格式错误等接口的请求非法性抛出的通用错误
-3 用户不在当前项目
-4 用户未登录(或者会话无效),且该接口需要登录
-5 加锁失败
-6 签名无效
-7 无可用项目
>=1000 后四位为具体业务异常码,具体请看子产品文档的响应码说明。前1~2为子产品编排,请看下表对照关系。例如返回21000,2表示easydmap,1000请查看easydmap文档说明

业务异常码前缀与子产品对照表

子产品编码 子产品功能URI 相关openAPI
1 mammut 离线开发,自助分析,数据管理等
2 easydmap 数据地图
3 easydataservice 数据服务
4 easymetahub 元数据中心
5 easyaac 统一登录果
6 easyaccess 安全中心
7 easyconsole 控制台
8 easyindex 指标系统
9 easydesign 模型设计
10 easydasset 数据治理360
11 easytag 标签工厂
12 easytaskops 任务运维
13 easycoop 流程协作
14 easytransfer 数据传输
15 bdmsmeta 平台元信息
16 easytest 数据测试
17 easystandard 数据标准
18 easydqc 数据质量
19 easyalert 报警系统
20 easystream 实时计算平台
21 easymetrics 指标平台