API使用帮助

ShineMonitor光伏监控开放平台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)

请求: http://api.shinemonitor.com/public/?sign=675bd5418fce7be5e30b920a16a46ce075c90a35&salt=1491967716993&action=auth&usr=vplant&company-key=0123456789ABCDEF

  • URI前缀:

      固定为: http://api.shinemonitor.com/public/
    
  • URI参数:

  • sign

      签名, 计算方式为: sign = SHA-1(salt + SHA-1(pwd) + "&action=auth&usr=" + usr + "&company-key=" + company-key);
      经过SHA-1摘要算法后的结果总是以小写16进制字符串的形式表现, 如上面的sign: 675bd5418fce7be5e30b920a16a46ce075c90a35
    
  • salt

      盐值, 参与签名计算, 长度不小于8个字节的可读字符串, 如: "12345678", 可使用当前系统时间, 如: javascript中的new Date().getTime(), 或java语言中的System.currentTimeMillis(), 等等.
    
  • action

      要调用的API接口.
    
  • usr

      平台分配的账号.
    
  • company-key

      平台分配的厂家标识.
    

响应:

{
    "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总是类似于如下格式:

请求: http://api.shinemonitor.com/public/?sign=f0c57c88bdd73a1867355068e9e3c49d735ae668&salt=1491967717697&token=88d22d819e31897eea2d9d5b9f7792cf4065ac5372aad3672f5e4e147cd25b5f&action=queryCollectorInfo&pn=G0916522248153

URI总是由以下几个部分组成:

  • URI前缀:

      固定为: http://api.shinemonitor.com/public/
    
  • URI参数:

  • sign

      签名, 计算方式为: sign = SHA-1(salt + secret + token + "&action=...");
      即盐值(见下文)加上通过认证接口获得的secret和token, 再加上"&action"及其后面的所有参数部分, 再经过SHA-1摘要算法计算得出.
    
  • salt

      同认证接口中的slat.
    
  • token

      通过认证接口获得的令牌.
    
  • action

          要调用的API接口.
    
  • 参数部分

      参数部分是可选的, 这取决于要调用的action(API)是否需要传递参数.
    

需要注意的是: "&action"及其参数部分总是位于sign, slat, token参数之后.


响应, 与认证接口类似, 也是返回一个JSON格式的对象, 由以下部分组成:

  • err

      错误码, 整数形式.
    

    参见通用错误码.

  • desc

      错误码的简单描述.
    

    参见通用错误码.

  • dat

      响应的正文部分, 这部分是可选的, 这取决于调用的API类型, 如下就是一个无dat的响应:
    
          {"err":0,"desc":"ERR_NONE"}
    

3. 例子

java语言例子