秀杰智联

Appearance

拓扑关系管理 ​

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

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

方式对比 ​

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

提示

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

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

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

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

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

设备发送消息 ​

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

Topic：things/up/${tenantId}/${productKey}/${deviceKey}/sub/bind

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

参数说明

参数类型说明必选备注
${productKey}String产品 Key是发起绑定子设备的网关设备 ProductKey。
${deviceKey}String设备 Key是发起绑定子设备的网关设备 DeviceKey。
versionString协议版本否默认 1.0，当前仅支持 1.0。
msgIdString消息 ID是总长度不超过 32 位的字符，上报和订阅消息通过该值建立应答关系。
timeNumber消息时间戳是消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
dataArray子设备参数列表是多个子设备绑定参数，子设备数量不超过 100 个。
data[].productString子设备的产品 Key是-
data[].deviceString子设备的设备 Key是-

设备接收消息 ​

云端响应网关设备发送的绑定子设备消息。

Topic：things/down/${tenantId}/${productKey}/${deviceKey}/sub/bind_reply

json
{
    "msgId":"45lkj3551234****",
    "time":1626197189640,
    "version":"1.0",
    "code":0,
	"data":[
      {
        "product":"a123b456****",
        "device":"123455asdf****"
      },
      {
        "product":"a123b457****",
        "device":"453455asdf****"
      }
    ]
}

参数说明

参数类型说明必选备注
${productKey}String产品 Key是发起绑定子设备的网关设备 ProductKey。
${deviceKey}String设备 Key是发起绑定子设备的网关设备 DeviceKey。
versionString协议版本否默认 1.0，当前仅支持 1.0。
msgIdString消息 ID是总长度不超过 32 位的字符，上报和订阅消息通过该值建立应答关系。
timeNumber消息时间戳是消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
codeNumber响应状态码否0 代表成功，默认值；非 0 代表失败。
dataArray子设备绑定结果列表是-
data[].productString子设备的产品 Key是-
data[].deviceString子设备的设备 Key是-

状态码说明

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

网关删除子设备 ​

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

警告

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

设备发送消息 ​

Topic：things/up/${tenantId}/${productKey}/${deviceKey}/sub/delete

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

参数说明

参数类型说明必选备注
${productKey}String产品 Key是发起删除子设备的网关设备 ProductKey。
${deviceKey}String设备 Key是发起删除子设备的网关设备 DeviceKey。
versionString协议版本否默认 1.0，当前仅支持 1.0。
msgIdString消息 ID是总长度不超过 32 位的字符，上报和订阅消息通过该值建立应答关系。
timeNumber消息时间戳是消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
dataArray待删除的子设备 ID 列表是子设备 ID 列表，设备数量不超过 10。
data[].productString子设备的产品 Key是-
data[].deviceString子设备的设备 Key是-

设备接收消息 ​

云端删除设备及拓扑关系后，给网关设备回复消息。

Topic：things/down/${tenantId}/${productKey}/${deviceKey}/sub/delete_reply

json
{
    "msgId":"45lkj355123****",
    "time":1626197189640,
    "version":"1.0",
  	"code":0,
	"data":[
      {
        "product":"a123b456****",
        "device":"123455asdf****"
      },
      {
        "product":"a123b457****",
        "device":"453455asdf****"
      }
    ]
}

参数说明

参数类型说明必选备注
${productKey}String产品 Key是发起删除子设备的网关设备 ProductKey。
${deviceKey}String设备 Key是发起删除子设备的网关设备 DeviceKey。
versionString协议版本否默认 1.0，当前仅支持 1.0。
msgIdString消息 ID是总长度不超过 32 位的字符，上报和订阅消息通过该值建立应答关系。
timeNumber消息时间戳是消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
codeNumber响应状态码否0 代表成功，非 0 代表失败，默认 0。
dataArray被删除的子设备 ID 列表是-
data[].productString子设备的产品 Key是-
data[].deviceString子设备的设备 Key是-

状态码说明

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

建立拓扑关系 ​

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

设备发送消息 ​

Topic：things/up/${tenantId}/${productKey}/${deviceKey}/topo/add

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

参数说明

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

设备接收消息 ​

Topic：things/down/${tenantId}/${productKey}/${deviceKey}/topo/add_reply

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

参数说明

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

状态码说明

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

删除拓扑关系 ​

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

设备发送消息 ​

Topic：things/up/${tenantId}/${productKey}/${deviceKey}/topo/delete

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

参数说明

参数类型说明必选备注
${productKey}String产品 Key是发起删除拓扑关系的网关设备 ProductKey。
${deviceKey}String设备 Key是发起删除拓扑关系的网关设备 DeviceKey。
versionString协议版本否默认 1.0，当前仅支持 1.0。
msgIdString消息 ID是总长度不超过 32 位的字符，上报和订阅消息通过该值建立应答关系。
timeNumber消息时间戳是消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
dataArray待删除的子设备 列表是子设备列表，设备数量不超过 100 个。
data[].productString子设备的产品 Key是-
data[].deviceString子设备的设备 Key是-

设备接收消息 ​

Topic：things/down/${tenantId}/${productKey}/${deviceKey}/topo/delete_reply

json
{
    "msgId":"45lkj355123****",
    "time":1626197189640,
    "version":"1.0",
  	"code":0,
	"data":[
      {
        "product":"a123b456****",
        "device":"123455asdf****"
      },
      {
        "product":"a123b457****",
        "device":"453455asdf****"
      }
    ]
}

参数说明

参数类型说明必选备注
${productKey}String产品 Key是发起删除拓扑关系的网关设备 ProductKey。
${deviceKey}String设备 Key是发起删除拓扑关系的网关设备 DeviceKey。
versionString协议版本否默认 1.0，当前仅支持 1.0。
msgIdString消息 ID是总长度不超过 32 位的字符，上报和订阅消息通过该值建立应答关系。
timeNumber消息时间戳是消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
codeNumber响应状态码否0 代表成功，默认值；非 0 代表失败。
dataArray被删除的子设备列表是-
data[].productString子设备的产品 Key是-
data[].deviceString子设备的设备 Key是-

状态码说明

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

查询拓扑关系 ​

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

设备发送消息 ​

Topic：things/up/${tenantId}/${productKey}/${deviceKey}/topo/get

json
{
    "msgId":"45lkj355123****",
    "time":1626197189600,
    "version":"1.0",
	"data":{
      "startId": 0,
      "pageSize": 20, 
      "devs":[
        {
            "product":"a123b456****",
            "device":"123455asdf****"
        },
        {
            "product":"a123b457****",
            "device":"453455asdf****"
        }
      ]
    }
}

参数说明

参数类型说明必选备注
${productKey}String产品 Key是发起查询拓扑关系的网关设备 ProductKey。
${deviceKey}String设备 Key是发起查询拓扑关系的网关设备 DeviceKey。
versionString协议版本否默认 1.0，当前仅支持 1.0。
msgIdString消息 ID是总长度不超过 32 位的字符，上报和订阅消息通过该值建立应答关系。
timeNumber消息时间戳是消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
codeNumber响应状态码否0 代表成功，默认值；非 0 代表失败。
data.startIndexIdNumber本次查询子设备列表起始值否默认为 0，从第一条开始查询。如果查询第二页，则该值为第一页查询结果最后一条记录的索引 ID。第三页及以后，以此类推。
data.pageSizeNumber每次查询的设备数量否默认及最大查询数量均为 100 个。
data.devsArray本次查询子设备列表否子设备 Key 列表，设备数量不超过 100 个。
data[].productString子设备的产品 Key是-
data[].deviceString子设备的设备 Key是-

设备接收消息 ​

Topic：things/down/${tenantId}/${productKey}/${deviceKey}/topo/get_reply

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

参数说明

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

状态码说明

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

通知拓扑关系变更 ​

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

设备接收消息 ​

Topic：things/down/${tenantId}/${productKey}/${deviceKey}/topo/notify

json
{
    "msgId":"45lkj355123****",
    "time":1626197189600,
	"data":{
      "addDevs":[
            {
                "product":"a123b456****",
                "device":"123455asdf****"
            },
            {
                "product":"a123b457****",
                "device":"453455asdf****"
            }
        ],
       "delDevs":[
            {
                "product":"a123b456****",
                "device":"123455asdf****"
            },
            {
                "product":"a123b457****",
                "device":"453455asdf****"
            }
        ]
    }
}

参数说明

参数类型说明必选备注
${productKey}String产品 Key是拓扑关系发生变更的网关设备 ProductKey。
${deviceKey}String设备 Key是拓扑关系发生变更的网关设备 DeviceKey。
versionString协议版本否默认 1.0，当前仅支持 1.0。
msgIdString消息 ID是总长度不超过 32 位的字符，消息的唯一 ID。
timeNumber消息时间戳是消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
dataObject业务数据是-
data.productKeyString操作子设备的产品 Key是-
data.addDevsArray新增的子设备 Key 列表否子设备数量不超过 100 个。
data.delDevsArray删除的子设备 Key 列表否子设备数量不超过 100 个。
data.addDevs[].productString子设备的产品 Key是-
data.addDevs[].deviceString子设备的设备 Key是-
data.delDevs[].productString子设备的产品 Key是-
data.delDevs[].deviceString子设备的设备 Key是-