注意事项
HTTP 状态码
1.6 设备消息
1.6.2 下发设备消息
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.
Operation not allowed. The device has been frozen, can not be operated.
设备已被冻结，不 允许操作
请将设备解冻后再 重试。
404 IOTDA .01400 0
The device does
not exist. 设备不存在 请排查请求参数是 否有误并确认是否 有在平台注册该设 备。
500 IOTDA .00000 1
Internal server
error. 服务器内部错误 请联系华为工程师
分析解决。
IOTDA .00002 0
Decrypt IAM token
failed. IAM Token解析失 败
请联系华为工程师 分析解决。
1.6.2 下发设备消息
接口说明
发送给设备。注意：此接口适用于MQTT设备消息下发，暂不支持其他协议接入的设 备消息下发。
调试
您可以在API Explorer中调试该接口。
URI
请求方法 POST
URI /v5/iot/{project_id}/devices/{device_id}/messages 传输协议 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，只允 许字母、数字、下划线（_）、连 接符（-）的组合。
message
_id 可选 String Body 参数说明：消息id，由用户生成
（推荐使用UUID），同一个设备 下唯一， 如果用户填写的id在设备 下不唯一， 则接口返回错误。
取值范围：长度不超过100，只允 许字母、数字、下划线（_）、连 接符（-）的组合。
名称 必选/可 选
类型 位置 说明
name 可选 String Body 参数说明：消息名称。
取值范围：长度不超过128，只允 许中文、字母、数字、以及 _?'#().,&%@!-等字符的组合。
message 必选 Object Body 参数说明：消息内容，支持string 和json格式。
encoding 可选 String Body 参数说明：消息内容编码格式。默 认值none。
取值范围：
● none
● base64：只能通过
topic_full_name字段自定义的 topic发送消息,否则会发送失 败。
payload_
format 可选 String Body 参数说明：有效负载格式，在消息 内容编码格式为none时有效。默 认值standard（平台封装的标准格 式）。
取值范围：
● standard
● raw：时直接将消息内容作为有 效负载下发， 注意： 取值为 raw时，只能通过
topic_full_name字段自定义的 topic发送消息，否则会发送失 败。
名称 必选/可 选
类型 位置 说明
topic 可选 String Body 参数说明：消息下行到设备的 topic, 可选， 仅适用于MQTT协议 接入的设备。 用户只能填写在租 户产品界面配置的topic, 否则会校 验不通过。 平台给消息topic添加 的前缀为$oc/devices/{device_id}/
user/， 用户可以在前缀的基础上 增加自定义部分， 如增加
messageDown，则平台拼接前缀 后完整的topic为 $oc/devices/
{device_id}/user/
messageDown，其中device_id以 实际设备的网关id替代。 如果用户 指定该topic，消息会通过该topic 下行到设备，如果用户不指定，
则消息通过系统默认的topic下行 到设备,系统默认的topic格式为：
$oc/devices/{device_id}/sys/
messages/down。此字段与 topic_full_name字段只可填写一 个。
topic_full
_name 可选 String Body 参数说明：消息下行到设备的完整 topic名称, 可选。用户需要下发用 户自定义的topic给设备时，可以 使用该参数指定完整的topic名 称，物联网平台不校验该topic是 否在平台定义，直接透传给设备。
设备需要提前订阅该topic。此字 段与topic字段只可填写一个。
响应参数
名称 类型 说明
message_id String 消息id，由用户生成（推荐使用UUID），同一个 设备下唯一， 如果用户不填写，则由物联网平台 生成。
result MessageResult
Object 消息下发结果。Json格式。
表1-46 MessageResult
名称 类型 说明
status String 消息状态, PENDING，DELIVERED，FAILED和 TIMEOUT。如果设备不在线，则平台缓存消息，
并且返回PENDING，等设备数据上报之后再下 发；如果设备在线，则消息直接进行下发，下发 成功后接口返回DELIVERED，失败返回FAILED；
如果消息在平台默认时间内（1天）还没有下发给 设备，则平台会将消息设置为超时，状态为 TIMEOUT。另外应用可以订阅消息的执行结果，
平台会将消息结果推送给订阅的应用。
created_tim
e String 消息的创建时间，"yyyyMMdd'T'HHmmss'Z'"格 式的UTC字符串。
finished_tim
e String 消息结束时间, "yyyyMMdd'T'HHmmss'Z'"格式的 UTC字符串，包含消息转换到DELIVERED，
FAILED和TIMEOUT状态的时间。
请求示例
POST https://{Endpoint}/v5/iot/{project_id}/devices/{device_id}/messages Content-Type: application/json
X-Auth-Token: ********
Instance-Id: ********
{ "message_id" : "99b32da9-cd17-4cdf-a286-f6e849cbc364", "name" : "messageName",
"message" : "HelloWorld", "encoding" : "none",
"payload_format" : "standard", "topic" : "messageDown",
"topic_full_name" : "/device/message/down"
}
响应示例
Status Code: 201 Created
Content-Type: application/json
{ "message_id" : "b1224afb-e9f0-4916-8220-b6bab568e888", "result" : {
"status" : "PENDING",
"created_time" : "20151212T121212Z", "finished_time" : "20151212T121213Z"
}}
错误码
HTTP 状态码
错误码 错误码英文描述 错误码中文描述 处理建议
400 IOTDA .01413 0
Invalid input. The messageId of device is not unique.
Invalid input. The topic have no permission.
Invalid input. The input of topic related is duplicated.
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.
Operation not allowed. The device has been frozen, can not be operated.
设备已被冻结，不 允许操作
请将设备解冻后再 重试。
404 IOTDA .01400 0
The device does
not exist. 设备不存在 请排查请求参数是 否有误并确认是否 有在平台注册该设 备。
HTTP 状态码
错误码 错误码英文描述 错误码中文描述 处理建议
500 IOTDA .00000