子设备可以逐个上下线，也可以批量上下线。子设备上线之前，需在物联网平台为子设备注册身份，建立子设备与网关的拓扑关系。子设备上线时，物联网平台会根据拓扑关系进行子设备身份校验，以确定子设备是否具备使用网关通道的能力。

说明
  • 子设备上下线、批量上下线消息，只支持QoS=0，不支持QoS=1。
  • 一个网关下，同时在线的子设备数量不能超过2,000。在线子设备数量达到2,000个后，新的子设备上线请求将被拒绝。
  • 发送子设备批量上下线请求时，单个批次上下线的子设备数量不超过50个。
  • 设备批量上下线请求结果为全部成功或全部失败，失败时的data响应参数中会包含具体的设备信息。

子设备上线

数据上行：

  • 请求Topic：/ext/session/${productKey}/${deviceName}/combine/login
  • 响应Topic：/ext/session/${productKey}/${deviceName}/combine/login_reply
说明 因为子设备通过网关通道与物联网平台通信，以上Topic为网关设备的Topic。Topic中变量${productKey}和${deviceName}需替换为网关设备的对应信息。

Alink请求数据格式：

{
  "id": "123",
  "params": {
    "productKey": "al12345****",
    "deviceName": "device1234",
    "clientId": "al12345****&device1234",
    "timestamp": "1581417203000",
    "signMethod": "hmacmd5",
    "sign": "9B9C732412A4F84B981E1AB97CAB****",
    "cleanSession": "true"
  }
}
说明 消息体中，参数productKey和deviceName的值是子设备的对应信息。
表 1. 请求参数说明
参数类型说明
idString消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
paramsObject请求入参，包含的具体参数见下表params。
表 2. params
参数类型说明
deviceNameString子设备的设备名称。
productKeyString子设备所属的产品的ProductKey。
signString

子设备签名。签名方法与直连设备签名方法相同。

签名方法：

  1. 将所有提交给服务器的参数（sign，signMethod 和 cleanSession除外）按照字母顺序排序，然后将参数和值依次拼接（无拼接符号）。
  2. 对加签内容，通过signMethod指定的加签算法，并使用设备的DeviceSecret值，进行签名计算。

    计算结果作为sign的取值。

sign值计算方法示例如下：

hmac_md5(deviceSecret, clientIdal12345****&device1234deviceNamedevice1234productKeyal12345****timestamp1581417203000)
signMethodString签名方法，支持hmacSha1、hmacSha256、hmacMd5和Sha256。
timestampString毫秒级时间戳。
clientIdString设备端标识。可以为productKey&deviceName。
cleanSessionString
  • 如果取值是true，则清理所有子设备离线时的消息，即所有未接收的QoS1消息将被清除。
  • 如果取值是false，则不清理子设备离线时的消息。

Alink响应数据格式：

{
  "id":"123",
  "code":200,
  "message":"success"
  "data":{
      "deviceName": "device1234",
      "productKey": "al12345****"
    }
}
表 3. 响应参数说明
参数类型说明
idString消息ID，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
codeInteger返回结果，200代表成功。
messageString返回结果信息。
dataObject请求成功或失败时返回的子设备信息，具体参数请参见下表data。
表 4. data
参数类型说明
deviceNameString子设备的设备名称。
productKeyString子设备所属产品的密钥。

错误信息：

错误码错误信息描述
460request parameter error请求参数错误。
429rate limit, too many subDeviceOnline msg in one minute单个设备认证过于频繁被限流。
428too many subdevices under gateway网关下同时在线子设备过多。
6401topo relation not exist网关和子设备没有拓扑关系。
6100device not found子设备不存在。
521device deleted子设备已被删除。
522device forbidden子设备已被禁用。
6287invalid sign子设备密码或者签名错误。

子设备批量上线

重要 单次最多可请求50个子设备上线。

数据上行：

  • 请求Topic：/ext/session/${productKey}/${deviceName}/combine/batch_login
  • 响应Topic：/ext/session/${productKey}/${deviceName}/combine/batch_login_reply
说明 因为子设备通过网关通道与物联网平台通信，以上Topic为网关设备的Topic。Topic中变量${productKey}和${deviceName}需替换为网关设备的对应信息。

Alink请求数据格式：

{
  "id": "123",
  "params":{ 
     "deviceList":[{
        "productKey": "al12345****", 
        "deviceName": "device1234",
        "clientId": "al12345****&device1234",
        "timestamp": "1581417203000", 
        "cleanSession": "false",
        "signMethod": "hmacmd5",
        "sign": "9B9C732412A4F84B981E1AB97CAB****",
     }, {
        "productKey": "al12345****", 
        "deviceName": "device4321",
        "clientId": "al12345****&device4321",
        "timestamp": "1581417203000", 
        "cleanSession": "true",
        "signMethod": "hmacmd5",
        "sign": "9B9C732412A4F84B981E1AB97CAB****",
     }]
  }
}
说明 消息体中，参数productKey和deviceName的值是子设备的对应信息。
表 5. 请求参数说明
参数类型说明
idString消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
paramsObject请求入参，其中deviceList参数包含要上线的子设备认证参数列表，包含的具体参数见下表deviceList。
表 6. deviceList
参数类型说明
deviceNameString子设备的设备名称。
productKeyString子设备所属的产品的ProductKey。
signString

子设备签名。签名方法与直连设备签名方法相同。

签名方法：

  1. 将所有提交给服务器的参数（sign，signMethod 和 cleanSession除外）按照字母顺序排序，然后将参数和值依次拼接（无拼接符号）。
  2. 对加签内容，通过signMethod指定的加签算法，并使用设备的DeviceSecret值，进行签名计算。

    计算结果作为sign的取值。

sign值计算方法示例如下：

hmac_md5(deviceSecret, clientIdal12345****&device1234deviceNamedevice1234productKeyal12345****timestamp1581417203000)
signMethodString签名方法，支持hmacSha1、hmacSha256、hmacMd5和Sha256。
timestampString毫秒级时间戳。
clientIdString设备端标识。可以为productKey&deviceName。
cleanSessionString
  • 如果取值是true，则清理所有子设备离线时的消息，即所有未接收的QoS1消息将被清除。
  • 如果取值是false，则不清理子设备离线时的消息。

Alink响应数据格式：

{
  "id":"123",
  "code":"200",
  "message":"success",
  "data":[{
      "productKey": "al12345****",
      "deviceName": "device1234"
    },{
      "deviceName": "device4321",
      "productKey": "al12345****"
    }]
}
表 7. 响应参数说明
参数类型说明
idString消息ID，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
codeInteger返回结果，200代表成功。
messageString返回结果信息。
dataObject请求成功或失败时返回的子设备信息，具体参数请参见下表data。
表 8. data
参数类型说明
deviceNameString子设备的设备名称。
productKeyString子设备所属产品的密钥。

错误信息：

错误码错误信息描述
460request parameter error请求参数错误。
429rate limit, too many subDeviceOnline msg in one minute单个设备认证过于频繁被限流。
428too many subdevices under gateway网关下同时在线子设备过多。
6401topo relation not exist网关和子设备没有拓扑关系。
6100device not found子设备不存在。
521device deleted子设备已被删除。
522device forbidden子设备已被禁用。
6287invalid sign子设备密码或者签名错误。

子设备下线

数据上行：

  • 请求Topic：/ext/session/${productKey}/${deviceName}/combine/logout
  • 响应Topic：/ext/session/${productKey}/${deviceName}/combine/logout_reply
说明 因为子设备通过网关通道与物联网平台通信，以上Topic为网关设备的Topic。Topic中变量${productKey}和${deviceName}需替换为网关设备的对应信息。

Alink请求数据格式：

{
  "id": "123",
  "params": {
    "productKey": "al12345****",
    "deviceName": "device1234"
  }
}
说明 消息体中，参数productKey和deviceName的值是子设备的对应信息。
表 9. 请求参数说明
参数类型说明
idString消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
paramsObject请求入参，包含要下线的子设备信息。
表 10. params
参数类型说明
deviceNameString子设备的设备名称。
productKeyString子设备所属产品的ProductKey。

Alink响应数据格式：

{
  "id": "123",
  "code": 200,
  "message": "success",
  "data": {
      "deviceName": "device1234",
      "productKey": "al12345****"
    }
}
表 11. 响应参数说明
参数类型说明
idString消息ID，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
codeInteger返回结果，200代表成功。
messageString返回结果信息。
dataObject请求成功或失败时，返回的下线的子设备信息。具体参数请参见下表data。
表 12. data
参数类型说明
deviceNameString子设备的设备名称。
productKeyString子设备所属产品的ProductKey。

错误信息：

错误码错误信息描述
460request parameter error请求参数错误。
520device no session子设备会话不存在。

子设备批量下线

重要 单次最多可请求50个子设备下线。

数据上行：

  • 请求Topic：/ext/session/${productKey}/${deviceName}/combine/batch_logout
  • 响应Topic：/ext/session/${productKey}/${deviceName}/combine/batch_logout_reply
说明 因为子设备通过网关通道与物联网平台通信，以上Topic为网关设备的Topic。Topic中变量${productKey}和${deviceName}需替换为网关设备的对应信息。

Alink请求数据格式：

{
  "id": "123",
  "params":[{
            "productKey": "al12345****",
            "deviceName": "device1234"
          },{
            "productKey": "al12345****",
            "deviceName": "device4321"
      }]
}
说明 消息体中，参数productKey和deviceName的值是子设备的对应信息。
表 13. 请求参数说明
参数类型说明
idString消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
paramsObject请求入参，包含要下线的子设备信息。
表 14. params
参数类型说明
deviceNameString子设备的设备名称。
productKeyString子设备所属产品的ProductKey。

Alink响应数据格式：

{
  "id":"123",
  "code":"200",
  “message":"success",
  "data":[{
      "productKey": "al12345****"
      "deviceName": "device1234"
    },{
      "deviceName": "device4321",
      "productKey": "al12345****"
    }]
}
表 15. 响应参数说明
参数类型说明
idString消息ID，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
codeInteger返回结果，200代表成功。
messageString返回结果信息。
dataObject请求成功或失败时，返回的下线的子设备信息。具体参数请参见下表data。
表 16. data
参数类型说明
deviceNameString子设备的设备名称。
productKeyString子设备所属产品的ProductKey。

错误信息：

错误码消息描述
460request parameter error请求参数错误。
520device no session子设备会话不存在。

相关文档

子设备接入配置，可参见设备身份注册。

错误码说明及解决办法，可参见设备端接收的错误码。