服务端 API
注意 本页面已停止维护,新上线智慧照明系统,功能更丰富:
便捷APP控制,一键配网,更好的用户体验与界面
语音控制对接,常见智能音箱对接,远控设备
固件功能丰富,如有需求可定制
概述
本文是 ESPush IoT 服务器的开发者接入手册,API 使用类似 REST API 风格描述,使用 HTTP 方式调用,使您尽快完成接入。
协议描述
domain,请求地址的HOST && PORT,应为 espush.cn,自行部署版本请自行处理;
api/server,固定值,照填即可;
class,具体调用方法URL,参考下文的接口列表;
params,公共请求参数,参考下文请求参数;
请求方式
公共请求头,公共请求参数有 Key,Timestamp,Sign三个,请将其置于 HTTP API 接口的请求头中。其中 Key 在产品管理中,Timestamp为本请求的unix时间戳,用于确认请求的有效期,以秒为单位,请求时间戳与服务器时间(北京时间)偏差大于7200秒则会被拒绝;Sign 串的计算方式见下文;
URL内参数,本文档部分接口URL中包含可变字段,如 /devices/:devid 接口中,devid 为URL内参数,需要对应填值,具体参考下文接口列表;
POST请求参数,对于本文档中的POST接口,传递的参数必须使用JSON格式,公共请求参数仍置于URL中,具体方式可参考下文的代码示例;
认证方式
请求使用公共参数Sign字段进行认证,Sign字段的具体生成步骤列举如下:
提取本次请求的方法,将其字符串(如GET、POST、DELETE等)记为M;
提取请求的URL信息中的PATH部分,意即整体URL中,去除了http://IP,去除了请求参数后的部分,如/api/server/devices即为请求的PATH,记为P;
提取公共请求参数Key与Timestamp,并按此固定排列key=%vtimestamp=%v,其中 %v 代表对应值,记为C;
提取Key对应的Password,记为字符串K;
组合以上所有结果,直接连接在一起,并取其小写字符表示,记为S,使用公式表达为 S=lower(M+P+C+K)
取字符串S的MD5,记为字符串R,R的小写表示即为最终的sign串,使用公式表达为 sign=lower(md5(lower(M+P+C+K)))
返回结果
API接口使用标准http返回码,只有2XX的返回才是正确的返回,下面是可能的返回码汇总
200,请求成功,具体请求结果参考响应内容json值;
400,多数情况下是请求参数错误,或请求不合法;
401,sign值计算错误,或APP已被删除;
404,设备或对应的APP信息不存在,将返回NotFound错误;
50X,服务器错误,服务器内部数据或逻辑有误,返回此错误;
接口列表
以下所有接口,均配置 CURL 请求示例,其示例的 APPKEY 与 PASSWORD 均为演示之用,请勿使用在自己的产品中。所有 CURL 命令,均在 Linux 操作系统中进行过测试,如果使用 windows 系统,请对应调整命令行中的特殊字符转义规则。如果使用了自行部署,请更换URL中的 Host 部分。
APPKEY:4836822619100005
PASSWORD:f784cfd3ea4a40af8df36c62d9d0f0de
设备列表
描述 获取所有已注册的设备ID列表
路径 /devices
方法 GET
参数 page, count
CURL 请求示例
curl -X GET https://espush.cn/api/server/devices -H "Key: 4836822619100005" -H "Timestamp: 1529051966" -H "Sign: 123123123123"
设备详细信息查询
描述 获取指定设备详细信息
路径 /devices/:deviceid
方法 GET
参数 无
CURL 请求示例
curl -X GET https://espush.cn/api/server/devices -H "Key: 4836822619100005" -H "Timestamp: 1529051966" -H "Sign: 123123123123"
更新设备信息
描述 为设备更名,或禁用/恢复设备
路径 /devices/:deviceid
方法 PUT
参数 无
CURL 请求示例
curl -X GET https://espush.cn/api/server/devices -H "Key: 4836822619100005" -H "Timestamp: 1529051966" -H "Sign: 123123123123"
获取设备数据
描述 获取设备上行的数据,需要传入分页参数
路径 /up/messages
方法 GET
参数 无
CURL 请求示例
curl -X GET https://espush.cn/api/server/devices -H "Key: 4836822619100005" -H "Timestamp: 1529051966" -H "Sign: 123123123123"
为设备下发数据
描述 下设备下发透传数据
路径 /devices/:deviceid
方法 PUT
参数 无
CURL 请求示例
curl -X GET https://espush.cn/api/server/devices -H "Key: 4836822619100005" -H "Timestamp: 1529051966" -H "Sign: 123123123123"