API使用帮助
DessMonitor储能监控开放平台API采用的是HTTP协议. 使用规范的HTTP响应代码来表示请求结果. 所有的API请求都会以规范友好的JSON对象格式返回.
如非特殊说明, 默认情况下API都使用HTTP-GET方式进行调用.
GET形式的API调用方法
1. 认证接口调用
在调用任何业务API之前, 都需要通过认证接口进行鉴权. 调用认证接口时需要提供由平台分配的usr(账号), pwd(密码), company-key(厂家标识), 一个典型的调用如下:
如测试账号(可用于测试接口):
usr: vplant
pwd: vplant
company-key: 0123456789ABCDEF(需使用平台分配的company-key)
URI前缀:
固定为: http://api.dessmonitor.com/public/URI参数:
sign
签名, 计算方式为: sign = SHA-1(salt + SHA-1(pwd) + "&action=authSource&usr=" + usr + "&company-key=" + company-key + "&source=" + source + "&_app_client_=" + _app_client_ + "&_app_id_=" + _app_id_ + "&_app_version_=" + _app_version_); 经过SHA-1摘要算法后的结果总是以小写16进制字符串的形式表现, 如上面的sign: 675bd5418fce7be5e30b920a16a46ce075c90a35salt
盐值, 参与签名计算, 长度不小于8个字节的可读字符串, 如: "12345678", 可使用当前系统时间, 如: javascript中的new Date().getTime(), 或java语言中的System.currentTimeMillis(), 等等.action
要调用的API接口.usr
平台分配的账号.company-key
平台分配的厂家标识.source
用于区分平台，1-储能，0-光伏.app_id
域名标识.app_version
应用版本号.app_client
平台区分，ios或android或web.
响应:
{
"err":0,
"desc":"ERR_NONE",
"dat":{
"secret":"ffa1655ee3726840822063a02ac5017795809b18",
"expire":604800,
"token":"88d22d819e31897eea2d9d5b9f7792cf4065ac5372aad3672f5e4e147cd25b5f",
"role":0
}
}
这是一个JSON格式的对象, 由以下部分组成:
err
错误码, 整数形式.见通用错误码.
desc
错误码的简单描述. 如: "desc":"ERR_NONE", 或者: "desc":"ERR_FORMAT(can not found devcode)", "()"中的内容是一段对于错误更详细的描述, 它是可选的, 可用于提示, 如: alert("can not found devcode.");见通用错误码.
dat.secret
这是一个由系统分配的具有有效期的secret, 在随后的业务API接口调用中使用.dat.expire
此次认证的过期时间, 单位是秒, 表示从即刻起, 经过expire秒后, 所获取的secret和token(见下文)都不再有效.dat.token
这是一个由系统分配的具有有效期的令牌, 它代表了认证者的身份, 在随后的业务API接口调用中使用.dat.role
当前账号类型.见账号类型.
2. 其它GET形式的API调用
除认证接口外, 任何其它GET形式接口调用的URI总是类似于如下格式:
URI总是由以下几个部分组成:
URI前缀:
固定为: http://api.dessmonitor.com/public/URI参数:
sign
签名, 计算方式为: sign = SHA-1(salt + secret + token + "&action=..."); 即盐值(见下文)加上通过认证接口获得的secret和token, 再加上"&action"及其后面的所有参数部分, 再经过SHA-1摘要算法计算得出.salt
同认证接口中的slat.token
通过认证接口获得的令牌.action
要调用的API接口.source
用于区分平台，1-储能，0-光伏.app_id
域名标识.app_version
应用版本号.app_client
平台区分，ios或android或web.参数部分
参数部分是可选的, 这取决于要调用的action(API)是否需要传递参数.
需要注意的是: "&action"及其参数部分总是位于sign, slat, token参数之后.
响应, 与认证接口类似, 也是返回一个JSON格式的对象, 由以下部分组成:
err
错误码, 整数形式.desc
错误码的简单描述.dat
响应的正文部分, 这部分是可选的, 这取决于调用的API类型, 如下就是一个无dat的响应:{"err":0,"desc":"ERR_NONE"}