Planifier et diffuser des travaux (.NET)

Article
10/01/2024

Utilisez Azure IoT Hub pour planifier et suivre des travaux qui mettent à jour des millions d’appareils. Utilisez les travaux pour :

Mettre à jour les propriétés souhaitées
Mettre à jour les balises
Appeler des méthodes directes

Un travail encapsule l’une de ces actions et suit l’exécution sur un ensemble d’appareils, défini par une requête de jumeau d’appareil. Par exemple, une application principale peut utiliser un travail pour appeler une méthode directe sur 10 000 appareils et les redémarrer. Vous spécifiez l’ensemble des appareils avec une requête de jumeau d’appareil et planifiez le travail à exécuter ultérieurement. Le travail suit la progression à mesure que chacun de ces appareils reçoit et exécute la méthode directe de redémarrage.

Pour plus d’informations sur chacune de ces fonctionnalités, consultez les pages :

Jumeau d’appareil et propriétés : Prise en main des représentations d’appareils (Node) et Comprendre et utiliser les jumeaux d’appareil IoT Hub
Méthodes directes : Guide du développeur IoT Hub - méthodes directes

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.

Cet article explique comment créer deux applications console .NET (C#) :

Une application pour appareils, SimulateDeviceMethods, implémentant une méthode directe nommée LockDoor, qui peut être appelée par l’application back-end.
Une application back-end, ScheduleJob, qui crée deux travaux. Un travail appelle la méthode directe lockDoor et un autre travail envoie les mises à jour de propriété souhaitées à plusieurs appareils.

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 hub IoT dans votre abonnement Azure. Si vous n’avez pas encore de hub, vous pouvez suivre les étapes décrites dans Créer un hub IoT.
Un appareil inscrit dans votre hub IoT. Si vous n’avez pas d’appareil dans votre hub IoT, suivez les étapes décrites dans Inscrire un appareil.
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).

Création d’une application de périphérique simulé

Dans cette section, vous allez créer une application console .NET qui répond à une méthode directe appelée par le serveur principal de la solution.

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.

Dans Visual Studio, sélectionnez Créer un nouveau projet, puis choisissez le modèle de projet Application console (.NET Framework) . Sélectionnez Suivant pour continuer.
Dans Configurer votre nouveau projet, nommez le projet SimulateDeviceMethods, puis sélectionnez Suivant.
Acceptez la version par défaut de .NET Framework, puis sélectionnez Créer pour créer le projet.
Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet SimulateDeviceMethods, puis sélectionnez Gérer les packages NuGet.
Dans Gestionnaire de package NuGet, 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.

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

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;
using Newtonsoft.Json;
using System.Threading.Tasks;
using System.Text;

Ajoutez les champs suivants à la classe Program . Remplacez la valeur d’espace réservé par la chaîne de connexion de l’appareil que vous avez notée dans la section précédente :
```
static string DeviceConnectionString = "<yourDeviceConnectionString>";
static DeviceClient Client = null;
```

Ajoutez le code suivant pour implémenter la méthode directe sur l’appareil :

static Task<MethodResponse> LockDoor(MethodRequest methodRequest, object userContext)
{
    Console.WriteLine();
    Console.WriteLine("Locking Door!");
    Console.WriteLine("\nReturning response for method {0}", methodRequest.Name);

    string result = "'Door was locked.'";
    return Task.FromResult(new MethodResponse(Encoding.UTF8.GetBytes(result), 200));
}

Ajoutez la méthode suivante pour implémenter l’écouteur des jumeaux d’appareils sur l’appareil :

private static async Task OnDesiredPropertyChanged(TwinCollection desiredProperties, 
  object userContext)
{
    Console.WriteLine("Desired property change:");
    Console.WriteLine(JsonConvert.SerializeObject(desiredProperties));
}

Enfin, ajoutez le code suivant à la méthode Main pour ouvrir la connexion à votre IoT Hub et initialiser l’écouteur de la méthode :

try
{
    Console.WriteLine("Connecting to hub");
    Client = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
      TransportType.Mqtt);

    Client.SetMethodHandlerAsync("LockDoor", LockDoor, null);
    Client.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChanged, null);

    Console.WriteLine("Waiting for direct method call and device twin update\n Press enter to exit.");
    Console.ReadLine();

    Console.WriteLine("Exiting...");

    Client.SetMethodHandlerAsync("LockDoor", null, null);
    Client.CloseAsync().Wait();
}
catch (Exception ex)
{
    Console.WriteLine();
    Console.WriteLine("Error in sample: {0}", ex.Message);
}

Enregistrez votre travail et générez votre solution.

Notes

Pour simplifier les choses, cet article n’implémente aucune stratégie de nouvelles tentatives. Dans le code de production, vous devez implémenter des stratégies de nouvelle tentative (par exemple, une nouvelle tentative de connexion), comme suggéré dans Gestion des erreurs temporaires.

Obtenir la chaîne de connexion du hub IoT

Dans cet article, vous créez un service back-end qui planifie une tâche pour appeler une méthode directe sur un appareil, planifie une tâche pour mettre à jour le jumeau d’appareil, et supervise l’avancement de chaque tâche. Pour effectuer ces opérations, votre service requiert les autorisations de lecture du registre et d’écriture du registre. Par défaut, chaque hub IoT est créé avec une stratégie d’accès partagé nommée registryReadWrite qui accorde ces autorisations.

Pour obtenir la chaîne de connexion IoT Hub pour la stratégie registryReadWrite, procédez comme suit :

Dans le portail Azure, sélectionnez Groupes de ressources. Sélectionnez le groupe de ressources dans lequel se trouve votre hub, puis sélectionnez votre hub dans la liste des ressources.
Dans le volet de gauche de votre hub, sélectionnez Stratégies d’accès partagé.
Dans la liste des stratégies, sélectionnez la stratégie registryReadWrite.
Copiez la Chaîne de connexion principale, puis enregistrez la valeur.

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

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.

Planifier des travaux pour appeler une méthode directe et envoyer des mises à jour de jumeaux d’appareils

Dans cette section, vous allez créer une application console .NET (en C#) qui utilise des travaux pour appeler la méthode directe LockDoor et envoyer les mises à jour des propriétés souhaitées à plusieurs appareils.

Dans Visual Studio, sélectionnez Fichier>Nouveau>Projet. Sous Créer un projet, choisissez Application console (.NET Framework) , puis cliquez sur Suivant.
Dans Configurer votre nouveau projet, nommez le projet ScheduleJob, puis sélectionnez Créer.
Acceptez la version par défaut de .NET Framework, puis sélectionnez Créer pour créer le projet.
Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet ScheduleJob, puis sélectionnez Gérer les packages NuGet.
Dans le Gestionnaire de package NuGet, sélectionnez Parcourir, recherchez et choisissez Microsoft.Azure.Devices, puis sélectionnez Installer.

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.

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

using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Shared;

Ajoutez l’instruction using suivante si elle ne figure pas déjà dans les instructions par défaut.
```
using System.Threading;
using System.Threading.Tasks;
```
Ajoutez les champs suivants à la classe Program . Remplacez les espaces réservés par la chaîne de connexion de l’IoT Hub que vous avez précédemment copiée dans Obtention de la chaîne de connexion de l’IoT Hub, puis nommez votre appareil.
```
static JobClient jobClient;
static string connString = "<yourIotHubConnectionString>";
static string deviceId = "<yourDeviceId>";
```

Ajoutez la méthode suivante à la classe Program :

public static async Task MonitorJob(string jobId)
{
    JobResponse result;
    do
    {
        result = await jobClient.GetJobAsync(jobId);
        Console.WriteLine("Job Status : " + result.Status.ToString());
        Thread.Sleep(2000);
    } while ((result.Status != JobStatus.Completed) && 
      (result.Status != JobStatus.Failed));
}

Ajoutez la méthode suivante à la classe Program :

public static async Task StartMethodJob(string jobId)
{
    CloudToDeviceMethod directMethod = 
      new CloudToDeviceMethod("LockDoor", TimeSpan.FromSeconds(5), 
      TimeSpan.FromSeconds(5));

    JobResponse result = await jobClient.ScheduleDeviceMethodAsync(jobId,
        $"DeviceId IN ['{deviceId}']",
        directMethod,
        DateTime.UtcNow,
        (long)TimeSpan.FromMinutes(2).TotalSeconds);

    Console.WriteLine("Started Method Job");
}

Ajoutez une autre méthode à la classe Program :

public static async Task StartTwinUpdateJob(string jobId)
{
    Twin twin = new Twin(deviceId);
    twin.Tags = new TwinCollection();
    twin.Tags["Building"] = "43";
    twin.Tags["Floor"] = "3";
    twin.ETag = "*";

    twin.Properties.Desired["LocationUpdate"] = DateTime.UtcNow;

    JobResponse createJobResponse = jobClient.ScheduleTwinUpdateAsync(
        jobId,
        $"DeviceId IN ['{deviceId}']", 
        twin, 
        DateTime.UtcNow, 
        (long)TimeSpan.FromMinutes(2).TotalSeconds).Result;

    Console.WriteLine("Started Twin Update Job");
}

Notes

Pour plus d’informations sur la syntaxe de requête, consultez l’article Langage de requête IoT Hub.

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

Console.WriteLine("Press ENTER to start running jobs.");
Console.ReadLine();

jobClient = JobClient.CreateFromConnectionString(connString);

string methodJobId = Guid.NewGuid().ToString();

StartMethodJob(methodJobId);
MonitorJob(methodJobId).Wait();
Console.WriteLine("Press ENTER to run the next job.");
Console.ReadLine();

string twinUpdateJobId = Guid.NewGuid().ToString();

StartTwinUpdateJob(twinUpdateJobId);
MonitorJob(twinUpdateJobId).Wait();
Console.WriteLine("Press ENTER to exit.");
Console.ReadLine();

Enregistrez votre travail et générez votre solution.

Exécuter les applications

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

Dans l’Explorateur de solutions de Visual Studio, cliquez avec le bouton droit sur votre solution, puis sélectionnez Définir les projets de démarrage.
Sélectionnez Propriétés communes>Projet de démarrage, puis sélectionnez Plusieurs projets de démarrage.
Assurez-vous que SimulateDeviceMethods figure en haut de la liste, suivi de ScheduleJob. Définissez leurs deux actions sur Démarrer, puis sélectionnez OK.
Exécutez les projets en cliquant sur Démarrer ou accédez au menu Déboguer et cliquez sur Démarrer le débogage.

La sortie de l’appareil et des applications principales s’affiche.

Étapes suivantes

Dans cet article, vous avez planifié des travaux pour exécuter une méthode directe et mettre à jour les propriétés du jumeau d’appareil.

Pour continuer à explorer le hub IoT et les modèles de gestion des appareils, mettez à jour une image dans le Tutoriel sur le service Device Update pour IoT Hub : Utilisation de l’image de référence Raspberry Pi 3 B+.

Partager via

Planifier et diffuser des travaux (.NET)

Prérequis

Création d’une application de périphérique simulé

Obtenir la chaîne de connexion du hub IoT

Planifier des travaux pour appeler une méthode directe et envoyer des mises à jour de jumeaux d’appareils

Exécuter les applications

Étapes suivantes

Commentaires

Ressources supplémentaires