命令下发（联通用户专用）

概述

为能有效地对设备进行管理，设备的产品模型中定义了物联网平台可向设备下发的命令，应用服务器可以调用物联网平台开放的API接口向单个设备或批量设备下发命令，或者用户通过物联网平台直接向单个设备下发命令，以实现对设备的远程控制。

物联网平台有两种命令下发机制，如下表所示。

业务流程

LWM2M/CoAP协议设备场景

物联网平台提供立即下发和缓存下发两种机制。应用服务器向物联网平台下发命令时，携带参数expireTime（简称TTL，表示最大缓存时间）。如果不带expireTime，则默认expireTime为48小时。

• expireTime=0：命令立即下发。

• expireTime>0：命令缓存下发。

图1 命令立即下发流程

1. 应用调用创建设备命令接口，下发请求到物联网平台，携带expireTime参数为0。消息样例如下：

   Method: POST
   request: https://server:port/iocm/app/cmd/v1.4.0/deviceCommands
   Header:
   "app_key: ******"
   "Authorization:Bearer******"
   Content-Type:application/json
   Body:
   {
     "deviceId": "********",
     "command": {
       "serviceId": "Brightness",
       "method": "SET_DEVICE_LEVEL",
       "paras": {
         "value": "1",
         }
     },
     "callbackUrl": "http://127.0.0.1:9999/cmd/callbackUrl",
     "expireTime": 0,
     "maxRetransmit": 1
   }

2. 物联网平台调用编解码插件对命令请求进行编码后，会通过LWM2M协议定义的设备管理和服务实现接口的Execute操作下发命令，消息体为二进制格式。
3. 物联网平台向应用返回201 Created，携带命令状态为SENT。（如果设备不在线或者设备没收到指令则下发失败，命令状态为FAIL）
4. 设备收到命令后返回ACK响应。
5. 若应用下发命令时携带了"callbackUrl"，物联网平台通过命令状态变化通知接口推送消息给应用，携带命令状态为DELIVERED。消息样例如下：

   Method: POST
   request:
   Body:
   {
     "deviceId": "6543214c-72bb-4131-9e14-fad974123456",
     "commandId": "108a9c71462a48e09426e06e844d47ba3",
     "result": {
       "resultCode": "DELIVERED",
       "resultDetail": null
     }
   }

6. 设备执行命令后通过205 Content响应返回命令执行结果。
7. 若应用下发命令时携带了"callbackUrl"，物联网平台会调用编解码插件对设备响应进行解码，然后通过命令状态变化通知接口推送消息给应用，携带命令状态为SUCCESSFUL。消息样例如下：

   Method: POST
   request:
   Body:
   {
     "deviceId": "6543214c-72bb-4131-9e14-fad974123456",
     "commandId": "108a9c71462a48e09426e06e844d47ba",
     "result": {
       "resultCode": "SUCCESSFUL",
       "resultDetail": null
     }
   }

图2 命令缓存下发流程

1. 应用调用创建设备命令接口，下发请求到物联网平台，携带expireTime参数大于0。
2. 物联网平台将命令写入缓存队列，并上报201 Created，携带命令状态为PENDING。
3. 设备上线或设备上报数据到平台。
4. 物联网平台调用编解码插件对命令请求进行编码后，根据协议规范下发命令给设备。
5. 若应用下发命令时携带了"callbackUrl"，物联网平台通过命令状态变化通知接口推送消息给应用，携带命令状态为SENT。
6. 后续流程请参考“命令立即下发”的步骤4到步骤7。

集成Agent Lite SDK设备/原生MQTT设备场景

对于集成Agent Lite SDK设备/原生MQTT设备，物联网平台只支持直接下发模式，设备不在线时命令下发失败。

1. 应用调用设备服务调用接口，下发请求到物联网平台。消息样例如下：

   Method: POST
   request: https://server:port/iocm/app/cmd/v1.4.0/deviceCommands
   Header:
   "app_key: ******"
   "Authorization:Bearer******"
   Content-Type:application/json
   Body:
   {
     "deviceId": "********",
     "command": {
       "serviceId": "Brightness",
       "method": "SET_DEVICE_LEVEL",
       "paras": {
         "value": "1",
         }
     },
     "callbackUrl": "http://127.0.0.1:9999/cmd/callbackUrl",
     "expireTime": 0,
     "maxRetransmit": 1
   }

2. 物联网平台根据协议规范下发命令给设备。
   MQTT设备必须先订阅平台命令下发接口对应的Topic才能收到平台下发的命令，消息样例如下：

   { 
   "msgType": "cloudReq", 
   "serviceId": "Brightness", 
   "mid": 2016, 
   "cmd": "SET_DEVICE_LEVEL", 
   "paras": { 
    "value": "1"
    } 
   }

3. 物联网平台向应用返回202 Accepted，携带命令状态为SENT。
4. 设备收到命令后返回ACK响应。
5. 若应用下发命令时携带了"callbackUrl"，物联网平台通过命令状态变化通知接口推送消息给应用，携带命令状态为DELIVERED。消息样例如下：

   Method: POST
   request:
   Body:
   {
     "deviceId": "6543214c-72bb-4131-9e14-fad974123456",
     "commandId": "108a9c71462a48e09426e06e844d47ba",
     "result": {
       "resultCode": "DELIVERED",
       "resultDetail": null
     }
   }

6. 设备执行命令后通过设备命令响应通知接口返回命令执行结果，消息样例如下：

   response: Status 
   Code: 200 OK

7. 若应用下发命令时携带了"callbackUrl"，物联网平台会调用编解码插件对设备响应进行解码，然后通过命令状态变化通知接口推送消息给应用，携带命令状态为SUCCESSFUL。消息样例如下：

   Method: POST
   request:
   Body:
   {
     "deviceId": "6543214c-72bb-4131-9e14-fad974123456",
     "commandId": "108a9c71462a48e09426e06e844d47ba",
     "result": {
       "resultCode": "SUCCESSFUL",
       "resultDetail": null
     }
   }

单个设备命令下发

LWM2M/CoAP协议设备

批量设备命令下发

当前物联网平台仅支持对批量NB-IoT设备进行相同命令的下发。应用服务器可以调用创建批量任务接口，对批量设备下发控制指令。

批量任务下发之后，可以登录物联网平台控制台，点击右上角“进入设备管理服务”。在“批量任务”->“批量命令下发”界面查看任务执行的状态和结果，如果成功率低于100%，则可以单击具体的任务名称，进入任务详情，查看执行失败的原因。

命令执行状态说明

命令执行状态以及状态变化机制如下所示。

相关API接口

• 创建设备命令
• 设备服务调用
• 查询设备服务能力
• 查询设备命令
• 修改设备命令
• 创建设备命令撤销任务
• 查询设备命令撤销任务
• 创建批量任务
• 查询指定批量任务信息
• 查询批量任务的子任务信息