Prise en main des représentations d’appareils (.NET)

  • Article

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

Notes

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

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

  • Stockez les métadonnées d’appareil à partir de votre serveur principal de solution.

  • Signaler les informations d’état actuel, telles que les capacités disponibles et les conditions, par exemple la méthode de connectivité utilisée, à partir de votre application d’appareil

  • Synchronisez l’état des workflows de longue durée, par exemple les mises à jour de microprogramme et de configuration, entre une application d’appareil et une application back-end.

  • Interroger les métadonnées, la configuration ou l’état de vos appareils

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

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

  • Tags (balises). Métadonnées d’appareil uniquement accessibles par le back-end de solution.

  • Propriétés souhaitées (Desired) . Objets JSON modifiables par le back-end de solution et observables par l’application d’appareil.

  • Propriétés signalées (Reported) . Objets JSON modifiables par l’application d’appareil et consultables par le back-end de solution.

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

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

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

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

Cet article vous montre comment :

  • Utilisez une application d’appareil simulé pour signaler son canal de connectivité en tant que propriété signalée sur le jumeau d’appareil.

  • Interrogez les appareils à partir de votre application principale à l’aide de filtres sur les étiquettes et les propriétés précédemment créées.

Dans cet article, vous allez créer deux applications console .NET :

  • AddTagsAndQuery : une application back-end qui ajoute des balises et interroge les jumeaux d’appareils.

  • ReportConnectivity : une application d’appareil simulé qui se connecte à votre hub IoT et signale son état de connectivité.

Notes

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

Prérequis

  • Visual Studio.

  • Un IoT Hub. Créez-en un avec l’interface CLI ou le portail Azure.

  • Appareil inscrit. Inscrivez-en un dans le portail Azure.

  • Vérifiez que le port 8883 est ouvert dans votre pare-feu. L’exemple d’appareil décrit dans cet article utilise le protocole MQTT, qui communique via le port 8883. Ce port peut être bloqué dans certains environnements réseau professionnels et scolaires. Pour plus d’informations sur les différentes façons de contourner ce problème, consultez Connexion à IoT Hub (MQTT).

Obtenir la chaîne de connexion du hub IoT

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

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

  1. Dans le portail Azure, sélectionnez Groupes de ressources. Sélectionnez le groupe de ressources dans lequel se trouve votre hub, puis sélectionnez votre hub dans la liste des ressources.

  2. Dans le volet de gauche de votre hub, sélectionnez Stratégies d’accès partagé.

  3. Dans le menu supérieur au-dessus de la liste des stratégies, sélectionnez Ajouter une stratégie de politiques d’accès partagé.

  4. Sous Ajouter une stratégie de politiques d’accès partagé, entrez un nom descriptif pour votre stratégie, par exemple serviceAndRegistryRead. Sous Autorisations, sélectionnez Lecture du registre et Connexion du service, puis sélectionnez Ajouter.

    Capture d’écran qui montre comment ajouter une nouvelle politique d’accès partagé.

  5. Sélectionnez votre nouvelle stratégie dans la liste des stratégies.

  6. Sélectionnez l’icône de copie pour la Chaîne de connexion principale et enregistrez la valeur.

    Capture d’écran qui montre comment récupérer la chaîne de connexion.

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

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

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

  1. Ouvrez Visual Studio et sélectionnez Créer un projet.

  2. Choisissez Application console (.NET Framework), puis sélectionnez Suivant.

  3. Dans Configurer votre nouveau projet, nommez le projet ReportConnectivity, puis sélectionnez Suivant.

  4. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet ReportConnectivity, puis sélectionnez Gérer les packages NuGet.

  5. Conservez la version par défaut de .NET Framework, puis sélectionnez Créer pour créer le projet.

  6. Sélectionnez Parcourir, puis recherchez et choisissez Microsoft.Azure.Devices.Client. Sélectionnez Installer.

    Cette étape télécharge, installe et ajoute une référence au package NuGet Azure IoT device SDK et à ses dépendances.

  7. Ajoutez les instructions using suivantes en haut du fichier Program.cs :

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

  8. Ajoutez les champs suivants à la classe Program . Remplacez {device connection string} par la chaîne de connexion de l’appareil que vous avez vu au moment de l’inscription d’un appareil dans IoT Hub :

    static string DeviceConnectionString = "HostName=<yourIotHubName>.azure-devices.net;DeviceId=<yourIotDeviceName>;SharedAccessKey=<yourIotDeviceAccessKey>";
static DeviceClient Client = null;

  9. Ajoutez la méthode suivante à la classe Program :

    public static async void InitClient()
{
    try
    {
        Console.WriteLine("Connecting to hub");
        Client = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
          TransportType.Mqtt);
        Console.WriteLine("Retrieving twin");
        await Client.GetTwinAsync();
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
    }
}

    L’objet Client expose toutes les méthodes requises pour interagir avec des jumeaux d’appareil à partir de l’appareil. Le code présenté ci-dessus initialise l’objet Client, puis récupère le jumeau d’appareil pour myDeviceId.

  10. Ajoutez la méthode suivante à la classe Program :

    public static async void ReportConnectivity()
{
    try
    {
        Console.WriteLine("Sending connectivity data as reported property");

        TwinCollection reportedProperties, connectivity;
        reportedProperties = new TwinCollection();
        connectivity = new TwinCollection();
        connectivity["type"] = "cellular";
        reportedProperties["connectivity"] = connectivity;
        await Client.UpdateReportedPropertiesAsync(reportedProperties);
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
    }
}

    Le code ci-dessus met à jour la propriété signalée de myDeviceId avec les informations de connectivité.

  11. Enfin, ajoutez les lignes suivantes à la méthode Main :

    try
{
    InitClient();
    ReportConnectivity();
}
catch (Exception ex)
{
    Console.WriteLine();
    Console.WriteLine("Error in sample: {0}", ex.Message);
}
Console.WriteLine("Press Enter to exit.");
Console.ReadLine();

  12. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur votre solution, puis sélectionnez Définir les projets de démarrage.

  13. Dans Propriétés communes>Projet de démarrage, sélectionnez Plusieurs projets de démarrage. Pour ReportConnectivity,sélectionnez Démarrer comme Action. Sélectionnez OK pour enregistrer vos modifications.

  14. Exécutez cette application en cliquant avec le bouton droit sur le projet ReportConnectivity et en sélectionnant Déboguer, puis Démarrer une nouvelle instance. Vous devez voir l’application obtenir les informations relatives au jumeau puis envoyer la connectivité sous la forme d’une propriété signalée.

    Exécuter l’application pour appareil pour signaler la connectivité

    Une fois que l’appareil a signalé ses informations de connectivité, il doit apparaître dans les deux requêtes.

  15. Cliquez avec le bouton droit sur le projet AddTagsAndQuery, puis sélectionnez Déboguer>Démarrer une nouvelle instance pour réexécuter les requêtes. Cette fois, myDeviceId doit apparaître dans les résultats des deux requêtes.

    Connectivité des appareils signalée avec succès

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

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

  1. Dans Visual Studio, sélectionnez Fichier > Nouveau > Projet. Sous Créer un projet, sélectionnez Application console (.NET Framework) , puis cliquez sur Suivant.

  2. Dans Configurer votre nouveau projet, nommez le projet AddTagsAndQuery, puis sélectionnez Suivant.

    Capture d’écran montrant comment créer un projet Visual Studio.

  3. Acceptez la version par défaut de .NET Framework, puis sélectionnez Créer pour créer le projet.

  4. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet AddTagsAndQuery, puis sélectionnez Gérer les packages NuGet.

  5. Sélectionnez Parcourir, puis recherchez et sélectionnez Microsoft.Azure.Devices. Sélectionnez Installer.

    Fenêtre du gestionnaire de package NuGet

    Cette étape lance le téléchargement et l’installation et ajoute une référence au package Azure IoT Service SDK NuGet et ses dépendances.

  6. Ajoutez les instructions using suivantes en haut du fichier Program.cs :

    using Microsoft.Azure.Devices;

  7. Ajoutez les champs suivants à la classe Program . Remplacez {iot hub connection string} par la chaîne de connexion IoT Hub que vous avez copiée dans Obtenir la chaîne de connexion du hub IoT.

    static RegistryManager registryManager;
static string connectionString = "{iot hub connection string}";

  8. Ajoutez la méthode suivante à la classe Program :

    public static async Task AddTagsAndQuery()
{
    var twin = await registryManager.GetTwinAsync("myDeviceId");
    var patch =
        @"{
            tags: {
                location: {
                    region: 'US',
                    plant: 'Redmond43'
                }
            }
        }";
    await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);

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

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

    La classe RegistryManager expose toutes les méthodes requises pour interagir avec des jumeaux d’appareil à partir du service. Le code précédent initialise l’objet registryManager, récupère le jumeau d’appareil de myDeviceId, puis met à jour ses balises avec les informations d’emplacement souhaitées.

    Après la mise à jour, il 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 via un réseau cellulaire.

    Quand il crée l’objet query, le code précédent spécifie un nombre maximal de documents retournés. L’objet query contient une propriété booléenne HasMoreResults permettant d’appeler les méthodes GetNextAsTwinAsync plusieurs fois afin de récupérer tous les résultats. Une méthode appelée GetNextAsJson 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.

  9. Enfin, ajoutez les lignes suivantes à la méthode Main :

    registryManager = RegistryManager.CreateFromConnectionString(connectionString);
AddTagsAndQuery().Wait();
Console.WriteLine("Press Enter to exit.");
Console.ReadLine();

  10. Exécutez cette application en cliquant avec le bouton droit sur le projet AddTagsAndQuery et en sélectionnant Déboguer, puis Démarrer une nouvelle instance. Vous devriez voir un appareil dans les résultats de la requête demandant tous les appareils situés à Redmond43, et aucun pour la requête limitant les résultats aux appareils utilisant un réseau cellulaire.

    Résultats de requête dans la fenêtre

Dans cet article, vous découvrirez comment :

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

Étapes suivantes

Pour découvrir comment :