华为云用户手册

下发消息状态 MQTT设备消息执行状态以及状态变化机制如下所示。 图4 设备消息状态 表1 消息执行状态 消息执行状态 说明 等待（PENDING） MQTT协议设备不在线，物联网平台会将消息进行缓存，此时任务状态为“等待”状态。 超时（TIMEOUT） 物联网平台缓存的PENDING状态的消息，如果1天之内还没有下发下去，物联网平台会将消息状态设置为“超时”。 已送达（DELIVERED） 物联网平台将消息发送给设备后，状态变为“已送达”。 失败（FAILED） 物联网平台发送消息给设备不成功，消息状态变为“失败”。

概述 消息下发不依赖产品模型，提供给设备的单向通知，具有消息缓存功能；云端消息下发中，平台会以异步方式（消息下发后无需等待设备侧回复响应）下发消息给设备；若设备不在线，则在设备在线后发送数据（支持配置，最长缓存时间24小时）。平台对每个设备默认只保存20条消息，超过20条后，后续的消息会替换下发最早的消息。同时，消息下发支持使用自定义topic的格式进行数据下发。 表1 消息下发Topic类别 消息下发Topic类别 描述 系统Topic 平台预先定义了各种设备和平台通信的Topic，具体Topic列表和功能说明可参考Topic定义。 自定义Topic 用户可以自定义Topic，设备和平台间可以基于用户自定义的Topic进行通信。 自定义topic分类： 在产品中定义需要使用的Topic，这类Topic有$oc/devices/{device_id}/user/前缀，消息上报或者消息下发时平台会校验Topic是否在产品中定义，未在产品中定义的Topic会被平台拒绝。使用方式可以参考链接使用自定义Topic进行通信的最佳实践。 使用非$oc开头的自定义Topic，如/aircondition/data/up进行消息通信，这类Topic平台不校验Topic权限，根据MQTT协议定义的规则进行Topic的消息上下行通信。使用方式可以参考链接设备自定义Topic迁移上云。

消息下发使用QoS 1说明 MQTT设备接入，使用QoS 1的系统Topic进行设备消息下发说明： 图2 消息下发使用Qos 1流程图 设备上线。 订阅Topic，设置订阅Topic的QoS为1。 图3 订阅Topic的QoS为1 应用侧或平台用下发设备消息接口，下发请求到物联网平台，下发消息样例如下： POST https://{Endpoint}/v5/iot/{project_id}/devices/{device_id}/messagesContent-Type: application/jsonX-Auth-Token: ********{ "message_id": "99b32da9-cd17-4cdf-a286-f6e849cbc364", "name": "messageName", "message": "HelloWorld"} 物联网平台根据协议规范下发消息给设备。MQTT设备必须先订阅平台消息下发下行接口对应的Topic才能收到平台下发的消息，消息样例如下： Topic: $oc/devices/{device_id}/sys/messages/down 数据格式：{ "object_device_id": "{object_device_id}", "name": "name", "id": "id", "content": "hello"} 物联网平台向设备下发消息后，向应用服务器返回201 Created，消息状态为DELIVERED。消息下发是异步操作，不需要等设备ACK就可以回响应。 物联网平台没有收到设备接收消息的ACK响应，重发消息；默认每隔2s重发一次，总下发3次。 设备再次上线或订阅Topic。 物联网平台会重发之前设备未回ACK且未超时的消息，默认每隔10s重发一次，总下发5次；此次重发也会触发每隔2s重发机制，故总下发15次。 平台将消息的最终结果推送给应用服务器，设备消息状态为已送达（DELIVERED）或超时（TIMEOUT）。使用接口：设备消息状态变更通知接口。 Topic: $oc/devices/{device_id}/sys/messages/down 数据格式：{ "resource": "device.message.status", "event": "update", "notify_data": { "message_id": "string", "name": "string", "device_id": "string", "status": "DELIVERED", "timestamp": "string" } }

概述 为能有效地对设备进行管理，设备的产品模型中定义了物联网平台可向设备下发的命令，应用服务器可以调用物联网平台应用侧API接口向设备下发命令，以实现对设备的远程控制。 物联网平台有同步命令下发和异步命令下发两种命令下发机制，如下表所示。 表1 命令下发概述 命令下发机制 定义 适用场景 LwM2M/CoAP协议设备 MQTT协议设备 同步命令下发 应用服务器可调用同步命令下发接口向指定设备下发命令，以实现对设备的同步控制。平台负责将命令以同步方式发送给设备，并将设备执行命令结果在HTTP请求中同步返回, 如果设备没有响应，平台会返回给应用服务器超时。 同步命令下发适合对命令实时性有要求的场景，比如路灯开关灯，燃气表开关阀。使用同步命令下发时，命令下发的时机需要由应用服务器来保证。 不适用 适用 异步命令下发 应用服务器可调用异步命令下发接口向指定设备下发命令，以实现对设备的控制。平台负责将命令发送给设备，并将命令执行结果异步推送给应用。 异步命令下发又分为缓存下发和立即下发。 立即下发：不管设备是否在线，平台收到命令后立即下发给设备。如果设备不在线或者设备没收到指令则下发失败。 缓存下发：物联网平台在收到命令后先缓存，等设备上线或者设备上报属性时再下发给设备，如果单个设备存在多条缓存命令，则进行排队串行下发。 立即命令下发适用于实时性要求高的场景； 缓存下发适合对命令实时性要求不高的场景，比如配置水表的参数。 适用 不适用 具体使用流程请见：同步命令下发、异步命令下发。

消息缓存下发使用说明 以MQTT设备接入为例，使用系统Topic进行设备消息缓存下发说明： 图1 消息缓存下发流程 应用侧或平台用下发设备消息接口，下发请求到物联网平台，下发消息样例如下： POST https://{Endpoint}/v5/iot/{project_id}/devices/{device_id}/messagesContent-Type: application/jsonX-Auth-Token: ********{ "message_id": "99b32da9-cd17-4cdf-a286-f6e849cbc364", "name": "messageName", "message": "HelloWorld"} 物联网平台向应用返回201 Created，消息状态为PENDING。 物联网平台通过设备消息状态变更通知接口推送消息结果给应用，设备未上线时，设备消息状态为等待（PENDING），对应的消息样例如下： Topic: $oc/devices/{device_id}/sys/messages/down 数据格式：{ "resource": "device.message.status", "event": "update", "notify_data": { "message_id": "string", "name": "string", "device_id": "string", "status": "PENDING", "timestamp": "string" } } 设备上线。 设备订阅消息下发的topic，用于接收消息，订阅的topic见步骤6。 物联网平台根据协议规范下发消息给设备。MQTT设备必须先订阅平台消息下发下行接口对应的Topic才能收到平台下发的消息，消息样例如下： Topic: $oc/devices/{device_id}/sys/messages/down 数据格式：{ "object_device_id": "{object_device_id}", "name": "name", "id": "id", "content": "hello"} 平台将消息的最终结果推送给应用服务器，设备消息状态为已送达（DELIVERED）。使用接口：设备消息状态变更通知接口。 Topic: $oc/devices/{device_id}/sys/messages/down 数据格式：{ "resource": "device.message.status", "event": "update", "notify_data": { "message_id": "string", "name": "string", "device_id": "string", "status": "DELIVERED", "timestamp": "string" } }

单个MQTT设备同步命令下发 属性设置和属性查询分别参考查询设备属性和修改设备属性接口。 图1 命令下发流程图 应用调用下发设备命令接口，下发请求到物联网平台，命令下发消息样例如下： POST https://{Endpoint}/v5/iot/{project_id}/devices/{device_id}/commandsContent-Type: application/jsonX-Auth-Token: ********{ "service_id" : "WaterMeter", "command_name" : "ON_OFF", "paras" : { "value" : "ON" }} 物联网平台根据协议规范下发命令给设备。 MQTT设备使用平台命令下发下行接口对应的Topic用来接收平台下发的命令，消息样例如下： Topic: $oc/devices/{device_id}/sys/commands/request_id={request_id} 数据格式： { "object_device_id": "{object_device_id}", "command_name": "ON_OFF", "service_id": "WaterMeter", "paras": { "value": "ON" }} 设备执行命令后通过平台命令下发上行接口返回命令执行结果，消息样例如下： Topic：$oc/devices/{device_id}/sys/commands/response/request_id={request_id}数据格式： { "result_code": 0, "response_name": "COMMAND_RESPONSE", "paras": { "result": "success" }} 应用侧收到发送HTTP下发命令的同步响应结果。消息样例如下： Status Code: 200 OKContent-Type: application/json{ "command_id" : "b1224afb-e9f0-4916-8220-b6bab568e888", "response" : { "result_code" : 0, "response_name" : "COMMAND_RESPONSE", "paras" : { "result" : "success" } }}

批量MQTT设备同步命令下发 平台支持通过调用创建批量任务接口，对多个MQTT协议设备下发同步命令。下面介绍如何调用创建批量任务下发批量命令。 应用调用创建批量任务接口，下发请求到物联网平台，下发消息样例如下。 POST https://{Endpoint}/v5/iot/{project_id}/batchtasks Content-Type: application/jsonX-Auth-Token: ********{ "app_id": "84fb64e43c5f4c6cbec339e52449bcea", "task_name": "task123", "task_type": "createCommands", "targets": [ "5f2bc9b961e7670469c5ef6d_1997930"， "5f2bc9b961e7670469c5ef6d_1997931" ], "document": { "service_id": "water", "command_name": "ON_OFF", "paras": { "value": "ON" } }} 表2 命令下发创建批量任务参数表 参数 是否必选 描述 app_id 否 资源空间ID。 task_name 是 任务名（自定义）。 task_type 是 批量任务类型。具体可见创建批量任务，命令下发中取值有： createCommands-批量创建同步命令任务 createAsyncCommands-批量创建异步命令任务 targets 否 设备ID数组，执行批量任务的目标。 document 否 命令相关参数，执行任务数据文档，Json格式，Json里面是(K,V)键值对。参考设备同步命令 物联网平台向应用返回“201 Created”。 设备订阅下行topic接收命令，并通过上行topic向平台响应命令结果，参考平台命令下发。 通过调用查询批量任务列表接口查询批量命令下发任务执行情况。

概述 同步命令下发主要用于MQTT设备，分为单个MQTT设备同步命令下发与批量MQTT设备同步命令下发。 表1 同步命令下发 类型 描述 适用场景 使用示例 单个MQTT设备命令下发 平台向单个设备下发设备控制命令。 对单个设备进行下发设备控制命令。 单个MQTT设备命令下发使用示例 批量MQTT设备命令下发 平台向多个设备下发设备控制命令。可创建批量处理任务，对多个设备进行批量操作 对多个设备进行批量下发设备控制命令。 批量MQTT设备同步命令下发

LwM2M/CoAP设备命令执行状态说明 命令执行状态以及状态变化机制如下所示。 图3 LwM2M/CoAP命令下发状态 表2 LwM2M/CoAP命令执行状态 命令执行状态 说明 等待（PENDING） LwM2M/CoAP设备采用缓存下发模式下发命令时，如果设备未上报数据，物联网平台会将命令进行缓存，此时任务状态为“等待”状态。 LwM2M/CoAP设备采用立即下发模式下发命令时，无此状态。 超期（EXPIRED） LwM2M/CoAP设备采用缓存下发模式下发命令时，如果在设置的超期时间内，物联网平台未将命令下发给设备，则状态变更为“超期”。超期时间会根据应用侧接口中携带的expireTime为准，如果未携带，默认24h。 LwM2M/CoAP设备采用立即下发模式下发命令时，无此状态。 已发送（SENT） LwM2M/CoAP设备采用缓存下发模式下发命令时，设备上报数据，物联网平台会将缓存的命令发送给设备，此时状态会由“等待”变为“已发送”。 LWM2M/CoAP设备采用立即下发模式下发命令时，如果设备在线，状态为“已发送”。 超时（TIMEOUT） LwM2M/CoAP设备收到命令后，物联网平台在180秒内未收到设备反馈的收到命令响应，此时状态会变为“超时”。 已送达（DELIVERED） 物联网平台收到设备反馈的已收到下发命令响应后，状态变为“已送达”。 成功（SUCCESSFUL） 如果设备在执行完命令后，会给物联网平台反馈命令执行成功的结果，将任务状态变更为“成功”。 失败（FAILED） 如果设备在执行完命令后，会给物联网平台反馈命令执行失败的结果，将任务状态变更为“失败”。 LwM2M/CoAP设备采用立即下发模式下发命令时，如果设备离线，状态为“失败”。

异步命令缓存下发 图2 LwM2M/CoAP命令缓存下发流程 应用调用下发异步设备命令接口，下发请求到物联网平台，携带send_strategy为delay。 物联网平台将命令写入缓存队列，并上报200 OK，携带命令状态为PENDING。 设备上线或设备上报数据到平台。 物联网平台调用编解码插件对命令请求进行编码后，根据协议规范下发命令给设备。 若应用订阅了命令的状态变更通知，物联网平台通过命令状态变化通知接口推送消息给应用，携带命令状态为SENT。 后续流程请参考“命令立即下发”的步骤4到步骤7。

异步命令立即下发 图1 LwM2M/CoAP命令下发流程 按照上述使用流程，进行对应步骤的示例如下： 应用调用下发异步设备命令接口，下发请求到物联网平台，携带send_strategy为immediately。消息样例如下： POST https://{endpoint}/v5/iot/{project_id}/devices/{device_id}/async-commandsContent-Type: application/jsonX-Auth-Token: ********{ "service_id" : "WaterMeter", "command_name" : "ON_OFF", "paras" : { "value" : "ON" }, "expire_time": 0, "send_strategy": immediately} 物联网平台调用编解码插件对命令请求进行编码后，会通过LwM2M协议定义的设备管理和服务实现接口的Execute操作下发命令，消息体为二进制格式。 物联网平台向应用返回200 OK，携带命令状态为SENT。（如果设备不在线或者设备没收到指令则下发失败，命令状态为FAILED） 设备收到命令后返回ACK响应。 若应用订阅了命令的状态变更通知，物联网平台通过命令状态更新通知接口推送消息给应用，携带命令状态为DELIVERED。消息样例如下： Method: POSTrequest:Body:{ "resource": "device.commmad.status", "event": "update", "event_time": "20200811T080745Z", "notify_data": { "header": { "app_id": "8d4a34e5363a49bfa809c6bd788e6ffa", "device_id": "5f111a5a29c62ac7edc88828_test0001", "node_id": "test0001", "product_id": "5f111a5a29c62ac7edc88828", "gateway_id": "5f111a5a29c62ac7edc88828_test0001", "tags": [] }, "body": { "command_id": "49ca40af-7e14-4f7b-b97b-78cdd347a6b9", "created_time": "20200811T080738Z", "sent_time": "20200811T080738Z", "delivered_time": "20200811T080745Z", "response_time": "", "status": "DELIVERED", "result": null } }} 设备执行命令后通过205 Content响应返回命令执行结果。 若应用订阅了命令的状态变更通知，物联网平台会调用编解码插件对设备响应进行解码，然后通过命令状态更新通知接口推送消息给应用，携带命令状态为SUCCESSFUL。消息样例如下： Method: POSTrequest:Body:{ "resource": "device.commmad.status", "event": "update", "event_time": "20200811T080745Z", "notify_data": { "header": { "app_id": "8d4a34e5363a49bfa809c6bd788e6ffa", "device_id": "5f111a5a29c62ac7edc88828_test0001", "node_id": "test0001", "product_id": "5f111a5a29c62ac7edc88828", "gateway_id": "5f111a5a29c62ac7edc88828_test0001", "tags": [] }, "body": { "command_id": "49ca40af-7e14-4f7b-b97b-78cdd347a6b9", "created_time": "20200811T080738Z", "sent_time": "20200811T080738Z", "delivered_time": "20200811T080745Z", "response_time": "20200811T081745Z", "status": "SUCCESSFUL", "result": { "resultCode":"SUCCESSFUL", "resultDetail": { "value": "ON" } } } }}

概述 异步命令下发主要用于LwM2M/CoAP设备接入物联网平台，平台或应用侧可通过以下方式进行命令下发： 表1 异步命令下发 类型 描述 适用场景 使用流程 异步命令立即下发 不管设备是否在线，平台收到命令后立即下发给设备。如果设备不在线或者设备没收到指令则下发失败。 适用于实时性要求高的场景。 异步命令立即下发 异步命令缓存下发 物联网平台在收到命令后先缓存，等设备上线或者设备上报属性时再下发给设备，如果单个设备存在多条缓存命令，则进行排队串行下发。 适合对命令实时性要求不高的场景，比如配置水表的参数。 异步命令缓存下发

请求示例 POST https://{endpoint}/v5/devices/{device_id}/sys/gateway/sub-devices/properties/reportContent-Type: application/jsonaccess_token: d144a524-1997-4b99-94bf-f27128da8a34{ "devices" : [ { "device_id" : "deviceId_0001", "services" : [ { "service_id" : "serviceId", "properties" : { "Height" : 124, "Speed" : 23.24 }, "event_time" : "2021-08-13T10:10:10.555Z" } ] }, { "device_id" : "deviceId_0002", "services" : [ { "service_id" : "serviceId", "properties" : { "Height" : 124, "Speed" : 23.24 }, "event_time" : "2021-08-13T10:10:10.555Z" } ] } ]}

错误码 HTTP状态码 HTTP状态码描述 错误码 错误码描述 错误码中文描述 400 Bad Request IOTDA.000006 Invalid input data. 请求参数不合法 IOTDA.021104 Subdevices in the request does not exist or does not belong to the gateway. 请求中有部分子设备不存在或不属于该网关. 403 Forbidden IOTDA.000004 Invalid access token. 非法token IOTDA.021101 Request reached the maximum rate limit. 请求已经达到限制速率 IOTDA.021102 The request rate has reached the upper limit of the tenant, limit %s. 请求已经达到租户的限制速率 IOTDA.021103 The request batch properties number has reached the upper limit, limit %s. 请求中子设备数量达到上限 IOTDA.021105 The content reported in a single request cannot exceed 1 MB. 单次请求上报的内容不能超过1MB

请求示例 POST https://{endpoint}/v5/devices/{device_id}/sys/properties/reportContent-Type: application/jsonaccess_token: d144a524-1997-4b99-94bf-f27128da8a34{ "services" : [ { "service_id" : "serviceId", "properties" : { "Height" : 124, "Speed" : 23.24 }, "event_time" : "2021-08-13T10:10:10.555Z" } ]}

错误码 HTTP状态码 HTTP状态码描述 错误码 错误码描述 错误码中文描述 400 Bad Request IOTDA.000006 Invalid input data. 请求参数不合法 IOTDA.021104 Subdevices in the request does not exist or does not belong to the gateway. 请求中有部分子设备不存在或不属于该网关. 403 Forbidden IOTDA.000004 Invalid access token. 非法token IOTDA.021101 Request reached the maximum rate limit. 请求已经达到限制速率 IOTDA.021102 The request rate has reached the upper limit of the tenant, limit %s. 请求已经达到租户的限制速率 IOTDA.021105 The content reported in a single request cannot exceed 1 MB. 单次请求上报的内容不能超过1MB

操作步骤 设备发起连接鉴权，鉴权参数填写规则参考设备连接鉴权。 设备鉴权成功后，发起广播Topic订阅，广播Topic必须为“$oc/broadcast/”前缀，样例如下： $oc/broadcast/test 应用服务器下发广播消息，指定Topic名称和消息内容。 POST https://{Endpoint}/v5/iot/{project_id}/broadcast-messagesContent-Type: application/jsonX-Auth-Token: ********{ "topic_full_name" : "$oc/broadcast/test", "message" : "eyJhIjoxfQ=="} 这里Topic必须为“$oc/broadcast/”前缀，消息内容需要使用BASE64编码。 设备接收广播消息，设备接收的广播消息样例如下。 Topic: $oc/broadcast/test 数据内容：{"a":1}

概述 MQTT消息由固定报头（Fixed header）、可变报头（Variable header）和有效载荷（Payload）三部分组成。 其中固定报头（Fixed header）和可变报头（Variable header）格式的填写请参考MQTT标准规范，有效载荷（Payload）的格式由应用定义，即设备和物联网平台之间自己定义。 MQTT的语法和接口细节，请以MQTT标准规范为准。 常见MQTT消息类型主要有CONNECT、SUBSCRIBE、PUBLISH。 CONNECT：指客户端请求和服务端连接。有效载荷（Payload）的主要参数，参考设备连接鉴权填写。 SUBSCRIBE：指客户端订阅请求。有效载荷（Payload）中的主要参数“Topic name”，参考Topic定义中订阅者为设备的Topic。 PUBLISH：平台发布消息。 可变报头（Variable header）中的主要参数“Topic name”，指设备上报到物联网平台时发布者为设备的Topic。详细请参考Topic定义。 有效载荷（Payload）中的主要参数为完整的数据上报和命令下发的消息内容，目前是一个JSON对象。

操作步骤 使用设备间消息通信功能时，需要在产品中配置用于设备间通信的Topic，同时配置该Topic具有发布和订阅的权限。具体步骤如下： 访问设备接入服务，单击“管理控制台 ”进入设备接入控制台。 创建产品，产品的“协议类型”选择“MQTT”。 图2 创建产品 在产品中创建自定义Topic，如“$oc/devices/{device_id}/user/up”，注意这个Topic需要有发布与订阅的操作权限。 图3 自定义Topic 配置好设备间通信Topic后，您可以根据自己的业务场景来实现设备间消息通信。下面以MQTT.fx为例说明如何进行设备间消息通信： 在2中创建的产品下分别注册设备A和设备B，详细步骤可参考注册单个设备。 图4 注册设备 打开两个MQTT.fx，分别模拟设备A、B。如何使用MQTT.fx可参考使用Mqtt.fx调测。 设备B在Subscribe页面中输入Topic“ $oc/devices/{device_id}/user/up”（其中"{device_id}"替换为设备B的设备ID）后，单击“Subscribe”订阅。 图5 设备B在Subscribe页面中输入topic 如设备A向设备B发送消息，在设备A的MQTT.fx的“Publish”页面中，输入topic"$oc/devices/{device_id}/user/up”（其中“{device_id}”替换成接收者设备B的设备ID） ，在内容输入框中输入要发送的消息（如：hello）单击“Publish”即可发送。 图6 设备A Publish页面输入消息 设备B Subscribe页面可以看到接受到发送者设备A消息如下： 图7 设备B Subscribe页面展示

设备鉴权 API 说明 设备鉴权 设备鉴权接口，鉴权通过后建立设备与平台间才能处理业务连接。鉴权成功后平台返回access_token。调用属性上报、消息上报等其他接口时，都需要携带access_token信息。如果access_token超期，需要重新认证设备获取access_token。如果access_token未超期重复获取access_token，老的access_token在未超期前保留30s，30s之后失效。

MQTT的TLS支持 平台推荐使用TLS来保护设备和平台的传输安全。 平台目前支持TLS1.0、1.1 、1.2和1.3版本以及GMTLS。其中TLS 1.0 和1.1 计划后续不再支持，建议使用 TLS 1.3作为首选 TLS 版本。GMTLS版本仅在国密算法的企业版才支持。 基础版，标准版以及支持通用加密算法的企业版使用TLS连接时，平台支持如下加密套件： TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA 支持国密算法的企业版使用TLS连接时平台支持如下加密套件： ECC_SM4_GCM_SM3 ECC_SM4_CBC_SM3 ECDHE_SM4_GCM_SM3 ECDHE_SM4_CBC_SM3 TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

使用限制 描述 限制 单个MQTT直连设备在同一时间的连接数 1 单个MQTT直连设备最大建链每分钟请求次数 5/min 单账户设备侧每秒最大建链请求数量 500/s 单账号设备侧每秒最大上行的请求数量（单消息payload平均为512字节） 20000/s 单个MQTT连接每秒最大上行消息数量 50/s 单个MQTT连接最大带宽（上行消息） 1MB（默认） MQTT单条发布消息最大长度。超过此大小的发布请求将被直接拒绝。 1MB MQTT协议规范 MQTT v5.0、MQTT v3.1.1、MQTT v3.1 与标准MQTT协议的区别 不支持QoS2 不支持will、retain msg MQTT协议支持的安全等级 采用TCP通道基础 + TLS协议（TLSv1、 TLSv1.1、TLSv1.2和TLSv1.3版本） MQTT连接心跳时间建议值 心跳时间限定为30至1200秒，推荐设置为120秒 MQTT协议消息发布与订阅 设备只能对自己的Topic进行消息发布与订阅 MQTT协议每个订阅请求的最大订阅数 无限制 MQTT自定义Topic支持的最大长度 64字节 MQTT自定义Topic支持每个产品添加的最大个数 10个/产品 单账号支持上传设备侧CA证书个数 100个

使用限制 描述 限制 支持的HTTP协议版本 支持 Hypertext Transfer Protocol — HTTP/1.0 协议 支持 Hypertext Transfer Protocol — HTTP/1.1 协议 支持HTTPS协议 物联网平台仅支持HTTPS协议，证书下载请参考证书资源。 支持的TLS版本 TLS 1.2 支持的body体最大长度 1MB 接口规格说明 请参考产品规格说明。 网关上报子设备属性时一次最大可上报子设备数 50

HTTPS设备与物联网平台通信 设备使用HTTPS协议接入平台时，平台和设备通过https接口调用通信。通过这些接口，平台和设备可以实现设备鉴权、消息上报及属性上报。 消息类型 说明 设备鉴权 用于设备获取鉴权信息access_token。 设备属性上报 用于设备按产品模型中定义的格式将属性数据上报给平台。 设备消息上报 用于设备将自定义数据上报给平台，平台将设备上报的消息转发给应用服务器或华为云其他云服务上进行存储和处理。 网关批量属性上报 用于网关设备将多个子设备的属性数据一次性上报给平台。

业务流程 设备接入前，需创建产品（可通过控制台创建或者使用应用侧API创建产品）。 产品创建完毕后，需注册设备（可通过控制台注册单个设备或者使用应用侧API注册设备创建）。 设备注册完毕后，通过设备鉴权接口获取设备的access_token。 图1 获取设备access_token 获取到access_token之后，可以消息/属性上报等功能。其中access_token放于消息头中，下面示例为上报属性： 图2 上报属性 图3 上报属性

http接口介绍 物联网平台的接口如下表所示： 接口分类 用途 接口 设备鉴权相关接口 设备鉴权 /v5/device-auth 设备消息相关接口 设备消息上报 /v5/devices/{device_id}/sys/messages/up 设备属性相关接口 设备属性上报 /v5/devices/{device_id}/sys/properties/report 网关上报子设备属性 /v5/devices/{device_id}/sys/gateway/sub-devices/properties/report

错误码 HTTP状态码 HTTP状态码描述 错误码 错误码描述 错误码中文描述 400 Bad Request IOTDA.000006 Invalid input data. 请求参数不合法 403 Forbidden IOTDA.000004 Invalid access token. 非法token IOTDA.021101 Request reached the maximum rate limit. 请求已经达到限制速率 IOTDA.021102 The request rate has reached the upper limit of the tenant, limit %s. 请求已经达到租户的限制速率

请求参数 名称 必选 类型 位置 说明 access_token 是 String Header 参数说明: 调用设备鉴权信息返回的access_token 取值范围: 长度1-256 device_id 是 String Path 参数说明: 参数说明：设备ID，用于唯一标识一个设备。在注册设备时直接指定，或者由物联网平台分配获得。由物联网平台分配时，生成规则为"product_id" + "_" + "node_id"拼接而成。 取值范围：长度不超过128，只允许字母、数字、下划线（_）、连接符（-）的组合。 取值范围: 长度1-128 该接口支持设备将自定义数据通过请求中的body体上报给平台，平台收到该请求后会将body内容转发给应用服务器或华为云其他云服务上进行存储和处理。平台对body中的内容无具体格式限制，小于1MB的数据可以通过该接口携带。

请求示例 POST https://{endpoint}/v5/devices/{device_id}/sys/messages/upContent-Type: application/jsonaccess_token: d144a524-1997-4b99-94bf-f27128da8a34{ "name" : "name", "id" : "id", "content" : "messageUp"}

固件升级失败原因 物联网平台上报的失败原因： 失败原因 原因解释 处理建议 Device Abnormal is not online 设备异常未在线 请检查设备侧。 Task Conflict 任务冲突 请检查当前设备是否有软件升级、固件升级、日志收集或设备重启的任务正在进行。 Waiting for the device online timeout 等待设备上线超时 请检查设备侧。 Wait for the device to report upgrade result timeout 等待设备上报升级结果超时 请检查设备侧。 Waiting for report device firmware version timeout 等待上报设备固件版本超时 请检查设备侧。 Waiting for report cellId timeout 等待上报cellId超时 请检查设备侧。 Updating timeout and query device version for check timeout 等待升级结果超时，且等待设备版本信息超时 请检查设备侧。 Waiting for device downloaded package timeout 等待设备完成下载固件包超时 请检查设备侧。 Waiting for device start to update timeout 等待设备启动更新超时 请检查设备侧。 Waiting for device start download package timeout 等到设备开始下载固件包超时 请检查设备侧。 设备上报的失败原因： 失败原因 原因解释 处理建议 Not enough storage for the new firmware package 下载的固件包存储空间不足 请检查设备存储。 Out of memory during downloading process 下载过程中内存不足 请检查设备内存。 Connection lost during downloading process 下载过程中连接断开 请检查设备连接状态。 Integrity check failure for new downloaded package 下载的固件包完整性校验失败 请检查设备下载的固件包是否完整。 Unsupported package type 固件包类型不支持 请检查设备状态和厂商提供的固件包是否正确。 Invalid URI URI不可用 检查设备侧的固件包下载地址是否正确。 Firmware update failed 固件更新失败 请检查设备侧。