下发命令¶

命令下发一般分为两种：立即下发和缓存下发。

立即下发：EnOS 立即发送收到的命令，如果设备不在线或者设备没收到命令则下发失败。
缓存下发：EnOS 首先将该条命令加入到此设备的缓存下发队列中，缓存队列是一个有序的队列，等待设备重新与 EnOS 端建立连接后，EnOS 对缓存的命令按顺序进行下发。缓存下发适合在设备与 EnOS 连接断开，或在低功耗设备因长期休眠无法及时获取及执行 EnOS 下发的命令的场景。EnOS 为单个设备缓存最多 50 条命令。

当应用通过 API，如 Invoke Service API 或 Set Measurement Point API，向 EnOS 发送请求时，将会携带参数 pendingTtl。该参数表示缓存命令的有效期，取值范围是 0-172800 中的整数值，单位是秒，即 0-48 小时。pendingTtl的默认值为 0，即命令默认会立即下发。

pendingTtl = 0：命令立即下发。

pendingTtl > 0：命令缓存下发。

缓存命令下发流程¶

命令缓存下发的流程如下图，假定 pendingTtl=3600：

../../_images/issuing_cached_commands.png

缓存命令在下发的过程中，遵守以下规则：

缓存有序下发：设备处理并返回上一条命令的响应信息后，EnOS 才会发送下一条缓存命令，上一条命令的处理结果包括：发送成功（设备接收命令并正常响应）和响应超时（EnOS 已经发送了命令但是设备没有及时响应）。
命令无优先级：无论设备是否在线，在缓存命令尚未处理完，而应用又发送了一条新命令的情况下，无论新命令是立即下发的还是缓存下发的，都会加入到队列中等待按照顺序下发。如果要优先发送新命令，应用应当调用 Cancel Command API 对缓存的命令进行撤销，才可下发新的命令。也就是说缓存队列中，也可以存储本应立即下发的命令，所有命令按顺序下发。如果此时设备下线了，则立即下发的命令将自动失败。
超期命令清除出队列：超过有效期的缓存命令，EnOS 从缓存队列中自动清除，并将状态置为“已超期”。

设备端开发¶

设备可以在响应信息中带上自定义的业务描述信息以说明命令执行的状态，响应数据格式如下，message 为描述命令执行状态的字段。

{
    "id": "123",
    "code": 200,
    "message": "该命令已成功执行"
    "data": {
               "outputdata1":234,
               "outputdata2":"xyz"
              }
}

查看缓存的命令状态¶

当应用向设备发送的命令被缓存时，用户可以通过控制台查看缓存命令的状态。

开始前准备¶

你需要有设备管理操作权限，如果没有请联系组织管理员添加，参见策略，角色，与权限。

步骤¶

在控制面板中选择 设备管理 > 设备资产。
选择需查看命令的设备，并点击其查看图标。
在 设备详情 页面，点击命令页签，即可查看当前设备当前的所有缓存命令。

你可以在该查看页面进行以下操作：
- 根据条件筛选需查看的命令。
- 对于 已创建 而未下发的命令，应用可以调用 Cancel Command API 进行撤销。
你最多可以查询到最近7天的历史命令的相关信息，包括 request id、命令名称、命令内容、设备响应信息、命令创建时间、状态信息等。

结果¶

命令有以下几种状态：

已创建：云端接收命令并创建，但未发送给设备。
已取消：该命令已被撤销，只有处于 已创建 状态的命令才能被撤销。
已过期：命令超过指定的有效期为过期。有效期可以由应用指定，默认值为 0s，即应用不指定的话即作为即时命令下发，有效期最大值不超过 48 小时（172800s），对于超过有效期的缓存命令，云端需要从缓存队列中自动清除，并将状态置为 已过期。
已下发：云端已将命令投递到发往设备的下行消息通道中，但设备尚未响应。注意，该状态不代表一定发送成功；
发送成功：设备接收命令并返回响应信息，表示设备已执行命令成功。设备可以在响应信息中的 message 里带上自定义的业务描述信息（可选）。
发送失败：命令因为各种原因发送失败：该条命令无法被正确的投递到下行消息通道中；或者设备已收到命令，但执行失败。可能原因为：设备离线、脚本解析错误，无效命令等。
响应超时：命令发送到设备下行消息通道，设备在 timeout 周期内无响应。

下发命令¶

缓存命令下发流程¶

设备端开发¶

查看缓存的命令状态¶

开始前准备¶

步骤¶

结果¶

相关文档¶