Prise en main des représentations d’appareils

Article
12/04/2024

Utilisez le SDK d’appareil Azure IoT Hub et le SDK de service pour développer des applications qui gèrent les tâches courantes de jumeau d’appareil. 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.

Vous pouvez utiliser des jumeaux d’appareil pour :

Stocker les métadonnées d’appareil à partir d’une solution back-end
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
Synchroniser 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

Pour plus d’informations sur les jumeaux d’appareil, notamment sur leur utilisation, consultez Comprendre et utiliser les jumeaux d’appareil IoT Hub.

Remarque

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.

Cet article explique comment développer deux types d’applications :

Les applications d’appareil peuvent gérer les demandes de mise à jour des propriétés souhaitées et répondre aux modifications apportées aux propriétés signalées.
Les applications de service peuvent mettre à jour des étiquettes de jumeau d’appareil, définir de nouvelles propriétés souhaitées et interroger des appareils en fonction des valeurs de jumeau d’appareil.

Remarque

Cet article est destiné à compléter les exemples de SDK Azure IoT référencés à partir de cet article. Vous pouvez utiliser des outils SDK pour créer des applications d’appareil et de back-end.

Prérequis

Un hub IoT. Certains appels du Kit de développement logiciel (SDK) nécessitent la chaîne de connexion principale d’IoT Hub : prenez donc note de la chaîne de connexion.
Un appareil inscrit. Certains appels du Kit de développement logiciel (SDK) nécessitent la chaîne de connexion principale de l’appareil : prenez donc note de la chaîne de connexion.
Si votre application utilise le protocole MQTT, assurez-vous que port 8883 est ouvert dans votre pare-feu. Le protocole MQTT communique sur 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).
Configuration requise du SDK de langage :
- .NET SDK – Nécessite Visual Studio.
- SDK Python - Python version 3.7 ou ultérieure est recommandé. Veillez à utiliser l’installation 32 bits ou 64 bits comme requis par votre programme d’installation. Lorsque vous y êtes invité pendant l’installation, veillez à ajouter Python à votre variable d’environnement propre à la plateforme.
- Java – Nécessite 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.
- Node.js – Nécessite Node.js version 10.0.x ou ultérieure.

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

Important

Cet article comprend les étapes à suivre pour connecter un appareil en utilisant une signature d’accès partagé, également appelée « authentification par clé symétrique ». Cette méthode d’authentification est pratique pour les tests et les évaluations, mais l’authentification d’un appareil en utilisant des certificats X.509 est une approche plus sécurisée. Pour plus d’informations, consultez Meilleures pratiques de sécurité > Sécurité des connexions.

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 :

Créez un objet TwinCollection pour la mise à jour de propriété signalée
Mettez à jour une ou plusieurs propriétés signalées dans l’objet TwinCollection
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 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 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

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.

Ajouter un package NuGet de service

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

Se connecter au hub IoT

Vous pouvez connecter un service back-end à IoT Hub à l’aide des méthodes suivantes :

Stratégie d’accès partagé
Microsoft Entra

Important

Cet article comprend les étapes à suivre pour se connecter à un service à l’aide d’une signature d’accès partagé. Cette méthode d’authentification est pratique pour les tests et les évaluations, mais l’authentification à un service avec Microsoft Entra ID ou des identités managées est une approche plus sécurisée. Pour plus d’informations, consultez Meilleures pratiques de sécurité > Sécurité du cloud.

Se connecter à l’aide d’une stratégie d’accès partagé

Connectez une application back-end à un appareil à l’aide de CreateFromConnectionString. Votre application 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. Il n’existe aucune stratégie d’accès partagé par défaut contenant uniquement ces deux autorisations. Vous devez donc en créer une s’il n’en existe pas déjà une. Fournissez cette chaîne de connexion de stratégie d’accès partagé en tant que paramètre pour fromConnectionString. Pour plus d’informations sur les stratégies d’accès partagé, consultez Contrôler l’accès à IoT Hub avec des signatures d’accès partagé.

using Microsoft.Azure.Devices;
static RegistryManager registryManager;
static string connectionString = "{Shared access policy connection string}";
registryManager = RegistryManager.CreateFromConnectionString(connectionString);

Se connecter à l’aide de Microsoft Entra

Une application back-end qui utilise Microsoft Entra doit s’authentifier et obtenir des informations d’identification de jeton de sécurité avant de se connecter à IoT Hub. Ce jeton est passé à une méthode de connexion IoT Hub. Pour obtenir des informations générales sur la configuration et l’utilisation de Microsoft Entra pour IoT Hub, consultez Contrôler l’accès à IoT Hub à l’aide de Microsoft Entra ID.

Configurer l’application Microsoft Entra

Vous devez configurer une application Microsoft Entra configurée pour vos informations d’identification d’authentification préférées. L’application contient des paramètres tels que la clé secrète client utilisée par l’application back-end pour s’authentifier. Les configurations d’authentification d’application disponibles sont les suivantes :

Clè secrète client
Certificat
Informations d’identification d’identité fédérée

Les applications Microsoft Entra peuvent nécessiter des autorisations de rôle spécifiques en fonction des opérations effectuées. Par exemple, le Contributeur de jumeaux IoT Hub est nécessaire pour activer l’accès en lecture et en écriture à un appareil IoT Hub et à des jumeaux de module. Pour plus d’informations, consultez Gérer l’accès à IoT Hub à l’aide de l’attribution de rôle RBAC Azure.

Pour plus d’informations concernant la configuration d’une application Microsoft Entra, consultez Démarrage rapide : inscrire une application auprès de la plateforme d’identités Microsoft.

S’authentifier à l’aide de DefaultAzureCredential

Le moyen le plus simple d’utiliser Microsoft Entra pour authentifier une application back-end consiste à utiliser DefaultAzureCredential. Cependant, nous vous recommandons d’utiliser une autre méthode dans un environnement de production, y compris un TokenCredential spécifique ou un ChainedTokenCredential simplifié. Par souci de simplicité, cette section décrit l’authentification à l’aide de DefaultAzureCredential et de la clé secrète client. Pour plus d’informations sur les avantages et les inconvénients de l’utilisation de DefaultAzureCredential, consultez Conseils d’utilisation pour DefaultAzureCredential.

DefaultAzureCredential prend en charge différents mécanismes d’authentification et détermine le type d’informations d’identification approprié en fonction de l’environnement dans lequel il s’exécute. Cette méthode tente d’utiliser plusieurs types d’informations d’identification dans un ordre jusqu’à ce qu’elle trouve des informations d’identification fonctionnelles.

Microsoft Entra nécessite ces packages NuGet et les instructions using correspondantes :

Azure.Core
Azure.Identity

using Azure.Core;
using Azure.Identity;

Dans cet exemple, la clé secrète client d’inscription de l’application Microsoft Entra, l’ID client et l’ID de locataire sont ajoutés aux variables d’environnement. Ces variables d’environnement sont utilisées par DefaultAzureCredential pour authentifier l’application. Le résultat d’une authentification Microsoft Entra réussie est une information d’identification de jeton de sécurité passée à une méthode de connexion IoT Hub.

string clientSecretValue = "xxxxxxxxxxxxxxx";
string clientID = "xxxxxxxxxxxxxx";
string tenantID = "xxxxxxxxxxxxx";

Environment.SetEnvironmentVariable("AZURE_CLIENT_SECRET", clientSecretValue);
Environment.SetEnvironmentVariable("AZURE_CLIENT_ID", clientID);
Environment.SetEnvironmentVariable("AZURE_TENANT_ID", tenantID);

TokenCredential tokenCredential = new DefaultAzureCredential();

Le TokenCredential résultant peut ensuite être passé pour se connecter à une méthode IoT Hub pour n’importe quel client du Kit de développement logiciel (SDK) qui accepte les informations d’identification Microsoft Entra :

Dans cet exemple, TokenCredential est passé à ServiceClient.Create pour créer un objet de connexion ServiceClient.

string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);

Dans cet exemple, TokenCredential est passé à RegistryManager.Create pour créer un objet RegistryManager.

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);

Exemple de code

Pour obtenir un exemple fonctionnel de l’authentification du service Microsoft Entra, consultez Exemple d’authentification basée sur les rôles.

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

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.

Important

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 :

Utilisez IotHubClientProtocol pour choisir un protocole de transport. Par exemple :
```
IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
```

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

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 :

Appelez getReportedProperties pour extraire les propriétés signalées du jumeau dans un objet TwinCollection.
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.
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);

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

Vous pouvez connecter un service back-end à IoT Hub à l’aide des méthodes suivantes :

Stratégie d’accès partagé
Microsoft Entra

Important

Se connecter à l’aide d’une stratégie d’accès partagé

Utilisez un constructeur DeviceTwin pour créer la connexion à IoT Hub. L’objet DeviceTwin gère la communication avec votre IoT Hub.

Votre application 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. Il n’existe aucune stratégie d’accès partagé par défaut contenant uniquement ces deux autorisations. Vous devez donc en créer une s’il n’en existe pas déjà une. Fournissez cette chaîne de connexion de stratégie d’accès partagé en tant que paramètre pour fromConnectionString. Pour plus d’informations sur les stratégies d’accès partagé, consultez Contrôler l’accès à IoT Hub avec des signatures d’accès partagé.

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 = "{Shared access policy 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
DeviceTwin twinClient = new DeviceTwin(iotHubConnectionString);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);

Se connecter à l’aide de Microsoft Entra

Pour obtenir une vue d’ensemble de l’authentification à l’aide du kit SDK Java, consultez Authentification Azure avec Java et Azure Identity.

Par souci de simplicité, cette section se concentre sur la description de l’authentification à l’aide d’une clé secrète client.

Configurer l’application Microsoft Entra

Clè secrète client
Certificat
Informations d’identification d’identité fédérée

Pour plus d’informations concernant la configuration d’une application Microsoft Entra, consultez Démarrage rapide : inscrire une application auprès de la plateforme d’identités Microsoft.

S’authentifier à l’aide de DefaultAzureCredential

Le moyen le plus simple d’utiliser Microsoft Entra pour authentifier une application back-end consiste à utiliser DefaultAzureCredential. Cependant, nous vous recommandons d’utiliser une autre méthode dans un environnement de production, y compris un TokenCredential spécifique ou un ChainedTokenCredential simplifié. Pour plus d’informations sur les avantages et les inconvénients de l’utilisation de DefaultAzureCredential, consultez Chaînes d’informations d’identification dans la bibliothèque de client Azure Identity pour Java.

DefaultAzureCredential prend en charge différents mécanismes d’authentification et détermine le type d’informations d’identification approprié en fonction de l’environnement dans lequel il s’exécute. Cette méthode tente d’utiliser plusieurs types d’informations d’identification dans un ordre jusqu’à ce qu’elle trouve des informations d’identification fonctionnelles.

Vous pouvez authentifier les informations d’identification de l’application Microsoft Entra en utilisant DefaultAzureCredentialBuilder. Enregistrez les paramètres de connexion tels que l’ID de locataire, l’ID client et les valeurs de la clé secrète client en tant que variables environnementales. Une fois TokenCredential créé, passez-le à ServiceClient ou à un autre générateur en tant que paramètre « credential ».

Dans cet exemple, DefaultAzureCredentialBuilder tente d’authentifier une connexion à partir de la liste décrite dans DefaultAzureCredential. Le résultat d’une authentification Microsoft Entra réussie est une information d’identification de jeton de sécurité passée à un constructeur tel que ServiceClient.

TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();

S’authentifier en utilisant ClientSecretCredentialBuilder

Vous pouvez utiliser ClientSecretCredentialBuilder pour créer des informations d’identification à l’aide des informations de la clé secrète client. Si cette méthode réussit, elle retourne un TokenCredential qui peut être passé à ServiceClient ou à un autre générateur en tant que paramètre « credential ».

Dans cet exemple, les valeurs de l’ID de locataire, de l’ID client et de la clé secrète client d’inscription de l’application Microsoft Entra ont été ajoutés aux variables d’environnement. Ces variables d’environnement sont utilisées par ClientSecretCredentialBuilder pour générer les informations d’identification.

string clientSecretValue = System.getenv("AZURE_CLIENT_SECRET");
string clientID = System.getenv("AZURE_CLIENT_ID");
string tenantID = System.getenv("AZURE_TENANT_ID");

TokenCredential credential =
     new ClientSecretCredentialBuilder()
          .tenantId(tenantID)
          .clientId(clientID)
          .clientSecret(clientSecretValue)
          .build();

Autres classes d’authentification

Le kit SDK Java inclut également ces classes qui authentifient une application back-end auprès de Microsoft Entra :

Exemples de code

Pour obtenir des exemples fonctionnels d’authentification auprès du service Microsoft Entra, consultez Exemple d’authentification basée sur les rôles.

Mise à jour des champs de jumeau d’appareil

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

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

Utilisez un objet HashSet pour add (ajouter) un groupe de paires d’étiquettes de jumeau
Utilisez setTags pour ajouter un groupe de paires d’étiquettes depuis un objet tags à un objet DeviceTwinDevice

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 :

Utilisez createSqlQuery pour générer la requête SQL de jumeaux
Utilisez queryTwin pour exécuter la requête
Utilisez hasNextDeviceTwin pour vérifier s’il existe un autre jumeau d’appareil dans le jeu de résultats
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

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

Important

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 :

Appelez create_from_connection_string pour ajouter la chaîne de connexion de l’appareil
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 :

Affectez un correctif JSON de propriété signalée à une variable.
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

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

Vous pouvez connecter un service back-end à IoT Hub à l’aide des méthodes suivantes :

Stratégie d’accès partagé
Microsoft Entra

Important

Se connecter à l’aide d’une stratégie d’accès partagé

Connectez-vous à IoT Hub à l’aide de fromConnectionString. Votre application 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. Il n’existe aucune stratégie d’accès partagé par défaut contenant uniquement ces deux autorisations. Vous devez donc en créer une s’il n’en existe pas déjà une. Fournissez cette chaîne de connexion de stratégie d’accès partagé en tant que paramètre pour fromConnectionString. Pour plus d’informations sur les stratégies d’accès partagé, consultez Contrôler l’accès à IoT Hub avec des signatures d’accès partagé.

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)

Se connecter à l’aide de Microsoft Entra

Pour obtenir une vue d’ensemble de l’authentification à l’aide du kit SDK Python, consultez Authentifier des applications Python auprès des services Azure à l’aide du Kit de développement logiciel (SDK) Azure pour Python

Configurer l’application Microsoft Entra

Clè secrète client
Certificat
Informations d’identification d’identité fédérée

Pour plus d’informations concernant la configuration d’une application Microsoft Entra, consultez Démarrage rapide : inscrire une application auprès de la plateforme d’identités Microsoft.

S’authentifier à l’aide de DefaultAzureCredential

Le moyen le plus simple d’utiliser Microsoft Entra pour authentifier une application back-end consiste à utiliser DefaultAzureCredential. Cependant, nous vous recommandons d’utiliser une autre méthode dans un environnement de production, y compris un TokenCredential spécifique ou un ChainedTokenCredential simplifié. Par souci de simplicité, cette section décrit l’authentification à l’aide de DefaultAzureCredential et de la clé secrète client. Pour plus d’informations sur les avantages et les inconvénients de l’utilisation de DefaultAzureCredential, consultez Chaînes d’informations d’identification dans la bibliothèque de client Azure Identity pour Python.

Microsoft Entra nécessite ce package d’importation et l’instruction import correspondante :

pip install azure-identity

from azure.identity import DefaultAzureCredential

Dans cet exemple, l’ID de locataire, l’ID client et la clé secrète client d’inscription de l’application Microsoft Entra ont été ajoutés aux variables d’environnement. Ces variables d’environnement sont utilisées par DefaultAzureCredential pour authentifier l’application. Le résultat d’une authentification Microsoft Entra réussie est une information d’identification de jeton de sécurité passée à une méthode de connexion IoT Hub.

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

Le jeton AccessToken résultant peut ensuite être passé à from_token_credential pour se connecter à IoT Hub pour n’importe quel client du kit SDK qui accepte les informations d’identification Microsoft Entra :

IoTHubRegistryManager pour créer une connexion de service à IoT Hub à l’aide d’informations d’identification de jeton Entra.
IoTHubJobManager
DigitalTwinClient
IoTHubHttpRuntimeManager
IoTHubConfigurationManager

from_token_credential nécessite deux paramètres :

URL du service Azure : l’URL du service Azure doit être au format {Your Entra domain URL}.azure-devices.net sans préfixe https://. Par exemple : MyAzureDomain.azure-devices.net.
Jeton d’informations d’identification Azure

Dans cet exemple, les informations d’identification Azure sont obtenues en utilisant DefaultAzureCredential. L’URL et les informations d’identification du service Azure sont ensuite fournies à IoTHubRegistryManager.from_token_credential pour créer la connexion à IoT Hub.

import sys
import os

from azure.identity import DefaultAzureCredential
from azure.iot.hub import IoTHubRegistryManager

# Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

# Set environment variables
os.environ['AZURE_CLIENT_SECRET'] = clientSecretValue
os.environ['AZURE_CLIENT_ID'] = clientID
os.environ['AZURE_TENANT_ID'] = tenantID

# Acquire a credential object
credential = DefaultAzureCredential()

# Use Entra to authorize IoT Hub service
print("Connecting to IoTHubRegistryManager...")
iothub_registry_manager = IoTHubRegistryManager.from_token_credential(
url="MyAzureDomain.azure-devices.net",
token_credential=credential)

Exemples de code

Pour obtenir des exemples d’authentification du service Microsoft Entra, consultez Bibliothèque d’authentification Microsoft (MSAL) pour Python.

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.

Appelez get_twin pour obtenir la version actuelle du jumeau d’appareil
Utilisez la classe Twin pour ajouter des balises et des propriétés au format JSON.
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 :

Utilisez un objet QuerySpecification pour définir une requête de type SQL.
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

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

Important

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 :

Les propriétés minTemperature et maxTemperature se trouvent sous un regroupement de propriétés nommé properties.desired.climate changes.
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, },
    },
  },
 };
```
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.

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

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

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 :

Créer une application back-end

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

Vous pouvez connecter un service back-end à IoT Hub à l’aide des méthodes suivantes :

Stratégie d’accès partagé
Microsoft Entra

Important

Se connecter à l’aide d’une stratégie d’accès partagé

Utilisez fromConnectionString pour vous connecter au hub IoT Hub. Votre application 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. Il n’existe aucune stratégie d’accès partagé par défaut contenant uniquement ces deux autorisations. Vous devez donc en créer une s’il n’en existe pas déjà une. Fournissez cette chaîne de connexion de stratégie d’accès partagé en tant que paramètre pour fromConnectionString. Pour plus d’informations sur les stratégies d’accès partagé, consultez Contrôler l’accès à IoT Hub avec des signatures d’accès partagé.

'use strict';
var iothub = require('azure-iothub');
var connectionString = '{Shared access policy connection string}';
var registry = iothub.Registry.fromConnectionString(connectionString);

Se connecter à l’aide de Microsoft Entra

Pour obtenir une vue d’ensemble de l’authentification à l’aide du kit SDK Node.js, consultez :

Configurer l’application Microsoft Entra

Clè secrète client
Certificat
Informations d’identification d’identité fédérée

Pour plus d’informations concernant la configuration d’une application Microsoft Entra, consultez Démarrage rapide : inscrire une application auprès de la plateforme d’identités Microsoft.

S’authentifier à l’aide de DefaultAzureCredential

Le moyen le plus simple d’utiliser Microsoft Entra pour authentifier une application back-end consiste à utiliser DefaultAzureCredential. Cependant, nous vous recommandons d’utiliser une autre méthode dans un environnement de production, y compris un TokenCredential spécifique ou un ChainedTokenCredential simplifié. Par souci de simplicité, cette section décrit l’authentification à l’aide de DefaultAzureCredential et de la clé secrète client. Pour plus d’informations sur les avantages et les inconvénients de l’utilisation de DefaultAzureCredential, consultez Chaînes d’informations d’identification dans la bibliothèque de client Azure Identity pour JavaScript.

Microsoft Entra nécessite ce package :

npm install --save @azure/identity

import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

Le jeton d’informations d’identification résultant peut ensuite être passé à fromTokenCredential pour se connecter à IoT Hub pour n’importe quel client du kit SDK qui accepte les informations d’identification Microsoft Entra :

fromTokenCredential nécessite deux paramètres :

URL du service Azure : l’URL du service Azure doit être au format {Your Entra domain URL}.azure-devices.net sans préfixe https://. Par exemple : MyAzureDomain.azure-devices.net.
Jeton d’informations d’identification Azure

Dans cet exemple, les informations d’identification Azure sont obtenues en utilisant DefaultAzureCredential. L’URL et les informations d’identification du domaine Azure sont ensuite fournies à Registry.fromTokenCredential pour créer la connexion à IoT Hub.

const { DefaultAzureCredential } = require("@azure/identity");

let Registry = require('azure-iothub').Registry;

// Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

// Set environment variables
process.env['AZURE_CLIENT_SECRET'] = clientSecretValue;
process.env['AZURE_CLIENT_ID'] = clientID;
process.env['AZURE_TENANT_ID'] = tenantID;

// Acquire a credential object
const credential = new DefaultAzureCredential()

// Create an instance of the IoTHub registry
hostName = 'MyAzureDomain.azure-devices.net';
let registry = Registry.fromTokenCredential(hostName,credential);

Exemples de code

Pour obtenir des exemples fonctionnels d’authentification auprès du service Microsoft Entra, consultez Exemples d’identité Azure.

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 :

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.

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.

Partager via

Prise en main des représentations d’appareils

Prérequis

Vue d’ensemble

Créer une application d’appareil

Ajouter un package NuGet d’appareil

Connexion à un appareil

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

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

Exemple d’appareil SDK

Créer une application back-end

Ajouter un package NuGet de service

Se connecter au hub IoT

Se connecter à l’aide d’une stratégie d’accès partagé

Se connecter à l’aide de Microsoft Entra

Configurer l’application Microsoft Entra

S’authentifier à l’aide de DefaultAzureCredential

Exemple de code

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

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

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

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

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

Autres méthodes de mise à jour de jumeau

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

Exemple de service de SDK

Vue d’ensemble

Créer une application d’appareil

Instructions d’importation d’appareil

Se connecter à l’appareil

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

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

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

Exemple d’appareil SDK

Créer une application back-end

Instructions d’importation de service

Se connecter au hub IoT

Se connecter à l’aide d’une stratégie d’accès partagé

Se connecter à l’aide de Microsoft Entra

Configurer l’application Microsoft Entra

S’authentifier à l’aide de DefaultAzureCredential

S’authentifier en utilisant ClientSecretCredentialBuilder

Autres classes d’authentification

Exemples de code

Mise à jour des champs de jumeau d’appareil

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

Exemple de service de SDK

Vue d’ensemble

Créer une application d’appareil

Connexion à un appareil

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

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

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

Exemples d’appareils SDK

Créer une application back-end

Se connecter au hub IoT

Se connecter à l’aide d’une stratégie d’accès partagé

Se connecter à l’aide de Microsoft Entra

Configurer l’application Microsoft Entra

S’authentifier à l’aide de DefaultAzureCredential

Exemples de code

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

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

Exemple de service de SDK

Vue d’ensemble

Créer une application d’appareil

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

Choisir un protocole de transport

Créer un module client

Créer un module de protocole

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

Ouvrir la connexion à IoT Hub

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

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

Exemples pour le SDK d’appareils