下发异步设备命令
功能介绍
设备的产品模型中定义了物联网平台可向设备下发的命令，应用服务器可调用此接口向指定设备下发异步命令，以实现对设备的控制。平台负责将命令发送给设备，并将设备执行命令结果异步通知应用服务器。 命令执行结果支持灵活的数据流转，应用服务器通过调用物联网平台的创建规则触发条件（Resource:device.command.status，Event:update）、创建规则动作并激活规则后，当命令状态变更时，物联网平台会根据规则将结果发送到规则指定的服务器，如用户自定义的HTTP服务器，AMQP服务器，以及华为云的其他存储服务器等, 详情参考设备命令状态变更通知。
注意：
-
此接口适用于NB设备异步命令下发，暂不支持其他协议类型设备命令下发。
-
此接口仅支持单个设备异步命令下发，如需多个设备异步命令下发，请参见 创建批量任务。
调试
您可以在API Explorer中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。
URI
POST /v5/iot/{project_id}/devices/{device_id}/async-commands
|
参数 |
是否必选 |
参数类型 |
描述 |
|---|---|---|---|
|
project_id |
是 |
String |
参数说明：项目ID。获取方法请参见 获取项目ID。 |
|
device_id |
是 |
String |
参数说明：下发命令的设备ID，用于唯一标识一个设备，在注册设备时由物联网平台分配获得。 取值范围：长度不超过128，只允许字母、数字、下划线（_）、连接符（-）的组合。 |
请求参数
|
参数 |
是否必选 |
参数类型 |
描述 |
|---|---|---|---|
|
X-Auth-Token |
否 |
String |
参数说明：用户Token。通过调用IAM服务 获取IAM用户Token接口获取，接口返回的响应消息头中“X-Subject-Token”就是需要获取的用户Token。简要的获取方法样例请参见 Token认证。 |
|
Instance-Id |
否 |
String |
参数说明：实例ID。物理多租下各实例的唯一标识，建议携带该参数，在使用专业版时必须携带该参数。您可以在IoTDA管理控制台界面，选择左侧导航栏“总览”页签查看当前实例的ID，具体获取方式请参考 查看实例详情。 |
|
参数 |
是否必选 |
参数类型 |
描述 |
|---|---|---|---|
|
service_id |
否 |
String |
参数说明：设备命令所属的设备服务ID，在设备关联的产品模型中定义。如设备需要编解码插件来解析命令，此参数为必填项。 取值范围：长度不超过64的字符串。 |
|
command_name |
否 |
String |
参数说明：设备命令名称，在设备关联的产品模型中定义。如设备需要编解码插件来解析命令，此参数为必填项。 取值范围：长度不超过128的字符串。 |
|
paras |
是 |
Object |
参数说明：设备执行的命令，Json格式，里面是一个个键值对，如果service_id不为空，每个键都是profile中命令的参数名（paraName）;如果service_id为空则由用户自定义命令格式。设备命令示例：{"value":"1"}，具体格式需要应用和设备约定，请求对象最大长度为256KB |
|
expire_time |
否 |
Integer |
参数说明：物联网平台缓存命令的时长， 单位秒, 平台最多缓存20条消息（即最多缓存20条PENDING状态的命令） 该参数在send_strategy字段为delay时有效，默认缓存24小时，最大缓存2天。 |
|
send_strategy |
是 |
String |
参数说明：下发策略，默认缓存下发。 取值范围：
|
响应参数
状态码： 200
|
参数 |
参数类型 |
描述 |
|---|---|---|
|
device_id |
String |
设备ID，用于唯一标识一个设备，在注册设备时由物联网平台分配获得。 |
|
command_id |
String |
设备命令ID，用于唯一标识一条命令，在下发设备命令时由物联网平台分配获得。 |
|
service_id |
String |
设备命令所属的设备服务ID，在设备关联的产品模型中定义。 |
|
command_name |
String |
设备命令名称，在设备关联的产品模型中定义。 |
|
paras |
Object |
设备执行的命令，Json格式，里面是一个个键值对，如果service_id不为空，每个键都是profile中命令的参数名（paraName）;如果service_id为空则由用户自定义命令格式。设备命令示例：{"value":"1"}，具体格式需要应用和设备约定。 |
|
expire_time |
Integer |
物联网平台缓存命令的时长， 单位秒。 |
|
status |
String |
设备命令状态,如果命令被缓存，返回PENDING, 如果命令下发给设备，返回SENT。 |
|
created_time |
String |
命令的创建时间，"yyyyMMdd'T'HHmmss'Z'"格式的UTC字符串。 |
|
send_strategy |
String |
下发策略， immediately表示立即下发，delay表示缓存起来，等数据上报或者设备上线之后下发。 |
请求示例
创建异步命令，命令名为ON_OFF，命令为ON。
POST https://{endpoint}/v5/iot/{project_id}/devices/{device_id}/async-commands
{
"service_id" : "reboot",
"command_name" : "ON_OFF",
"paras" : {
"value" : "ON"
},
"expire_time" : 0,
"send_strategy" : "immediately"
}
响应示例
状态码： 200
OK
{
"device_id" : "c1224afb-e9f0-4916-8220-b6bab568e888",
"command_id" : "b1224afb-e9f0-4916-8220-b6bab568e888",
"service_id" : "Switch",
"command_name" : "ON_OFF",
"send_strategy" : "immediately",
"paras" : {
"value" : "ON"
},
"expire_time" : 0,
"status" : "SENT",
"created_time" : "20151212T121212Z"
}
状态码
|
状态码 |
描述 |
|---|---|
|
200 |
OK |
|
400 |
Bad Request |
|
401 |
Unauthorized |
|
403 |
Forbidden |
|
404 |
Not Found |
|
500 |
Internal Server Error |
错误码
请参见错误码。
