Начало работы с двойниками устройств (Java)

Статья
03/18/2023

Двойники устройств — это документы JSON, хранящие сведения о состоянии устройства, в том числе метаданные, конфигурации и условия. Центр Интернета вещей сохраняет двойник устройства для каждого устройства, подключаемого к нему.

Примечание.

Функции, описанные в этой статье, доступны только на стандартном уровне Центра Интернета вещей. Дополнительные сведения о базовых и бесплатных уровнях Центр Интернета вещей см. в разделе "Выбор подходящего уровня Центр Интернета вещей" для решения.

Двойники устройства используются для выполнения следующих действий:

хранение метаданных устройства из серверной части вашего решения;
сообщение сведений о текущем состоянии приложения устройства, таких как доступные возможности и условия, например используемый метод подключения;
синхронизация состояния длительных рабочих процессов между приложением устройства и серверной частью, например при обновлении встроенного ПО и конфигурации;
выполнение запроса метаданных, конфигурации или состояния устройства.

Двойники устройств используются для синхронизации и выполнения запроса конфигураций или условий устройства. Дополнительные сведения об двойниках устройств, включая использование двойников устройств, см. в разделе "Общие сведения о двойниках устройств".

Центры Интернета вещей хранят двойники устройств, которые содержат следующие элементы:

Теги. Метаданные устройства, доступные только в серверной части решения.
Требуемые свойства. Объекты JSON, задаваемые только в серверной части решения и наблюдаемые в приложении устройства.
Сообщаемые свойства. Объекты JSON, задаваемые только в приложении устройства и считываемые в серверной части решения.

Теги и свойства не могут содержать массивы, но могут содержать вложенные объекты.

Следующая иллюстрация показывает организацию двойника устройства:

Снимок экрана: схема концепции двойника устройства.

Кроме того, из серверной части решения можно запросить двойники устройств на основе всех вышеизложенных данных. Дополнительные сведения о двойниках устройств см. в статье Основные сведения о двойниках устройств. Дополнительные сведения запросах см. в статье Язык запросов Центра Интернета вещей.

Из этой статьи вы узнаете, как выполнять следующие задачи:

С помощью приложения имитированного устройства вы можете передавать данные о своем канале подключения как передаваемое свойство двойника устройства.
запрос устройств из серверного приложения с использованием фильтров в созданных ранее тегах и свойствах.

В этой статье создаются два консольных приложения для Java:

add-tags-query: внутреннее приложение, которое добавляет теги и выполняет запросы к двойникам устройств.
simulated-device: приложение для имитированного устройства, которое подключается к Центру Интернета вещей и предоставляет сведения о состоянии подключения.

Примечание.

Дополнительные сведения о средствах SDK, доступных для создания приложения устройства и внутреннего приложения, см. в статье Пакеты SDK для Интернета вещей Azure.

Необходимые компоненты

Центр Интернета вещей в подписке Azure. Если у вас еще нет центра, выполните действия, описанные в разделе Создание центра Интернета вещей.
Устройство, зарегистрированное в центре Интернета вещей. Если у вас нет устройства в Центре Интернета вещей, выполните действия, описанные в разделе "Регистрация устройства".
Пакет SDK для Java SE 8. Щелкните ссылку Java 8 в разделе Долгосрочная поддержка, чтобы скачать все необходимое для работы с JDK 8.
Maven 3
Убедитесь, что в брандмауэре открыт порт 8883. Пример устройства в этой статье использует протокол MQTT, который передает данные через порт 8883. В некоторых корпоративных и академических сетях этот порт может быть заблокирован. Дополнительные сведения и способы устранения этой проблемы см. в разделе о подключении к Центру Интернета вещей по протоколу MQTT.

Получение строки подключения центра Интернета вещей

В этой статье вы создадите серверную службу, которая добавляет требуемые свойства в двойник устройства, а затем запрашивает реестр удостоверений, чтобы найти все устройства с передаваемыми свойствами, которые были обновлены соответствующим образом. Службе требуется разрешение service connect для изменения требуемых свойств двойника устройства и разрешение registry read для запроса реестра удостоверений. Политика общего доступа по умолчанию, которая содержит только эти два разрешения, не существует, поэтому необходимо создать ее.

Чтобы создать политику общего доступа, которая предоставляет разрешения service connect и registry read, и получить строку подключения для этой политики, выполните следующие действия.

На портале Azure выберите Группы ресурсов. Выберите группу ресурсов, в которой находится центр, а затем выберите центр из списка ресурсов.
В левой части центра выберите Политики общего доступа.
В верхнем меню над списком политик выберите Добавить политику общего доступа.
В области Добавить политику общего доступа справа введите описательное имя политики, например serviceAndRegistryRead. В разделе Разрешения выберите Чтение реестра и Подключение службы, а затем нажмите кнопку Добавить.
Выберите новую политику из списка политик.
Выберите значок копирования рядом с пунктом Первичная строка подключения и сохраните значение.

Дополнительные сведения о политиках и разрешениях общего доступа Центра Интернета вещей см. в разделе Управления доступом и разрешения.

Создание приложения устройства, которое обновляет сообщаемые свойства

При работе с этим разделом вы создадите консольное приложение Java, которое подключается к центру как myDeviceId и обновляет передаваемые свойства двойника устройства для подтверждения сетевого подключения.

В папке iot-java-twin-getstarted создайте проект Maven с именем simulated-device, выполнив следующую команду в командной строке:
```
mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=simulated-device -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
```
В командной строке перейдите к папке simulated-device.
Откройте в текстовом редакторе файл pom.xml из папки simulated-device и добавьте приведенные ниже зависимости в узел dependencies. Эта зависимость позволит вам использовать в приложении пакет iot-device-client для обмена данными с центром Интернета вещей.
```
<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-device-client</artifactId>
  <version>1.17.5</version>
</dependency>
```
Примечание.

Наличие последней версии пакета iot-device-client можно проверить с помощью поиска Maven.
Добавьте указанную ниже зависимость в узел dependencies. Эта зависимость настраивает NOP для интерфейса ведения журнала Apache SLF4J, который используется пакетом SDK клиента устройства для реализации ведения журнала. Эта конфигурация является необязательной, но если ее опустить, при запуске приложения может появиться предупреждение в консоли. Дополнительные сведения о ведении журнала в пакете SDK клиента устройства см. в разделе Ведение журнала в файле сведений Примеры для пакета SDK для устройств Azure IoT для Java.
```
<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-nop</artifactId>
  <version>1.7.28</version>
</dependency>
```

Добавьте следующий узел, build, после узла dependencies. Эта конфигурация дает указание 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} строкой подключения устройства, которую вы видели при регистрации устройства в Центре Интернета вещей:
```
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 следующим кодом:

Создать клиент устройства для взаимодействия с Центром Интернета вещей.
Создать объект 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 и отправить его в Центр Интернета вещей:

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 следующий код: Во время ожидания нажатия клавиши ВВОД Центр Интернета вещей сообщает состояние операций двойника устройства.
```
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, которое добавляет метаданные расположения в виде тега в двойник устройства в Центре Интернета вещей, связанный с myDeviceId. Приложение запрашивает центр Интернета вещей для устройств, расположенных в США, а затем запрашивает устройства, которые сообщают о подключении к сотовой сети.

На компьютере разработки создайте пустую папку с именем iot-java-twin-getstarted.
В папке iot-java-twin-getstarted создайте проект Maven с именем add-tags-query, выполнив следующую команду в командной строке:
```
mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=add-tags-query -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
```
В командной строке перейдите к новой папке add-tags-query.
Откройте в текстовом редакторе файл pom.xml из папки add-tags-query и добавьте зависимости, приведенные ниже, в узел dependencies. Эта зависимость позволит вам использовать в приложении пакет iot-service-client для обмена данными с Центром Интернета вещей:
```
<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-service-client</artifactId>
  <version>1.17.1</version>
  <type>jar</type>
</dependency>
```
Примечание.

Наличие последней версии пакета iot-service-client можно проверить с помощью поиска Maven.

Добавьте следующий узел, build, после узла dependencies. Эта конфигурация дает указание 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} строкой подключения центра Интернета вещей, скопированной в разделе Получение строки подключения центра Интернета вещей.
```
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 обрабатывает взаимодействие с вашим Центром Интернета вещей. Объект 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);

Чтобы отправить запрос к двойникам устройств в Центре Интернета вещей, добавьте следующий код в блок 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 в Центр Интернета вещей, второй запрос возвращает устройство.

Работая с этой статьей, вы выполните следующие задачи:

Добавлены метаданные устройства в виде тегов из внутреннего приложения
передача сведений о возможности подключения устройства в двойнике устройства;
Запрошена информация о двойнике устройства с помощью подобного SQL языка запросов Центра Интернета вещей

Следующие шаги

Ознакомьтесь со следующими материалами.

Сведения об отправке данных телеметрии с устройств см. в статье Краткое руководство. Отправка данных телеметрии с устройства IoT Plug and Play в Центр Интернета вещей Azure
Сведения о настройке устройств с использованием нужных свойств двойника устройства см. в статье Руководство. Настройка устройств из внутренней службы
Сведения об интерактивном управлении устройствами, например о включении вентилятора из контролируемого пользователем приложения, см. в статье Краткое руководство. Управление подключенным к Центру Интернета вещей устройством

Поделиться через