Partager via

Comment planifier et diffuser des travaux

Cet article explique comment créer du code d’application back-end pour planifier et diffuser des travaux.

Utilisez Azure IoT Hub pour planifier et suivre les tâches qui mettent à jour jusqu'à des millions d'appareils pour ces opérations :

  • Appeler des méthodes directes
  • Mise à jour des jumeaux d’appareil

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. La tâche surveille 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 :

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.

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

  • Un appareil inscrit

  • 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).

  • Nécessite Visual Studio

Vue d’ensemble

Cet article explique comment utiliser la Kit de développement logiciel (SDK) Azure IoT pour .NET pour créer du code d’application de service principal vers une tâche de planification pour appeler une méthode directe ou effectuer une mise à jour de jumeau d’appareil sur un ou plusieurs appareils.

Ajouter un package NuGet de service

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

Utilisation d’instructions

Ajoutez les instructions using suivantes.

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

using System.Threading;
using System.Threading.Tasks;

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.

Cet article décrit le code principal qui peut planifier une tâche pour appeler une méthode directe, planifier une tâche pour mettre à jour un jumeau d’appareil et surveiller la progression d’une tâche pour un ou plusieurs appareils. 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 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é.

static JobClient jobClient;
static string connectionString = "{Shared access policy connection string}";
jobClient = JobClient.CreateFromConnectionString(connString);

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.

Planifier une tâche de méthode directe

Utilisez ScheduleDeviceMethodAsync pour planifier une tâche pour exécuter une méthode directe sur un ou plusieurs appareils.

Utilisez l’objet CloudToDeviceMethod pour spécifier les valeurs de délai d’attente de la méthode directe et de connexion de l’appareil.

Par exemple :

// The CloudToDeviceMethod record specifies the direct method name and device connection time-out
CloudToDeviceMethod directMethod = 
new CloudToDeviceMethod("LockDoor", TimeSpan.FromSeconds(5), 
TimeSpan.FromSeconds(5));

Cet exemple planifie une tâche pour une méthode directe nommée « LockDoor » sur un appareil nommé « Device-1 ». Les appareils inclus dans la tâche planifié sont contenus deuxième paramètre en tant que condition de requête. Pour plus d'informations sur les conditions d'interrogation, voir le langage d'interrogation d'IoT Hub pour les jumeaux d'appareils et de modules, les tâches et l'acheminement des messages.

string methodJobId = Guid.NewGuid().ToString();  // a unique job ID
static string deviceId = "Device-1";             // In this example, there is only one device affected
JobResponse result = await jobClient.ScheduleDeviceMethodAsync(methodJobId,
   $"DeviceId IN ['{deviceId}']",
   directMethod,
   DateTime.UtcNow,
   (long)TimeSpan.FromMinutes(2).TotalSeconds);

Planifier une tâche de mise à jour de jumeau d’appareil

Utilisez ScheduleTwinUpdateAsync pour planifier une nouvelle tâche de mise à jour des propriétés et balises de jumeau d’appareil pour s’exécuter sur un ou plusieurs appareils.

Tout d’abord, créez et remplissez un appareil objet Twin pour la mise à jour. Par exemple :

static string deviceId = "Device-1";

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;

Ensuite, appelez ScheduleTwinUpdateAsync. Spécifiez les appareils à mettre à jour en tant que requête dans le deuxième paramètre. Pour plus d'informations sur les conditions d'interrogation, voir le langage d'interrogation d'IoT Hub pour les jumeaux d'appareils et de modules, les tâches et l'acheminement des messages.

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

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

Surveiller un travail

Utilisez GetJobAsync pour surveiller le statut de la tâche pour obtenir un ID de tâche spécifique.

Cet exemple vérifie régulièrement le statut de la tâche d’un ID de tâche jusqu’à ce que le statut de la tâche soit terminé ou échoué. Par exemple :

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

Exemples de travaux de planification du Kit de développement logiciel (SDK)

Le Kit de développement logiciel (SDK) Azure IoT pour .NET fournit des exemples de tâche d’applications de service qui gèrent les tâches de planification de tâche. Pour plus d’informations, consultez l’article suivant :

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

Vue d’ensemble

Cet article explique comment utiliser la Kit de développement logiciel (SDK) Azure IoT pour Java pour créer du code d’application de service principal vers une tâche de planification pour appeler une méthode directe ou effectuer une mise à jour de jumeau d’appareil sur un ou plusieurs appareils.

Instructions d’importation de service

La classe JobClient contient des méthodes que les services peuvent utiliser pour planifier des travaux.

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.DeviceTwinDevice;
import com.microsoft.azure.sdk.iot.service.devicetwin.Pair;
import com.microsoft.azure.sdk.iot.service.devicetwin.Query;
import com.microsoft.azure.sdk.iot.service.devicetwin.SqlQuery;
import com.microsoft.azure.sdk.iot.service.jobs.JobClient;
import com.microsoft.azure.sdk.iot.service.jobs.JobResult;
import com.microsoft.azure.sdk.iot.service.jobs.JobStatus;

import java.util.Date;
import java.time.Instant;
import java.util.HashSet;
import java.util.Set;
import java.util.UUID;

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é

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

Cet article décrit le code principal qui peut planifier une tâche pour appeler une méthode directe, planifier une tâche pour mettre à jour un jumeau d’appareil et surveiller la progression d’une tâche pour un ou plusieurs appareils. 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 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 :

public static final String iotHubConnectionString = "{Shared access policy connection string}";
JobClient jobClient = new JobClient(iotHubConnectionString);

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.

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

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

Programmer une tâche de mise à jour de la méthode directe

Utilisez scheduleDeviceMethod pour exécuter une méthode directe sur un ou plusieurs appareils.

Cet exemple de méthode planifie une tâche pour une méthode directe nommée « lockDoor » sur un appareil nommé « Device-1 ».

// Schedule a job now to call the lockDoor direct method
// against a single device. Response and connection
// timeouts are set to 5 seconds.
String deviceId = "Device-1";
String jobId = "DMCMD" + UUID.randomUUID();  //Job ID must be unique

// How long the job is permitted to run without
// completing its work on the set of devices
private static final long maxExecutionTimeInSeconds = 30;

System.out.println("Schedule job " + jobId + " for device " + deviceId);
try {
  JobResult jobResult = jobClient.scheduleDeviceMethod(jobId,
    "deviceId='" + deviceId + "'",
    "lockDoor",
    5L, 5L, null,
    new Date(),
    maxExecutionTimeInSeconds);
} catch (Exception e) {
  System.out.println("Exception scheduling direct method job: " + jobId);
  System.out.println(e.getMessage());
}

Planifier une tâche de mise à jour de jumeau d’appareil

Utilisez scheduleUpdateTwin pour planifier une tâche pour exécuter une mise à jour de jumeau d’appareil sur un ou plusieurs appareils.

Tout d’abord, préparez un enregistrement DeviceTwinDevice pour la mise à jour du jumeau d’appareil. Par exemple :

String deviceId = "Device-1";

//Create a device twin desired properties update object
DeviceTwinDevice twin = new DeviceTwinDevice(deviceId);
Set<Pair> desiredProperties = new HashSet<Pair>();
desiredProperties.add(new Pair("Building", 43));
desiredProperties.add(new Pair("Floor", 3));
twin.setDesiredProperties(desiredProperties);
// Optimistic concurrency control
twin.setETag("*");

Appelez ensuite scheduleUpdateTwin pour programmer la mise à jour. Par exemple :

String jobId = "DPCMD" + UUID.randomUUID();  //Unique job ID

// How long the job is permitted to run without
// completing its work on the set of devices
private static final long maxExecutionTimeInSeconds = 30;

// Schedule the update twin job to run now for a single device
System.out.println("Schedule job " + jobId + " for device " + deviceId);
try {
  JobResult jobResult = jobClient.scheduleUpdateTwin(jobId, 
    "deviceId='" + deviceId + "'",
    twin,
    new Date(),
    maxExecutionTimeInSeconds);
} catch (Exception e) {
  System.out.println("Exception scheduling desired properties job: " + jobId);
  System.out.println(e.getMessage());
}

Surveiller un travail

Utilisez getJob pour récupérer des informations de tâche en fonction d’un ID de tâche spécifique. getJob retourne un objet JobResult qui contient des méthodes et des propriétés que vous pouvez utiliser pour vérifier les informations de tâche, y compris le statut en cours d’exécution.

Par exemple :

try {
  JobResult jobResult = jobClient.getJob(jobId);
  if(jobResult == null)
  {
    System.out.println("No JobResult for: " + jobId);
    return;
  }
  // Check the job result until it's completed
  while(jobResult.getJobStatus() != JobStatus.completed)
  {
    Thread.sleep(100);
    jobResult = jobClient.getJob(jobId);
    System.out.println("Status " + jobResult.getJobStatus() + " for job " + jobId);
  }
  System.out.println("Final status " + jobResult.getJobStatus() + " for job " + jobId);
} catch (Exception e) {
  System.out.println("Exception monitoring job: " + jobId);
  System.out.println(e.getMessage());
  return;
}

Interroger le statut d’une tâche

Utilisez queryDeviceJob pour interroger le statut de tâche pour un ou plusieurs travaux.

Par exemple :

private static void queryDeviceJobs(JobClient jobClient, String start) throws Exception {
  System.out.println("\nQuery device jobs since " + start);

  // Create a jobs query using the time the jobs started
  Query deviceJobQuery = jobClient
      .queryDeviceJob(SqlQuery.createSqlQuery("*", SqlQuery.FromType.JOBS, "devices.jobs.startTimeUtc > '" + start + "'", null).getQuery());

  // Iterate over the list of jobs and print the details
  while (jobClient.hasNextJob(deviceJobQuery)) {
    System.out.println(jobClient.getNextJob(deviceJobQuery));
  }
}

Exemple de travaux de planification du Kit de développement logiciel (SDK)

Le SDK Azure IoT pour Java fournit un exemple fonctionnel d'application de service qui gère les tâches de planification des travaux. Pour plus d'informations, voir l'échantillon de client de l'emploi.

  • Kit de développement logiciel (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.

Vue d’ensemble

Cet article décrit comment utiliser le SDK Azure IoT pour Python afin de créer un code d'application de service backend pour planifier une tâche afin d'invoquer une méthode directe ou d'effectuer une mise à jour de propriété souhaitée pour un jumelage de périphérique sur un ou plusieurs périphériques.

Installation du package

La bibliothèque azure-iot-hub doit être installée pour créer des applications de service back-end.

pip install azure-iot-hub

Importer des instructions

La classe IoTHubJobManager expose toutes les méthodes nécessaires à la création d'une application dorsale permettant de planifier des tâches à partir du service.

Ajoutez les instructions import suivantes.

import os
import sys
import datetime
import time
import threading
import uuid
import msrest

from azure.iot.hub import IoTHubJobManager
from azure.iot.hub.models import JobProperties, JobRequest, Twin, TwinProperties, CloudToDeviceMethod

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-vous à IoT Hub à l’aide de fromConnectionString.

Cet article décrit le code principal qui peut planifier une tâche pour appeler une méthode directe, planifier une tâche pour mettre à jour un jumeau d’appareil et surveiller la progression d’une tâche pour un ou plusieurs appareils. 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 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 :

IoTHubConnectionString = "{Shared access policy connection string}"
iothub_job_manager = IoTHubJobManager.from_connection_string(IoTHubConnectionString)

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.

Planifier une tâche de méthode directe

Utilisez create_scheduled_job pour planifier une nouvelle méthode directe afin d'exécuter une méthode directe sur un ou plusieurs appareils :

notes de paramètrecreate_scheduled_job :

Par exemple :

METHOD_NAME = "lockDoor"
METHOD_PAYLOAD = "{\"lockTime\":\"10m\"}"
job_id = uuid.uuid4()
DEVICE_ID = "Device-1"
TIMEOUT = 60

job_request = JobRequest()
job_request.job_id = job_id
job_request.type = "scheduleDeviceMethod"
job_request.start_time = datetime.datetime.utcnow().isoformat()
job_request.cloud_to_device_method = CloudToDeviceMethod(method_name=METHOD_NAME, payload=METHOD_PAYLOAD)
job_request.max_execution_time_in_seconds = TIMEOUT
job_request.query_condition = "DeviceId in ['{}']".format(device_id)

new_job_response = iothub_job_manager.create_scheduled_job(job_id, job_request)

Planifier une tâche de mise à jour de jumeau d’appareil

Utilisez create_scheduled_job pour créer une tâche pour exécuter une mise à jour des propriétés souhaitées d’un jumeau d’appareil sur un ou plusieurs appareils.

notes de paramètrecreate_scheduled_job :

Par exemple :

UPDATE_PATCH = {"building":43,"floor":3}
job_id = uuid.uuid4()
TIMEOUT = 60

job_request = JobRequest()
job_request.job_id = job_id
job_request.type = "scheduleUpdateTwin"
job_request.start_time = datetime.datetime.utcnow().isoformat()
job_request.update_twin = Twin(etag="*", properties=TwinProperties(desired=UPDATE_PATCH))
job_request.max_execution_time_in_seconds = TIMEOUT
job_request.query_condition = "DeviceId in ['{}']".format(device_id)

new_job_response = iothub_job_manager.create_scheduled_job(job_id, job_request)

Surveiller un travail

Utilisez get_scheduled_job pour récupérer les détails d’une tâche spécifique sur un hub IoT.

Cet exemple vérifie le statut de la tâche pour un ID de tâche spécifique toutes les cinq secondes jusqu’à ce que la tâche soit terminée.

while True:
    get_job_response = iothub_job_manager.get_scheduled_job(job_request.job_id)
    print_job_response("Get job response: ", get_job_response)
    if get_job_response.status == "completed":
      print ( "Job is completed." )
    time.sleep(5)

Exemples de travaux de planification du Kit de développement logiciel (SDK)

Le Kit de développement logiciel (SDK) Azure IoT pour Python fournit des exemples de tâche d’applications de service qui gèrent les tâches de planification de tâche. Pour plus d’informations, consultez l’article suivant :

  • Nécessite Node.js version 10.0.x ou ultérieure

Vue d’ensemble

Cet article explique comment utiliser la Kit de développement logiciel (SDK) Azure IoT pour Node.js pour créer du code d’application de service principal vers une tâche de planification pour appeler une méthode directe ou effectuer une mise à jour de jumeau d’appareil sur un ou plusieurs appareils.

Installer le package de Kit de développement logiciel (SDK) de service

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

npm install azure-iothub --save

La classe JobClient expose toutes les méthodes nécessaires pour interagir avec la planification des tâches à partir d'une application dorsale.

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é

Utilisez fromConnectionString pour vous connecter au hub IoT Hub.

Cet article décrit le code principal qui peut planifier une tâche pour appeler une méthode directe, planifier une tâche pour mettre à jour un jumeau d’appareil et surveiller la progression d’une tâche pour un ou plusieurs appareils. 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 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 :

'use strict';
var JobClient = require('azure-iothub').JobClient;
var connectionString = '{Shared access policy connection string}';
var jobClient = JobClient.fromConnectionString(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.

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

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 Chaînes d’informations d’identification dans la bibliothèque de client Azure Identity pour JavaScript.

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 ce package :

npm install --save @azure/identity

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.

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.

Créer une tâche de méthode directe

Utilisez scheduleDeviceMethod pour planifier une tâche pour exécuter une méthode directe sur un ou plusieurs appareils.

Tout d’abord, créez une variable de mise à jour de méthode directe avec des informations de nom de méthode, de charge utile et de délai d’attente de réponse. Par exemple :

var methodParams = {
    methodName: 'lockDoor',
    payload: null,
    responseTimeoutInSeconds: 15 // Time-out after 15 seconds if device is unable to process method
};

Appelez ensuite scheduleDeviceMethod pour planifier le travail d’appel de méthode directe :

  • Chaque travail doit avoir un ID de travail unique. Vous pouvez utiliser cet ID de travail pour surveiller un travail, comme décrit dans la section Surveiller une tâche de cet article.
  • Spécifiez un paramètre queryCondition pour évaluer les appareils sur lesquels exécuter la tâche. Pour plus d'informations sur les conditions d'interrogation, voir le langage d'interrogation d'IoT Hub pour les jumeaux d'appareils et de modules, les tâches et l'acheminement des messages.
  • Vérifiez le rappel jobResult pour le résultat de la planification de la tâche. Si la tâche a été correctement planifiée, vous pouvez surveiller le statut de la tâche comme indiqué dans la Surveiller un travail section de cet article.

Par exemple :

var methodJobId = uuid.v4();
var queryCondition = "deviceId IN ['myDeviceId']";
var startTime = new Date();
var maxExecutionTimeInSeconds =  300;

jobClient.scheduleDeviceMethod(methodJobId,
                            queryCondition,
                            methodParams,
                            startTime,
                            maxExecutionTimeInSeconds,
                            function(err) {
    if (err) {
        console.error('Could not schedule direct method job: ' + err.message);
    } else {
        monitorJob(methodJobId, function(err, result) {
            if (err) {
                console.error('Could not monitor direct method job: ' + err.message);
            } else {
                console.log(JSON.stringify(result, null, 2));
            }
        });
    }
});

Planifier une tâche de mise à jour de jumeau d’appareil

Utilisez scheduleUpdateTwin pour planifier une tâche pour exécuter une mise à jour de jumeau d’appareil sur un ou plusieurs appareils.

Tout d'abord, créez une variable de mise à jour de la propriété de jumeau d'appareil.

var twinPatch = {
   etag: '*',
   properties: {
       desired: {
           building: '43',
           floor: 3
       }
   }
};

Appelez ensuite scheduleTwinUpdate pour planifier le travail de mise à jour de propriété souhaitée du jumeau d’appareil :

  • Chaque travail doit avoir un ID de travail unique. Vous pouvez utiliser cet ID de travail pour surveiller un travail, comme décrit dans la section Surveiller une tâche de cet article.
  • Spécifiez un paramètre queryCondition pour évaluer les appareils sur lesquels exécuter la tâche. Pour plus d'informations sur les conditions d'interrogation, voir le langage d'interrogation d'IoT Hub pour les jumeaux d'appareils et de modules, les tâches et l'acheminement des messages.
  • Vérifiez le rappel jobResult pour le résultat de la planification de la tâche. Si la tâche a été correctement planifiée, vous pouvez surveiller le statut de la tâche comme indiqué dans la Surveiller un travail section de cet article.

Par exemple :

var twinJobId = uuid.v4();
var queryCondition = "deviceId IN ['myDeviceId']";
var startTime = new Date();
var maxExecutionTimeInSeconds =  300;

console.log('scheduling Twin Update job with id: ' + twinJobId);
jobClient.scheduleTwinUpdate(twinJobId,
                            queryCondition,
                            twinPatch,
                            startTime,
                            maxExecutionTimeInSeconds,
                            function(err) {
    if (err) {
        console.error('Could not schedule twin update job: ' + err.message);
    } else {
        monitorJob(twinJobId, function(err, result) {
            if (err) {
                console.error('Could not monitor twin update job: ' + err.message);
            } else {
                console.log(JSON.stringify(result, null, 2));
            }
        });
    }
});

Surveiller un travail

Utilisez getJob pour surveiller le statut de la tâche pour obtenir un ID de tâche spécifique.

Cet exemple de fonction vérifie périodiquement l'état d'un travail pour un ID de travail spécifique jusqu'à ce que le travail soit terminé ou qu'il ait échoué.

function monitorJob (jobId, callback) {
    var jobMonitorInterval = setInterval(function() {
        jobClient.getJob(jobId, function(err, result) {
        if (err) {
            console.error('Could not get job status: ' + err.message);
        } else {
            console.log('Job: ' + jobId + ' - status: ' + result.status);
            if (result.status === 'completed' || result.status === 'failed' || result.status === 'cancelled') {
            clearInterval(jobMonitorInterval);
            callback(null, result);
            }
        }
        });
    }, 5000);
}

Exemple de travaux de planification du Kit de développement logiciel (SDK)

Le SDK Azure IoT pour Node.js fournit un échantillon fonctionnel d'application de service qui gère les tâches de planification des travaux. Pour plus d'informations, voir Test E2E du client de l'emploi.

  • Last updated on