使用API Explorer测试设备属性查询功能

引言

华为云物联网平台设备接入云服务（IoTDA）提供海量设备的接入和管理能力，将物理设备联接到云，支撑设备数据采集上云和云端下发命令给设备进行远程控制。使用物联网平台构建一个完整的物联网解决方案主要包括3部分：物联网平台、业务应用和设备。前面的博文介绍了较多的是设备侧开发，今天开始研究一下应用侧开发。

华为IoTDA平台的API体系

物联网平台作为连接业务应用和设备的中间层，屏蔽了各种复杂的设备接口，实现设备的快速接入；同时提供强大的开放能力，支撑行业用户构建各种物联网解决方案。业务应用通过调用物联网平台提供的API，实现设备数据采集、命令下发、设备管理等业务场景。

有关应用侧API参见：应用侧API参考_设备接入 IoTDA_华为云。

API调用的基本步骤如下图所示。

API Explorer

为了简化应用侧程序的开发，华为提供了各种语言的SDK：SDK概述_设备接入 IoTDA_华为云。不过，今天不介绍SDK，只介绍如何用API Explorer进行API测试和学习。

华为云API Explorer为开发者提供一站式API 解决方案 统一平台，集成华为 云服务 所有开放API，支持全量快速检索、可视化调试、帮助文档、代码示例等能力，帮助开发者快速查找、学习API和使用API开发代码。API Explorer致力于帮助您更快地查找华为云Open API，您可以使用API Explorer来检索华为云开放的API并查看相应的文档，同时应用于API调试、 故障排查 等场景。

API Explorer的网站：API Explorerhttps://console.huaweicloud.com/apiexplorer/#/openapi/overview

测试设备属性查询功能

下面以测试设备属性查询功能为例介绍API Explorer。可以在API Explorer中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。

查询设备属性API接口

设备的产品模型中定义了物联网平台可向设备下发的属性，应用服务器可调用此接口向设备发送指令用以查询设备的实时属性, 并由设备将属性查询的结果同步返回给应用服务器。

URI

GET /v5/iot/{project_id}/devices/{device_id}/properties

表1 路径参数

参数	是否必选	参数类型	描述
device_id	是	String	参数说明：下发属性的设备ID，用于唯一标识一个设备，在注册设备时由物联网平台分配获得。 取值范围：长度不超过128，只允许字母、数字、下划线（_）、连接符（-）的组合。
project_id	是	String	参数说明：项目ID。获取方法请参见 获取项目ID。

表2 Query参数

参数	是否必选	参数类型	描述
service_id	是	String	参数说明：设备的服务ID，在设备关联的产品模型中定义。

请求参数

表3 请求Header参数

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

响应参数

状态码： 200

表4 响应Body参数

参数	参数类型	描述
request_id	String	设备属性查询ID，用于唯一标识一条属性查询，在下发查询属性时由物联网平台分配获得。
response	Object	设备上报的属性执行结果。Json格式，具体格式需要应用和设备约定。
error_code	String	属性查询异常错误码。
error_msg	String	属性查询异常错误信息。

设备侧行为

当平台向设备查询属性信息时，首先设备必须在线。

设备侧会自动收到特定Topic的查询请求（无需订阅），设备收到属性查询请求后，需要将设备的属性数据返回给平台，如果设备没回响应平台会认为属性查询请求执行超时。

Topic

下行: $oc/devices/{device_id}/sys/properties/get/request_id={request_id}

上行: $oc/devices/{device_id}/sys/properties/get/response/request_id={request_id}

说明：

• {request_id}用于唯一标识这次请求。设备侧收到下行请求的topic带该参数时，上行响应的topic需要将该参数值返回给平台。
• 应用查询设备属性时，平台会生成唯一ID用于标识该请求。同时该唯一标识会通过平台查询设备属性下行Topic中的requst_id携带给设备。
• 设备无法提前感知该request_id，在订阅该Topic时请使用通配符“#”来替代“request_id={request_id}”即为：$oc/devices/{device_id}/sys/properties/get/#。

下行请求参数说明

字段名	必选/可选	类型	参数描述
object_device_id	可选	String	参数解释： 平台下发时，若为直连设备，不携带该参数。 平台下发时，若为网关子设备，该参数为Topic中设备的子设备ID。
service_id	可选	String	参数解释： 设备的服务ID，由创建的产品模型确定。

上行响应参数说明

字段名	必选/可选	类型	参数描述
services	可选	List<ServiceProperty>	参数解释： 设备服务数据列表。

ServiceProperty结构定义：

字段名	必选/可选	类型	参数描述
service_id	必选	String	参数解释： 设备的服务ID，由创建的产品模型确定。
properties	必选	Object	参数解释： 设备服务的属性列表，具体字段在设备关联的产品模型里定义，可以设置多个字段。
event_time	可选	String	参数解释： 设备采集数据UTC时间（格式：yyyyMMdd'T'HHmmss'Z'），如：20161219T114920Z。 设备上报数据不带该参数或参数格式错误时，则数据上报时间以平台时间为准。

测试结果

如果对华为IoTDA平台如何建立物模型不熟悉的朋友，可以看我先前的博文：MQTTX连接华为云IoTDA-优快云博客。

我在API Explorer中对test1设备的“温湿度”属性进行查询。

 

 下图是MQTTX所模拟的设备收到请求，并进行回复的情况。

API Explorer收到回复后显示成功。 

结语

今天利用API Explorer测试了查询设备属性API接口，对华为IoT平台应用的开发有所了解。后面将继续探索相关应用开发。