设备孪生入门 (Java)
设备孪生是存储设备状态信息(包括元数据、配置和条件)的 JSON 文档。 IoT 中心为连接到它的每台设备保留一个设备孪生。
注意
本文所述的功能只能用于 IoT 中心的标准层。 有关 IoT 中心基本层和标准/免费层的详细信息,请参阅选择适合你的解决方案的 IoT 中心层。
使用设备克隆可以:
存储来自解决方案后端的设备元数据。
通过设备应用报告当前状态信息,例如可用功能和条件(例如,使用的连接方法)。
同步设备应用和后端应用之间长时间运行的工作流(例如固件和配置更新)的状态。
查询设备的元数据、配置或状态。
设备孪生旨在执行同步以及查询设备的配置和条件。 有关设备孪生的详细信息(包括何时使用设备孪生),请参阅了解设备孪生。
IoT 中心存储包含以下元素的设备孪生:
标记。 只能由解决方案后端访问的设备元数据。
所需属性。 可以由解决方案后端修改以及由设备应用观察的 JSON 对象。
报告属性。 可以由设备应用修改以及由解决方案后端读取的 JSON 对象。
标记和属性不能包含数组,但可以包含嵌套对象。
下图显示了设备孪生组织:
此外,解决方案后端可以根据上述所有数据查询设备孪生。 有关设备孪生的详细信息,请参阅了解设备孪生。 有关查询的详细信息,请参阅 IoT 中心查询语言。
在本文中,将创建两个 Java 控制台应用:
- add-tags-query:一个后端应用,用于添加标记并查询设备孪生。
- simulated-device:一个模拟设备应用,用于连接到 IoT 中心并报告其连接状况。
备注
有关可用于生成设备和后端应用的 SDK 工具的详细信息,请参阅 Azure IoT SDK。
先决条件
已注册的设备。 在 Azure 门户中注册一个。
Java SE 开发工具包 8。 请确保在“长期支持”下选择“Java 8”以获取 JDK 8 的下载。
确保已在防火墙中打开端口 8883。 本文中的设备示例使用 MQTT 协议,该协议通过端口 8883 进行通信。 在某些公司和教育网络环境中,此端口可能被阻止。 有关解决此问题的更多信息和方法,请参阅连接到 IoT 中心(MQTT)。
获取 IoT 中心连接字符串
在本文中,你将创建一项后端服务,该服务将所需的属性添加到设备孪生,然后查询标识注册表,从而查找具有已相应更新的报告属性的所有设备。 服务需要“服务连接”权限才能修改设备孪生的所需属性,并且需要“注册表读取”权限才能查询标识注册表。 没有仅包含这两个权限的默认共享访问策略,因此需要创建一个。
若要创建授予“服务连接”和“注册表读取”权限的共享访问策略并获取此策略的连接字符串,请执行以下步骤:
在 Azure 门户中,选择“资源组”。 选择中心所在的资源组,然后从资源列表中选择中心。
在中心的左侧窗格上,选择“共享访问策略”。
在策略列表上方的顶部菜单中,选择“添加共享策略访问策略”。
在右侧的“添加共享访问策略”窗格中,为策略输入一个描述性名称,例如 serviceAndRegistryRead。 在“权限”下,选择“注册表读取”和“服务连接”,然后选择“添加”。
从策略列表中选择新策略。
选择“主连接字符串”的复制图标并保存值。
有关 IoT 中心共享访问策略和权限的详细信息,请参阅访问控制和权限。
创建更新报告的属性的设备应用
在本部分中,将创建一个 Java 控制台应用作为 myDeviceId 连接到中心,然后更新其设备孪生的报告属性,以确认它使用手机网络进行连接。
在 iot-java-twin-getstarted 文件夹中,通过命令提示符使用以下命令创建名为 simulated-device 的 Maven 项目:
mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=simulated-device -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
在命令提示符下,导航到 simulated-device 文件夹。
使用文本编辑器,打开 simulated-device 文件夹中的 pom.xml 文件,并在 dependencies 节点中添加以下依赖项 。 通过此依赖项可以使用应用中的 iot-device-client 包来与 IoT 中心进行通信。
<dependency> <groupId>com.microsoft.azure.sdk.iot</groupId> <artifactId>iot-device-client</artifactId> <version>1.17.5</version> </dependency>
注意
可以使用 Maven 搜索检查是否有最新版本的 iot-device-client。
将以下依赖项添加到 dependencies 节点。 此依赖项为 Apache SLF4J 日志记录外观配置 NOP,设备客户端 SDK 使用它实现日志记录。 此配置是可选的,但是如果省略此配置,则在运行该应用时,可能会在控制台中看到警告。 有关设备客户端 SDK 中的日志记录的详细信息,请参阅适用于 Java 的 Azure IoT 设备 SDK 示例自述文件中的日志记录。
<dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-nop</artifactId> <version>1.7.28</version> </dependency>
在 dependencies 节点后添加以下 build 节点。 此配置指示 Maven 使用 Java 1.8 来生成应用:
<build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <version>3.3</version> <configuration> <source>1.8</source> <target>1.8</target> </configuration> </plugin> </plugins> </build>
保存并关闭 pom.xml 文件。
使用文本编辑器打开 simulated-device\src\main\java\com\mycompany\app\App.java 文件。
在该文件中添加以下 import 语句:
import com.microsoft.azure.sdk.iot.device.*; import com.microsoft.azure.sdk.iot.device.DeviceTwin.*; import java.io.IOException; import java.net.URISyntaxException; import java.util.Scanner;
将以下类级变量添加到 App 类。 将
{yourdeviceconnectionstring}
替换为在 IoT 中心注册设备时看到的设备连接字符串:private static String connString = "{yourdeviceconnectionstring}"; private static IotHubClientProtocol protocol = IotHubClientProtocol.MQTT; private static String deviceId = "myDeviceId";
本示例应用在实例化 DeviceClient 对象时使用 protocol 变量。
将以下方法添加到 App 类以输出有关孪生更新的信息:
protected static class DeviceTwinStatusCallBack implements IotHubEventCallback { @Override public void execute(IotHubStatusCode status, Object context) { System.out.println("IoT Hub responded to device twin operation with status " + status.name()); } }
将 main 方法中的代码替换为以下代码,以便可:
创建用来与 IoT 中心通信的设备客户端。
创建一个 Device 对象用于存储设备孪生属性。
DeviceClient client = new DeviceClient(connString, protocol); // Create a Device object to store the device twin properties Device dataCollector = new Device() { // Print details when a property value changes @Override public void PropertyCall(String propertyKey, Object propertyValue, Object context) { System.out.println(propertyKey + " changed to " + propertyValue); } };
将以下代码添加到 main 方法,创建 connectivityType 报告属性并将其发送到 IoT 中心:
try { // Open the DeviceClient and start the device twin services. client.open(); client.startDeviceTwin(new DeviceTwinStatusCallBack(), null, dataCollector, null); // Create a reported property and send it to your IoT hub. dataCollector.setReportedProp(new Property("connectivityType", "cellular")); client.sendReportedProperties(dataCollector.getReportedProp()); } catch (Exception e) { System.out.println("On exception, shutting down \n" + " Cause: " + e.getCause() + " \n" + e.getMessage()); dataCollector.clean(); client.closeNow(); System.out.println("Shutting down..."); }
将以下代码添加到 main 方法的末尾。 按 Enter 键,等待一段时间让 IoT 中心报告设备孪生操作的状态。
System.out.println("Press any key to exit..."); Scanner scanner = new Scanner(System.in); scanner.nextLine(); dataCollector.clean(); client.close();
修改 main 方法的签名,包含如下所示的异常:
public static void main(String[] args) throws URISyntaxException, IOException
保存并关闭 simulated-device\src\main\java\com\mycompany\app\App.java 文件。
生成 simulated-device 应用并更正任何错误。 在命令提示符下,导航到 simulated-device 文件夹并运行以下命令:
mvn clean package -DskipTests
创建更新所需属性和查询孪生的服务应用
本部分将创建一个 Java 应用,用于将位置元数据作为标记添加到 IoT 中心内与 myDeviceId 关联的设备孪生。 该应用在 IoT 中心查询位于美国的设备,然后查询报告已建立移动电话网络连接的设备。
在开发计算机上,创建名为 iot-java-twin-getstarted 的空文件夹。
在 iot-java-twin-getstarted 文件夹中,通过命令提示符使用以下命令创建名为 add-tags-query 的 Maven 项目:
mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=add-tags-query -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
在命令提示符下,导航到 add-tags-query 文件夹。
使用文本编辑器打开 add-tags-query 文件夹中的 pom.xml 文件,并在 dependencies 节点中添加以下依赖项 。 通过此依赖项可以使用应用中的 iot-service-client 包来与 IoT 中心通信:
<dependency> <groupId>com.microsoft.azure.sdk.iot</groupId> <artifactId>iot-service-client</artifactId> <version>1.17.1</version> <type>jar</type> </dependency>
注意
可以使用 Maven 搜索检查是否有最新版本的 iot-service-client。
在 dependencies 节点后添加以下 build 节点。 此配置指示 Maven 使用 Java 1.8 来生成应用。
<build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <version>3.3</version> <configuration> <source>1.8</source> <target>1.8</target> </configuration> </plugin> </plugins> </build>
保存并关闭 pom.xml 文件。
使用文本编辑器打开 add-tags-query\src\main\java\com\mycompany\app\App.java 文件。
在该文件中添加以下 import 语句:
import com.microsoft.azure.sdk.iot.service.devicetwin.*; import com.microsoft.azure.sdk.iot.service.exceptions.IotHubException; import java.io.IOException; import java.util.HashSet; import java.util.Set;
将以下类级变量添加到 App 类。 将
{youriothubconnectionstring}
替换为在获取 IoT 中心连接字符串中复制的 IoT 中心连接字符串。public static final String iotHubConnectionString = "{youriothubconnectionstring}"; public static final String deviceId = "myDeviceId"; public static final String region = "US"; public static final String plant = "Redmond43";
更新 main 方法签名,以包含以下
throws
子句:public static void main( String[] args ) throws IOException
将 main 方法中的代码替换为以下代码,以创建 DeviceTwin 和 DeviceTwinDevice 对象。 DeviceTwin 对象处理与 IoT 中心之间的通信。 DeviceTwinDevice 对象使用设备孪生的属性和标记来表示设备孪生:
// Get the DeviceTwin and DeviceTwinDevice objects DeviceTwin twinClient = DeviceTwin.createFromConnectionString(iotHubConnectionString); DeviceTwinDevice device = new DeviceTwinDevice(deviceId);
将以下
try/catch
块添加到 main 方法:try { // Code goes here } catch (IotHubException e) { System.out.println(e.getMessage()); } catch (IOException e) { System.out.println(e.getMessage()); }
若要更新设备孪生中的 region 和 plant 设备孪生标记,请在
try
块中添加以下代码:// Get the device twin from IoT Hub System.out.println("Device twin before update:"); twinClient.getTwin(device); System.out.println(device); // Update device twin tags if they are different // from the existing values String currentTags = device.tagsToString(); if ((!currentTags.contains("region=" + region) && !currentTags.contains("plant=" + plant))) { // Create the tags and attach them to the DeviceTwinDevice object Set<Pair> tags = new HashSet<Pair>(); tags.add(new Pair("region", region)); tags.add(new Pair("plant", plant)); device.setTags(tags); // Update the device twin in IoT Hub System.out.println("Updating device twin"); twinClient.updateTwin(device); } // Retrieve the device twin with the tag values from IoT Hub System.out.println("Device twin after update:"); twinClient.getTwin(device); System.out.println(device);
若要在 IoT 中心查询设备孪生,请将以下代码添加到
try
块(添加到上一步骤中添加的代码后面)。 该代码运行两个查询。 每个查询最多返回 100 个设备。// Query the device twins in IoT Hub System.out.println("Devices in Redmond:"); // Construct the query SqlQuery sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43'", null); // Run the query, returning a maximum of 100 devices Query twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 100); while (twinClient.hasNextDeviceTwin(twinQuery)) { DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery); System.out.println(d.getDeviceId()); } System.out.println("Devices in Redmond using a cellular network:"); // Construct the query sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43' AND properties.reported.connectivityType = 'cellular'", null); // Run the query, returning a maximum of 100 devices twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 3); while (twinClient.hasNextDeviceTwin(twinQuery)) { DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery); System.out.println(d.getDeviceId()); }
保存并关闭 add-tags-query\src\main\java\com\mycompany\app\App.java 文件
生成 add-tags-query 应用并更正任何错误。 在命令提示符下,导航到 add-tags-query 文件夹并运行以下命令:
mvn clean package -DskipTests
运行应用
现在可以运行控制台应用了。
在 add-tags-query 文件夹中的命令提示符下,运行以下命令以运行 add-tags-query 服务应用:
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
可以看到,plant 和 region 标记已添加到设备孪生。 第一个查询返回设备,但第二个查询则不会。
在 simulated-device 文件夹中的命令提示符下,运行以下命令将 connectivityType 报告属性添加到设备孪生:
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
在 add-tags-query 文件夹中的命令提示符下,再次运行以下命令以运行 add-tags-query 服务应用:
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
现在,设备已将 connectivityType 属性发送到 IoT 中心,第二个查询返回了设备。
本文内容:
- 从后端应用添加了设备元数据作为标记
- 在设备孪生中报告了设备连接信息
- 使用类似 SQL 的 IoT 中心查询语言查询了设备孪生信息
后续步骤
若要了解操作方法:
若要了解如何从设备发送遥测数据,请参阅快速入门:将遥测数据从 IoT 即插即用设备发送到 Azure IoT 中心
若要了解如何使用设备孪生的所需属性配置设备,请参阅教程:从后端服务配置设备
若要了解如何以交互方式控制设备(例如从用户控制的应用打开风扇),请参阅快速入门:控制连接到 IoT 中心的设备