OpenApi使用

基于数据签名的OpenApi模块.用于提供对外开放接口的认证方式.

注意

本功能仅在专业版中提供.

创建客户端

进入平台:[系统设置]-[OpenApi客户端]

点击新建按钮:

新建客户端

填写对应的内容保存.

注意

clientIdsecureKey需要提供给客户端开发者. 用户名和密码是系统统一的用户主体,会自动创建到用户管理中.使用此用户名密码也能登录到系统中. 与其他用户相同,可以将用户绑定到机构实现数据权限控制.

赋权

点击操作列中的赋权按钮对客户端进行赋权.大部分情况下只需要勾选: 设备操作API设备数据API权限即可.

注意

此赋权操作实际上是对OpenAPI客户端对应对用户主体进行赋权.

使用签名的方式

验证流程

流程

说明

  1. 图中Signature函数为客户端设置的签名方式,支持MD5Sha256.
  2. 发起请求的签名信息都需要放到请求头中,而不是请求体.
  3. OpenApi对开发是透明的,开发只需要关心权限控制即可.OpenAPI和后台接口使用的是相同的权限控制API. 因此开发一个OpenAPI接口就是写一个WebFlux Controller. 查看使用方式

签名

平台使用签名来校验客户端请求的完整性以及合法性.

例:

ClientId为testId, SecureKey为:testSecure. 客户端请求接口: /api/v1/device/dev0001/log/_query,参数为pageSize=20&pageIndex=0,签名方式为md5.

  1. 将参数key按ascii排序得到: pageIndex=0&pageSize=20
  2. 使用拼接时间戳以及密钥得到: pageIndex=0&pageSize=201574993804802testSecure
  3. 使用md5("pageIndex=0&pageSize=201574993804802testSecure")得到837fe7fa29e7a5e4852d447578269523

示例:

  1. GET /api/device?pageIndex=0&pageSize=20
  2. X-Client-Id: testId
  3. X-Timestamp: 1574993804802
  4. X-Sign: 837fe7fa29e7a5e4852d447578269523

响应结果:

  1. HTTP/1.1 200 OK
  2. X-Timestamp: 1574994269075
  3. X-Sign: c23faa3c46784ada64423a8bba433f25
  4. {"status":200,result:[]}

验签

使用和签名相同的算法(不需要对响应结果排序):

  1. String secureKey = ...; //密钥
  2. String responseBody = ...;//服务端响应结果
  3. String timestampHeader = ...;//响应头: X-Timestamp
  4. String signHeader = ...; //响应头: X-Sign
  5. String sign = DigestUtils.md5Hex(responseBody+timestampHeader+secureKey);
  6. if(sign.equalsIgnoreCase(signHeader)){
  7. //验签通过
  8. }

使用token的方式

通过请求接口/api/v1/token来获取X-Access-Token,之后可以使用此token来发起api请求。

申请token

客户端请求接口/api/v1/token
请求方式: POST

  1. POST /api/v1/token
  2. X-Sign: 932bbe8a39ae03f568f73a507d87afac
  3. X-Timestamp: 1587719082698
  4. X-Client-Id: kF**********HRZ
  5. Content-Type: application/json
  6. {
  7. "expires": 7200 // 过期时间,单位秒.
  8. }
  9. //返回
  10. {
  11. "status":200,
  12. "result":"3bcddb719b01da679b88d07acde2516" //token信息
  13. }

使用token发起请求

此处以获取设备test001详情为例。

  1. GET /api/v1/device/test001/_detail
  2. X-Access-Token: 3bcddb719b01da679b88d07acde2516

响应结果:

  1. {
  2. "result": {
  3. "id": "test001",
  4. "name": "温控设备0309",
  5. "protocol": "demo-v1",
  6. "transport": "MQTT",
  7. "orgId": "test",
  8. "productId": "1236859833832701952",
  9. "productName": "智能温控",
  10. "deviceType": {
  11. "text": "网关设备",
  12. "value": "gateway"
  13. },
  14. "state": {
  15. "text": "离线",
  16. "value": "offline"
  17. },
  18. "address": "/127.0.0.1:36982",
  19. "onlineTime": 1586705515429,
  20. "offlineTime": 1586705507734,
  21. "createTime": 1585809343175,
  22. "registerTime": 1583805253659,
  23. "metadata": "{\"events\":[{\"id\":\"fire_alarm\",\"name\":\"火警报警\",\"expands\":{\"eventType\":\"reportData\",\"level\":\"urgent\"},\"valueType\":{\"type\":\"object\",\"properties\":[{\"id\":\"a_name\",\"name\":\"区域名称\",\"valueType\":{\"type\":\"string\"}},{\"id\":\"b_name\",\"name\":\"建筑名称\",\"valueType\":{\"type\":\"string\"}},{\"id\":\"l_name\",\"name\":\"位置名称\",\"valueType\":{\"type\":\"string\"}}]}}],\"properties\":[{\"id\":\"temperature\",\"name\":\"温度\",\"valueType\":{\"type\":\"float\",\"min\":\"0\",\"max\":\"100\",\"step\":\"0.1\",\"unit\":\"celsiusDegrees\"},\"expands\":{\"readOnly\":\"true\"}}],\"functions\":[{\"id\":\"get-log\",\"name\":\"获取日志\",\"isAsync\":true,\"output\":{\"type\":\"string\",\"expands\":{\"maxLength\":\"2048\"}},\"inputs\":[{\"id\":\"start_date\",\"name\":\"开始日期\",\"valueType\":{\"type\":\"date\",\"dateFormat\":\"yyyy-MM-dd HH:mm:ss\"}},{\"id\":\"end_data\",\"name\":\"结束日期\",\"valueType\":{\"type\":\"date\",\"dateFormat\":\"yyyy-MM-dd HH:mm:ss\"}},{\"id\":\"time\",\"name\":\"分组\",\"valueType\":{\"type\":\"string\"}}]}]}",
  24. "configuration": {
  25. "username": "test",
  26. "password": "test"
  27. },
  28. "tags": []
  29. },
  30. "status": 200,
  31. "code": "success"
  32. }

Demo

Demo中测试包org.jetlinks.demo.openapi下的测试类已测试通过平台已有的openApi接口。
Demo中使用签名的方式接入。

前往下载Demo接入 - 图3