Gérer automatiquement les appareils dans Azure Digital Twins en utilisant le service Device Provisioning (DPS)

Article
11/18/2022

Dans cet article, vous allez apprendre à intégrer Azure Digital Twins avec le service Device Provisioning (DPS).

La solution décrite dans cet article vous permet d’automatiser le processus d’approvisionnement et de mise hors service d’appareils IoT Hub dans Azure Digital Twins, à l’aide du service Device Provisioning.

Pour plus d’informations sur les étapes d’approvisionnement et de mise hors service, et pour mieux comprendre l’ensemble des étapes générales de gestion des appareils communes à tous les projets IoT d’entreprise, consultez la section Cycle de vie des appareils de la documentation de gestion des appareils d’IoT Hub.

Prérequis

Avant de pouvoir configurer l’approvisionnement, vous devez configurer les ressources suivantes :

Une instance d’Azure Digital Twins. Suivez les instructions données dans Configurer une instance et l’authentification pour créer une instance Azure Digital Twins. Collectez le Nom d’hôte de l’instance dans le portail Azure (instructions).
Un hub IoT. Pour obtenir des instructions, consultez la section Créer un IoT Hub de ce démarrage rapide d’IoT Hub.
Une fonction Azure qui met à jour les informations du jumeau numérique à partir des données IoT Hub. Suivez les instructions données dans Ingérer des données IoT Hub pour créer cette fonction Azure. Récupérez le nom de la fonction pour l’utiliser dans cet article.

Cet exemple utilise également un simulateur d’appareil qui comprend l’approvisionnement à l’aide du service Device Provisioning. Le simulateur d’appareil se trouve ici : Exemple d’intégration d’Azure Digital Twins et d’IoT Hub. Obtenez l’exemple de projet sur votre ordinateur en accédant au dépôt GitHub pour l’exemple, que vous pouvez télécharger en tant que fichier .zip en sélectionnant le bouton Code et télécharger le fichier ZIP.

Décompressez le dossier téléchargé.

Node.js doit être installé sur votre machine. Le simulateur d’appareil est basé sur Node.js, version 10.0.x ou ultérieure.

Architecture de solution

Cette solution comprend les étapes de provisionnement et de mise hors service d’un appareil dans Azure Digital Twins à l’aide du service de provisionnement d’appareil.

Pour allouer des appareils dans la solution, les données circulent entre un appareil à thermostat et le service de provisionnement d’appareil. Les données passent ensuite du service de provisionnement d’appareil à IoT Hub et à Azure Digital Twins via une fonction Azure.

Pour mettre hors service un appareil, les données issues d’une suppression manuelle d’appareil sont transmises à Azure Digital Twins via IoT Hub, Event Hubs et une fonction Azure.

L’image ci-dessous illustre cette architecture.

Cet article est divisé en deux sections, chacune axée sur une partie de cette architecture complète :

Provisionner automatiquement un appareil avec le service Device Provisioning
Mettre hors service automatiquement un appareil avec des événements de cycle de vie IoT Hub

Provisionner automatiquement un appareil avec le service Device Provisioning

Dans cette section, vous attachez le service Device Provisioning à Azure Digital Twins pour provisionner automatiquement des appareils en suivant la procédure ci-dessous. Ce diagramme est un extrait de l’architecture complète présentée plus tôt.

Voici une description du flux de processus :

L’appareil contacte le point de terminaison DPS, en transmettant les informations d’identification pour prouver son identité.
Le DPS valide l’identité de l’appareil en validant l’ID d’inscription et la clé par rapport à la liste d’inscriptions, et appelle une Azure Function pour effectuer l’allocation.
La fonction Azure crée une nouvelle représentation dans Azure Digital Twins pour l’appareil. Le jumeau numérique aura le même nom que l’ID d’inscription de l’appareil.
DPS inscrit l’appareil sur un hub IoT et renseigne l’état choisi du jumeau de l’appareil.
IoT Hub renvoie les informations d’ID d’appareil et les informations de connexion IoT Hub à l’appareil. L’appareil peut maintenant se connecter à IoT Hub.

Les sections suivantes décrivent les étapes à suivre pour configurer ce flux de provisionnement automatique des appareils.

Créer un service Device Provisioning

Lorsqu’un nouvel appareil est configuré à l’aide du service Device Provisioning, une nouvelle représentation de cet appareil peut être créée dans Azure Digital Twins avec le même nom que l’ID d’inscription.

Créez une instance de service Device Provisioning, qui sera utilisée pour approvisionner des appareils IoT. Vous pouvez suivre les instructions pour Azure CLI ci-dessous, ou utiliser le portail Azure comme expliqué dans Configurer le service IoT Hub Device Provisioning avec le portail Azure.

La commande Azure CLI suivante crée un service Device Provisioning. Vous devez spécifier un nom de service de provisionnement des appareils, un groupe de ressources et une région. Pour connaître les régions qui prennent en charge le service de provisionnement des appareils, consultez Produits Azure disponibles par région. La commande peut être exécutée dans Cloud Shell ou localement si Azure CLI est installé sur votre ordinateur.

az iot dps create --name <Device-Provisioning-Service-name> --resource-group <resource-group-name> --location <region>

Ajouter une fonction à utiliser avec le service de provisionnement des appareils

Dans votre projet d’application de fonction que vous avez créé dans la section Prérequis, vous allez créer une nouvelle fonction à utiliser avec le service de provisionnement d’appareil. Cette fonction sera utilisée par le service Device Provisioning dans une stratégie d’allocation personnalisée pour approvisionner un nouvel appareil.

Naviguez vers le projet d’application de fonction sur votre ordinateur et suivez les étapes ci-dessous.

Créez d’abord une fonction de type déclencheur HTTP dans le projet d’application de fonction.
Ajoutez un nouveau package NuGet au projet : Microsoft.Azure.Devices.Provisioning.Service. Vous devrez peut-être également ajouter d’autres packages à votre projet, si les packages utilisés dans le code ne font pas déjà partie du projet.

Dans le fichier de code de fonction nouvellement créé, collez le code suivant, nommez la fonction DpsAdtAllocationFunc.cs, et enregistrez le fichier.

// Copyright (c) Microsoft. All rights reserved.
// Licensed under the MIT license. See LICENSE file in the project root for full license information.

using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Threading.Tasks;
using Azure;
using Azure.Core.Pipeline;
using Azure.DigitalTwins.Core;
using Azure.Identity;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Http;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.Devices.Shared;
using Microsoft.Azure.Devices.Provisioning.Service;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;

namespace Samples.AdtIothub
{
    public static class DpsAdtAllocationFunc
    {
        private static string adtInstanceUrl = Environment.GetEnvironmentVariable("ADT_SERVICE_URL");
        private static readonly HttpClient singletonHttpClientInstance = new HttpClient();

        [FunctionName("DpsAdtAllocationFunc")]
        public static async Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = null)] HttpRequest req, ILogger log)
        {
            // Get request body
            string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
            log.LogDebug($"Request.Body: {requestBody}");
            dynamic data = JsonConvert.DeserializeObject(requestBody);

            // Get registration ID of the device
            string regId = data?.deviceRuntimeContext?.registrationId;

            bool fail = false;
            string message = "Uncaught error";
            var response = new ResponseObj();

            // Must have unique registration ID on DPS request
            if (regId == null)
            {
                message = "Registration ID not provided for the device.";
                log.LogInformation("Registration ID: NULL");
                fail = true;
            }
            else
            {
                string[] hubs = data?.linkedHubs.ToObject<string[]>();

                // Must have hubs selected on the enrollment
                if (hubs == null
                    || hubs.Length < 1)
                {
                    message = "No hub group defined for the enrollment.";
                    log.LogInformation("linkedHubs: NULL");
                    fail = true;
                }
                else
                {
                    // Find or create twin based on the provided registration ID and model ID
                    dynamic payloadContext = data?.deviceRuntimeContext?.payload;
                    string dtmi = payloadContext.modelId;
                    log.LogDebug($"payload.modelId: {dtmi}");
                    string dtId = await FindOrCreateTwinAsync(dtmi, regId, log);

                    // Get first linked hub (TODO: select one of the linked hubs based on policy)
                    response.iotHubHostName = hubs[0];

                    // Specify the initial tags for the device.
                    var tags = new TwinCollection();
                    tags["dtmi"] = dtmi;
                    tags["dtId"] = dtId;

                    // Specify the initial desired properties for the device.
                    var properties = new TwinCollection();

                    // Add the initial twin state to the response.
                    var twinState = new TwinState(tags, properties);
                    response.initialTwin = twinState;
                }
            }

            log.LogDebug("Response: " + ((response.iotHubHostName != null)? JsonConvert.SerializeObject(response) : message));

            return fail
                ? new BadRequestObjectResult(message)
                : (ActionResult)new OkObjectResult(response);
        }

        public static async Task<string> FindOrCreateTwinAsync(string dtmi, string regId, ILogger log)
        {
            // Create Digital Twins client
            var cred = new DefaultAzureCredential();
            var client = new DigitalTwinsClient(new Uri(adtInstanceUrl), cred);

            // Find existing DigitalTwin with registration ID
            try
            {
                // Get DigitalTwin with Id 'regId'
                BasicDigitalTwin existingDt = await client.GetDigitalTwinAsync<BasicDigitalTwin>(regId).ConfigureAwait(false);

                // Check to make sure it is of the correct model type
                if (StringComparer.OrdinalIgnoreCase.Equals(dtmi, existingDt.Metadata.ModelId))
                {
                    log.LogInformation($"DigitalTwin {existingDt.Id} already exists");
                    return existingDt.Id;
                }

                // Found DigitalTwin but it is not of the correct model type
                log.LogInformation($"Found DigitalTwin {existingDt.Id} but it is not of model {dtmi}");
            }
            catch(RequestFailedException ex) when (ex.Status == (int)HttpStatusCode.NotFound)
            {
                log.LogDebug($"Did not find DigitalTwin {regId}");
            }

            // Either the DigitalTwin was not found, or we found it but it is of a different model type
            // Create or replace it with what it needs to be, meaning if it was not found a brand new DigitalTwin will be created
            // and if it was of a different model, it will replace that existing DigitalTwin
            // If it was intended to only create the DigitalTwin if there is no matching DigitalTwin with the same Id,
            // ETag.All could have been used as the ifNonMatch parameter to the CreateOrReplaceDigitalTwinAsync method call.
            // Read more in the CreateOrReplaceDigitalTwinAsync documentation here:
            // https://docs.microsoft.com/en-us/dotnet/api/azure.digitaltwins.core.digitaltwinsclient.createorreplacedigitaltwinasync?view=azure-dotnet
            BasicDigitalTwin dt = await client.CreateOrReplaceDigitalTwinAsync(
                regId, 
                new BasicDigitalTwin
                {
                    Metadata = { ModelId = dtmi },
                    Contents = 
                    {
                        { "Temperature", 0.0 }
                    }
                }
            ).ConfigureAwait(false);

            log.LogInformation($"Digital Twin {dt.Id} created.");
            return dt.Id;
        }
    }

    /// <summary>
    /// Expected function result format
    /// </summary>
    public class ResponseObj
    {
        public string iotHubHostName { get; set; }
        public TwinState initialTwin { get; set; }
    }
}

Publiez le projet avec la fonction DpsAdtAllocationFunc.cs sur l’application de fonction dans Azure.

Pour obtenir des instructions sur la façon de publier une fonction à l’aide de Visual Studio, consultez Développer des Azure Functions à l’aide de Visual Studio. Pour obtenir des instructions sur la publication de la fonction à l’aide de Visual Studio Code, consultez Créer une fonction C# dans Azure à l’aide de Visual Studio Code. Pour obtenir des instructions sur la publication de la fonction à l’aide d’Azure CLI, consultez Créer une fonction C# dans Azure à partir de la ligne de commande.

Important

Lors de la création de l’application de fonction pour la première fois dans la section Prérequis, vous avez peut-être déjà attribué un rôle d’accès à la fonction et configuré les paramètres d’application pour l’accès à votre instance Azure Digital Twins. Ces opérations doivent être effectuées une seule fois pour l’ensemble de l’application de fonction. Vérifiez qu’elles ont été effectuées dans votre application avant de continuer. Pour obtenir des instructions, consultez la section Configurer l’application publiée dans l’article Écrire le code d’authentification de l’application.

Créer une inscription Device Provisioning

Ensuite, vous devez créer une inscription dans le service Device Provisioning à l’aide d’une fonction d’allocation personnalisée. Pour créer une inscription, suivez les instructions pour effectuer cette opération dans la section Créer l’inscription de l’article sur les stratégies d’allocation personnalisées de la documentation du service de provisionnement des appareils.

Pendant cette procédure, veillez à sélectionner les options suivantes pour lier l’inscription à la fonction que vous avez créé.

Sélectionner le mode d’affectation des appareils aux hubs : Personnalisé (Utiliser Azure Functions).
Sélectionnez les hubs IoT auxquels ce groupe peut être affecté : choisissez le nom de votre hub IoT ou sélectionnez le bouton Lier un nouveau hub IoT, puis choisissez votre hub IoT dans les options.

Ensuite, choisissez le bouton Sélectionner une nouvelle fonction pour lier votre application de fonction au groupe d’inscription. Renseignez ensuite les valeurs suivantes :

Abonnement : votre abonnement Azure est rempli automatiquement. Assurez-vous qu’il s’agit de l’abonnement approprié.
Application de fonction : nom de votre application de fonction.
Fonction : choisissez DpsAdtAllocationFunc.

Enregistrez ces informations.

Après avoir créé l’inscription, sélectionnez-la pour afficher ses paramètres. Copiez la clé primaire de l’inscription, qui sera utilisée plus loin dans cet article pour configurer le simulateur d’appareil.

Configurer le simulateur d’appareil

Cet exemple utilise un simulateur d’appareil qui comprend l’approvisionnement à l’aide du service Device Provisioning. Le simulateur d’appareil se trouve dans l’exemple d’intégration Azure Digital Twins et IoT Hub que vous avez téléchargé dans la section Prérequis.

Télécharger le modèle

Le simulateur d’appareil est un appareil de type thermostat qui utilise le modèle avec cet ID : dtmi:contosocom:DigitalTwins:Thermostat;1. Vous devez charger ce modèle dans Azure Digital Twins avant de pouvoir créer une représentation de ce type pour l’appareil.

Le modèle se présente ainsi :

{
    "@id": "dtmi:contosocom:DigitalTwins:Thermostat;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;3",
    "contents": [
      {
        "@type": "Property",
        "name": "Temperature",
        "schema": "double"
      }
    ]
  }

Pour charger ce modèle dans votre instance Twins, exécutez la commande Azure CLI suivante, qui charge le modèle ci-dessus en tant que JSON inlined. Vous pouvez exécuter la commande dans Azure Cloud Shell dans votre navigateur (utiliser l’environnement Bash) ou sur votre ordinateur si l’interface CLI est installée localement. Il existe un espace réservé pour le nom d’hôte de l’instance. (Vous pouvez également utiliser le nom convivial de l’instance avec une légère baisse des performances.)

az dt model create --dt-name <instance-hostname-or-name> --models '{  "@id": "dtmi:contosocom:DigitalTwins:Thermostat;1",  "@type": "Interface",  "@context": "dtmi:dtdl:context;2",  "contents": [    {      "@type": "Property",      "name": "Temperature",      "schema": "double"    }  ]}'

Remarque

Si vous utilisez autre chose que Cloud Shell dans l’environnement Bash, vous devrez peut-être placer dans une séquence d’échappement devant certains caractères dans le JSON inlined afin qu’il soit analysé correctement. Pour plus d’informations, consultez Utiliser des caractères spéciaux dans différents shells.

Pour plus d’informations sur les modèles, consultez Gérer les modèles.

Configurer et exécuter le simulateur

Dans une fenêtre de commande sur votre ordinateur local, accédez à l’exemple téléchargé d’Intégration d’Azure Digital Twins et d’IoT Hub que vous avez décompressé précédemment, puis dans le répertoire du simulateur d’appareil. Ensuite, installez les dépendances pour le projet à l’aide de la commande suivante :

npm install

Ensuite, dans le répertoire de votre simulateur d’appareil, copiez le fichier .env.template dans un nouveau fichier appelé .env, et rassemblez les valeurs suivantes pour renseigner les paramètres :

PROVISIONING_IDSCOPE : pour obtenir cette valeur, accédez à votre service de provisionnement des appareils dans le portail Azure, puis sélectionnez Vue d’ensemble dans les options de menu et recherchez l’étendue le champ Étendue de l’ID.
PROVISIONING_REGISTRATION_ID : vous pouvez choisir un ID d’inscription pour votre appareil.
ADT_MODEL_ID : dtmi:contosocom:DigitalTwins:Thermostat;1
PROVISIONING_SYMMETRIC_KEY : cette variable d'environnement est la clé primaire pour l’inscription que vous avez configurée précédemment. Pour obtenir à nouveau cette valeur, accédez à votre service de provisionnement des appareils dans le portail Azure, sélectionnez Gérer les inscriptions, puis sélectionnez le groupe d’inscription que vous avez créé précédemment et copiez la Clé primaire.

À présent, utilisez les valeurs ci-dessus pour mettre à jour les paramètres du fichier .env.

PROVISIONING_HOST = "global.azure-devices-provisioning.net"
PROVISIONING_IDSCOPE = "<Device-Provisioning-Service-Scope-ID>"
PROVISIONING_REGISTRATION_ID = "<Device-Registration-ID>"
ADT_MODEL_ID = "dtmi:contosocom:DigitalTwins:Thermostat;1"
PROVISIONING_SYMMETRIC_KEY = "<Device-Provisioning-Service-enrollment-primary-SAS-key>"

Enregistrez le fichier et fermez-le.

Lancer l’exécution du simulateur d’appareil

Toujours dans le répertoire device-simulator, dans votre fenêtre de commande, démarrez le simulateur d’appareil à l’aide de la commande suivante :

node .\adt_custom_register.js

Vous devriez voir que l’appareil est enregistré et connecté à IoT Hub, puis qu’il commence à envoyer des messages.

Valider

En raison du flux que vous avez configuré dans cet article, l’appareil est automatiquement inscrit dans Azure Digital Twins. Utilisez la commande Azure Digital Twins CLI suivante pour trouver la représentation de l’appareil dans l’instance Azure Digital Twins que vous avez créée. Il existe un espace réservé pour le nom d’hôte de l’instance (vous pouvez également utiliser le nom convivial de l’instance avec une légère baisse des performances) et un espace réservé pour l’ID d’inscription de l’appareil.

az dt twin show --dt-name <instance-hostname-or-name> --twin-id "<device-registration-ID>"

La représentation de l’appareil doit se trouver dans l’instance Azure Digital Twins.

Mettre hors service automatiquement un appareil avec des événements de cycle de vie IoT Hub

Dans cette section, vous attachez des événements de cycle de vie IoT Hub à Azure Digital Twins pour mettre hors service automatiquement les appareils en suivant la procédure ci-dessous. Ce diagramme est un extrait de l’architecture complète présentée plus tôt.

Voici une description du flux de processus :

Un processus externe ou manuel déclenche la suppression d’un appareil dans IoT Hub.
IoT Hub supprime l’appareil et génère un événement de cycle de vie de l’appareil qui est routé vers un Event Hub.
Une fonction Azure supprime la représentation de l’appareil dans Azure Digital Twins.

Les sections suivantes décrivent les étapes à suivre pour configurer ce flux de mise hors service automatique des appareils.

Créer un concentrateur d’événements

Ensuite, vous allez créer un Event Hub Azure pour recevoir les événements du cycle de vie d’IoT Hub.

Suivez les étapes décrites dans le guide de démarrage rapide Créer un Event Hub. Nommez votre Event Hub lifecycleevents. Vous utiliserez ce nom d’Event Hub lorsque vous configurerez l’itinéraire IoT Hub et une fonction Azure dans les sections suivantes.

La capture d’écran ci-dessous illustre la création du Event Hub.

Créer une stratégie SAS pour votre Event Hub

Ensuite, vous devez créer une stratégie de signature d’accès partagé (SAS) pour configurer Event Hub avec votre application de fonction. Pour créer la stratégie SAP :

Accédez au Event Hub que vous venez de créer dans le portail Azure et sélectionnez Stratégies d’accès partagé dans les options de menu de sur la gauche.
Sélectionnez Ajouter. Dans la fenêtre Ajouter une stratégie SAS qui s’ouvre, entrez le nom de stratégie de votre choix et cochez la case Écouter.
Sélectionnez Créer.

Configurer Event Hub avec l’application de fonction

Ensuite, configurez l’application de fonction Azure que vous avez configurée dans la section Prérequis pour utiliser votre nouveau hub d’événements. Vous configurerez cette fonction en définissant une variable d’environnement à l’intérieur de l’application de fonction avec la chaîne de connexion de l’Event Hub.

Ouvrez la stratégie que vous avez créée et copiez la valeur de Chaîne de connexion - clé primaire.
Ajoutez la chaîne de connexion en tant que variable dans les paramètres de l’application de fonction à l’aide de la commande Azure CLI suivante. La commande peut être exécutée dans Cloud Shell ou localement si Azure CLI est installé sur votre ordinateur.
```
az functionapp config appsettings set --settings "EVENTHUB_CONNECTIONSTRING=<Event-Hubs-SAS-connection-string-Listen>" --resource-group <resource-group> --name <your-function-app-name>
```

Ajouter une fonction pour mettre hors service avec les événements de cycle de vie IoT Hub

Dans le projet d’application de fonction que vous avez créé dans la section Prérequis, vous allez créer une nouvelle fonction pour mettre hors service un appareil existant à l’aide d’événements de cycle de vie IoT Hub.

Pour plus d’informations sur les événements de cycle de vie, consultez Événements IoT Hub autres que les événements de télémétrie. Pour plus d’informations sur l’utilisation d’Event Hubs avec Azure Functions, consultez Déclencheur Azure Event Hubs pour Azure Functions.

Naviguez vers le projet d’application de fonction sur votre ordinateur et suivez les étapes ci-dessous.

Créez d’abord une fonction de type déclencheur Event Hub dans le projet d’application de fonction.
Ajoutez un nouveau package NuGet au projet : Microsoft.Azure.Devices.Provisioning.Service. Vous devrez peut-être également ajouter d’autres packages à votre projet, si les packages utilisés dans le code ne font pas déjà partie du projet.

Dans le fichier de code de fonction nouvellement créé, collez le code suivant, nommez la fonction DeleteDeviceInTwinFunc.cs, puis enregistrez le fichier.

// Copyright (c) Microsoft. All rights reserved.
// Licensed under the MIT license. See LICENSE file in the project root for full license information.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Threading.Tasks;
using Azure;
using Azure.Core.Pipeline;
using Azure.DigitalTwins.Core;
using Azure.Identity;
using Microsoft.Azure.EventHubs;
using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;

namespace Samples.AdtIothub
{
    public static class DeleteDeviceInTwinFunc
    {
        private static string adtAppId = "https://digitaltwins.azure.net";
        private static readonly string adtInstanceUrl = Environment.GetEnvironmentVariable("ADT_SERVICE_URL", EnvironmentVariableTarget.Process);
        private static readonly HttpClient singletonHttpClientInstance = new HttpClient();

        [FunctionName("DeleteDeviceInTwinFunc")]
        public static async Task Run(
            [EventHubTrigger("lifecycleevents", Connection = "EVENTHUB_CONNECTIONSTRING")] EventData[] events, ILogger log)
        {
            var exceptions = new List<Exception>(events.Length);

            // Create Digital Twin client
            var cred = new ManagedIdentityCredential(adtAppId);
            var client = new DigitalTwinsClient(
                new Uri(adtInstanceUrl),
                cred,
                new DigitalTwinsClientOptions
                {
                    Transport = new HttpClientTransport(singletonHttpClientInstance)
                });

            foreach (EventData eventData in events)
            {
                try
                {
                    //log.LogDebug($"EventData: {System.Text.Json.JsonSerializer.Serialize(eventData)}");

                    string opType = eventData.Properties["opType"] as string;
                    if (opType == "deleteDeviceIdentity")
                    {
                        string deviceId = eventData.Properties["deviceId"] as string;

                        try
                        {
                            // Find twin based on the original Registration ID
                            BasicDigitalTwin digitalTwin = await client.GetDigitalTwinAsync<BasicDigitalTwin>(deviceId);

                            // In order to delete the twin, all relationships must first be removed
                            await DeleteAllRelationshipsAsync(client, digitalTwin.Id, log);

                            // Delete the twin
                            await client.DeleteDigitalTwinAsync(digitalTwin.Id, digitalTwin.ETag);
                            log.LogInformation($"Twin {digitalTwin.Id} deleted in DT");
                        }
                        catch (RequestFailedException e) when (e.Status == (int)HttpStatusCode.NotFound)
                        {
                            log.LogWarning($"Twin {deviceId} not found in DT");
                        }
                    }
                }
                catch (Exception e)
                {
                    // We need to keep processing the rest of the batch - capture this exception and continue.
                    exceptions.Add(e);
                }
            }

            if (exceptions.Count > 1)
                throw new AggregateException(exceptions);

            if (exceptions.Count == 1)
                throw exceptions.Single();
        }

        /// <summary>
        /// Deletes all outgoing and incoming relationships from a specified digital twin
        /// </summary>
        public static async Task DeleteAllRelationshipsAsync(DigitalTwinsClient client, string dtId, ILogger log)
        {
            AsyncPageable<BasicRelationship> relationships = client.GetRelationshipsAsync<BasicRelationship>(dtId);
            await foreach (BasicRelationship relationship in relationships)
            {
                await client.DeleteRelationshipAsync(dtId, relationship.Id, relationship.ETag);
                log.LogInformation($"Twin {dtId} relationship {relationship.Id} deleted in DT");
            }

            AsyncPageable<IncomingRelationship> incomingRelationships = client.GetIncomingRelationshipsAsync(dtId);
            await foreach (IncomingRelationship incomingRelationship in incomingRelationships)
            {
                await client.DeleteRelationshipAsync(incomingRelationship.SourceId, incomingRelationship.RelationshipId);
                log.LogInformation($"Twin {dtId} incoming relationship {incomingRelationship.RelationshipId} from {incomingRelationship.SourceId} deleted in DT");
            }
        }
    }
}

Publiez le projet avec la fonction DeleteDeviceInTwinFunc.cs sur une application de fonction dans Azure.

Pour obtenir des instructions sur la façon de publier une fonction à l’aide de Visual Studio, consultez Développer des Azure Functions à l’aide de Visual Studio. Pour obtenir des instructions sur la publication de la fonction à l’aide de Visual Studio Code, consultez Créer une fonction C# dans Azure à l’aide de Visual Studio Code. Pour obtenir des instructions sur la publication de la fonction à l’aide d’Azure CLI, consultez Créer une fonction C# dans Azure à partir de la ligne de commande.

Important

Créer un itinéraire IoT Hub pour les événements de cycle de vie

Vous devez maintenant configurer un itinéraire IoT Hub pour acheminer les événements de cycle de vie des appareils. Dans ce cas, vous écouterez spécifiquement les événements de suppression d’appareil, identifiés par if (opType == "deleteDeviceIdentity"). Cet événement déclenchera la suppression de sa représentation numérique, achevant ainsi le processus de retrait d'un appareil et de sa représentation numérique.

Tout d’abord, vous devez créer un point de terminaison Event Hub dans votre IoT Hub. Ensuite, vous allez ajouter un itinéraire dans IoT Hub pour envoyer des événements de cycle de vie à ce point de terminaison Event Hub. Pour créer un point de terminaison Event Hub, procédez comme suit :

Dans le portail Azure, accédez au hub IoT que vous avez créé dans la section Prérequis et sélectionnez Routage des messages dans les options de menu de gauche.
Sélectionnez l’onglet Points de terminaison personnalisés.
Sélectionnez + Ajouter et choisissez Event Hubs pour ajouter un point de terminaison de type Event Hubs.
Dans la fenêtre Ajouter un point de terminaison Event Hub qui s’ouvre, choisissez les valeurs suivantes :
- Nom du point de terminaison : choisissez un nom de point de terminaison.
- Espace de noms Event Hub : sélectionnez votre espace de noms Event Hub dans la liste déroulante.
- Instance Event Hub : choisissez le nom de l’Event Hub que vous avez créé à l’étape précédente.
Sélectionnez Créer. Laissez cette fenêtre ouverte pour ajouter un itinéraire à l’étape suivante.

Ensuite, vous allez ajouter un itinéraire qui se connecte au point de terminaison que vous avez créé à l’étape ci-dessus, avec une requête de routage qui envoie les événements de suppression. Procédez comme suit pour créer une route :

Accédez à l’onglet Itinéraires et sélectionnez Ajouter pour ajouter un itinéraire.
Dans la page Ajouter un itinéraire qui s’ouvre, choisissez les valeurs suivantes :
- Nom : choisissez un nom pour votre itinéraire.
- Point de terminaison : choisissez le point de terminaison Event Hubs que vous avez créé précédemment dans la liste déroulante.
- Source de données : choisissez les Événements de cycle de vie des appareils.
- Requête de routage : Entrez opType='deleteDeviceIdentity'. Cette requête limite les événements de cycle de vie de l’appareil pour envoyer uniquement les événements de suppression.
Cliquez sur Enregistrer.

Une fois que vous avez parcouru ce processus, tout est configuré pour mettre les appareils hors service de bout en bout.

Valider

Pour déclencher le processus de mise hors service, vous devez supprimer manuellement l’appareil d’IoT Hub.

Vous pouvez supprimer manuellement l’appareil IoT Hub avec une commande Azure CLI ou dans le portail Azure. Effectuez les étapes ci-dessous pour supprimer l’appareil dans le portail Azure :

Accédez à votre IoT Hub, puis sélectionnez Appareils IoT dans les options de menu sur la gauche.
Vous verrez un appareil avec l’ID d’inscription de l’appareil que vous avez choisi dans la première moitié de cet article. Vous pouvez également choisir n’importe quel autre appareil à supprimer, à condition qu’il dispose d’un jumeau numérique dans Azure Digital Twins pour vous permettre de vérifier que le jumeau numérique est automatiquement supprimé une fois l’appareil supprimé.
Sélectionnez l’appareil et choisissez Supprimer.

Plusieurs minutes peuvent être nécessaires pour voir les modifications reflétées dans Azure Digital Twins.

Utilisez la commande Azure Digital Twins CLI suivante pour vérifier que la représentation de l’appareil dans l’instance Azure Digital Twins a été supprimée. Il existe un espace réservé pour le nom d’hôte de l’instance (vous pouvez également utiliser le nom convivial de l’instance avec une légère baisse des performances) et un espace réservé pour l’ID d’inscription de l’appareil.

az dt twin show --dt-name <instance-hostname-or-name> --twin-id "<device-registration-ID>"

Vous devez voir que la représentation de l’appareil est introuvable dans l’instance Azure Digital Twins.

Nettoyer les ressources

Si vous n’avez plus besoin des ressources créées dans cet article, effectuez les étapes suivantes pour les supprimer.

Dans Azure Cloud Shell ou Azure CLI en local, vous pouvez supprimer toutes les ressources Azure d’un groupe de ressources avec la commande az group delete. Cette commande supprime le groupe de ressources, l’instance Azure Digital Twins, le hub IoT et l’inscription de l’appareil hub, la rubrique Event Grid et les abonnements associés, l’espace de noms Event Hubs et les deux applications Azure Functions, y compris les ressources associées comme le stockage.

Important

La suppression d’un groupe de ressources est irréversible. Le groupe de ressources et toutes les ressources qu’il contient sont supprimés définitivement. Veillez à ne pas supprimer accidentellement des ressources ou un groupe de ressources incorrects.

az group delete --name <your-resource-group>

Ensuite, supprimez de votre ordinateur local le dossier d’exemple de projet que vous avez téléchargé.

Étapes suivantes

Les jumeaux numériques créés pour les appareils sont stockés sous la forme d’une hiérarchie plate dans Azure Digital Twins, mais ils peuvent être enrichis avec des informations de modèle et une hiérarchie à plusieurs niveaux pour l’organisation. Pour en savoir plus sur ce concept, lisez :

Jumeaux numériques et graphique de jumeaux

Pour plus d’informations sur l’utilisation des requêtes HTTP avec les fonctions Azure, consultez:

Déclencheur de requête HTTP Azure pour Azure Functions

Vous pouvez écrire une logique personnalisée pour fournir automatiquement ces informations à l’aide des données de modèle et de graphique déjà stockées dans Azure Digital Twins. Pour en savoir plus sur la gestion, la mise à niveau et la récupération d’informations à partir du graphique de jumeaux, consultez les guides suivants :

Partager via

Gérer automatiquement les appareils dans Azure Digital Twins en utilisant le service Device Provisioning (DPS)

Prérequis

Architecture de solution

Provisionner automatiquement un appareil avec le service Device Provisioning

Créer un service Device Provisioning

Ajouter une fonction à utiliser avec le service de provisionnement des appareils

Créer une inscription Device Provisioning

Configurer le simulateur d’appareil

Télécharger le modèle

Configurer et exécuter le simulateur

Lancer l’exécution du simulateur d’appareil

Valider

Mettre hors service automatiquement un appareil avec des événements de cycle de vie IoT Hub

Créer un concentrateur d’événements

Créer une stratégie SAS pour votre Event Hub

Configurer Event Hub avec l’application de fonction

Ajouter une fonction pour mettre hors service avec les événements de cycle de vie IoT Hub

Créer un itinéraire IoT Hub pour les événements de cycle de vie

Valider

Nettoyer les ressources

Étapes suivantes

Ressources supplémentaires