批量上线子设备¶

你可以通过 MQTT 协议批量上线子设备。

前提条件¶

需要确保子设备身份已经在 EnOS 云端中注册。
在网关设备中添加拓扑关系。

Topics¶

上行：

请求 TOPIC: /ext/session/{productKey}/{deviceKey}/combine/login/batch
响应 TOPIC: /ext/session/{productKey}/{deviceKey}/combine/login/batch_reply

备注

TOPIC 中的 productKey 和 deviceKey 为网关的三元组。

请求数据格式¶

{
    "id":"1",
    "params":{
        "clientId":"Lx5Q1X6M",
        "subDevices":[
            {
                "sign":"c14fc21231e6c44849683ccfb7a2089895a278b37a30c33ccb58d3b8690d16e1",
                "deviceKey":"deviceKey1",
                "productKey":"productKey1"
            },
            {
                "sign":"1fbf0cd0903a9405d567fe5909a1aae75012df5465211db367c7666c0ae33bf2",
                "deviceKey":"deviceKey2",
                "productKey":"productKey1"
            },
            {
                "sign":"480869163c85777c9fcb9fe53340fb13d38ef19e644df82927fcd2393b3819c4",
                "deviceKey":"deviceKey3",
                "productKey":"productKey1"
            }
        ],
        "signMethod":"sha256",
        "timestamp":"1564988853275"
    },
    "version":"1.1",
    "method":"combine.login.batch"
}

响应数据格式¶

根据结果不同，响应数据格式分为以下 3 种。

子设备全部登入成功¶

{
    "id":"1",
    "code":200,
    "data":{
        "loginedSubDevices":[
            {
                "assetId":"assetId1",
                "deviceKey":"deviceKey1",
                "productKey":"productKey1"
            },
            {
                "assetId":"assetId2",
                "deviceKey":"deviceKey2",
                "productKey":"productKey1"
            },
            {
                "assetId":"assetId3",
                "deviceKey":"deviceKey3",
                "productKey":"productKey1"
            }
        ],
        "failedSubDevices":[]
    },
    "message":""
}

部分子设备登入失败¶

{
    "id":"1",
    "code":723,
    "data":{
        "loginedSubDevices":[
            {
                "assetId":"assetId1",
                "deviceKey":"deviceKey1",
                "productKey":"productKey1"
            },
            {
                "assetId":"assetId2",
                "deviceKey":"deviceKey2",
                "productKey":"productKey1"
            }
        ],
        "failedSubDevices":[
            {
                "deviceKey":"deviceKey3",
                "productKey":"productKey1"
            }
        ]
    },
    "message":"deviceKey3&productKey1 has error: Device is disable;"
}

请求格式存在错误¶

{
    "id":"1",
    "code":1220,
    "data":{
        "loginedSubDevices":[],
        "failedSubDevices":[]
    },
    "message":"payload format error, ..."
}

正确处理响应¶

当相应数据的 code 为 200 时，这表明子设备全部登入成功。否则，这表明子设备全部或者部分登入失败。当请求存则格式错误（或者其他内部服务错误）时，响应中 loginedSubDevices 和 failedSubDevices 将为空。

因此，当响应中 code 不为 200 时，用户不能简单地通过 failedSubDevices 判断哪些子设备登入失败。因此，响应的正确处理方式应为：

if (code == 200) {
  // 所有的子设备登入成功
} else {
  if (loginedSubDevices.isEmpty() && failedSubDevices.isEmpty()) {
    // 存在格式错误或内部服务错误
  } else {
    if (loginedSubDevices.isNotEmpty()) {
      // 处理登入成功的子设备
    }
    if (failedSubDevices.isNotEmpty()) {
      // 处理登入失败的子设备
    }
  }
}

请求参数说明¶

参数	类型	是否必需	描述
id	String	可选	消息 ID 号，保留值。
params	List	必需	子设备上线的参数。
deviceKey	String	必需	子设备的 deviceKey。
productKey	String	必需	子设备的 productKey。
sign	String	必需	子设备签名，规则与网关相同。
signmethod	String	必需	签名方法，支持 hmacSha1。
timestamp	String	必需	时间戳
version	必需	String	版本号。
method	String	必需	请求方法。
clientId	String	必需	设备端标识，可以为任意标志（建议用网关的 productKey 或者 deviceKey）。

响应参数说明¶

参数	类型	描述
message	String	结果返回信息。
code	Integer	结果返回码，200 代表请求成功执行。
data	JSON	返回的详细信息。JSON 格式。
loginedSubDevices	Array	登入成功的子设备。
failedSubDevices	Array	登入失败的子设备。

结果返回码¶

返回码	错误信息	释义
705	It failed to query device, not existed this device	子设备不存在
723	Device is disable	子设备被禁用
770	Dynamic activate is not allowed	该产品未启用动态激活
771	Sub device cannot connect to mqtt broker directly	子设备不能与 EnOS 云端直连
740	Sub device not belong the gateway	该设备并非该网关的子设备
742	Sign check failed	Hash 签名验证失败
746	The device must login by ssl	该产品启用了证书双向认证