Prise en main des représentations d’appareils

Vue d’ensemble

Cet article décrit comment utiliser les kits de développement logiciel (SDK) Azure IoT pour .NET pour créer du code d’application de back-end et d’appareil pour les jumeaux d’appareil.

Créer une application d’appareil

Les applications d’appareil peuvent lire et écrire des propriétés signalées de jumeau et être averties des modifications de propriété de jumeau souhaitées définies par une application back-end ou par IoT Hub.

Cette section explique comment utiliser le code d’application d’appareil pour :

• Récupérer un jumeau d’appareil et examiner les propriétés signalées
• Mettre à jour les propriétés de jumeau d’appareil signalées
• Créer un gestionnaire de rappel de mise à jour de propriété souhaitée

Ajouter un package NuGet d’appareil

Les applications clientes d’appareil écrites en C# nécessitent le package NuGet Microsoft.Azure.Devices.Client.

Connexion à un appareil

La classe DeviceClient expose toutes les méthodes requises pour interagir avec des jumeaux d’appareils à partir de l’appareil.

Connectez-vous à l’appareil à l’aide de la méthode CreateFromConnectionString avec la chaîne de connexion de l’appareil et du protocole de transfert de connexion.

Le paramètre de protocole de transfert CreateFromConnectionString TransportType prend en charge les protocoles de transfert suivants :

• Mqtt
• Mqtt_WebSocket_Only
• Mqtt_Tcp_Only
• Amqp
• Amqp_WebSocket_Only
• Amqp_Tcp_Only

Le protocole Http1 n’est pas pris en charge pour les mises à jour de jumeau d’appareil.

Cet exemple se connecte à un appareil à l’aide du protocole de transfert Mqtt.

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;
using Newtonsoft.Json;

static string DeviceConnectionString = "{IoT hub device connection string}";
static _deviceClient = null;
_deviceClient = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
   TransportType.Mqtt);

Récupérer un jumeau d’appareil et examiner les propriétés

Appelez GetTwinAsync pour récupérer les propriétés actuelles du jumeau d’appareil. Il existe de nombreuses propriétés d’objet Twin que vous pouvez utiliser pour accéder à des zones spécifiques des données JSON Twin, notamment Properties, Status, Tags et Version.

Cet exemple récupère les propriétés du jumeau d’appareil et imprime les valeurs de jumeau au format JSON.

Console.WriteLine("Retrieving twin...");
Twin twin = await _deviceClient.GetTwinAsync();
Console.WriteLine("\tInitial twin value received:");
Console.WriteLine($"\t{twin.ToJson()}");

Mettre à jour les propriétés de jumeau d’appareil signalées

Pour mettre à jour une propriété signalée de jumeau :

1. Créez un objet TwinCollection pour la mise à jour de propriété signalée
2. Mettez à jour une ou plusieurs propriétés signalées dans l’objet TwinCollection
3. Utilisez UpdateReportedPropertiesAsync pour envoyer (push) les modifications de propriété signalées au service IoT Hub

Par exemple :

try
{
Console.WriteLine("Sending sample start time as reported property");
TwinCollection reportedProperties = new TwinCollection();
reportedProperties["DateTimeLastAppLaunch"] = DateTime.UtcNow;
await _deviceClient.UpdateReportedPropertiesAsync(reportedProperties);
}
catch (Exception ex)
{
   Console.WriteLine();
   Console.WriteLine("Error in sample: {0}", ex.Message);
}

Créer un gestionnaire de rappel de mise à jour de propriété souhaitée

Créez un gestionnaire de rappel de mise à jour de propriété souhaitée qui s’exécute lorsqu’une propriété souhaitée est modifiée dans le jumeau d’appareil en passant le nom de méthode du gestionnaire de rappel à SetDesiredPropertyUpdateCallbackAsync.

Par exemple, cet appel configure le système pour notifier une méthode nommée OnDesiredPropertyChangedAsync chaque fois qu’une propriété souhaitée est modifiée.

await _deviceClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

Les propriétés de jumeau sont passées à la méthode de rappel en tant que TwinCollection et peuvent être examinées comme des structures KeyValuePair.

Cet exemple reçoit les mises à jour de propriété souhaitées sous la forme de TwinCollection, puis effectue une boucle et imprime les mises à jour de collection KeyValuePair. Après avoir effectué une boucle dans la collection KeyValuePair, le code appelle UpdateReportedPropertiesAsync pour mettre à jour la propriété signalée DateTimeLastDesiredPropertyChangeReceived pour conserver la dernière heure de mise à jour.

private async Task OnDesiredPropertyChangedAsync(TwinCollection desiredProperties, object userContext)
{
   var reportedProperties = new TwinCollection();

   Console.WriteLine("\tDesired properties requested:");
   Console.WriteLine($"\t{desiredProperties.ToJson()}");

   // For the purpose of this sample, we'll blindly accept all twin property write requests.
   foreach (KeyValuePair<string, object> desiredProperty in desiredProperties)
   {
         Console.WriteLine($"Setting {desiredProperty.Key} to {desiredProperty.Value}.");
         reportedProperties[desiredProperty.Key] = desiredProperty.Value;
   }

   Console.WriteLine("\tAlso setting current time as reported property");
   reportedProperties["DateTimeLastDesiredPropertyChangeReceived"] = DateTime.UtcNow;

   await _deviceClient.UpdateReportedPropertiesAsync(reportedProperties);
}

Exemple d’appareil SDK

Le SDK Azure IoT pour .NET fournit un exemple fonctionnel d’application d’appareil qui gère les tâches de jumeau d’appareil. Pour plus d'informations, consultez TwinSample.

Créer une application back-end

Une application back-end :

• Se connecte à un appareil via IoT Hub
• Peut lire les propriétés signalées et souhaitées de l’appareil, écrire les propriétés souhaitées de l’appareil et exécuter des requêtes d’appareil

La classe RegistryManager expose toutes les méthodes requises pour créer une application back-end pour interagir avec des jumeaux d’appareil à partir du service.

Cette section explique comment créer du code d’application back-end pour :

• Lire et mettre à jour les champs de jumeau d’appareil
• Créer une requête de jumeau d’appareil

Ajouter un package NuGet de service

Les applications de service principal nécessitent le package NuGet Microsoft.Azure.Devices.

Se connecter au hub IoT

Connectez une application back-end à un appareil à l’aide de CreateFromConnectionString. Pour le paramètre, fournissez la chaîne de connexion de service IoT Hub que vous avez créée dans la section des conditions préalables.

using Microsoft.Azure.Devices;
static RegistryManager registryManager;
static string connectionString = "{IoT hub service connection string}";
registryManager = RegistryManager.CreateFromConnectionString(connectionString);

Lire et mettre à jour les champs de jumeau d’appareil

Vous pouvez récupérer les champs de jumeau d’appareil actuels dans un objet Twin en appelant GetTwinAsync.

La classe Twin inclut des propriétés qui correspondent à chaque section d’un jumeau d’appareil. Utilisez les propriétés de classe Twin pour afficher et mettre à jour les champs de jumeau d’appareil. Vous pouvez utiliser les propriétés de l’objet Twin pour mettre à jour plusieurs champs jumeaux avant d’écrire les mises à jour sur l’appareil à l’aide de UpdateTwinAsync.

Après avoir effectué des mises à jour de champ de jumeau, appelez UpdateTwinAsync pour écrire des mises à jour de champ d’objet Twin sur un appareil. Utilisez la logique try et catch avec un gestionnaire d’erreurs pour intercepter les erreurs de correctif mal mis en forme à partir de UpdateTwinAsync.

Lire et mettre à jour les balises de jumeau d’appareil

Utilisez la propriété Balises de jumeau d’appareil pour lire et écrire des informations sur les étiquettes d’appareil.

Mettre à jour des balises à l’aide d’un objet jumeau

Cet exemple crée un correctif de balise location, l’affecte à l’objet Twin à l’aide de la propriété Tags, puis applique le correctif à l’aide de UpdateTwinAsync.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

// Create the tag patch
var tagspatch =
   @"{
   tags: {
         location: {
            region: 'US',
            plant: 'Redmond43'
         }
   }
}";

// Assign the patch to the Twin object
twin.Tags["location"] = tagspatch;

// Apply the patch to update the device twin tags section
try
{
   await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);
}
catch (Exception e)
{
   console.WriteLine("Twin update failed.", e.Message);
}

Mettre à jour des balises à l’aide d’une chaîne JSON

Vous pouvez créer et appliquer un correctif de mise à jour des informations de jumeau d’appareil au format JSON. IoT Hub analyse et applique le correctif s’il est correctement mis en forme.

Cet exemple appelle GetTwinAsync pour récupérer les champs actuels du jumeau d’appareil dans un objet Twin, crée un correctif tag au format JSON avec des informations d’emplacement de région et d’usine, puis appelle UpdateTwinAsync pour appliquer le correctif pour mettre à jour le jumeau d’appareil. Un message d’erreur s’affiche si UpdateTwinAsync a échoué.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

// Create the JSON tags patch
var patch =
   @"{
      tags: {
            location: {
               region: 'US',
               plant: 'Redmond43'
            }
      }
   }";
// Apply the patch to update the device twin tags
try
{
   await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);
}
catch (Exception e)
{
   console.WriteLine("Twin update failed.", e.Message);
}

Afficher et mettre à jour les propriétés souhaitées du jumeau

Utilisez la propriété TwinProperties.Desired de jumeau d’appareil pour lire et écrire les informations de propriété souhaitées de l’appareil. Mettez à jour les propriétés de jumeau Desired à l’aide d’un correctif au format JSON.

Cet exemple appelle GetTwinAsync pour récupérer les champs de jumeau d’appareil actuels dans un objet Twin, met à jour la propriété souhaitée du jumeau speed, puis appelle UpdateTwinAsync pour appliquer l’objet Twin pour mettre à jour le jumeau d’appareil.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

twin.Properties.Desired["speed"] = "type: '5G'";
await registryManager.UpdateTwinAsync(twin.DeviceId, twin, twin.ETag);

Autres méthodes de mise à jour de jumeau

Vous pouvez également appliquer des mises à jour de jumeau à l’aide de ces méthodes SDK :

• Appelez ReplaceTwinAsync pour remplacer l’intégralité du jumeau d’appareil.
• Appelez UpdateTwins2Async pour mettre à jour une liste de jumeaux précédemment créés dans le système.

Créer une requête de jumeau d’appareil

Cette section illustre deux requêtes de jumeau d’appareil. Les requêtes de jumeau d’appareil sont des requêtes de type SQL qui retournent un jeu de résultats de jumeaux d’appareil.

Pour créer une requête de jumeau d’appareil, appelez CreateQuery pour envoyer une requête SQL de jumeaux et obtenir une interface IQuery. Vous pouvez éventuellement appeler CreateQuery avec un deuxième paramètre pour spécifier un nombre maximal d’éléments par page.

Ensuite, appelez la méthode GetNextAsTwinAsync ou GetNextAsJsonAsync autant de fois que nécessaire pour récupérer tous les résultats de jumeau.

• GetNextAsTwinAsync pour récupérer le résultat paginé ensuite en tant qu’objets Twin.
• GetNextAsJsonAsync pour récupérer le résultat paginé ensuite sous forme de chaînes JSON.

L’interface IQuery inclut une propriété booléenne HasMoreResults que vous pouvez utiliser pour vérifier s’il existe plus de résultats de jumeau à extraire.

Cet exemple de requête sélectionne uniquement les jumeaux d’appareils situés dans l’usine Redmond43.

var query = registryManager.CreateQuery(
"SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
var twinsInRedmond43 = await query.GetNextAsTwinAsync();
Console.WriteLine("Devices in Redmond43: {0}", 
string.Join(", ", twinsInRedmond43.Select(t => t.DeviceId)));

Cet exemple de requête affine la première requête pour sélectionner uniquement les appareils qui sont également connectés via un réseau cellulaire.

query = registryManager.CreateQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
var twinsInRedmond43UsingCellular = await query.GetNextAsTwinAsync();
Console.WriteLine("Devices in Redmond43 using cellular network: {0}", 
string.Join(", ", twinsInRedmond43UsingCellular.Select(t => t.DeviceId)));

Exemple de service de SDK

Le SDK Azure IoT pour .NET fournit un exemple fonctionnel d’application de service qui gère les tâches de jumeau d’appareil. Pour plus d’informations, consultez Example de gestionnaire de registre.

Vue d’ensemble

Cet article décrit comment utiliser les kits de développement logiciel (SDK) Azure IoT pour Java pour créer du code d’application de back-end et d’appareil pour les jumeaux d’appareil.

Créer une application d’appareil

Les applications d’appareil peuvent lire et écrire des propriétés signalées de jumeau et être averties des modifications de propriété de jumeau souhaitées définies par une application back-end ou par IoT Hub.

Cette section explique comment créer le code d’application d’appareil pour :

• Récupérer et afficher un jumeau d’appareil
• Mettre à jour les propriétés de jumeau d’appareil signalées
• S’abonner aux modifications de propriétés souhaitées

La classe DeviceClient expose toutes les méthodes dont vous avez besoin pour interagir avec des jumeaux d’appareils à partir de l’appareil.

Instructions d’importation d’appareil

Utilisez les instructions d’importation d’appareil suivantes pour accéder au SDK Azure IoT pour Java.

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.DeviceTwin.*;

Se connecter à l’appareil

Pour vous connecter à un appareil :

1. Utilisez IotHubClientProtocol pour choisir un protocole de transport. Par exemple :

   IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
   

2. Utilisez le constructeur DeviceClient pour ajouter la chaîne et le protocole de connexion principal de l’appareil.

   String connString = "{IoT hub device connection string}";
   DeviceClient client = new DeviceClient(connString, protocol);
   

3. Utilisez open pour connecter l’appareil à IoT Hub. Si le client est déjà ouvert, la méthode ne fait rien.

   client.open(true);
   

Récupérer et afficher un jumeau d’appareil

Après avoir ouvert la connexion cliente, appelez getTwin pour récupérer les propriétés de jumeau actuelles dans un objet Twin.

Par exemple :

private static Twin twin;
System.out.println("Getting current twin");
twin = client.getTwin();
System.out.println("Received current twin:");
System.out.println(twin);

Mettre à jour les propriétés signalées du jumeau d’appareil

Après avoir récupéré le jumeau actuel, vous pouvez commencer à mettre à jour les propriétés signalées. Vous pouvez également mettre à jour les propriétés signalées sans obtenir le jumeau actuel tant que vous disposez de la version correcte des propriétés signalées. Si vous envoyez des propriétés signalées et recevez une erreur « Échec de la condition préalable », la version de vos propriétés signalées est obsolète. Dans ce cas, obtenez la dernière version en appelant getTwin à nouveau.

Pour mettre à jour partiellement les propriétés signalées :

1. Appelez getReportedProperties pour extraire les propriétés signalées du jumeau dans un objet TwinCollection.

2. Utilisez put pour mettre à jour une propriété signalée dans l’objet TwinCollection. Appelez put pour chaque mise à jour de propriété signalée.

3. Utilisez updateReportedProperties pour appliquer le groupe de propriétés signalées mises à jour à l’aide de la méthode put.

Par exemple :

TwinCollection reportedProperties = twin.getReportedProperties();

int newTemperature = new Random().nextInt(80);
reportedProperties.put("HomeTemp(F)", newTemperature);
System.out.println("Updating reported property \"HomeTemp(F)\" to value " + newTemperature);

ReportedPropertiesUpdateResponse response = client.updateReportedProperties(reportedProperties);
System.out.println("Successfully set property \"HomeTemp(F)\" to value " + newTemperature);

S’abonner aux modifications de propriétés souhaitées

Appelez subscribeToDesiredProperties pour vous abonner aux modifications de propriété souhaitées. Ce client reçoit un rappel avec un objet Twin chaque fois qu’une propriété souhaitée est mise à jour. Ce rappel contient l’ensemble de propriétés souhaitées complètes ou uniquement la propriété souhaitée mise à jour en fonction de la façon dont la propriété souhaitée a été modifiée.

Cet exemple s’abonne aux modifications de propriété souhaitées. Toutes les modifications de propriété souhaitées sont passées à un gestionnaire nommé DesiredPropertiesUpdatedHandler.

client.subscribeToDesiredProperties(new DesiredPropertiesUpdatedHandler(), null);

Dans cet exemple, le gestionnaire de rappel de modification de propriété souhaitée DesiredPropertiesUpdatedHandler appelle getDesiredProperties pour récupérer les modifications de propriété, puis imprime les propriétés de jumeau mises à jour.

  private static class DesiredPropertiesUpdatedHandler implements DesiredPropertiesCallback
  {
      @Override
      public void onDesiredPropertiesUpdated(Twin desiredPropertyUpdateTwin, Object context)
      {
          if (twin == null)
          {
              // No need to care about this update because these properties will be present in the twin retrieved by getTwin.
              System.out.println("Received desired properties update before getting current twin. Ignoring this update.");
              return;
          }

          // desiredPropertyUpdateTwin.getDesiredProperties() contains all the newly updated desired properties as well as the new version of the desired properties
          twin.getDesiredProperties().putAll(desiredPropertyUpdateTwin.getDesiredProperties());
          twin.getDesiredProperties().setVersion(desiredPropertyUpdateTwin.getDesiredProperties().getVersion());
          System.out.println("Received desired property update. Current twin:");
          System.out.println(twin);
      }
  }

Exemple d’appareil SDK

Le SDK Azure IoT pour Java inclut un exemple de travail pour tester les concepts de l’application d’appareil décrits dans cet article. Pour plus d’informations, consultez Exemple de jumeau d’appareil.

Créer une application back-end

Cette section explique comment créer une application back-end qui :

• Met à jour des balises de représentation d’appareil
• Interroge les appareils à l’aide de filtres sur les étiquettes et les propriétés

La classe DeviceTwin ServiceClient contient des méthodes que les services peuvent utiliser pour accéder aux jumeaux d’appareil.

Instructions d’importation de service

Utilisez les instructions d’importation de service suivantes pour accéder au SDK Azure IoT pour Java.

import com.microsoft.azure.sdk.iot.service.devicetwin.*;
import com.microsoft.azure.sdk.iot.service.exceptions.IotHubException;

Se connecter au client du service IoT Hub

Pour vous connecter à IoT Hub pour afficher et mettre à jour les informations de jumeau d’appareil :

1. Créez un objet DeviceTwinClientOptions. Définissez les options nécessaires pour votre application. Ces options sont transmises à l’objet DeviceTwin.
2. Utilisez un constructeur DeviceTwin pour créer la connexion à IoT Hub. L’objet DeviceTwin gère la communication avec votre IoT Hub. Pour les paramètres, fournissez la chaîne de connexion de service IoT Hub que vous avez créée dans la section Conditions préalables et l’objet DeviceTwinClientOptions.
3. L’objet DeviceTwinDevice représente le jumeau de l’appareil avec ses propriétés et ses balises.

Par exemple :

public static final String iotHubConnectionString = "{IoT hub service connection string}";
public static final String deviceId = "myDeviceId";
public static final String region = "US";
public static final String plant = "Redmond43";

// Get the DeviceTwin and DeviceTwinDevice objects
DeviceTwinClientOptions twinOptions = new DeviceTwinClientOptions();
DeviceTwin twinClient = new DeviceTwin(iotHubConnectionString,twinOptions);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);

Mise à jour des champs de jumeau d’appareil

Pour mettre à jour des champs de jumeau d’appareil :

1. Utilisez getTwin pour récupérer les champs de jumeau d’appareil actuels

   Cet exemple récupère et imprime les champs de jumeau d’appareil :

   // Get the device twin from IoT Hub
   System.out.println("Device twin before update:");
   twinClient.getTwin(device);
   System.out.println(device);
   

2. Utilisez un objet HashSet pour add (ajouter) un groupe de paires d’étiquettes de jumeau

3. Utilisez setTags pour ajouter un groupe de paires d’étiquettes depuis un objet tags à un objet DeviceTwinDevice

4. Utilisez updateTwin pour mettre à jour le jumeau dans le hub IoT Hub

   Cet exemple met à jour les balises de jumeau d’appareil de région et d’usine pour un jumeau d’appareil :

   // 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 and display the device twin with the tag values from IoT Hub
   System.out.println("Device twin after update:");
   twinClient.getTwin(device);
   System.out.println(device);
   

Créer une requête de jumeau d’appareil

Cette section illustre deux requêtes de jumeau d’appareil. Les requêtes de jumeau d’appareil sont des requêtes de type SQL qui retournent un jeu de résultats de jumeaux d’appareil.

La classe Query contient des méthodes qui peuvent être utilisées pour créer des requêtes de style SQL vers IoT Hub pour les jumeaux, les travaux, les travaux d’appareil ou les données brutes.

Pour créer une requête d’appareil :

1. Utilisez createSqlQuery pour générer la requête SQL de jumeaux

2. Utilisez queryTwin pour exécuter la requête

3. Utilisez hasNextDeviceTwin pour vérifier s’il existe un autre jumeau d’appareil dans le jeu de résultats

4. Utilisez getNextDeviceTwin pour récupérer le jumeau d’appareil suivant à partir du jeu de résultats

L’exemple de requête suivant retourne un maximum de 100 appareils.

Cet exemple de requête sélectionne uniquement les jumeaux d’appareils situés dans l’usine Redmond43.

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

Cet exemple de requête affine la première requête pour sélectionner uniquement les appareils qui sont également connectés via un réseau cellulaire.

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

Exemple de service de SDK

Le SDK Azure IoT pour Java fournit un exemple fonctionnel d’application de service qui gère les tâches de jumeau d’appareil. Pour plus d’informations, consultez Exemple de jumeau d’appareil.

Vue d’ensemble

Cet article décrit comment utiliser les kits de développement logiciel (SDK) Azure IoT pour Python pour créer du code d’application de back-end et d’appareil pour les jumeaux d’appareil.

Créer une application d’appareil

Les applications d’appareil peuvent lire et écrire des propriétés signalées de jumeau et être averties des modifications de propriété de jumeau souhaitées définies par une application back-end ou par IoT Hub.

La classe IoTHubDeviceClient contient des méthodes qui peuvent être utilisées pour travailler avec des jumeaux d’appareil.

Cette section explique comment créer le code d’application d’appareil qui :

• Récupère un jumeau d’appareil et examine les propriétés signalées
• Corrige les propriétés de jumeau d’appareil signalées

Connexion à un appareil

Cette section montre comment connecter une application à un appareil à l’aide d’une clé primaire d’appareil qui inclut une clé d’accès partagé.

Pour connecter une application à un appareil :

1. Appelez create_from_connection_string pour ajouter la chaîne de connexion de l’appareil
2. Appelez connect pour connecter le client d’appareil à un hub Azure IoT

# import the device client library
import asyncio
from azure.iot.device.aio import IoTHubDeviceClient

# substitute the device connection string in conn_str
# and add it to the IoTHubDeviceClient object
conn_str = "{IOT hub device connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(conn_str)

# connect the application to the device
await device_client.connect()

Récupérer un jumeau d’appareil et examiner les propriétés signalées

Vous pouvez récupérer et examiner les informations de jumeau d’appareil, y compris les balises et les propriétés. Les informations de jumeau d’appareil récupérées correspondent aux données au format JSON de jumeau d’appareil que vous pouvez afficher pour un appareil dans le portail Azure.

Appelez get_twin pour obtenir le jumeau d’appareil à partir du service Azure IoT Hub. Les informations de jumeau sont placées dans une variable qui peut être imprimée ou examinée.

Cet exemple récupère le jumeau d’appareil et utilise la commande print pour afficher le jumeau d’appareil au format JSON.

# get the twin
twin = await device_client.get_twin()
print("Twin document:")
print("{}".format(twin))

Corrige les propriétés de jumeau d’appareil signalées

Vous pouvez appliquer un correctif pour mettre à jour les propriétés signalées par l’appareil au format JSON.

Pour appliquer un correctif pour mettre à jour les propriétés signalées :

1. Affectez un correctif JSON de propriété signalée à une variable.
2. Appelez patch_twin_reported_properties pour appliquer le correctif JSON aux propriétés signalées. Il s’agit d’un appel synchrone, ce qui signifie que cette fonction ne retourne pas tant que le correctif n’est pas envoyé au service et reconnu.

Si patch_twin_reported_properties retourne une erreur, cette fonction déclenche l’erreur correspondante.

# create the reported properties patch
reported_properties = {"temperature": random.randint(320, 800) / 10}
print("Setting reported temperature to {}".format(reported_properties["temperature"]))
# update the reported properties and wait for the result
await device_client.patch_twin_reported_properties(reported_properties)

Vous pouvez également appeler ces méthodes pour mettre à jour les jumeaux d’appareil :

• Appelez replace_twin pour remplacer les balises de jumeau d’appareil et les propriétés souhaitées.
• Appelez update_twin pour mettre à jour les balises de jumeau d’appareil et les propriétés souhaitées.

Gestionnaire de correctifs de propriétés souhaitées entrants

Appelez on_twin_desired_properties_patch_received pour créer une fonction de gestionnaire ou une coroutine appelée lorsqu’un correctif de propriétés souhaitées de jumeau est reçu. Le gestionnaire prend un argument, qui est le correctif de jumeau sous la forme d’un objet de dictionnaire JSON.

Cet exemple montre comment configurer un gestionnaire de correctifs de propriétés souhaitées nommé twin_patch_handler.

Par exemple :

try:
    # Set handlers on the client
    device_client.on_twin_desired_properties_patch_received = twin_patch_handler
except:
    # Clean up in the event of failure
    client.shutdown()

Le twin_patch_handler reçoit et imprime les mises à jour de propriétés souhaitées JSON.

    # Define behavior for receiving twin desired property patches
    def twin_patch_handler(twin_patch):
        print("Twin patch received:")
        print(twin_patch)

Exemples d’appareils SDK

Le SDK Azure IoT pour Python inclut les exemples suivants :

• get_twin – Se connecter à un appareil et récupérez les informations de jumeau.
• update_twin_reported_properties – Mettre à jour les propriétés signalées du jumeau.
• receive_twin_desired_properties – Recevoir et mettre à jour les propriétés souhaitées.

Créer une application back-end

Une application back-end se connecte à un appareil via IoT Hub et peut lire les propriétés signalées et souhaitées de l’appareil, écrire les propriétés souhaitées de l’appareil et exécuter des requêtes d’appareil.

Cette section explique comment créer une application back-end pour :

• Mettre à jour les étiquettes de jumeau et les propriétés souhaitées
• Interroge les appareils à l’aide de filtres sur les étiquettes et les propriétés

La classe IoTHubRegistryManager expose toutes les méthodes requises pour créer une application back-end pour interagir avec des jumeaux d’appareil à partir du service.

Se connecter au hub IoT

Connectez-vous à IoT Hub à l’aide de fromConnectionString. Pour le paramètre, fournissez la chaîne de connexion de service IoT Hub que vous avez créée dans la section des conditions préalables.

Par exemple :

import sys
from time import sleep
from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import Twin, TwinProperties, QuerySpecification, QueryResult

# Connect to IoT hub
IOTHUB_CONNECTION_STRING = "{IoT hub service connection string}"
iothub_registry_manager = IoTHubRegistryManager.from_connection_string(IOTHUB_CONNECTION_STRING)

Mettre à jour les étiquettes de jumeau et les propriétés souhaitées

Vous pouvez mettre à jour les étiquettes de jumeau d’appareil et les propriétés souhaitées à partir d’une application back-end en même temps à l’aide de update_twin.

1. Appelez get_twin pour obtenir la version actuelle du jumeau d’appareil
2. Utilisez la classe Twin pour ajouter des balises et des propriétés au format JSON.
3. Appelez update_twin pour appliquer le correctif au jumeau d’appareil. Vous pouvez également utiliser replace_twin pour remplacer les propriétés et balises souhaitées pour un jumeau d’appareil.

Cet exemple met à jour les informations de balises region et plant, et définit une propriété power_level souhaitée sur 1.

new_tags = {
        'location' : {
            'region' : 'US',
            'plant' : 'Redmond43'
        }
    }

DEVICE_ID = "[Device Id]"
twin = iothub_registry_manager.get_twin(DEVICE_ID)
twin_patch = Twin(tags=new_tags, properties= TwinProperties(desired={'power_level' : 1}))
twin = iothub_registry_manager.update_twin(DEVICE_ID, twin_patch, twin.etag)

Créer une requête de jumeau d’appareil

Vous pouvez interroger des informations de jumeau d’appareil à l’aide de requêtes de jumeau d’appareil. Les requêtes de jumeau d’appareil sont des requêtes de type SQL qui retournent un jeu de résultats de jumeaux d’appareil.

Pour utiliser une requête de jumeau d’appareil :

1. Utilisez un objet QuerySpecification pour définir une requête de type SQL.

2. Utilisez query_iot_hub pour interroger un IoTHub et récupérer des informations de jumeau d’appareil à l’aide de la spécification de requête de type SQL.

Cet exemple exécute deux requêtes. La première sélectionne uniquement les jumeaux d’appareils situés dans l’usine Redmond43 et la seconde affine la requête pour sélectionner uniquement les appareils qui sont également connectés par le biais d’un réseau cellulaire. Les résultats sont imprimés après chaque requête.

query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'")
query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
print("Devices in Redmond43 plant: {}".format(', '.join([twin.device_id for twin in query_result.items])))

print()

query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity = 'cellular'")
query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
print("Devices in Redmond43 plant using cellular network: {}".format(', '.join([twin.device_id for twin in query_result.items])))

print()

Exemple de service de SDK

Le SDK Azure IoT pour Python fournit un exemple fonctionnel d’application de service qui gère les tâches de jumeau d’appareil. Pour plus d’informations, consultez Example de requête de gestionnaire de registre.

Vue d’ensemble

Cet article décrit comment utiliser les kits de développement logiciel (SDK) Azure IoT pour Node.js pour créer du code d’application de back-end et d’appareil pour les jumeaux d’appareil.

Créer une application d’appareil

Les applications d’appareil peuvent lire et écrire des propriétés signalées de jumeau et être averties des modifications de propriété de jumeau souhaitées définies par une application back-end ou par IoT Hub.

Cette section explique comment utiliser le package de azure-iot-device dans le SDK Azure IoT pour Node.js pour créer une application d’appareil pour :

• Récupérer un jumeau d’appareil et examiner les propriétés signalées
• Mettre à jour les propriétés de jumeau d’appareil signalées
• Recevoir une notification des modifications de propriété souhaitées

Installer les packages du Kit de développement logiciel (SDK)

Exécutez cette commande pour installer le SDK d’appareil azure-iot-device sur votre ordinateur de développement :

npm install azure-iot-device --save

Le package azure-iot-device contient des objets qui s’interfacent avec les appareils IoT. La classe Twin inclut des objets spécifiques aux jumeaux. Cette section décrit le code de classe Client utilisé pour lire et écrire des données de jumeau d’appareil.

Choisir un protocole de transport

L’objet Client prend en charge ces protocoles :

• Amqp
• Http - Lors de l'utilisation de Http, l'instance Client vérifie rarement les messages provenant d'IoT Hub (au minimum toutes les 25 minutes).
• Mqtt
• MqttWs
• AmqpWs

Installez les protocoles de transport nécessaires sur votre ordinateur de développement.

Par exemple, cette commande installe le protocole Mqtt :

npm install azure-iot-device-mqtt --save

Pour plus d’informations sur les différences de prise en charge entre MQTT, AMQP et HTTPS, consultez Conseils sur les communications cloud-à-appareil et Choisir un protocole de communication.

Créer un module client

Créer un module Client à l’aide du package installé.

Par exemple :

const Client = require('azure-iot-device').Client;

Créer un module de protocole

Créez un module Protocol à l’aide d’un package de transfert installé.

Cet exemple affecte le protocole MQTT :

const Protocol = require('azure-iot-device-mqtt').Mqtt;

Ajouter la chaîne de connexion d’appareil et le protocole de transfert

Appelez fromConnectionString pour fournir des paramètres de connexion d’appareil :

• connStr : chaîne de connexion qui encapsule les autorisations de « connexion de périphérique » pour un hub IoT. La chaîne de connexion contient le nom d'hôte, l'ID de l'appareil et la clé d'accès partagé dans ce format : « HostName=<iothub_host_name>;DeviceId=<device_id>;SharedAccessKey=<device_key> ».
• transportCtor : protocole de transport.

Cet exemple utilise le protocole de transfert Mqtt :

const deviceConnectionString = "{IoT hub device connection string}"
const Protocol = require('azure-iot-device-mqtt').Mqtt;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);

Ouvrir la connexion à IoT Hub

Utilisez la méthode ouvrir pour ouvrir une connexion entre un appareil IoT et IoT Hub. Utilisez .catch(err) pour intercepter une erreur et exécuter un code de gestionnaire.

Par exemple :

client.open()  //open the connection
.catch((err) => {
  console.error('Could not connect: ' + err.message);
});

Récupérer un jumeau d’appareil et examiner les propriétés signalées

Appelez getTwin pour récupérer les informations actuelles du jumeau d’appareil dans un objet Twin.

Par exemple :

client.getTwin(function(err, twin))
if (err)
    console.error('could not get twin');

Mettre à jour les propriétés de jumeau d’appareil signalées

Utilisez update pour mettre à jour les propriétés signalées par l’appareil. Incluez un correctif au format JSON comme premier paramètre, et une méthode de rappel d’état d’exécution de fonction comme deuxième paramètre de la méthode.

Dans cet exemple, un correctif de jumeau d’appareil au format JSON est stocké dans la variable patch. Le correctif contient une valeur de mise à jour de jumeau d’appareil connectivity de cellular. Le correctif et le gestionnaire d’erreurs sont passés à la méthode update. En cas d’erreur, un message d’erreur de console s’affiche.

var patch = {
    connectivity: {
        type: 'cellular'
    }
}
twin.properties.reported.update(patch, function(err)
  {
    if (err)
      {
        console.error('could not update twin');
      } 
    else
      {
        console.log('twin state reported');
        process.exit();
      }
  });

Recevoir une notification des modifications de propriété souhaitées

Créez un écouteur d’événements de mise à jour de propriété souhaitée qui s’exécute lorsqu’une propriété souhaitée est modifiée dans l’appareil en passant le nom de méthode du gestionnaire de rappel à twin.on.

L’écouteur d’événements de propriété souhaitée peut prendre l’une des formes suivantes :

• Recevoir tous les correctifs avec un seul gestionnaire d’événements
• Recevoir un événement si quelque chose change sous un regroupement de propriétés
• Recevoir un événement pour une modification de propriété unique

Recevoir tous les correctifs avec un seul gestionnaire d’événements

Vous pouvez créer un écouteur pour recevoir toute modification de propriété souhaitée.

Cet exemple de code génère toutes les propriétés reçues par le service.

twin.on('properties.desired', function (delta) {
    console.log('new desired properties received:');
    console.log(JSON.stringify(delta));
});

Recevoir un événement si quelque chose change sous un regroupement de propriétés

Vous pouvez créer un écouteur pour recevoir un événement si quelque chose sous un regroupement de propriétés change.

Par exemple :

1. Les propriétés minTemperature et maxTemperature se trouvent sous un regroupement de propriétés nommé properties.desired.climate changes.

2. Une application de service back-end applique ce correctif pour mettre à jour les propriétés souhaitées minTemperature et maxTemperature :

   const twinPatch1 = {
   properties: {
      desired: {
       climate: { minTemperature: 68, maxTemperature: 76, },
       },
     },
    };
   

3. Ce code configure un écouteur d’événements de modification des propriétés souhaitées qui déclenche toutes les modifications dans le regroupement de propriétés properties.desired.climate. S’il existe une modification de propriété souhaitée dans ce groupe, les messages de modification de température minimale et maximale affichés dans la console sont les suivants :

   twin.on('properties.desired.climate', function (delta) {
       if (delta.minTemperature || delta.maxTemperature) {
           console.log('updating desired temp:');
           console.log('min temp = ' + twin.properties.desired.climate.minTemperature);
           console.log('max temp = ' + twin.properties.desired.climate.maxTemperature);
       }
   });
   

Recevoir un événement pour une modification de propriété unique

Vous pouvez configurer un écouteur pour une modification de propriété unique. Dans cet exemple, le code de cet événement est exécuté uniquement si la valeur booléenne fanOn fait partie du correctif. Le code génère le nouvel état de fanOn souhaité chaque fois que le service le met à jour.

1. Une application back-end applique ce correctif de propriété souhaitée :

    const twinPatch2 = {
     properties: {
       desired: {
         climate: {
           hvac: {
             systemControl: { fanOn: true, },
           },
         },
       },
     },
   };
   

2. L’écouteur se déclenche uniquement lorsque la propriété fanOn change :

    twin.on('properties.desired.climate.hvac.systemControl', function (fanOn) {
        console.log('setting fan state to ' + fanOn);
     });
   

Exemples pour le SDK d’appareils

Le SDK Azure IoT pour Node.js contient deux exemples de jumeau d’appareil :

• Exemple de jumeau d’appareil simple

• Exemple de jumeau d’appareil simple avec SAP

Créer une application back-end

Une application back-end se connecte à un appareil via IoT Hub et peut lire les propriétés signalées et souhaitées de l’appareil, écrire les propriétés souhaitées de l’appareil et exécuter des requêtes d’appareil.

Cette section explique comment créer une application back-end qui :

• Récupère et met à jour un jumeau d’appareil
• Crée une requête de jumeau d’appareil

Installer des packages de SDK de service

Exécutez cette commande pour installer azure-iothub sur votre machine de développement :

npm install azure-iothub --save

La classe Registry expose toutes les méthodes requises pour interagir avec les jumeaux d’appareil à partir d’une application back-end.

Se connecter au hub IoT

Utilisez fromConnectionString pour vous connecter au hub IoT Hub. Pour le paramètre, fournissez la chaîne de connexion de service IoT Hub que vous avez créée dans la section des conditions préalables.

'use strict';
var iothub = require('azure-iothub');
var connectionString = '{Iot Hub service connection string}';
var registry = iothub.Registry.fromConnectionString(connectionString);

Récupérer et mettre à jour un jumeau d’appareil

Vous pouvez créer un correctif qui contient des mises à jour de balises et de propriétés souhaitées pour un jumeau d’appareil.

Pour mettre à jour un jumeau d’appareil :

1. Appelez getTwin pour récupérer l’objet jumeau d’appareil.

• Mettez en forme un correctif qui contient la mise à jour du jumeau d’appareil. Le correctif est mis en forme au format JSON, comme décrit dans classe Twin. Un correctif de service principal peut contenir des mises à jour de balises et de propriétés souhaitées. Pour plus d’informations sur le format des correctifs, consultez Format de balises et de propriétés.

1. Appelez update pour mettre à jour le jumeau d’appareil avec le correctif.

Dans cet exemple, le jumeau d’appareil est récupéré pour myDeviceId, puis un correctif est appliqué aux jumeaux, qui contient la mise à jour de balise location de region: 'US', plant: 'Redmond43'.

     registry.getTwin('myDeviceId', function(err, twin){
         if (err) {
             console.error(err.constructor.name + ': ' + err.message);
         } else {
             var patch = {
                 tags: {
                     location: {
                         region: 'US',
                         plant: 'Redmond43'
                   }
                 }
             };

             twin.update(patch, function(err) {
               if (err) {
                 console.error('Could not update twin: ' + err.constructor.name + ': ' + err.message);
               } else {
                 console.log(twin.deviceId + ' twin updated successfully');
                 queryTwins();
               }
             });
         }
     });

Créer une requête de jumeau d’appareil

Vous pouvez créer des requêtes d’appareil de type SQL pour collecter des informations à partir de jumeaux d’appareil.

Utilisez createQuery pour créer une requête qui peut être exécutée sur une instance IoT Hub pour trouver des informations sur les appareils ou les travaux.

createQuery inclut deux paramètres :

• sqlQuery – Requête écrite en tant que chaîne SQL.
• pageSize – Nombre souhaité de résultats par page (facultatif. valeur par défaut : 1 000 ; max : 10 000).

Si le paramètre pageSize est spécifié, l’objet de requête contient une propriété booléenne hasMoreResults que vous pouvez vérifier, et utilisez la méthode nextAsTwin pour obtenir la page de résultats du jumeau suivant autant de fois que nécessaire pour récupérer tous les résultats. Une méthode appelée next est disponible pour les résultats qui ne sont pas des jumeaux d’appareil, par exemple les résultats de requêtes d’agrégation.

Cet exemple de requête sélectionne uniquement les jumeaux d’appareils situés dans l’usine Redmond43.

var queryTwins = function() {
var query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
query.nextAsTwin(function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        console.log("Devices in Redmond43: " + results.map(function(twin) {return twin.deviceId}).join(','));
    }
});

Cet exemple de requête affine la première requête pour sélectionner uniquement les appareils qui sont également connectés via un réseau cellulaire.

query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
query.nextAsTwin(function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        console.log("Devices in Redmond43 using cellular network: " + results.map(function(twin) {return twin.deviceId}).join(','));
    }
});
};

Exemple de SDK de service

Le SDK Azure IoT pour Node.js fournit un exemple fonctionnel d’application de service qui gère les tâches de jumeau d’appareil. Pour plus d’informations, consultez Service back-end de jumeau d’appareil : ce projet est utilisé pour envoyer des mises à jour correctives de jumeau d’appareil pour un appareil spécifique.