Bien démarrer avec les jumeaux d’appareils (Java)

Article
03/19/2023

Les jumeaux d’appareil sont des documents JSON qui stockent des informations sur l’état des appareils (métadonnées, configurations et conditions). IoT Hub conserve une représentation d’appareil pour chaque appareil que vous y connectez.

Notes

Les fonctionnalités décrites dans cet article sont uniquement disponibles au niveau Standard d’IoT Hub. Pour plus d’informations sur les niveaux de base et standard/gratuit d’IoT Hub, consultez Choisir le niveau IoT Hub correspondant à votre solution.

Vous pouvez utiliser des jumeaux d’appareil pour répondre aux besoins suivants :

Stockez les métadonnées d’appareil à partir de votre serveur principal de solution.
Signaler les informations d’état actuel, telles que les capacités disponibles et les conditions, par exemple la méthode de connectivité utilisée, à partir de votre application d’appareil
Synchronisez l’état des workflows de longue durée, par exemple les mises à jour de microprogramme et de configuration, entre une application d’appareil et une application back-end.
Interroger les métadonnées, la configuration ou l’état de vos appareils

Les représentations d’appareil sont conçues pour les synchronisations et pour l’interrogation des configurations et des conditions d’appareil. Pour plus d’informations sur les jumeaux d’appareil, notamment quand utiliser des jumeaux d’appareil, consultez Comprendre les jumeaux d’appareil.

Les hubs IoT stockent des jumeaux d’appareil, qui contiennent les éléments suivants :

Tags (balises). Métadonnées d’appareil uniquement accessibles par le back-end de solution.
Propriétés souhaitées (Desired) . Objets JSON modifiables par le back-end de solution et observables par l’application d’appareil.
Propriétés signalées (Reported) . Objets JSON modifiables par l’application d’appareil et consultables par le back-end de solution.

Les balises et les propriétés ne peuvent pas contenir de tableaux, mais peuvent contenir des objets imbriqués.

L’illustration suivante montre l’organisation des jumeaux d’appareil :

Capture d’écran d’un schéma de concept de jumeau d’appareil.

En outre, le serveur principal de solution peut interroger les représentations d’appareil concernant toutes les données ci-dessus. Pour plus d’informations sur les jumeaux d’appareil, consultez Présentation des jumeaux d’appareil. Pour plus d’informations sur l’interrogation, consultez Langage de requête IoT Hub.

Cet article vous montre comment :

Utilisez une application d’appareil simulé pour signaler son canal de connectivité en tant que propriété signalée sur le jumeau d’appareil.
Interrogez les appareils à partir de votre application principale à l’aide de filtres sur les étiquettes et les propriétés précédemment créées.

Dans cet article, vous allez créer deux applications de console Java :

add-tags-query : une application principale qui ajoute des balises et interroge les jumeaux d’appareils.
simulated-device : une application d’appareil simulé qui se connecte à votre hub IoT et signale son état de connectivité.

Notes

Pour plus d’informations sur les outils SDK disponibles pour créer des applications d’appareil et de back-end, consultez les SDK Azure IoT.

Prérequis

Un IoT Hub. Créez-en un avec l’interface CLI ou le portail Azure.
Appareil inscrit. Inscrivez-en un dans le portail Azure.
Java SE Development Kit 8. Veillez à sélectionner Java 8 sous Prise en charge à long terme pour accéder aux téléchargements du kit JDK 8.
Maven 3
Vérifiez que le port 8883 est ouvert dans votre pare-feu. L’exemple d’appareil décrit dans cet article utilise le protocole MQTT, qui communique via le port 8883. Ce port peut être bloqué dans certains environnements réseau professionnels et scolaires. Pour plus d’informations sur les différentes façons de contourner ce problème, consultez Connexion à IoT Hub (MQTT).

Obtenir la chaîne de connexion du hub IoT

Dans cet article, vous créez un service back-end qui ajoute des propriétés souhaitées à un jumeau d’appareil, puis interroge le registre des identités pour trouver tous les appareils dont les propriétés signalées ont été mises à jour en conséquence. Votre service a besoin de l’autorisation de connexion du service pour modifier les propriétés souhaitées d'un jumeau d’appareil, et de l’autorisation de lecture du registre pour interroger le registre des identités. Aucune stratégie d'accès partagé par défaut ne contient que ces deux autorisations. Vous devez donc en créer une.

Pour créer une stratégie d'accès partagé qui accorde des autorisations de connexion de service et de lecture du registre, et obtenir une chaîne de connexion pour cette stratégie, procédez comme suit :

Dans le portail Azure, sélectionnez Groupes de ressources. Sélectionnez le groupe de ressources dans lequel se trouve votre hub, puis sélectionnez votre hub dans la liste des ressources.
Dans le volet de gauche de votre hub, sélectionnez Stratégies d’accès partagé.
Dans le menu supérieur au-dessus de la liste des stratégies, sélectionnez Ajouter une stratégie de politiques d’accès partagé.
Sous Ajouter une stratégie de politiques d’accès partagé, entrez un nom descriptif pour votre stratégie, par exemple serviceAndRegistryRead. Sous Autorisations, sélectionnez Lecture du registre et Connexion du service, puis sélectionnez Ajouter.
Sélectionnez votre nouvelle stratégie dans la liste des stratégies.
Sélectionnez l’icône de copie pour la Chaîne de connexion principale et enregistrez la valeur.

Pour plus d’informations sur les autorisations et les stratégies d’accès partagé IoT Hub, consultez Contrôle d’accès et autorisations.

Créer une application d’appareil qui met à jour les propriétés signalées

Dans cette section, vous allez créer une application console Java qui se connecte à votre hub en tant que myDeviceId, puis met à jour les propriétés signalées de sa représentation d’appareil afin qu’elles contiennent les informations confirmant qu’elle est connectée par le biais d’un réseau cellulaire.

Dans le dossier iot-java-twin-getstarted, créez un projet Maven nommé simulated-device en entrant la commande suivante à l’invite de commandes :

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

À l'invite de commandes, accédez au dossier simulated-device.
À l'aide d'un éditeur de texte, ouvrez le fichier pom.xml situé dans le dossier simulated-device et ajoutez les dépendances suivantes au nœud dependencies. Cette dépendance vous permet d’utiliser le package iot-device-client dans votre application pour communiquer avec votre hub IoT.
```
<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-device-client</artifactId>
  <version>1.17.5</version>
</dependency>
```
Notes

Vous pouvez rechercher la dernière version de iot-device-client avec la recherche Maven.
Ajoutez la dépendance suivante au nœud dependencies. Cette dépendance configure un NOP pour la façade de journalisation Apache SLF4J utilisée par le kit de développement logiciel (SDK) du client d'appareil afin d'implémenter la journalisation. Cette configuration est facultative, mais si vous l’omettez, un avertissement peut s’afficher sur la console lorsque vous lancez l’application. Pour plus d’informations sur la journalisation dans le SDK du client d’appareil, consultez Journalisation dans le fichier Readme Exemples relatifs à Azure IoT device SDK pour Java.
```
<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-nop</artifactId>
  <version>1.7.28</version>
</dependency>
```

Ajoutez le nœud build suivant après le nœud dependencies. Cette configuration ordonne à Maven d’utiliser Java 1.8 pour générer l’application :

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

Enregistrez et fermez le fichier pom.xml.
À l'aide d'un éditeur de texte, ouvrez le fichier simulated-device\src\main\java\com\mycompany\app\App.java.

Ajoutez les instructions import suivantes au fichier :

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;

Ajoutez les variables de niveau classe suivantes à la classe App . Remplacez {yourdeviceconnectionstring} par la chaîne de connexion de l’appareil que vous avez vu au moment de l’inscription d’un appareil dans IoT Hub :
```
private static String connString = "{yourdeviceconnectionstring}";
private static IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
private static String deviceId = "myDeviceId";
```
Cet exemple d’application utilise la variable protocol lorsqu’il instancie un objet DeviceClient.

Ajoutez la méthode suivante à la classe App pour imprimer les informations sur les mises à jour de représentations :

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

Remplacez le code de la méthode main par le code suivant pour :

créer un client d’appareil afin de communiquer avec IoT Hub.
créer un objet Device afin de stocker les propriétés du jumeau d’appareil.

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

Ajoutez le code suivant à la méthode main pour créer une propriété signalée connectivityType et l’envoyer à 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...");
}

Ajoutez le code suivant à la fin de la méthode main. Le fait d’attendre la touche Entrée laisse le temps à IoT Hub de signaler l’état des opérations du jumeau d’appareil.
```
System.out.println("Press any key to exit...");

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

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

Modifiez la signature de la méthode main pour inclure les exceptions suivantes :

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

Enregistrez et fermez le fichier simulated-device\src\main\java\com\mycompany\app\App.java.
Générez l’application simulated-device et corrigez les erreurs. À l'invite de commandes, accédez au dossier simulated-device et exécutez la commande suivante :
```
mvn clean package -DskipTests
```

Créer une application de service qui met à jour les propriétés souhaitées et interroge les jumeaux

Dans cette section, vous créez une application Java qui ajoute des métadonnées d’emplacement sous forme de balise au jumeau d’appareil associé à myDeviceId dans IoT Hub. L’application interroge IoT Hub pour lister les appareils situés aux États-Unis, puis interroge les appareils qui signalent une connexion réseau cellulaire.

Sur votre ordinateur de développement, créez un dossier vide nommé iot-java-twin-getstarted.

Dans le dossier iot-java-twin-getstarted, créez un projet Maven nommé add-tags-query en lançant la commande ci-dessous dans votre invite de commandes :

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

Dans votre invite de commandes, accédez au dossier add-tags-query.
À l’aide d’un éditeur de texte, ouvrez le fichier pom.xml situé dans le dossier add-tags-query et ajoutez la dépendance suivante au nœud dependencies. Cette dépendance vous permet d’utiliser le package iot-service-client dans votre application pour communiquer avec votre IoT Hub :
```
<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-service-client</artifactId>
  <version>1.17.1</version>
  <type>jar</type>
</dependency>
```
Notes

Vous pouvez rechercher la dernière version de iot-service-client avec la recherche Maven.

Ajoutez le nœud build suivant après le nœud dependencies. Cette configuration ordonne à Maven d’utiliser Java 1.8 pour générer l’application.

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

Enregistrez et fermez le fichier pom.xml.
À l’aide d’un éditeur de texte, ouvrez le fichier add-tags-query\src\main\java\com\mycompany\app\App.java.

Ajoutez les instructions import suivantes au fichier :

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;

Ajoutez les variables de niveau classe suivantes à la classe App . Remplacez {youriothubconnectionstring} par la chaîne de connexion de l’IoT Hub que vous avez copiée dans Obtention de la chaîne de connexion de l’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";

Mettez à jour la signature de la méthode main pour qu’elle inclue la clause throws suivante :
```
public static void main( String[] args ) throws IOException
```
Remplacez le code dans la méthode main par le code suivant pour créer les objets DeviceTwin et DeviceTwinDevice. L’objet DeviceTwin gère la communication avec votre hub IoT. L’objet DeviceTwinDevice représente le jumeau de l’appareil avec ses propriétés et ses balises :
```
// Get the DeviceTwin and DeviceTwinDevice objects
DeviceTwin twinClient = DeviceTwin.createFromConnectionString(iotHubConnectionString);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);
```

Ajoutez le bloc try/catch suivant à la méthode main :

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

Pour mettre à jour les balises region et plant du jumeau de l’appareil, ajoutez le code suivant dans le bloc 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);

Pour interroger les jumeaux d’appareils dans IoT Hub, ajoutez le code suivant au bloc try après le code que vous avez ajouté à l’étape précédente. Le code exécute deux requêtes. Chaque requête retourne un maximum de 100 appareils.

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

Enregistrez le fichier add-tags-query\src\main\java\com\mycompany\app\App.java et fermez-le.
Générez l’application add-tags-query et corrigez les erreurs éventuelles. À l’invite de commandes, accédez au dossier add-tags-query et exécutez la commande suivante :
```
mvn clean package -DskipTests
```

Exécuter les applications

Vous êtes maintenant prêt à exécuter les applications de console.

Dans une invite de commandes, exécutez la commande suivante dans le dossier add-tags-query pour exécuter de nouveau l’application de service add-tags-query :
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
Vous pouvez constater que les balises plant et region sont ajoutées au jumeau d’appareil. La première requête retourne votre appareil, la seconde non.
Dans une invite de commandes, exécutez la commande suivante dans le dossier simulated-device pour ajouter la propriété signalée connectivityType au jumeau d’appareil :
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
Dans une invite de commandes, exécutez la commande suivante dans le dossier add-tags-query pour exécuter de nouveau l’application de service add-tags-query une deuxième fois :
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
Maintenant que votre appareil a envoyé la propriété connectivityType à IoT Hub, la deuxième requête retourne votre appareil.

Dans cet article, vous découvrirez comment :

Ajouté des métadonnées d’appareil en tant que balises à partir d’une application back-end
Signalé des informations de connectivité des appareils dans le jumeau d’appareil
Interrogé des informations du jumeau d’appareil, en utilisant le langage de requête IoT Hub de type SQL

Étapes suivantes

Pour découvrir comment :

Pour envoyer de la télémétrie à partir d’appareils, consultez Démarrage rapide : Envoyer des données de télémétrie à partir d’un appareil IoT Plug-and-Play vers Azure IoT Hub
Pour configurer des appareils à l’aide des propriétés souhaitées du jumeau d’appareil, consultez Tutoriel : Configurer vos appareils à partir d’un service back-end
Pour contrôler les appareils de manière interactive, comme l’activation d’un ventilateur à partir d’une application contrôlée par l’utilisateur, consultez Démarrage rapide : contrôler un appareil connecté à un IoT Hub

Share via