Wprowadzenie do bliźniaczych reprezentacji urządzeń (Java)

Artykuł
01/29/2024

Bliźniacze reprezentacje urządzeń to dokumenty JSON, które przechowują informacje o stanie urządzenia, takie jak metadane, konfiguracje i warunki. Usługa IoT Hub utrzymuje bliźniacze reprezentację urządzenia dla każdego urządzenia, które łączy się z nim.

Uwaga

Funkcje opisane w tym artykule są dostępne tylko w warstwie Standardowa usługi IoT Hub. Aby uzyskać więcej informacji na temat warstw podstawowej i standardowej/bezpłatnej usługi IoT Hub, zobacz Wybieranie odpowiedniej warstwy usługi IoT Hub dla rozwiązania.

Użyj bliźniaczych reprezentacji urządzeń, aby:

Przechowywanie metadanych urządzenia z zaplecza rozwiązania.
Zgłoś bieżące informacje o stanie, takie jak dostępne możliwości i warunki, na przykład użyta metoda łączności z poziomu aplikacji urządzenia.
Synchronizuj stan długotrwałych przepływów pracy, takich jak aktualizacje oprogramowania układowego i konfiguracji, między aplikacją urządzenia a aplikacją zaplecza.
Wykonywanie zapytań dotyczących metadanych, konfiguracji lub stanu urządzenia.

Bliźniacze reprezentacje urządzeń są przeznaczone do synchronizacji i wykonywania zapytań dotyczących konfiguracji i warunków urządzeń. Aby uzyskać więcej informacji o bliźniaczych reprezentacjach urządzeń, w tym o tym, kiedy używać bliźniaczych reprezentacji urządzeń, zobacz Omówienie bliźniaczych reprezentacji urządzeń.

Centra IoT przechowują bliźniacze reprezentacje urządzeń, które zawierają następujące elementy:

Tagi. Metadane urządzenia dostępne tylko przez zaplecze rozwiązania.
Żądane właściwości. Obiekty JSON modyfikowalne przez zaplecze rozwiązania i można je zaobserwować przez aplikację urządzenia.
Zgłoszone właściwości. Obiekty JSON modyfikowalne przez aplikację urządzenia i czytelne dla zaplecza rozwiązania.

Tagi i właściwości nie mogą zawierać tablic, ale mogą zawierać zagnieżdżone obiekty.

Poniższa ilustracja przedstawia organizację bliźniaczej reprezentacji urządzenia:

Zrzut ekranu przedstawiający diagram koncepcji bliźniaczej reprezentacji urządzenia.

Ponadto zaplecze rozwiązania może wykonywać zapytania dotyczące bliźniaczych reprezentacji urządzeń na podstawie wszystkich powyższych danych. Aby uzyskać więcej informacji na temat bliźniaczych reprezentacji urządzeń, zobacz Omówienie bliźniaczych reprezentacji urządzeń. Aby uzyskać więcej informacji na temat wykonywania zapytań, zobacz Język zapytań usługi IoT Hub.

W tym artykule pokazano, w jaki sposób wykonać następujące czynności:

Użyj aplikacji urządzenia symulowanego, aby zgłosić swój kanał łączności jako zgłoszoną właściwość na bliźniaczej reprezentacji urządzenia.
Wykonywanie zapytań dotyczących urządzeń z aplikacji zaplecza przy użyciu filtrów w utworzonych wcześniej tagach i właściwościach.

W tym artykule utworzysz dwie aplikacje konsolowe Java:

add-tags-query: aplikacja zaplecza, która dodaje tagi i wysyła zapytania do bliźniaczych reprezentacji urządzeń.
simulated-device: symulowana aplikacja urządzenia, która łączy się z centrum IoT Hub i zgłasza jej stan łączności.

Uwaga

Zobacz Zestawy SDK usługi Azure IoT, aby uzyskać więcej informacji na temat narzędzi zestawu SDK dostępnych do kompilowania aplikacji urządzeń i zaplecza.

Wymagania wstępne

Centrum IoT. Utwórz go za pomocą interfejsu wiersza polecenia lub witryny Azure Portal.
Zarejestrowane urządzenie. Zarejestruj je w witrynie Azure Portal.
Java SE Development Kit 8. Upewnij się, że wybrano środowisko Java 8 w obszarze Obsługa długoterminowa , aby pobrać plik JDK 8.
Maven 3
Upewnij się, że port 8883 jest otwarty w zaporze. Przykład urządzenia w tym artykule używa protokołu MQTT, który komunikuje się za pośrednictwem portu 8883. Ten port może zostać zablokowany w niektórych środowiskach sieci firmowych i edukacyjnych. Aby uzyskać więcej informacji i sposobów obejścia tego problemu, zobacz Połączenie do usługi IoT Hub (MQTT).

Pobieranie parametry połączenia centrum IoT

W tym artykule utworzysz usługę zaplecza, która dodaje żądane właściwości do bliźniaczej reprezentacji urządzenia, a następnie wysyła zapytanie do rejestru tożsamości w celu znalezienia wszystkich urządzeń z zgłoszonymi właściwościami, które zostały odpowiednio zaktualizowane. Usługa wymaga uprawnienia połączenia usługi, aby zmodyfikować żądane właściwości bliźniaczej reprezentacji urządzenia i potrzebuje uprawnień do odczytu rejestru w celu wykonywania zapytań dotyczących rejestru tożsamości. Nie ma domyślnych zasad dostępu współdzielonego, które zawierają tylko te dwa uprawnienia, więc musisz je utworzyć.

Aby utworzyć zasady dostępu współdzielonego, które udzielają uprawnień do nawiązywania połączenia z usługą i odczytu rejestru i uzyskiwania parametry połączenia dla tych zasad, wykonaj następujące kroki:

W witrynie Azure Portal wybierz pozycję Grupy zasobów. Wybierz grupę zasobów, w której znajduje się centrum, a następnie wybierz centrum z listy zasobów.
W okienku po lewej stronie centrum wybierz pozycję Zasady dostępu współdzielonego.
W górnym menu powyżej listy zasad wybierz pozycję Dodaj zasady dostępu współdzielonego.
W okienku Dodawanie zasad dostępu współdzielonego po prawej stronie wprowadź opisową nazwę zasad , taką jak serviceAndRegistryRead. W obszarze Uprawnienia wybierz pozycję Odczyt rejestru i usługa Połączenie, a następnie wybierz pozycję Dodaj.
Wybierz nowe zasady z listy zasad.
Wybierz ikonę kopiowania dla parametry połączenia podstawowej i zapisz wartość.

Aby uzyskać więcej informacji na temat zasad dostępu współdzielonego i uprawnień usługi IoT Hub, zobacz Kontrola dostępu i uprawnienia.

Tworzenie aplikacji urządzenia, która aktualizuje zgłoszone właściwości

W tej sekcji utworzysz aplikację konsolową Java, która łączy się z centrum jako myDeviceId, a następnie aktualizuje zgłoszone właściwości bliźniaczej reprezentacji urządzenia, aby potwierdzić, że jest połączona przy użyciu sieci komórkowej.

W folderze iot-java-twin-getstarted utwórz projekt Maven o nazwie simulated-device przy użyciu następującego polecenia w wierszu polecenia:

mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=simulated-device -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

W wierszu polecenia przejdź do folderu simulated-device .
Za pomocą edytora tekstów otwórz plik pom.xml w folderze simulated-device i dodaj następujące zależności do węzła zależności . Ta zależność umożliwia używanie pakietu iot-device-client w aplikacji do komunikowania się z centrum IoT.
```
<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-device-client</artifactId>
  <version>1.17.5</version>
</dependency>
```
Uwaga

Możesz sprawdzić dostępność najnowszej wersji pakietu iot-device-client za pomocą funkcji wyszukiwania narzędzia Maven.
Dodaj następującą zależność do węzła zależności . Ta zależność konfiguruje NOP dla fasady rejestrowania Apache SLF4J , która jest używana przez zestaw SDK klienta urządzenia do implementowania rejestrowania. Ta konfiguracja jest opcjonalna, ale jeśli ją pominięto, po uruchomieniu aplikacji może zostać wyświetlone ostrzeżenie w konsoli programu . Aby uzyskać więcej informacji na temat rejestrowania w zestawie SDK klienta urządzenia, zobacz Rejestrowanie w przykładach dla zestawu SDK urządzenia Azure IoT dla pliku readme języka Java .
```
<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-nop</artifactId>
  <version>1.7.28</version>
</dependency>
```

Dodaj następujący węzeł kompilacji po węźle zależności . Ta konfiguracja nakazuje narzędziu Maven użycie środowiska Java 1.8 do skompilowania aplikacji:

<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>

Zapisz i zamknij plik pom.xml.
Za pomocą edytora tekstów otwórz plik simulated-device\src\main\java\com\mycompany\app\App.java .

Dodaj do pliku następujące instrukcje importowania:

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;

Dodaj następujące zmienne na poziomie klasy do klasy App. Zastąp {yourdeviceconnectionstring} element urządzeniem parametry połączenia, który został wyświetlony podczas rejestrowania urządzenia w usłudze IoT Hub:
```
private static String connString = "{yourdeviceconnectionstring}";
private static IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
private static String deviceId = "myDeviceId";
```
Ta przykładowa aplikacja używa zmiennej protocol podczas tworzenia wystąpienia obiektu DeviceClient.

Dodaj następującą metodę do klasy App , aby wydrukować informacje o aktualizacjach reprezentacji bliźniaczych:

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());
    }
  }

Zastąp kod w metodzie main następującym kodem:

Utwórz klienta urządzenia do komunikowania się z usługą IoT Hub.
Utwórz obiekt Device do przechowywania właściwości bliźniaczej reprezentacji urządzenia.

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);
  }
};

Dodaj następujący kod do metody main, aby utworzyć właściwość connectivityType zgłaszane i wysłać go do usługi IoT Hub:

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...");
}

Dodaj następujący kod na końcu metody main . Oczekiwanie na klucz Enter umożliwia raportowanie stanu operacji bliźniaczej reprezentacji urządzenia przez usługę IoT Hub.
```
System.out.println("Press any key to exit...");

Scanner scanner = new Scanner(System.in);
scanner.nextLine();

dataCollector.clean();
client.close();
```

Zmodyfikuj podpis metody main, aby uwzględnić poniższe wyjątki:

public static void main(String[] args) throws URISyntaxException, IOException

Zapisz i zamknij plik simulated-device\src\main\java\com\mycompany\app\App.java .
Skompiluj aplikację symulowanego urządzenia i popraw wszelkie błędy. W wierszu polecenia przejdź do folderu simulated-device i uruchom następujące polecenie:
```
mvn clean package -DskipTests
```

Tworzenie aplikacji usługi, która aktualizuje żądane właściwości i wysyła zapytania do bliźniaczych reprezentacji

W tej sekcji utworzysz aplikację Java, która dodaje metadane lokalizacji jako tag do bliźniaczej reprezentacji urządzenia w usłudze IoT Hub skojarzonej z elementem myDeviceId. Aplikacja wysyła zapytanie do centrum IoT dla urządzeń znajdujących się w Stanach Zjednoczonych, a następnie wysyła zapytania do urządzeń, które zgłaszają połączenie sieciowe.

Na komputerze deweloperskim utwórz pusty folder o nazwie iot-java-twin-getstarted.

W folderze iot-java-twin-getstarted utwórz projekt Maven o nazwie add-tags-query przy użyciu następującego polecenia w wierszu polecenia:

mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=add-tags-query -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

W wierszu polecenia przejdź do folderu add-tags-query .
Za pomocą edytora tekstów otwórz plik pom.xml w folderze add-tags-query i dodaj następującą zależność do węzła zależności . Ta zależność umożliwia używanie pakietu iot-service-client w aplikacji do komunikowania się z centrum IoT:
```
<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-service-client</artifactId>
  <version>1.17.1</version>
  <type>jar</type>
</dependency>
```
Uwaga

Możesz sprawdzić dostępność najnowszej wersji pakietu iot-service-client za pomocą funkcji wyszukiwania narzędzia Maven.

Dodaj następujący węzeł kompilacji po węźle zależności . Ta konfiguracja nakazuje narzędziu Maven użycie środowiska Java 1.8 do skompilowania aplikacji.

<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>

Zapisz i zamknij plik pom.xml.
Za pomocą edytora tekstów otwórz plik add-tags-query\src\main\java\com\mycompany\app\App.java .

Dodaj do pliku następujące instrukcje importowania:

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;

Dodaj następujące zmienne na poziomie klasy do klasy App. Zastąp element {youriothubconnectionstring} parametry połączenia centrum IoT, który został skopiowany w parametry połączenia Pobierz centrum IoT Hub.

public static final String iotHubConnectionString = "{youriothubconnectionstring}";
public static final String deviceId = "myDeviceId";

public static final String region = "US";
public static final String plant = "Redmond43";

Zaktualizuj sygnaturę metody głównej, aby uwzględnić następującą throws klauzulę:
```
public static void main( String[] args ) throws IOException
```
Zastąp kod w metodzie main następującym kodem, aby utworzyć obiekty DeviceTwin i DeviceTwinDevice . Obiekt DeviceTwin obsługuje komunikację z centrum IoT Hub. Obiekt DeviceTwinDevice reprezentuje bliźniacze reprezentację urządzenia z jego właściwościami i tagami:
```
// Get the DeviceTwin and DeviceTwinDevice objects
DeviceTwin twinClient = DeviceTwin.createFromConnectionString(iotHubConnectionString);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);
```

Dodaj następujący try/catch blok do metody main :

try {
  // Code goes here
} catch (IotHubException e) {
  System.out.println(e.getMessage());
} catch (IOException e) {
  System.out.println(e.getMessage());
}

Aby zaktualizować tagi bliźniaczych reprezentacji urządzeń w regionie i zakładzie w bliźniaczej try reprezentacji urządzenia, dodaj następujący kod w bloku:

// 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);

Aby wykonać zapytanie dotyczące bliźniaczych reprezentacji urządzeń w usłudze IoT Hub, dodaj następujący kod do try bloku po kodzie dodanym w poprzednim kroku. Kod uruchamia dwa zapytania. Każde zapytanie zwraca maksymalnie 100 urządzeń.

// 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());
}

Zapisz i zamknij plik add-tags-query\src\main\java\com\mycompany\app\App.java
Skompiluj aplikację add-tags-query i popraw wszelkie błędy. W wierszu polecenia przejdź do folderu add-tags-query i uruchom następujące polecenie:
```
mvn clean package -DskipTests
```

Uruchamianie aplikacji

Teraz możesz uruchomić aplikacje konsolowe.

W wierszu polecenia w folderze add-tags-query uruchom następujące polecenie, aby uruchomić aplikację usługi add-tags-query :
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
Tagi zakładu i regionu dodane do bliźniaczej reprezentacji urządzenia. Pierwsze zapytanie zwraca urządzenie, ale drugie nie.
W wierszu polecenia w folderze simulated-device uruchom następujące polecenie, aby dodać właściwość connectivityType zgłaszane do bliźniaczej reprezentacji urządzenia:
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
W wierszu polecenia w folderze add-tags-query uruchom następujące polecenie, aby uruchomić aplikację add-tags-query service po raz drugi:
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
Teraz, gdy urządzenie wysłało właściwość connectivityType do usługi IoT Hub, drugie zapytanie zwraca urządzenie.

W tym artykule opisano następujące zagadnienia:

Dodano metadane urządzenia jako tagi z aplikacji zaplecza
Zgłoszone informacje o łączności urządzenia w bliźniaczej reprezentacji urządzenia
Odpytywanie informacji o bliźniaczej reprezentacji urządzenia przy użyciu języka zapytań przypominającego usługę IoT Hub

Następne kroki

Aby dowiedzieć się, jak:

Wysyłanie danych telemetrycznych z urządzeń, zobacz Szybki start: wysyłanie danych telemetrycznych z urządzenia IoT Plug and Play do usługi Azure IoT Hub
Konfigurowanie urządzeń przy użyciu żądanych właściwości bliźniaczej reprezentacji urządzenia, zobacz Samouczek: konfigurowanie urządzeń z poziomu usługi zaplecza
Interaktywne sterowanie urządzeniami, takimi jak włączanie wentylatora z aplikacji kontrolowanej przez użytkownika, zobacz Szybki start: kontrolowanie urządzenia podłączonego do centrum IoT Hub

Share via