Erste Schritte mit Gerätezwillingen (Java)

  • Artikel

Gerätezwillinge sind JSON-Dokumente, in denen Gerätestatusinformationen gespeichert werden, einschließlich Metadaten, Konfigurationen und Bedingungen. Von IoT Hub wird für jedes Gerät, das eine Verbindung herstellt, dauerhaft ein Gerätezwilling gespeichert.

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 Gerätezwillinge für Folgendes:

  • Speichern von Gerätemetadaten von Ihrem Lösungs-Back-End

  • Melden von aktuellen Zustandsinformationen wie verfügbare Funktionen und Bedingungen, z.B. die verwendete Verbindungsmethode, von Ihrer Geräte-App

  • Synchronisieren des Zustands von Workflows mit langer Ausführungsdauer, z.B. Firmware- und Konfigurationsupdates, zwischen einer Geräte-App und einer Back-End-App

  • Abfragen von Metadaten, Konfiguration oder Status des Geräts

Gerätezwillinge sind für die Synchronisierung und zum Abfragen von Gerätekonfigurationen und -bedingungen ausgelegt. Weitere Informationen zu Gerätezwillingen, einschließlich der Verwendung von Gerätezwillingen, finden Sie unter Verstehen und Verwenden von Gerätezwillingen in IoT Hub.

IoT-Hubs speichern Gerätezwillinge, die die folgenden Elemente enthalten:

  • Tags. Gerätemetadaten, auf die nur vom Lösungs-Back-End zugegriffen werden kann.

  • Gewünschte Eigenschaften JSON-Objekte, die vom Lösungs-Back-End geändert und von der Geräte-App überwacht werden können.

  • Gemeldete Eigenschaften JSON-Objekte, die von der Geräte-App geändert und vom Lösungs-Back-End gelesen werden können.

Tags und Eigenschaften können keine Arrays, aber geschachtelte Objekte enthalten.

Die folgende Abbildung zeigt die Organisation des Gerätezwillings:

Screenshot eines Konzeptdiagramms für Gerätezwillinge.

Außerdem können mit dem Lösungs-Back-End Gerätezwillinge basierend auf allen obigen Daten abgefragt werden. Weitere Informationen zu Gerätezwillingen finden Sie unter Grundlegendes zu Gerätezwillingen. Weitere Informationen zu Abfragen finden Sie unter IoT Hub-Abfragesprache.

In diesem Artikel lernen Sie Folgendes:

  • Verwenden Sie eine simulierte Geräte-App, um ihren Konnektivitätskanal als gemeldete Eigenschaft auf dem Gerätezwilling zu melden.

  • Fragen Sie Geräte von Ihrer Back-End-App ab, indem Sie Filter für die zuvor erstellten Tags und Eigenschaften verwenden.

In diesem Artikel erstellen Sie zwei Java-Konsolen-Apps:

  • add-tags-query: eine Back-End-App, die Tags hinzufügt und Gerätezwillinge abfragt.
  • simulated-device: eine simulierte Geräte-App, die eine Verbindung mit Ihrem IoT-Hub herstellt und seine Konnektivitätsbedingung meldet.

Hinweis

Weitere Informationen zu den SDK-Tools zum Erstellen von Geräten und Back-End-Apps finden Sie unter Azure IoT SDKs.

Voraussetzungen

  • Einen IoT Hub. Erstellen Sie einen mit der CLI oder dem Azure-Portal.

  • Ein registriertes Gerät. Registrieren Sie eins im Azure-Portal.

  • 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).

Abrufen der IoT-Hub-Verbindungszeichenfolge

In diesem Artikel erstellen Sie einen Back-End-Dienst, der einem Gerätezwilling die gewünschten Eigenschaften hinzufügt und anschließend die Identitätsregistrierung abfragt, um alle Geräte mit gemeldeten Eigenschaften zu ermitteln, die entsprechend aktualisiert wurden. Ihr Dienst benötigt die Berechtigung Dienstverbindung, um die gewünschten Eigenschaften eines Gerätezwillings ändern zu können, sowie die Berechtigung Lesevorgänge in Registrierung, um die Identitätsregistrierung abfragen zu können. Da keine SAS-Standardrichtlinie mit nur diesen beiden Berechtigungen zur Verfügung steht, müssen Sie eine erstellen.

Gehen Sie wie folgt vor, um eine SAS-Richtlinie zu erstellen, die die Berechtigungen Dienstverbindung und Lesevorgänge in Registrierung gewährt, und eine Verbindungszeichenfolge für diese Richtlinie abzurufen:

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

  2. Wählen Sie im linken Bereich Ihres Hubs SAS-Richtlinien aus.

  3. Wählen Sie im Menü oberhalb der Richtlinienliste die Option Richtlinie für den gemeinsamen Zugriff hinzufügen aus.

  4. Geben Sie unter Richtlinie für den gemeinsamen Zugriff hinzufügen einen aussagekräftigen Namen für Ihre Richtlinie ein, wie z.B. serviceAndRegistryRead. Wählen Sie unter Berechtigungen die Berechtigungen Registry Read und Service Connect aus und klicken Sie anschließend auf Hinzufügen.

    Screenshot: Hinzufügen einer neuen SAS-Richtlinie.

  5. Wählen Sie Ihre neue Richtlinie aus der Liste der Richtlinien aus.

  6. Wählen Sie das Kopiersymbol für Primäre Verbindungszeichenfolge aus, und speichern Sie den Wert.

    Screenshot vom Abrufen der Verbindungszeichenfolge.

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

Erstellen einer Geräte-App, die gemeldete Eigenschaften aktualisiert

In diesem Abschnitt erstellen Sie eine Java-Konsolen-App, die sich als Ihre myDeviceId mit Ihrem Hub verbindet und dann die gemeldeten Eigenschaften von dessen Gerätezwilling aktualisiert, um zu bestätigen, dass sie über ein Mobilfunknetz verbunden ist.

  1. Erstellen Sie im Ordner iot-java-twin-getstarted 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

  2. Navigieren Sie an der Eingabeaufforderung zum Ordner simulated-device.

  3. Öffnen Sie mit einem Text-Editor die Datei pom.xml im Ordner simulated-device, und fügen Sie dem Knoten dependencies die folgenden Abhängigkeiten hinzu. Mit dieser Abhängigkeit können Sie das Paket iot-device-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.

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

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

  6. Speichern und schließen Sie die Datei pom.xml.

  7. Öffnen Sie die Datei simulated-device\src\main\java\com\mycompany\app\App.java mit einem Text-Editor.

  8. 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.util.Scanner;

  9. 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 String connString = "{yourdeviceconnectionstring}";
private static IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
private static String deviceId = "myDeviceId";

    Diese Beispiel-App verwendet beim Instanziieren eines DeviceClient-Objekts die protocol-Variable.

  10. Fügen Sie die der App-Klasse folgende Methode hinzu, um Informationen zu Zwillingsupdates zu drucken:

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

  11. Ersetzen Sie den Code in der main-Methode durch den folgenden Code:

    • Erstellen Sie einen Geräteclient zur Kommunikation mit IoT Hub.

    • Erstellen Sie ein Device-Objekt, das die Gerätezwillingseigenschaften speichert.

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

  12. Fügen Sie der main-Methode den folgenden Code hinzu, um eine gemeldete connectivityType-Eigenschaft zu erstellen und an den IoT Hub zu senden:

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

  13. Fügen Sie den folgenden Code am Ende der main-Methode hinzu. Das Warten auf die EINGABETASTE lässt IoT Hub genügend Zeit, um den Status der Gerätezwillingsvorgänge zu melden.

    System.out.println("Press any key to exit...");

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

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

  14. Ändern Sie die Signatur der main -Methode, um die Ausnahmen wie folgt einzufügen:

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

  15. Speichern und schließen Sie die Datei simulated-device\src\main\java\com\mycompany\app\App.java.

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

Erstellen einer Dienst-App, die gewünschte Eigenschaften aktualisiert und Zwillinge abfragt

In diesem Abschnitt erstellen Sie eine Java-App, die dem Gerätezwilling in IoT Hub, der myDeviceId zugeordnet ist, Standortmetadaten als Tag hinzufügt. Die App fragt IoT Hub nach Geräten ab, die sich in den USA befinden, und fragt dann Geräte ab, die eine Mobilfunknetzverbindung melden.

  1. Erstellen Sie auf dem Entwicklungscomputer einen leeren Ordner mit dem Namen iot-java-twin-getstarted.

  2. Erstellen Sie im Ordner iot-java-twin-getstarted ein Maven-Projekt namens add-tags-query, indem Sie an der Eingabeaufforderung den folgenden Befehl ausführen:

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

  3. Navigieren Sie an der Eingabeaufforderung zum Ordner add-tags-query.

  4. Öffnen Sie mit einem Text-Editor die Datei pom.xml im Ordner add-tags-query, 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.

  5. Fügen Sie den Knoten build hinter dem Knoten dependencies hinzu. Diese Konfiguration weist Maven an, zum Erstellen der App Java 1.8 zu verwenden.

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

  6. Speichern und schließen Sie die Datei pom.xml.

  7. Öffnen Sie die Datei add-tags-query\src\main\java\com\mycompany\app\App.java in einem Text-Editor.

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

    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;

  9. 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 unter Abrufen der IoT-Hub-Verbindungszeichenfolge kopiert haben.

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

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

  10. Aktualisieren Sie die Signatur der main-Methode und schließen Sie die folgende throws-Klausel ein:

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

  11. Ersetzen Sie den Code in der main-Methode durch den folgenden Code zum Erstellen der Objekte DeviceTwin und DeviceTwinDevice. Das DeviceTwin-Objekt führt die Kommunikation mit Ihrem IoT Hub durch. Das DeviceTwinDevice-Objekt stellt den Gerätezwilling mit seinen Eigenschaften und Tags dar:

    // Get the DeviceTwin and DeviceTwinDevice objects
DeviceTwin twinClient = DeviceTwin.createFromConnectionString(iotHubConnectionString);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);

  12. Fügen Sie den folgenden try/catch-Block der main-Methode hinzu:

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

  13. Fügen Sie zum Aktualisieren der Gerätezwillingstags region und plant in Ihrem Gerätezwilling folgenden Code im try-Block hinzu:

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

  14. Um die Gerätezwillinge in IoT Hub abzufragen, fügen Sie den folgenden Code dem try-Block nach dem Code hinzu, den Sie im vorherigen Schritt hinzugefügt haben. Der Code führt zwei Abfragen aus. Jede Abfrage gibt maximal 100 Geräte zurück.

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

  15. Speichern und schließen Sie die Datei add-tags-query\src\main\java\com\mycompany\app\App.java.

  16. Erstellen Sie die App add-tags-query, und korrigieren Sie etwaige Fehler. Navigieren Sie an der Eingabeaufforderung zum Ordner add-tags-query, und führen Sie den folgenden Befehl aus:

    mvn clean package -DskipTests

Ausführen der Apps

Sie können nun die Konsolen-Apps ausführen.

  1. Führen Sie an der Eingabeaufforderung im Ordner add-tags-query den folgenden Befehl aus, um die Dienst-App add-tags-query auszuführen:

    mvn exec:java -Dexec.mainClass="com.mycompany.app.App"

    Der Screenshot zeigt die Ausgabe aus dem Befehl zur Ausführung der Dienst-App „add-tags-query“.

    Sie sehen die Tags plant und region, die dem Gerätezwilling hinzugefügt wurden. Die erste Abfrage gibt das Gerät zurück, die zweite jedoch nicht.

  2. Führen Sie an der Eingabeaufforderung im Ordner simulated-device den folgenden Befehl aus, um dem Gerätezwilling die gemeldete connectivityType-Eigenschaft hinzuzufügen:

    mvn exec:java -Dexec.mainClass="com.mycompany.app.App"

    Der Geräteclient fügt die gemeldete Eigenschaft „connectivityType“ hinzu.

  3. Führen Sie an der Eingabeaufforderung im Ordner add-tags-query den folgenden Befehl aus, um die Dienst-App add-tags-query ein zweites Mal auszuführen:

    mvn exec:java -Dexec.mainClass="com.mycompany.app.App"

    Java IoT Hub-Dienst-App zum Aktualisieren von Tagwerten und Ausführen von Geräteabfragen

    Nachdem Ihr Gerät nun die connectivityType-Eigenschaft an IoT Hub gesendet hat, gibt die zweite Abfrage das Gerät zurück.

In diesem Artikel führen Sie folgende Schritte aus:

  • Gerätemetadaten als Tags aus einer Back-End-App hinzugefügt
  • Gemeldete Gerätekonnektivitätsinformationen im Gerätezwilling
  • Sie haben zudem erfahren, wie die Gerätezwillingsinformationen mithilfe der SQL-ähnlichen IoT Hub-Abfragesprache abgefragt werden können

Nächste Schritte

Eine entsprechende Anleitung