拓扑关系管理

更新时间：2024-07-19 08:57:59下载pdf

在设备对接涂鸦的云端过程中，一部分设备由于自身资源或硬件配置，无法直接连接云端。而是需要通过网关进行中转，由网关代理实现和云端进行数据交互，间接实现设备接入云端。这样的设备也称为子设备。

要想实现网关代理子设备接入云端，子设备和网关需要先建立关联关系，也称为 拓扑关系。

方式对比

建立拓扑关系有三种方式，您可以根据实际情况，选择其中一种，并且注意不要混用。

例如，网关通过动态发现的方式和子设备建立了拓扑关系，之后又使用其它方式再次建立拓扑关系，这就属于混用，后期使用设备时会出现问题。

名称	适用场景	接口	特点
动态发现	无法事先获取子设备信息，无法提前在云端注册子设备和烧录注册信息。网关能发现子设备，动态向云端注册子设备并建立拓扑。	网关绑定子设备	全自动
网关建立拓扑	事先获取子设备信息，并在云端注册子设备。拿到子设备注册信息后，烧录到子设备或者网关里面。网关发现子设备，调用云端接口建立拓扑关系。	建立拓扑关系	半自动
平台管理	事先获取子设备信息，并在云端注册子设备。在云端上建立拓扑关系。	建立拓扑关系	全手动

本文主要介绍用于网关设备侧管理拓扑关系的协议内容，并详细说明每个协议。

网关绑定子设备（动态发现）

网关动态发现子设备，请求云端注册子设备并建立拓扑关系，云端返回请求结果。这对应方式对比章节的 动态发现 方式。

交互流程

设备发送消息

设备检测到子设备连接，主动向云端发送绑定子设备消息。

Topic: tylink/${deviceId}/device/sub/bind

{
    "msgId":"45lkj355123****",
    "time":1626197189600,
    "version":"1.0",
	"data":[
      {
        "productId":"a123b456****",
        "clientId":"123455asdf****"
      },
      {
        "productId":"a123b457****",
        "clientId":"453455asdf****"
      }
    ]
}

参数说明

参数	类型	说明	必选	备注
`${deviceId}`	String	设备 ID	是	发起子设备绑定的网关设备 ID。
version	String	协议版本	否	默认 1.0，当前仅支持 1.0。
msgId	String	消息 ID	是	总长度不超过 32 位的字符，上报和订阅消息通过该值建立应答关系。
time	Number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
data	Array	子设备参数列表	是	多个子设备绑定参数，子设备数量不超过 100 个。
`data[].productId`	String	子设备的产品 ID	是	需要绑定在子设备的产品 ID。
`data[].clientId`	String	设备端唯一 ID	是	此处主要用于子设备硬件的唯一标识，可以是设备的 MAC、SN 等，至少保证产品下唯一，将显示在设备管理 > 注册 ID 字段。

设备接收消息

设备订阅接收绑定子设备消息回复。

Topic: tylink/${deviceId}/device/sub/bind_response

{
    "msgId":"45lkj3551234****",
    "time":1626197189640,
    "version":"1.0",
    "code":0,
	"data":[
      {
        "productId":"a123b456****",
        "clientId":"123455****",
        "deviceId":"6c828cba434ff40c07****"
      },
      {
        "productId":"a123b457****",
        "clientId":"123456****",
        "deviceId":"6c828cba434ff40c07****"
      }
    ]
}

参数说明

参数	类型	说明	必选	备注
`${deviceId}`	String	设备 ID	是	发起子设备绑定的网关设备 ID。
version	String	协议版本	否	默认 1.0，当前仅支持 1.0。
msgId	String	消息 ID	是	总长度不超过 32 位的字符，上报和订阅消息通过该值建立应答关系。
time	Number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
code	Number	响应状态码	否	`0` 代表成功，默认值。非 `0` 代表失败。
data	Array	子设备绑定结果列表	是	-
`data[].productId`	String	产品 ID	是	子设备的产品 ID。
`data[].clientId`	String	子设备硬件的唯一表示 ID	是	子设备的唯一标识，需保证产品下唯一。
`data[].deviceId`	String	云端分配的唯一设备 ID	是	同一个 `clientId`、同一个网关设备 ID，多次绑定只会生成同一个设备 ID，否则会重新生成一个新的设备 ID。

状态码说明

状态码	说明
0	默认状态，代表成功。
1001	服务异常。
1002	请求参数校验不合法。
1004	设备不存在。
2401	产品不存在。
2402	网关绑定了多个设备组。
2403	拓扑信息存在，子设备信息不存在。
2404	授权码数量不足，获取授权码失败。
2405	获取网关设备组异常。
2406	子设备重新注册时，必须先解绑。
2410	同一个网关绑定子设备的数量，不能超过 2000 个。

网关删除子设备

网关通过动态发现注册的子设备，可支持网关请求云端删除对应的子设备。云端接收到该请求后，会校验并删除该子设备，同时删除网关和子设备的拓扑关系。由于是设备端发起的删除操作，针对已绑定家庭或资产的子设备，支持网关直接删除子设备。

该删除操作会将子设备物理删除，同时回收授权码。

交互流程

设备发送消息

Topic：tylink/${deviceId}/device/sub/delete

消息内容

{
    "msgId":"45lkj355123****",
    "time":1626197189600,
    "version":"1.0",
	"data":[
      "devId123455as****",
      "devId123456ty****"
    ]
}

参数说明

参数	类型	说明	必选	备注
`${deviceId}`	String	设备 ID	是	发起删除子设备的网关设备 ID。
version	String	协议版本	否	默认 1.0，当前仅支持 1.0。
msgId	String	消息 ID	是	总长度不超过 32 位的字符，上报和订阅消息通过该值建立应答关系。
time	Number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
data	Array	待删除的子设备 ID 列表	是	子设备 ID 列表，设备数量不超过 10。

设备接收消息

Topic：tylink/${deviceId}/device/sub/delete_response

消息内容

{
    "msgId":"45lkj355123****",
    "time":1626197189640,
    "version":"1.0",
  	"code":0,
	"data":[
      "devId123455as****",
      "devId123456ty****"
    ]
}

参数说明

参数	类型	说明	必选	备注
`${deviceId}`	String	设备 ID	是	发起删除拓扑关系的网关设备 ID。
version	String	协议版本	否	默认 1.0，当前仅支持 1.0。
msgId	String	消息 ID	是	总长度不超过 32 位的字符，上报和订阅消息通过该值建立应答关系。
time	Number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
code	Number	响应状态码	否	`0` 代表成功，非 `0` 代表失败，默认 `0`。
data	Array	被删除的子设备 ID 列表。	是	-

状态码说明

状态码	说明
0	默认状态，代表成功。
1001	服务异常。
1004	设备记录不存在。
2407	子设备列表为空。
2408	子设备数量超限。

建立拓扑关系

对于已经在云端注册的子设备，拿到子设备注册信息后烧录到子设备。网关运行后动态发现子设备，请求云端建立拓扑关系，云端返回请求结果。这对应方式对比章节中的 网关建立拓扑 方式。

交互流程

设备发送消息

Topic：tylink/${deviceId}/device/topo/add

{
    "msgId":"45lkj355123****",
    "time":1626197189600,
    "version":"1.0",
	"data":[
      {
        "productId":"a123b456****",
        "deviceId":"123455asdf****",
        "sign":"adstewq35324ds****",
        "signMethod":"HmacSHA256",
        "timestamp":"16067836521"
      },
      {
        "productId":"a123b457****",
        "deviceId":"123456****",
        "sign":"adstewq35324ds****",
        "signMethod":"HmacSHA256",
        "timestamp":"16067836521"
      }
    ]
}

参数说明

参数	类型	说明	必选	备注
`${deviceId}`	String	设备 ID	是	发起建立拓扑关系的网关设备 ID。
version	String	协议版本	否	默认 1.0，当前仅支持 1.0。
msgId	String	消息 ID	是	总长度不超过 32 位的字符，上报和订阅消息通过该值建立应答关系。
time	Number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
data	Array	子设备参数列表	是	多个子设备拓扑参数，子设备数量不能超过 100 个。
`data[].productId`	String	子设备的产品 ID	是	-
`data[].deviceId`	String	子设备的设备 ID	是	注册设备时，获取的设备 ID，云端分配的唯一 ID。
`data[].signMethod`	String	签名算法	是	签名算法，当前仅支持 HmacSHA256。
`data[].timestamp`	String	时间戳	是	签名时间戳，10 位秒级或 13 位毫秒级。
`data[].sign`	String	签名	是	使用 `signMethod` 对内容进行签名。例如，`HmacSHA256（content, deviceSecret）` `content` 的内容如下：productId= a123b456**，deviceId=123455asdf**，timestamp=${签名时间戳} `deviceSecret` 为涂鸦开发者平台设备管理中展示的 `DeviceSecret` 字段。

设备接收消息

Topic：tylink/${deviceId}/device/topo/add_response

{
    "msgId":"45lkj355123****",
    "time":1626197189640,
    "version":"1.0",
  	"code":0,
	"data":[
      {
        "productId":"a123b456****",
        "deviceId":"6c828cba434ff40c07****"
      },
      {
        "productId":"a123b457****",
        "deviceId":"6c828cba434ff40c07****"
      }
    ]
}

参数说明

参数	类型	说明	必选	备注
`${deviceId}`	String	设备 ID	是	发起建立拓扑关系的网关设备 ID。
version	String	协议版本	否	默认 1.0，当前仅支持 1.0。
msgId	String	消息 ID	是	总长度不超过 32 位的字符，上报和订阅消息通过该值建立应答关系。
time	Number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
code	Number	响应状态码	否	`0` 代表成功，默认值。非 `0` 代表失败。
data	Array	建立拓扑关系成功的结果列表。	是	-
`data[].productId`	String	子设备的产品 ID。	是	-
`data[].deviceId`	String	子设备的设备 ID。	是	-

状态码说明

状态码	说明
0	默认状态，代表成功。
1001	服务异常。
1004	设备记录不存在。
2407	子设备列表为空。
2408	子设备数量超限。
2409	签名验证失败。
2410	同一个网关绑定子设备的数量，不能超过 2000 个。

删除拓扑关系

网关请求云端删除与指定子设备的拓扑关系，云端返回请求结果。该请求不会删除子设备。删除拓扑关系后，子设备还能和该网关或其它网关再次建立拓扑关系。

交互流程

设备发送消息

Topic：tylink/${deviceId}/device/topo/delete

{
    "msgId":"45lkj355123****",
    "time":1626197189600,
    "version":"1.0",
	"data":[
      "devId123455as****",
      "devId123456ty****"
    ]
}

参数说明

参数	类型	说明	必选	备注
`${deviceId}`	String	设备 ID	是	发起删除拓扑关系的网关设备 ID。
version	String	协议版本	否	默认 1.0，当前仅支持 1.0。
msgId	String	消息 ID	是	总长度不超过 32 位的字符，上报和订阅消息通过该值建立应答关系。
time	Number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
data	Array	待删除的子设备 ID 列表	是	子设备 ID 列表，设备数量不超过 100 个。

设备接收消息

Topic：tylink/${deviceId}/device/topo/delete_response

{
    "msgId":"45lkj355123****",
    "time":1626197189640,
    "version":"1.0",
  	"code":0,
	"data":[
      "devId123455as****",
      "devId123456ty****"
    ]
}

参数说明

参数	类型	说明	必选	备注
`${deviceId}`	String	设备 ID	是	发起删除拓扑关系的网关设备 ID。
version	String	协议版本	否	默认 1.0，当前仅支持 1.0。
msgId	String	消息 ID	是	总长度不超过 32 位的字符，上报和订阅消息通过该值建立应答关系。
time	Number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
code	Number	响应状态码	否	`0` 代表成功，默认值。非 `0` 代表失败。
data	Array	被删除的子设备 ID 列表	是	-

状态码说明

状态码	说明
0	默认状态，代表成功。
1001	服务异常。
1004	设备记录不存在。
2407	子设备列表为空。
2408	子设备数量超限。

查询拓扑关系

网关请求云端查询拓扑关系，云端返回请求结果。

交互流程

设备发送消息

Topic：tylink/${deviceId}/device/topo/get

{
    "msgId":"45lkj355123****",
    "time":1626197189600,
    "version":"1.0",
	"data":{
      "startId": 0,
      "pageSize": 20, 
      "devIds":[
        "devId123455as****",
        "devId123456ty****"
      ]
    }
}

参数说明

参数	类型	说明	必选	备注
`${deviceId}`	String	设备 ID	是	发起查询拓扑关系的网关设备 ID。
version	String	协议版本	否	默认 1.0，当前仅支持 1.0。
msgId	String	消息 ID	是	总长度不超过 32 位的字符，上报和订阅消息通过该值建立应答关系。
time	Number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
code	Number	响应状态码	否	`0` 代表成功，默认值。非 `0` 代表失败。
`data.startIndexId`	Number	本次查询子设备列表起始值	否	默认为 `0`，从第一条开始查询。如果查询第二页, 则该值为第一页查询结果最后一条记录的索引 ID。第三页及以后，以此类推。
`data.pageSize`	Number	每次查询的设备数量	否	默认及最大查询数量均为 100 个。
`data.devIds`	Array	本次查询子设备 ID 列表	否	子设备 ID 列表，设备数量不超过 100 个。

设备接收消息

Topic：tylink/${deviceId}/device/topo/get_response

{
    "msgId":"45lkj355123****",
    "time":1626197189640,
    "version":"1.0",
  	"code":0,
	"data":[
      {
        "productId":"a123b456****",
        "deviceId":"6c828cba434ff40c074***",
        "indexId": 1
      },
      {
        "productId":"a123b457****",
        "deviceId":"6c828cba434ff40c074***",
        "indexId": 2
      }
    ]
}

参数说明

参数	类型	说明	必选	备注
`${deviceId}`	String	设备 ID	是	发起拓扑关系查询的网关设备 ID。
version	String	协议版本	否	默认 1.0，当前仅支持 1.0。
msgId	String	消息 ID	是	总长度不超过 32 位的字符，上报和订阅消息通过该值建立应答关系。
time	Number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
code	Number	响应状态码	否	`0` 代表成功，默认值。非 `0` 代表失败。
data	Array	子设备列表	是	-
`data[].productId`	String	子设备的产品 ID	是	-
`data[].deviceId`	String	子设备的设备 ID	是	-
`data[].indexId`	Number	索引 ID	是	每页最后一条记录的索引 ID，作为下一页查询的 `startIndexId`。

状态码说明

状态码	说明
0	默认状态，代表成功。
1001	服务异常。
1004	设备不存在。
2408	子设备数量超限。

通知拓扑关系变更

云端变更拓扑关系，如往拓扑关系中新增子设备，或把子设备从拓扑关系中删除，发送消息通知网关。

交互流程

设备接收消息

Topic：tylink/${deviceId}/device/topo/change

{
    "msgId":"45lkj355123****",
    "time":1626197189600,
	"data":{
      "addDevIds":[
           "devId123asdf****",
           "devId456tyiy****"
        ],
       "delDevIds":[
           "devId789****",
           "devIdyiy****"
        ]
    }
}

参数说明

参数	类型	说明	必选	备注
`${deviceId}`	String	设备 ID	是	拓扑关系发生变更的网关设备 ID。
version	String	协议版本	否	默认 1.0，当前仅支持 1.0。
msgId	String	消息 ID	是	总长度不超过 32 位的字符，消息的唯一 ID。
time	Number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
data	object	业务数据	是	-
`data.addDevIds`	Array	新增的子设备 ID 列表	否	子设备数量不超过 100 个。
`data.delDevIds`	Array	删除的子设备 ID 列表	否	子设备数量不超过 100 个。