OpenAPI通用规范说明
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,新开页面的地址前缀即为统一入口域名。
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×tamp=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×tamp=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 | 指标平台 |
以上内容对您是否有帮助?