服务端 API

概述

本文是 ESPush IoT 服务器的开发者接入手册,API 使用类似 REST API 风格描述,使用 HTTP 方式调用,使您尽快完成接入。

协议描述

请求URL结构为: https://domain/api/server/class?params ,其中各字段含义如下:

  • 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"

results matching ""

    No results matching ""