Erste Schritte mit der Geräteverwaltung (Java)

Artikel
10/01/2024

Back-End-Apps können Azure IoT Hub-Primitive wie Gerätezwillinge und direkte Methoden verwenden, um Aktionen zur Geräteverwaltung auf Geräten remote zu starten und zu überwachen. In diesem Artikel wird veranschaulicht, wie eine Back-End-App und eine Geräte-App zusammen verwendet werden können, um einen Remoteneustart des Geräts mithilfe von IoT Hub zu initiieren und zu überwachen.

Hinweis

Die in diesem Artikel beschriebenen Features stehen nur im Standard-Tarif von IoT Hub zur Verfügung. Weitere Informationen zu den IoT Hub-Tarifen „Basic“ und „Standard/Free“ finden Sie unter Wählen des richtigen IoT Hub-Tarifs für Ihre Lösung.

Verwenden Sie eine direkte Methode, um Geräteverwaltungsaktionen (wie Neustarts, Zurücksetzen auf Werkseinstellungen und Firmwareaktualisierung) von einer Back-End-App aus in der Cloud zu initiieren. Das Gerät ist für Folgendes verantwortlich:

Verarbeiten der von IoT Hub gesendeten Methodenanforderung
Initiieren der entsprechenden gerätespezifischen Aktion auf dem Gerät.
Senden von Statusupdates über die gemeldeten Eigenschaften an IoT Hub

Sie können eine Back-End-App in der Cloud verwenden, um Gerätezwillingsabfragen auszuführen und Berichte zum Status der Geräteverwaltungsaktionen zu erstellen.

In diesem Artikel wird gezeigt, wie Sie Folgendes erstellen:

simulated-device: eine simulierte Geräte-App mit einer direkten Methode, die das Gerät neu startet und die letzte Neustartzeit meldet. Direkte Methoden werden aus der Cloud aufgerufen.
trigger-reboot: eine Java-App, die die direkte Methode in der simulierten Geräte-App über Ihren IoT-Hub aufruft. Sie zeigt die Antwort und aktualisierte gemeldete Eigenschaften an.

Hinweis

Informationen zu den verschiedenen SDKs, mit denen Sie Anwendungen für Geräte sowie das zugehörige Lösungs-Back-End erstellen können, finden Sie unter Azure IoT SDKs.

Voraussetzungen

Ein IoT Hub in Ihrem Azure-Abonnement. Wenn Sie noch keinen Hub haben, können Sie die Schritte unter Erstellen eines IoT-Hubs ausführen.
Ein in Ihrem IoT-Hub registriertes Gerät. Wenn Sie nicht über ein Gerät in Ihrem IoT-Hub verfügen, führen Sie die Schritte unter Registrieren eines Geräts aus.
Java SE Development Kit 8 Wählen Sie unter Langfristiger Support unbedingt Java 8 aus, um zu den Downloads für JDK 8 zu gelangen.
Maven 3
Stellen Sie sicher, dass der Port 8883 in Ihrer Firewall geöffnet ist. Das Beispielgerät in diesem Artikel verwendet das MQTT-Protokoll, das über Port 8883 kommuniziert. In einigen Netzwerkumgebungen von Unternehmen oder Bildungseinrichtungen ist dieser Port unter Umständen blockiert. Weitere Informationen und Problemumgehungen finden Sie unter Herstellen einer Verbindung mit IoT Hub (MQTT).

Erstellen einer Geräte-App mit einer direkten Methode

In diesem Abschnitt erstellen Sie eine Java-Konsolen-App, die ein Gerät simuliert. Die App lauscht auf den Aufruf der direkten Methode für den Neustart aus Ihrer IoT Hub-Instanz und reagiert sofort auf diesen Aufruf. Anschließend wechselt die App für eine Weile in den Ruhezustand, um den Neustartvorgang zu simulieren, bevor sie eine gemeldete Eigenschaft verwendet, um die Back-End-App trigger-reboot darüber zu informieren, dass der Neustart abgeschlossen ist.

Wichtig

Dieser Artikel enthält Schritte zum Verbinden eines Geräts mithilfe einer Shared Access Signature, was auch als symmetrische Schlüsselauthentifizierung bezeichnet wird. Diese Authentifizierungsmethode eignet sich für Tests und Auswertungen, aber die Authentifizierung eines Geräts mit X.509-Zertifikaten ist ein sichererer Ansatz. Weitere Informationen finden Sie unter Bewährte Methoden für die Sicherheit von IoT-Lösungen > Verbindungssicherheit.

Erstellen Sie im Ordner dm-get-started ein Maven-Projekt namens simulated-device, indem Sie an der Eingabeaufforderung den folgenden Befehl ausführen:

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

Navigieren Sie an der Eingabeaufforderung zum Ordner simulated-device.
Öffnen Sie mit einem Text-Editor die Datei pom.xml im Ordner simulated-device, und fügen Sie dem Knoten dependencies die folgende Abhängigkeit hinzu. Mit dieser Abhängigkeit können Sie das Paket „iot-service-client“ in Ihrer App zum Kommunizieren mit Ihrem IoT-Hub verwenden:
```
<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-device-client</artifactId>
  <version>1.17.5</version>
</dependency>
```
Hinweis

Sie finden die aktuelle Version von iot-device-client mithilfe der Maven-Suche.
Fügen Sie dem Knoten dependencies die folgende Abhängigkeit hinzu. Mit dieser Abhängigkeit wird ein NOP für die Apache SLF4J-Protokollierungsfassade konfiguriert, die vom Geräteclient-SDK zum Implementieren der Protokollierung verwendet wird. Diese Konfiguration ist optional, aber wenn Sie sie weglassen, wird in der Konsole beim Ausführen der App möglicherweise eine Warnung angezeigt. Weitere Informationen zur Protokollierung im Geräteclient-SDK finden Sie unter Logging (Protokollierung) in der Infodatei Samples for the Azure IoT device SDK for Java (Beispiele für das Azure IoT-Geräte-SDK für Java).
```
<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-nop</artifactId>
  <version>1.7.28</version>
</dependency>
```

Fügen Sie den Knoten build hinter dem Knoten dependencies hinzu. Diese Konfiguration weist Maven an, Java 1.8 zu verwenden, um die App zu erstellen:

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

Speichern und schließen Sie die Datei pom.xml.
Öffnen Sie die Quelldatei simulated-device\src\main\java\com\mycompany\app\App.java mit einem Text-Editor.

Fügen Sie der Datei die folgenden import -Anweisungen hinzu:

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.time.LocalDateTime;
import java.util.Scanner;
import java.util.Set;
import java.util.HashSet;

Fügen Sie die folgenden Variablen auf Klassenebene der App -Klasse die folgende Variable auf Klassenebene hinzu. Ersetzen Sie {yourdeviceconnectionstring} durch die Geräteverbindungszeichenfolge, die Ihnen beim Registrieren eines Geräts in IoT Hub angezeigt wurde:

private static final int METHOD_SUCCESS = 200;
private static final int METHOD_NOT_DEFINED = 404;

private static IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
private static String connString = "{yourdeviceconnectionstring}";
private static DeviceClient client;

Fügen Sie der App-Klasse die folgende geschachtelte Klasse hinzu, um einen Rückrufhandler für Statusereignisse der direkten Methode zu implementieren:

protected static class DirectMethodStatusCallback implements IotHubEventCallback
{
  public void execute(IotHubStatusCode status, Object context)
  {
    System.out.println("IoT Hub responded to device method operation with status " + status.name());
  }
}

Fügen Sie der App-Klasse die folgende geschachtelte Klasse hinzu, um einen Rückrufhandler für Statusereignisse des Gerätezwillings zu implementieren:

protected static class DeviceTwinStatusCallback implements IotHubEventCallback
{
    public void execute(IotHubStatusCode status, Object context)
    {
        System.out.println("IoT Hub responded to device twin operation with status " + status.name());
    }
}

Fügen Sie der App-Klasse die folgende geschachtelte Klasse hinzu, um einen Rückrufhandler für Eigenschaftenereignisse zu implementieren:

protected static class PropertyCallback implements PropertyCallBack<String, String>
{
  public void PropertyCall(String propertyKey, String propertyValue, Object context)
  {
    System.out.println("PropertyKey:     " + propertyKey);
    System.out.println("PropertyKvalue:  " + propertyKey);
  }
}

Fügen Sie der App-Klasse die folgende geschachtelte Klasse hinzu, um einen Thread für das Simulieren des Geräteneustarts zu implementieren. Der Thread wartet fünf Sekunden und legt dann die gemeldete lastReboot-Eigenschaft fest:

protected static class RebootDeviceThread implements Runnable {
  public void run() {
    try {
      System.out.println("Rebooting...");
      Thread.sleep(5000);
      Property property = new Property("lastReboot", LocalDateTime.now());
      Set<Property> properties = new HashSet<Property>();
      properties.add(property);
      client.sendReportedProperties(properties);
      System.out.println("Rebooted");
    }
    catch (Exception ex) {
      System.out.println("Exception in reboot thread: " + ex.getMessage());
    }
  }
}

Fügen Sie der App-Klasse die folgende geschachtelte Klasse hinzu, um auf dem Gerät eine direkte Methode zu implementieren. Wenn die simulierte App einen Aufruf der direkten Methode reboot empfängt, gibt sie eine Bestätigung an den Aufrufer zurück und startet dann einen Thread zum Verarbeiten des Neustarts:

protected static class DirectMethodCallback implements com.microsoft.azure.sdk.iot.device.DeviceTwin.DeviceMethodCallback
{
  @Override
  public DeviceMethodData call(String methodName, Object methodData, Object context)
  {
    DeviceMethodData deviceMethodData;
    switch (methodName)
    {
      case "reboot" :
      {
        int status = METHOD_SUCCESS;
        System.out.println("Received reboot request");
        deviceMethodData = new DeviceMethodData(status, "Started reboot");
        RebootDeviceThread rebootThread = new RebootDeviceThread();
        Thread t = new Thread(rebootThread);
        t.start();
        break;
      }
      default:
      {
        int status = METHOD_NOT_DEFINED;
        deviceMethodData = new DeviceMethodData(status, "Not defined direct method " + methodName);
      }
    }
    return deviceMethodData;
  }
}

Ändern Sie die Signatur der main-Methode, um die folgenden Ausnahmen auszulösen:
```
public static void main(String[] args) throws IOException, URISyntaxException
```

Ersetzen Sie den Code in der main-Methode durch den folgenden Code, um einen DeviceClientzu instanziieren:

System.out.println("Starting device client sample...");
client = new DeviceClient(connString, protocol);

Um mit dem Lauschen auf Aufrufe der direkten Methode zu beginnen, fügen Sie der main-Methode den folgenden Code hinzu:

try
{
  client.open();
  client.subscribeToDeviceMethod(new DirectMethodCallback(), null, new DirectMethodStatusCallback(), null);
  client.startDeviceTwin(new DeviceTwinStatusCallback(), null, new PropertyCallback(), null);
  System.out.println("Subscribed to direct methods and polling for reported properties. Waiting...");
}
catch (Exception e)
{
  System.out.println("On exception, shutting down \n" + " Cause: " + e.getCause() + " \n" +  e.getMessage());
  client.close();
  System.out.println("Shutting down...");
}

Fügen Sie der main-Methode den folgenden Code zum Herunterfahren des Gerätesimulators hinzu:

System.out.println("Press any key to exit...");
Scanner scanner = new Scanner(System.in);
scanner.nextLine();
scanner.close();
client.close();
System.out.println("Shutting down...");

Speichern und schließen Sie die Datei „simulated-device\src\main\java\com\mycompany\app\App.java“.
Erstellen Sie die App simulated-device, und korrigieren Sie etwaige Fehler. Navigieren Sie an der Eingabeaufforderung zum Ordner simulated-device, und führen Sie den folgenden Befehl aus:
```
mvn clean package -DskipTests
```

Abrufen der IoT-Hub-Verbindungszeichenfolge

In diesem Artikel erstellen Sie einen Back-End-Dienst, der eine direkte Methode auf einem Gerät aufruft. Ihr Dienst muss über die Berechtigung Dienstverbindung verfügen, um über IoT Hub eine direkte Methode auf einem Gerät aufrufen zu können. Standardmäßig wird jeder IoT-Hub mit einer SAS-Richtlinie namens service erstellt, die diese Berechtigung erteilt.

Führen Sie zum Abrufen der IoT-Hub-Verbindungszeichenfolge für die Richtlinie service die folgenden Schritte aus:

Wählen Sie im Azure-Portal die Option Ressourcengruppen aus. Wählen Sie die Ressourcengruppe aus, in der sich der Hub befindet, und wählen Sie dann in der Liste der Ressourcen Ihren Hub aus.
Wählen Sie im linken Bereich Ihres IoT-Hubs Freigegebene Zugriffsrichtlinien aus.
Wählen Sie in der Liste der Richtlinien die Richtlinie service aus.
Kopieren Sie die primäre Verbindungszeichenfolge und speichern Sie den Wert.

Weitere Informationen zu SAS-Richtlinien und Berechtigungen für IoT-Hubs finden Sie unter Access Control und Berechtigungen.

Erstellen einer Dienst-App zum Auslösen eines Neustarts

In diesem Abschnitt erstellen Sie eine Java-Konsolen-App, die folgende Aufgaben ausführt:

Aufrufen der direkten reboot-Methode in der simulierten Geräte-App
Anzeigen der Antwort
Abfragen der gemeldeten Eigenschaften, die vom Gerät gesendet werden, um zu bestimmen, wann der Neustart abgeschlossen ist

Wichtig

Dieser Artikel enthält Schritte zum Herstellen einer Verbindung mit einem Dienst mithilfe einer Shared Access Signature. Diese Authentifizierungsmethode eignet sich für Tests und Auswertungen, aber die Authentifizierung bei einem Dienst mit Microsoft Entra ID oder verwalteten Identitäten ist ein sichererer Ansatz. Weitere Informationen finden Sie unter Bewährte Methoden für die Sicherheit von IoT-Lösungen > Cloudsicherheit.

Diese Konsolen-App stellt eine Verbindung mit Ihrem IoT Hub her, um die direkte Methode aufzurufen und die gemeldeten Eigenschaften zu lesen.

Erstellen Sie einen leeren Ordner mit dem Namen dm-get-started.

Erstellen Sie im Ordner dm-get-started ein Maven-Projekt namens trigger-reboot, indem Sie an der Eingabeaufforderung den folgenden Befehl ausführen:

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

Navigieren Sie an der Eingabeaufforderung zum Ordner trigger-reboot.
Öffnen Sie mit einem Text-Editor die Datei pom.xml im Ordner trigger-reboot, und fügen Sie dem Knoten dependencies die folgende Abhängigkeit hinzu. Mit dieser Abhängigkeit können Sie das Paket „iot-service-client“ in Ihrer App zum Kommunizieren mit Ihrem IoT-Hub verwenden:
```
<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-service-client</artifactId>
  <version>1.17.1</version>
  <type>jar</type>
</dependency>
```
Hinweis

Sie finden die aktuelle Version von iot-service-client mithilfe der Maven-Suche.

Fügen Sie den Knoten build hinter dem Knoten dependencies hinzu. Diese Konfiguration weist Maven an, Java 1.8 zu verwenden, um die App zu erstellen:

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

Speichern und schließen Sie die Datei pom.xml.
Öffnen Sie die Quelldatei trigger-reboot\src\main\java\com\mycompany\app\App.java mit einem Text-Editor.

Fügen Sie der Datei die folgenden import -Anweisungen hinzu:

import com.microsoft.azure.sdk.iot.service.devicetwin.DeviceMethod;
import com.microsoft.azure.sdk.iot.service.devicetwin.MethodResult;
import com.microsoft.azure.sdk.iot.service.exceptions.IotHubException;
import com.microsoft.azure.sdk.iot.service.devicetwin.DeviceTwin;
import com.microsoft.azure.sdk.iot.service.devicetwin.DeviceTwinDevice;

import java.io.IOException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.Executors;
import java.util.concurrent.ExecutorService;

Fügen Sie die folgenden Variablen auf Klassenebene der App -Klasse die folgende Variable auf Klassenebene hinzu. Ersetzen Sie {youriothubconnectionstring} durch die IoT-Hub-Verbindungszeichenfolge, die Sie zuvor unter Abrufen der IoT-Hub-Verbindungszeichenfolge kopiert haben:

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

private static final String methodName = "reboot";
private static final Long responseTimeout = TimeUnit.SECONDS.toSeconds(30);
private static final Long connectTimeout = TimeUnit.SECONDS.toSeconds(5);

Fügen Sie der App-Klasse die folgende geschachtelte Klasse hinzu, um einen Thread zu implementieren, der die vom Gerätezwilling gemeldeten Eigenschaften alle 10 Sekunden liest:

private static class ShowReportedProperties implements Runnable {
  public void run() {
    try {
      DeviceTwin deviceTwins = DeviceTwin.createFromConnectionString(iotHubConnectionString);
      DeviceTwinDevice twinDevice = new DeviceTwinDevice(deviceId);
      while (true) {
        System.out.println("Get reported properties from device twin");
        deviceTwins.getTwin(twinDevice);
        System.out.println(twinDevice.reportedPropertiesToString());
        Thread.sleep(10000);
      }
    } catch (Exception ex) {
      System.out.println("Exception reading reported properties: " + ex.getMessage());
    }
  }
}

Ändern Sie die Signatur der main-Methode, um die folgende Ausnahme auszulösen:
```
public static void main(String[] args) throws IOException
```

Ersetzen Sie den Code in der main-Methode durch den folgenden Code, um die direkte reboot-Methode auf dem simulierten Gerät aufzurufen:

System.out.println("Starting sample...");
DeviceMethod methodClient = DeviceMethod.createFromConnectionString(iotHubConnectionString);

try
{
  System.out.println("Invoke reboot direct method");
  MethodResult result = methodClient.invoke(deviceId, methodName, responseTimeout, connectTimeout, null);

  if(result == null)
  {
    throw new IOException("Invoke direct method reboot returns null");
  }
  System.out.println("Invoked reboot on device");
  System.out.println("Status for device:   " + result.getStatus());
  System.out.println("Message from device: " + result.getPayload());
}
catch (IotHubException e)
{
    System.out.println(e.getMessage());
}

Fügen Sie der main-Methode den folgenden Code hinzu, um den Thread zum Abrufen der vom simulierten Gerät gemeldeten Eigenschaften zu starten:

ShowReportedProperties showReportedProperties = new ShowReportedProperties();
ExecutorService executor = Executors.newFixedThreadPool(1);
executor.execute(showReportedProperties);

Fügen Sie der main-Methode den folgenden Code hinzu, damit Sie die App beenden können:

System.out.println("Press ENTER to exit.");
System.in.read();
executor.shutdownNow();
System.out.println("Shutting down sample...");

Speichern und schließen Sie die Datei trigger-reboot\src\main\java\com\mycompany\app\App.java.
Erstellen Sie die Back-End-App trigger-reboot, und korrigieren Sie etwaige Fehler. Navigieren Sie an der Eingabeaufforderung zum Ordner trigger-reboot, und führen Sie den folgenden Befehl aus:
```
mvn clean package -DskipTests
```

Ausführen der Apps

Jetzt können Sie die Apps ausführen.

Führen Sie an einer Eingabeaufforderung im Ordner simulated-device den folgenden Befehl aus, um mit dem Lauschen auf Aufrufe der reboot-Methode aus Ihrer IoT Hub-Instanz zu beginnen:
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
Führen Sie an einer Eingabeaufforderung im Ordner trigger-reboot den folgenden Befehl aus, um aus Ihrer IoT Hub-Instanz die reboot-Methode auf Ihrem simulierten Gerät aufzurufen:
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
Das simulierte Gerät reagiert auf den Aufruf der direkten reboot-Methode:

Anpassen und Erweitern der Geräteverwaltungsaktionen

Ihre IoT-Lösungen können die festgelegten Geräteverwaltungsmuster erweitern oder benutzerdefinierte Muster ermöglichen. Dazu werden die Grundtypen für die Gerätezwillings- oder die C2D-Methode verwendet. Andere Beispiele für Geräteverwaltungsaktionen sind das Zurücksetzen auf die Werkseinstellungen, Firmware- und Softwareaktualisierungen, Energieverwaltung, Netzwerk- und Konnektivitätsverwaltung und Datenverschlüsselung.

Gerätewartungsfenster

In der Regel konfigurieren Sie die Ausführung von Aktionen für Geräte so, dass Unterbrechungen und Ausfallzeiten auf ein Minimum beschränkt sind. Bei Gerätewartungsfenstern handelt es sich um ein häufig verwendetes Muster zum Festlegen des Zeitpunkts, zu dem ein Gerät seine Konfiguration aktualisieren soll. Ihre Back-End-Lösungen können die gewünschten Eigenschaften des Gerätezwillings verwenden, um auf Ihrem Gerät eine Richtlinie zur Aktivierung eines Wartungsfensters festzulegen und zu aktivieren. Wenn ein Gerät die Wartungsfensterrichtlinie erhält, kann es mithilfe der gemeldeten Eigenschaft des Gerätezwillings den Richtlinienstatus melden. Die Back-End-App kann dann mithilfe von Gerätezwillingsabfragen die Konformität von Geräten und den einzelnen Richtlinien sicherstellen.

Nächste Schritte

In diesem Artikel haben Sie eine direkte Methode zum Auslösen eines Remoteneustarts auf einem Gerät verwendet. Sie haben die gemeldeten Eigenschaften zum Melden des letzten Neustartzeitpunkts des Geräts verwendet. Darüber hinaus haben Sie den Gerätezwilling abgefragt, um den letzten Neustartzeitpunkt des Geräts aus der Cloud zu ermitteln.

Um mit IoT Hub und Gerätemanagementmustern wie imagebasierten End-to-End-Updates fortzufahren, lesen Sie den Artikel „Geräteupdate für Azure IoT Hub unter Verwendung des Raspberry Pi 3 B+-Referenzimages.

Unter Planen und Übertragen von Aufträgen erfahren Sie, wie Sie Ihre IoT-Lösung erweitern und Methodenaufrufe für mehrere Geräte planen.

Freigeben über