注意事项
HTTP 状态码
1.7 设备命令
1.7.1 设备同步命令
Internal server
error. 服务器内部错误 请联系华为工程师
分析解决。
IOTDA .00002 0
Decrypt IAM token
failed. IAM Token解析失 败
请联系华为工程师 分析解决。
1.7 设备命令
1.7.1 设备同步命令
设备的产品模型中定义了物联网平台可向设备下发的命令，设备命令为应用服务器提 供向设备下发命令的功能，实现对设备的控制操作。
1.7.1.1 下发设备命令
接口说明
设备的产品模型中定义了物联网平台可向设备下发的命令，应用服务器可调用此接口 向指定设备下发命令，以实现对设备的同步控制。平台负责将命令以同步方式发送给 设备，并将设备执行命令结果同步返回, 如果设备没有响应，平台会返回给应用服务器 超时，平台超时间是20秒。注意：此接口适用于MQTT设备同步命令下发，暂不支持 NB-IoT设备命令下发。
调试
您可以在API Explorer中调试该接口。
URI
请求方法 POST
URI /v5/iot/{project_id}/devices/{device_id}/commands 传输协议 HTTPS
请求参数
名称 必选/可
选
类型 位置 说明
X-Auth-Token 必选 String Head
er 参数说明：用户Token。通过调用 IAM服务 获取IAM用户Token接口 获取，接口返回的响应消息头中
“X-Subject-Token”就是需要获 取的用户Token。简要的获取方法 样例请参见 Token认证。
Instance-Id 可选 String Head
er 参数说明：实例ID。物理多租下各 实例的唯一标识，一般华为云租户 无需携带该参数，仅在物理多租场 景下从管理面访问API时需要携带 该参数。
project_i
d 必选 String Path 参数说明：项目ID。获取方法请参 见 获取项目ID。
device_id 必选 String Path 参数说明：下发消息的设备ID，用 于唯一标识一个设备，在注册设备 时由物联网平台分配获得。
取值范围：长度不超过128，只允 许字母、数字、下划线（_）、连 接符（-）的组合。
service_id 可选 String Body 参数说明：设备命令所属的设备服 务ID，在设备关联的产品模型中定 义。
取值范围：长度不超过64的字符 串。
comman
d_name 可选 String Body 参数说明：设备命令名称，在设备 关联的产品模型中定义。
取值范围：长度不超过128的字符 串。
名称 必选/可 选
类型 位置 说明
paras 必选 Object Body 参数说明：设备执行的命令，Json 格式，里面是一个个键值对，如果 serviceId不为空，每个键都是 profile中命令的参数名
（paraName）;如果serviceId为空 则由用户自定义命令格式。设备命 令示例：{"value":"1"}，具体格式 需要应用和设备约定。此参数仅支 持Json格式，暂不支持字符串。
响应参数
名称 类型 说明
command_i
d String 设备命令ID，用于唯一标识一条命令，在下发设
备命令时由物联网平台分配获得。
response Object 设备上报的命令执行结果。Json格式，具体格式 需要应用和设备约定。
请求示例
POST https://{Endpoint}/v5/iot/{project_id}/devices/{device_id}/commands Content-Type: application/json
X-Auth-Token: ********
Instance-Id: ********
{ "service_id" : "b1224afb-e9f0-4916-8220-b6bab568e888", "command_name" : "ON_OFF",
"paras" : { "value" : "ON"
}}
响应示例
Status Code: 200 OK
Content-Type: application/json
{ "command_id" : "b1224afb-e9f0-4916-8220-b6bab568e888", "response" : {
"result_code" : 0,
"response_name" : "COMMAND_RESPONSE", "paras" : {
"result" : "success"
} }}
错误码
HTTP 状态码
错误码 错误码英文描述 错误码中文描述 处理建议
200 IOTDA .01411 1
Command request
timeout. 命令请求超时 请确认设备是否收
到平台的请求并订 阅正确的topic且回 复正确的响应给平 台。
400 IOTDA .01402 8
Invalid input. The gateway is not online.
Invalid parameter
'commandName'. commandName参 数不合法
请检查serviceId,command Name参数是否与
Send to device failed, device not subscribe topic.
发送到设备失败，
The interface does not support NB-IoT device.
此接口暂不支持NB-IoT设备 请采用下发异步设
备命令接口。
403 IOTDA .00002 1
Operation not allowed. User not found by IAM token or the authorized user has not subscribed IOTDA service.
没有找到IAM Token所对应的用户 信息或该用户没有 订阅设备接入服务
（IOTDA）
请排查IAM Token 所在用户是否订阅
Operation not allowed. The user does not have the permission
Operation not allowed.
Application not found by
authorized user or the authorized user has no application.
HTTP
Operation not allowed. The device is not online.
Operation not allowed. The device has been frozen, can not be operated.
CommandBody for mqtt protocol is not correct.
适用于mqtt协议的 404 IOTDA
.01400 0
The device does
not exist. 设备不存在 请排查请求参数是 否有误并确认是否 有在平台注册该设 备。
500 IOTDA .00000