华为云用户手册

响应参数 状态码： 200 表3 响应Body参数 参数 参数类型 描述 tunnel_id String 隧道ID device_id String 设备ID create_time String 隧道创建时间。格式：yyyyMMdd'T'HHmmss'Z'，如20151212T121212Z。 closed_time String 隧道更新时间。格式：yyyyMMdd'T'HHmmss'Z'，如20151212T121212Z。 status String 隧道状态 CLOSED | OPEN source_connect_state ConnectState object 访问端（console）状态 device_connect_state ConnectState object 设备端状态 表4 ConnectState 参数 参数类型 描述 last_update_time String 隧道最近一次状态更新时间。格式：yyyyMMdd'T'HHmmss'Z'，如20151212T121212Z。 status String 客户端连接状态 CONNECTED | DISCONNECTED

请求参数 表2 请求Header参数 参数 是否必选 参数类型 描述 X-Auth-Token 否 String 参数说明：用户Token。通过调用 IAM 服务 获取IAM用户Token接口获取，接口返回的响应消息头中“X-Subject-Token”就是需要获取的用户Token。简要的获取方法样例请参见 Token认证。 Instance-Id 否 String 参数说明：实例ID。物理多租下各实例的唯一标识，建议携带该参数，在使用专业版时必须携带该参数。您可以在IoTDA管理控制台界面，选择左侧导航栏“总览”页签查看当前实例的ID，具体获取方式请参考查看实例详情 。

请求参数 表2 请求Header参数 参数 是否必选 参数类型 描述 X-Auth-Token 否 String 参数说明：用户Token。通过调用IAM服务 获取IAM用户Token接口获取，接口返回的响应消息头中“X-Subject-Token”就是需要获取的用户Token。简要的获取方法样例请参见 Token认证。 Instance-Id 否 String 参数说明：实例ID。物理多租下各实例的唯一标识，建议携带该参数，在使用专业版时必须携带该参数。您可以在IoTDA管理控制台界面，选择左侧导航栏“总览”页签查看当前实例的ID，具体获取方式请参考查看实例详情 。

示例 Topic: $oc/devices/{device_id}/sys/events/up 数据格式： { "object_device_id": "{object_device_id}", "services": [{ "service_id": "$ota", "event_type": "upgrade_progress_report", "event_time": "20151212T121212Z", "paras": { "result_code": 0, "progress": 80, "version": "V2.0", "description": "upgrade processing" } }] }

响应示例 状态码： 201 创建设备隧道成功 { "tunnel_id" : "d144a524-1997-4b99-94bf-f27128da8a34", "tunnel_access_token" : "MIIDkgYJKoZIhvcNAQcCoIIDgzCCXXXXX", "expires_in" : 86400, "tunnel_uri" : "wss://tunnel.st1.iotda-app.cn-XXX.myhuaweicloud.com/v5/iot/tunnels/XXX/source-connect" }

请求参数 表2 请求Header参数 参数 是否必选 参数类型 描述 X-Auth-Token 否 String 参数说明：用户Token。通过调用IAM服务 获取IAM用户Token接口获取，接口返回的响应消息头中“X-Subject-Token”就是需要获取的用户Token。简要的获取方法样例请参见 Token认证。 Instance-Id 否 String 参数说明：实例ID。物理多租下各实例的唯一标识，建议携带该参数，在使用专业版时必须携带该参数。您可以在IoTDA管理控制台界面，选择左侧导航栏“总览”页签查看当前实例的ID，具体获取方式请参考查看实例详情 。 表3 请求Body参数 参数 是否必选 参数类型 描述 device_id 是 String 参数说明：设备ID

响应参数 状态码： 200 表4 响应Body参数 参数 参数类型 描述 group_id String 设备组ID，用于唯一标识一个设备组，在创建设备组时由 物联网平台 分配。 name String 设备组名称，单个资源空间下不可重复。 description String 设备组描述。 super_group_id String 父设备组ID，该设备组的父设备组ID。 group_type String 设备组类型，分为动态设备组和静态设备组两种 dynamic_group_rule String 动态设备组规则

响应示例 状态码： 200 OK { "group_id" : "04ed32dc1b0025b52fe3c01a27c2babc", "name" : "GroupA", "description" : "群组A", "super_group_id" : "04ed32dc1b0025b52fe3c01a27c2b0a8", "group_type" : "STATIC", "dynamic_group_rule" : null }

URI PUT /v5/iot/{project_id}/device-group/{group_id} 表1 路径参数 参数 是否必选 参数类型 描述 project_id 是 String 参数说明：项目ID。获取方法请参见 获取项目ID 。 group_id 是 String 参数说明：设备组ID，用于唯一标识一个设备组，在创建设备组时由物联网平台分配。 取值范围：长度不超过36，十六进制字符串和连接符（-）的组合。

请求参数 表2 请求Header参数 参数 是否必选 参数类型 描述 X-Auth-Token 否 String 参数说明：用户Token。通过调用IAM服务 获取IAM用户Token接口获取，接口返回的响应消息头中“X-Subject-Token”就是需要获取的用户Token。简要的获取方法样例请参见 Token认证。 Instance-Id 否 String 参数说明：实例ID。物理多租下各实例的唯一标识，建议携带该参数，在使用专业版时必须携带该参数。您可以在IoTDA管理控制台界面，选择左侧导航栏“总览”页签查看当前实例的ID，具体获取方式请参考查看实例详情 。 表3 请求Body参数 参数 是否必选 参数类型 描述 name 否 String 参数说明：设备组名称，单个资源空间下不可重复。 取值范围：长度不超过64，只允许中文、字母、数字、以及_? '#().,&%@!-等字符的组合。 最小长度：1 最大长度：64 description 否 String 参数说明：设备组描述。 取值范围：长度不超过64，只允许中文、字母、数字、以及_? '#().,&%@!-等字符的组合。 最小长度：1 最大长度：64

响应消息体 响应消息体通常以结构化格式返回，与响应消息头中Content-type对应，传递除响应消息头之外的内容。 对于创建产品接口，返回如下消息体。为篇幅起见，这里只展示部分内容。 { "product_id" : "5ba24f5ebbe8f56f5a14f605", "name" : "Thermometer", "device_type" : "Thermometer", "protocol_type" : "LWM2M", "data_format" : "binary", "manufacturer_name" : "ABC", "industry" : "smartCity", "description" : "this is a thermometer produced by Huawei", ...... } 当接口调用出错时，会返回错误码及错误信息说明，错误响应的Body体格式如下所示。 { "error_msg": "The format of message is error", "error_code": "IOTDA.013005" } 其中，error_code表示错误码，error_msg表示错误描述信息。

URI PUT /v5/iot/{project_id}/routing-rule/actions/{action_id} 表1 路径参数 参数 是否必选 参数类型 描述 project_id 是 String 参数说明：项目ID。获取方法请参见 获取项目ID 。 action_id 是 String 参数说明：规则动作ID。 取值范围：长度不超过36，只允许字母、数字、下划线（_）、连接符（-）的组合。

请求示例 修改指定规则动作， 推送到http服务器。 PUT https://{endpoint}/v5/iot/{project_id}/routing-rule/actions/{action_id} { "channel" : "HTTP_FORWARDING", "channel_detail" : { "http_forwarding" : { "url" : "http://host:port/callbackurltest" } } }

响应示例 状态码： 200 OK { "action_id" : "1a7ffc5c-d89c-44dd-8265-b1653d951ce0", "rule_id" : "1a7ffc5c-d89c-44dd-8265-b1653d951ce1", "app_id" : "1a7ffc5cd89c44dd8265b1653d951ce0", "channel" : "HTTP_FORWARDING", "channel_detail" : { "http_forwarding" : { "url" : "http://host:port/callbackurltest" } } }

示例 Topic: $oc/devices/{device_id}/sys/events/down 数据格式： { "object_device_id": "{object_device_id}", "services": [ { "service_id": "$ota", "event_type": "version_query", "event_time": "20151212T121212Z", "paras": { "task_id": "65d31bf2581ed33a42a58d76", "sub_device_count": 2, "task_ext_info": { "device_type": "DDC" } } } ] }

+HMREC 该指令用于将模组接收到的数据通过该方式传递给外部MCU。 指令 参数 参数缺省处理 AT响应结果 使用示例 +HMREC=topic, payload_len, payload topic：指定的topic - - +HMREC="$oc/devices/my_deviceid/user/my_subtopic",2,0102 (hexmode) len：接收到的数据长度，单位为字节 - - payload：转换为ascii码的数据 - - 父主题： 模组AT指令参考

请求示例 按标签查询资源，备查询绑定了指定标签的设备。 POST https://{endpoint}/v5/iot/{project_id}/tags/query-resources { "resource_type" : "device", "tags" : [ { "tag_key" : "testTagName", "tag_value" : "testTagValue" } ] }

请求参数 表3 请求Header参数 参数 是否必选 参数类型 描述 X-Auth-Token 否 String 参数说明：用户Token。通过调用IAM服务 获取IAM用户Token接口获取，接口返回的响应消息头中“X-Subject-Token”就是需要获取的用户Token。简要的获取方法样例请参见 Token认证。 Instance-Id 否 String 参数说明：实例ID。物理多租下各实例的唯一标识，建议携带该参数，在使用专业版时必须携带该参数。您可以在IoTDA管理控制台界面，选择左侧导航栏“总览”页签查看当前实例的ID，具体获取方式请参考查看实例详情 。 表4 请求Body参数 参数 是否必选 参数类型 描述 resource_type 是 String 参数说明：要查询的资源类型，当前支持设备（device）。 tags 是 Array of TagV5DTO objects 参数说明：标签列表，支持按照标签key和value组合查询，传入的多个标签之间是或的关系。 表5 TagV5DTO 参数 是否必选 参数类型 描述 tag_key 是 String 参数说明：标签键，在同一资源下标签键唯一。绑定资源时，如果设置的键已存在，则将覆盖之前的标签值。如果设置的键值不存在，则新增标签。 取值范围：长度不超过64，只允许中文、字母、数字、以及_.-等字符的组合。 tag_value 否 String 参数说明：标签值。 取值范围：长度不超过128，只允许中文、字母、数字、以及_.-等字符的组合。

URI POST /v5/iot/{project_id}/tags/query-resources 表1 路径参数 参数 是否必选 参数类型 描述 project_id 是 String 参数说明：项目ID。获取方法请参见 获取项目ID 。 表2 Query参数 参数 是否必选 参数类型 描述 limit 否 Integer 参数说明：分页查询时每页显示的记录数。 取值范围：1-50的整数，默认值为10。 最小值：1 最大值：50 缺省值：10 marker 否 String 参数说明：上一次分页查询结果中最后一条记录的ID，在上一次分页查询时由物联网平台返回获得。分页查询时物联网平台是按marker也就是记录ID降序查询的，越新的数据记录ID也会越大。若填写marker，则本次只查询记录ID小于marker的数据记录。若不填写，则从记录ID最大也就是最新的一条数据开始查询。如果需要依次查询所有数据，则每次查询时必须填写上一次查询响应中的marker值。 取值范围：长度为24的十六进制字符串，默认值为ffffffffffffffffffffffff。 缺省值：ffffffffffffffffffffffff offset 否 Integer 参数说明：表示从marker后偏移offset条记录开始查询。当offset为0时，表示从marker后第一条记录开始输出。限制offset最大值是出于API性能考虑，您可以搭配marker使用该参数实现翻页，例如每页50条记录，1-11页内都可以直接使用offset跳转到指定页，但到11页后，由于offset限制为500，您需要使用第11页返回的marker作为下次查询的marker，以实现翻页到12-22页。 取值范围：0-500的整数，默认为0。 最小值：0 最大值：500 缺省值：0

响应参数 状态码： 200 表6 响应Body参数 参数 参数类型 描述 resources Array of ResourceDTO objects 资源列表。 page Page object 查询结果的分页信息。 表7 ResourceDTO 参数 参数类型 描述 resource_id String 资源id。例如，要查询的资源类型为device，那么对应的资源id就是device_id。 表8 Page 参数 参数类型 描述 count Long 满足查询条件的记录总数。 marker String 本次分页查询结果中最后一条记录的ID，可在下一次分页查询时使用。

主要控制报文类型 常见MQTT消息类型主要有CONNECT、SUBSCRIBE、PUBLISH、PINGREQ。 CONNECT：指客户端请求和服务端连接。有效载荷（Payload）的主要参数，参考设备连接鉴权填写。 SUBSCRIBE：订阅包括主题筛选器（Topic Filter）和最大服务质量（QoS），一个会话可以进行多个订阅。向平台订阅可以参考：Topic定义。 PUBLISH：是指从客户端向服务端或者服务端向客户端传输一个应用消息。 可变报头（Variable header）中的主要参数“Topic name”，指服务端或客户端的发布主题。详细请参考Topic定义。 有效载荷（Payload）中的主要参数为完整的数据上报和命令下发的消息内容，一般是一个JSON或字符串对象。 PINGREQ：指客户端发给服务端的心跳请求。主要用于告知服务端客户端还活着、确认网络连接没有断开。约定的发送周期由协商的Keep Alive决定。

使用限制 上行Topic是指设备向平台发送请求，或上报数据，或回复响应。 下行Topic是指平台向设备下发指令，或回复响应。 设备与平台建立连接后，需要订阅下行Topic(华为云平台中具有隐式订阅功能，若通信质量为Qos0，平台的系统topic无需订阅。)，否则无法收到平台下发的指令或回复的响应。应用侧接口的调用，需要设备侧的配合，例如应用侧下发命令，设备侧需要先订阅“平台命令下发”的下行Topic，否则设备无法收到平台命令，应用下发命令的接口也会报超时。

数据包组成 MQTT消息由固定报头（Fixed header）、可变报头（Variable header）和有效载荷（Payload）三部分组成。在MQTT规范中有说明，建议使用设备侧SDK进行接入。 其中固定报头（Fixed header）和可变报头（Variable header）格式的填写请参考MQTT标准规范。有效载荷（Payload）的格式由应用定义，即设备和物联网平台之间的定义。 固定报头：每个 MQTT 控制报文都包含一个固定报头可变报头，用于决定控制报文类型、在PUBLISH中还用于决定最大服务质量（QoS），如：建链、订阅、发布。 可变报头：某些 MQTT 控制报文包含一个可变报头部分。它在固定报头和负载之间。可变报头的内容根据报文类型的不同而不同。包含可变报头的报文标识符（Packet Identifier），用于区分同一链路的不同数据包。 有效载荷：某些 MQTT 控制报文在报文的最后部分包含一个有效载荷，对于 PUBLISH 来说有效载荷就是应用消息（由用户自己定义）。 MQTT的语法和接口细节，请以MQTT标准规范为准。

请求参数 表1 请求Body参数 参数 是否必选 参数类型 描述 resource 是 String 参数说明：订阅的资源名称，取值为device.property。 event 是 String 参数说明：订阅的资源事件，取值为report。 event_time 是 String 参数说明：资源事件生成时间,格式：yyyyMMdd'T'HHmmss'Z' UTC字符串，如：20151212T121212Z。若需要显示本地时区，您需要自己进行时间转换。 event_time_ms 否 String 参数说明：资源事件生成时间,格式：yyyy-MM-dd'T'HH:mm:ss.SSS'Z' UTC字符串，如：2015-12-12T12:12:12.000Z。若需要显示本地时区，您需要自己进行时间转换。 request_id 否 String 参数说明：消息ID，由设备侧指定或平台生成，用于跟踪业务流程。 notify_data 是 DevicePropertyReportNotifyData object 参数说明：推送消息。 表2 DevicePropertyReportNotifyData 参数 是否必选 参数类型 描述 header 是 NotifyDataHeader object 参数说明：推送消息header。 body 是 DevicePropertyReport object 参数说明：推送消息body。 表3 NotifyDataHeader 参数 是否必选 参数类型 描述 app_id 否 String 参数说明：应用ID。 最大长度：256 device_id 否 String 参数说明：设备ID，用于唯一标识一个设备，在注册设备时由物联网平台分配获得。 最大长度：256 node_id 否 String 参数说明：设备标识码，通常使用IMEI、MAC地址或Serial No作为nodeId。 最大长度：256 product_id 否 String 参数说明：产品ID，用于唯一标识一个产品，在注册产品时由物联网平台分配获得。 最大长度：256 gateway_id 否 String 参数说明：网关ID，用于标识一个网关设备。当设备是直连设备时，gatewayId与设备的deviceId一致。当设备是非直连设备时，gatewayId为设备所关联的直连设备（即网关）的deviceId。 最大长度：256 tags 否 Array of TagV5DTO objects 参数说明：要绑定到指定资源的标签列表，标签列表中各项标签键值之间不允许重复，一个资源最多可以绑定10个标签。 表4 TagV5DTO 参数 是否必选 参数类型 描述 tag_key 是 String 参数说明：标签键，在同一资源下标签键唯一。绑定资源时，如果设置的键已存在，则将覆盖之前的标签值。如果设置的键值不存在，则新增标签。 tag_value 否 String 参数说明：标签值。 表5 DevicePropertyReport 参数 是否必选 参数类型 描述 services 是 Array of DevicePropertyV5 objects 参数说明：设备的服务信息列表。 表6 DevicePropertyV5 参数 是否必选 参数类型 描述 service_id 是 String 参数说明：设备的服务ID，在设备关联的产品模型中定义。 properties 是 Object 参数说明：设备上报的数据。 event_time 是 String 参数说明：设备数据上报的时间，格式取决于设备侧上报属性格式，支持的秒级格式：yyyyMMdd'T'HHmmss'Z'，毫秒级格式：yyyy-MM-dd'T'HH:mm:ss.SSS'Z'，例如20151212T121212Z或者2020-08-12T12:12:12.333Z。

请求示例 设备属性上报通知示例： 设备属性上报通知 { "resource" : "device.property", "event" : "report", "event_time" : "20151212T121212Z", "event_time_ms" : "2015-12-12T12:12:12.000Z", "request_id" : "3fe58d5e-8697-4849-a165-7db128f7e776", "notify_data" : { "header" : { "device_id" : "d4922d8a-6c8e-4396-852c-164aefa6638f", "product_id" : "ABC123456789", "app_id" : "d4922d8a-6c8e-4396-852c-164aefa6638f", "gateway_id" : "d4922d8a-6c8e-4396-852c-164aefa6638f", "node_id" : "ABC123456789", "tags" : [ { "tag_value" : "testTagValue", "tag_key" : "testTagName" } ] } }, "body" : { "services" : [ { "service_id" : "Battery", "properties" : { "batteryLevel" : 80 }, "event_time" : "20151212T121212Z" } ] } }

URI GET /v5/iot/{project_id}/device-group/{group_id} 表1 路径参数 参数 是否必选 参数类型 描述 project_id 是 String 参数说明：项目ID。获取方法请参见 获取项目ID 。 group_id 是 String 参数说明：设备组ID，用于唯一标识一个设备组，在创建设备组时由物联网平台分配。 取值范围：长度不超过36，十六进制字符串和连接符（-）的组合。

响应参数 状态码： 200 表3 响应Body参数 参数 参数类型 描述 group_id String 设备组ID，用于唯一标识一个设备组，在创建设备组时由物联网平台分配。 name String 设备组名称，单个资源空间下不可重复。 description String 设备组描述。 super_group_id String 父设备组ID，该设备组的父设备组ID。 group_type String 设备组类型，分为动态设备组和静态设备组两种 dynamic_group_rule String 动态设备组规则

响应示例 状态码： 200 OK { "group_id" : "04ed32dc1b0025b52fe3c01a27c2babc", "name" : "GroupA", "description" : "群组A", "super_group_id" : "04ed32dc1b0025b52fe3c01a27c2b0a8", "group_type" : "STATIC" }

请求参数 表2 请求Header参数 参数 是否必选 参数类型 描述 X-Auth-Token 否 String 参数说明：用户Token。通过调用IAM服务 获取IAM用户Token接口获取，接口返回的响应消息头中“X-Subject-Token”就是需要获取的用户Token。简要的获取方法样例请参见 Token认证。 Instance-Id 否 String 参数说明：实例ID。物理多租下各实例的唯一标识，建议携带该参数，在使用专业版时必须携带该参数。您可以在IoTDA管理控制台界面，选择左侧导航栏“总览”页签查看当前实例的ID，具体获取方式请参考查看实例详情 。

+HMSTS 该指令用于将模组连接或者断开的状态主动传递给外部MCU。 指令 参数 参数缺省处理 AT响应结果 使用示例 +HMSTS：status status：当前的状态。0表示已连接，1表示已断开。 如果在通信过程中因为网络原因断开，模组会尝试重连并订阅已经订阅的主题。 - - +HMSTS:0 表示和IoT平台已经连接上 +HMSTS:1 表示网络原因和IoT平台断开 父主题： 模组AT指令参考