拓扑关系如何管理？

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

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

方式对比

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

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

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

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

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

交互流程

设备发送消息

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

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 为 涂鸦 IoT 开发平台 设备管理中展示的 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 个。