简述

第三方接入是提供给外部系统来进行集成的方案,分为开放接口,和webhook消息推送,两种方式都使用http的方式进行

开放接口

开放接口是提供给第三方访问我方接口的认证方式,采用开放认证权限同用户的方式,开放认证的权限由绑定用户的权限来决定.

认证方式

开放服务使用 jwt Bearer auth方式 在http头中添加
Authorization Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2NvdW50IjoieWwiLCJ0ZW5hbnRDb2RlIjoiZGVmYXVsdCIsImV4cCI6MTczOTkyMjAxMCwiaWF0IjoxNzAzOTIyMDEwfQ.-oUyaBidThx5HFRsQfuCPULR7A3PeKsbiVA9qafRIn0
http头的值是Bearer+ jwt token,jwt使用提供的秘钥进行加密, jwt的payload为,参数会由我方提供

{
  "code": "yl",
  "userID":"1740358057038188544",
  "tenantCode": "default",
  "exp": 1739922010,
  "iat": 1703922010
}

参数说明:

参数	类型	说明
code	String	租户下一个唯一的编码,用来标识这个认证
userID	String	绑定的用户id
tenantCode	String	租户号
exp	Integer	授权的过期时间,应用需要提前更换
iat	Integer	token生成的时间

配置方式

开放认证暂不支持web配置,需要在数据库中添加配置信息 表名: sys_tenant_open_access 示例:

参数说明:

参数	类型	说明
code	String	租户下一个唯一的编码,用来标识这个认证
userID	String	绑定的用户id
tenantCode	String	租户号
access_secret	Integer	jwt的token
desc	Integer	描述
ip_range	array[string]	IP访问白名单,如果没有配置则不限制ip

webhook消息推送

消息推送需要第三方提供url,推送的方式为post,格式为json,推送http头可以添加第三方自定义参数

配置方式

暂不支持web配置,需要在数据库中添加配置信息 表名: sys_tenant_open_webhook 示例:

参数说明:

参数	类型	说明
code	String	租户下一个唯一的编码,用来标识这个认证
tenantCode	String	租户号
hosts	array[string]	访问的地址列表,负载均衡
uri	String	访问的路径
access_secret	Integer	jwt的token
desc	Integer	描述
handler	map[string]string	自定义http头

推送内容

设备上下线推送

需要甲方分别定义上线url和下线url,推送的body为:

  {
  "device": {
    "productID": "产品ID",
    "deviceName": "设备名"
  },
  "status": 1,//1为上线 2为下线
  "timestamp": "毫秒时间戳字符串"
}

设备属性变化推送

param为参数json对象

  {
  "device": {
    "productID": "产品ID",
    "deviceName": "设备名"
  },
  "identifier": "标识符id",
  "timestamp": "毫秒时间戳字符串",
  "param": {"aaa": 123}
}

字段定义:

字段名	含义	备注
device.productID	产品id
device.deviceName	设备名
timestamp	设备连接,断连时间	毫秒时间戳(string类型)
identifier	推送属性的标识符
param	推送属性的参数	和物模型上定义的类型一致

设备事件变化推送

{
    "device":{
        "productID":"254pwnKQsvK",
        "deviceName":"test5"
    },
    "timestamp":"1670852257719",
    "identifier":"low_power",
    "type":"alert",
    "params":{
        "voltage":2.8
    }
}

字段定义:

字段名	含义	备注
device.productID	产品id
device.deviceName	设备名
timestamp	设备连接,断连时间	毫秒时间戳(string类型)
identifier	推送事件的标识符
params	事件参数	和物模型上定义的类型一致
type	事件类型	信息:info 告警:alert 故障:fault