Ingérer des données de télémétrie IoT Hub dans Azure Digital Twins

Article
01/03/2024

Ce guide décrit le processus d’écriture d’une fonction qui peut ingérer des données de télémétrie d’appareil à partir d’IoT Hub et l’envoyer à une instance d’Azure Digital Twins.

Azure Digital Twins se base sur les données des appareils IoT et d’autres sources. Pour les données d’appareil, il est courant d’utiliser la source IoT Hub dans Azure Digital Twins.

Le processus d’ingestion de données dans Azure Digital Twins consiste à configurer une ressource de calcul externe, telle qu’une fonction créée à l’aide d’Azure Functions. La fonction reçoit les données et utilise les API DigitalTwins pour définir des propriétés ou déclencher des événements de télémétrie sur des jumeaux numériques en conséquence.

Ce guide pratique décrit le processus d’écriture d’une fonction qui peut ingérer des données de télémétrie d’appareil à partir d’IoT Hub.

Prérequis

Avant de poursuivre avec cet exemple, vous devez mettre en place les ressources suivantes en guise de conditions préalables :

Un IoT Hub. Pour obtenir des instructions, consultez la section Créer un hub IoT de ce guide de démarrage rapide IoT Hub.
Une instance Azure Digital Twins qui recevra la télémétrie de votre appareil. Pour obtenir des instructions, consultez Configurer une instance Azure Digital Twins et l’authentification.

Exemple de scénario de télémétrie

Cet article explique comment envoyer des messages entre IoT Hub et Azure Digital Twins à l’aide d’une fonction dans Azure. Pour envoyer des messages, il existe de nombreuses configurations et stratégies possibles. Cependant, l’exemple de cet article contient les éléments suivants :

Un thermostat situé dans IoT Hub, ayant un ID d’appareil connu
Un jumeau numérique représentant l’appareil, avec un ID correspondant

Remarque

Cet exemple utilise une correspondance d’ID simple entre l’ID de l’appareil et celui d’un jumeau numérique. Toutefois, il est possible de fournir des mappages plus sophistiqués entre l’appareil et son jumeau (par exemple, avec une table de mappage).

Chaque fois qu’un événement de télémétrie de température est envoyé par l’appareil thermostat, une fonction traite les données de télémétrie et la Temperature propriété du jumeau numérique doit être mise à jour. Ce scénario est présenté dans un diagramme ci-dessous :

Diagram of IoT Hub device sending Temperature telemetry to a function in Azure, which updates a Temperature property on a twin in Azure Digital Twins.

Ajouter un modèle et un jumeau

Dans cette section, vous allez configurer un jumeau numérique dans Azure Digital Twins qui représentera le thermostat et sera mis à jour avec les informations d’IoT Hub.

Pour créer un jumeau de type thermostat, vous devez d’abord charger le modèle de thermostat sur votre instance, qui décrit les propriétés d’un thermostat et sera utilisé ultérieurement pour créer le jumeau.

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.

Vous devez ensuite créer un jumeau à l’aide de ce modèle. Utilisez la commande suivante pour créer un jumeau de thermostat nommé thermostat67 et définissez 0,0 comme valeur initiale de température. 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 twin create  --dt-name <instance-hostname-or-name> --dtmi "dtmi:contosocom:DigitalTwins:Thermostat;1" --twin-id thermostat67 --properties '{"Temperature": 0.0}'

Lorsque le jumeau est créé, la sortie CLI de la commande doit ressembler à ceci :

{
  "$dtId": "thermostat67",
  "$etag": "W/\"0000000-9735-4f41-98d5-90d68e673e15\"",
  "$metadata": {
    "$model": "dtmi:contosocom:DigitalTwins:Thermostat;1",
    "Temperature": {
      "lastUpdateTime": "2021-09-09T20:32:46.6692326Z"
    }
  },
  "Temperature": 0.0
}

Créer la fonction Azure

Dans cette section, vous allez créer une fonction Azure pour accéder à Azure Digital Twins et mettre à jour des jumeaux en fonction des événements de télémétrie des appareils IoT qu’il reçoit. Suivez les étapes ci-dessous pour créer et publier la fonction.

Tout d’abord, créez un projet Azure Functions de type de déclencheur Event Grid.

Pour ce faire, vous pouvez utiliser Visual Studio (pour obtenir des instructions, voir Développer Azure Functions à l’aide de Visual Studio), Visual Studio Code (pour obtenir des instructions, voir Créer une fonction C# dans Azure à l’aide de Visual Studio Code) ou d’Azure CLI (pour obtenir des instructions, consultez Créer une fonction C# dans Azure à partir de la ligne de commande).
Ajoutez les packages suivants à votre projet (vous pouvez utiliser le gestionnaire de package Visual Studio NuGet ou la commande dotnet add package dans un outil de ligne de commande).

Créez une fonction dans le projet appelé IoTHubtoTwins.cs. Dans le fichier de fonction, collez le code suivant :

using System;
using Azure;
using System.Net.Http;
using Azure.Core.Pipeline;
using Azure.DigitalTwins.Core;
using Azure.Identity;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using Azure.Messaging.EventGrid;

namespace IotHubtoTwins
{
    public class IoTHubtoTwins
    {
        private static readonly string adtInstanceUrl = Environment.GetEnvironmentVariable("ADT_SERVICE_URL");
        private static readonly HttpClient httpClient = new HttpClient();

        [FunctionName("IoTHubtoTwins")]
        // While async void should generally be used with caution, it's not uncommon for Azure function apps, since the function app isn't awaiting the task.
#pragma warning disable AZF0001 // Suppress async void error
        public async void Run([EventGridTrigger] EventGridEvent eventGridEvent, ILogger log)
#pragma warning restore AZF0001 // Suppress async void error
        {
            if (adtInstanceUrl == null) log.LogError("Application setting \"ADT_SERVICE_URL\" not set");

            try
            {
                // Authenticate with Digital Twins
                var cred = new DefaultAzureCredential();
                var client = new DigitalTwinsClient(new Uri(adtInstanceUrl), cred);
                log.LogInformation($"ADT service client connection created.");
            
                if (eventGridEvent != null && eventGridEvent.Data != null)
                {
                    log.LogInformation(eventGridEvent.Data.ToString());

                    // <Find_device_ID_and_temperature>
                    JObject deviceMessage = (JObject)JsonConvert.DeserializeObject(eventGridEvent.Data.ToString());
                    string deviceId = (string)deviceMessage["systemProperties"]["iothub-connection-device-id"];
                    var temperature = deviceMessage["body"]["Temperature"];
                    // </Find_device_ID_and_temperature>

                    log.LogInformation($"Device:{deviceId} Temperature is:{temperature}");

                    // <Update_twin_with_device_temperature>
                    var updateTwinData = new JsonPatchDocument();
                    updateTwinData.AppendReplace("/Temperature", temperature.Value<double>());
                    await client.UpdateDigitalTwinAsync(deviceId, updateTwinData);
                    // </Update_twin_with_device_temperature>
                }
            }
            catch (Exception ex)
            {
                log.LogError($"Error in ingest function: {ex.Message}");
            }
        }
    }
}

Enregistrez le code de votre fonction.

Publiez le projet avec la fonction IoTHubtoTwins.cs dans 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.

Une fois le processus de publication de la fonction terminé, vous pouvez utiliser cette commande Azure CLI pour vérifier que la publication a réussi. Il y a des espaces réservés pour votre groupe de ressources, et le nom de votre application de fonction. La commande imprime des informations sur la fonction IoTHubToTwins.

az functionapp function show --resource-group <your-resource-group> --name <your-function-app> --function-name IoTHubToTwins

Configurer l’application de fonction

Pour accéder à Azure Digital Twins, votre application de fonction devra disposer d’une identité managée affectée par le système avec les autorisations nécessaires pour accéder à votre instance Azure Digital Twins. Vous allez le configurer dans cette section en affectant un rôle d’accès pour la fonction et en configurant les paramètres de l’application afin qu’il puisse accéder à votre instance Azure Digital Twins.

Exécutez les commandes suivantes dans Azure Cloud Shell ou une interface locale d’Azure CLI.

Remarque

Cette section doit être effectuée par un utilisateur Azure qui dispose des autorisations nécessaires pour gérer l’accès utilisateur aux ressources Azure, y compris l’octroi et la délégation d’autorisations. Les rôles communs qui répondent à cette exigence sont Propriétaire, Administrateur de compte ou la combinaison des rôles Administrateur de l’accès utilisateur et Contributeur. Pour plus d’informations sur les exigences d’autorisation pour les rôles Azure Digital Twins, consultez Configurer une instance et l’authentification.

Attribuer un rôle d’accès

La fonction Azure nécessite un jeton de porteur pour transmission. Pour vous assurer que le jeton du porteur est transmis, accordez à l’Application de fonction le rôle de Propriétaire des données Azure Digital Twins pour votre instance Azure Digital Twins, ce qui permettra à l’application de fonction d’effectuer des activités de plan de données sur l’instance.

Utilisez la commande suivante pour créer une identité managée affectée par le système pour votre fonction (si la fonction en a déjà une, cette commande imprime les détails). Notez le principalId champ dans la sortie. Vous utiliserez cet ID pour faire référence à la fonction afin de pouvoir lui accorder des autorisations à l’étape suivante.
```
az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
```
Utilisez la principalId valeur dans la commande suivante afin d’affecter à la fonction le rôle de Propriétaire des données Azure Digital Twins pour votre instance Azure Digital Twins.
```
az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"
```

Configurer les paramètres de l’application

Ensuite, rendez l’URL de votre instance Azure Digital Twins accessible à votre fonction en définissant une variable d’environnement pour celle-ci.

Conseil

L’URL de l’instance Azure Digital Twins est créée en ajoutant https:// au début du nom d’hôte de votre instance. Pour afficher le nom d’hôte, ainsi que toutes les propriétés de votre instance, exécutez az dt show --dt-name <your-Azure-Digital-Twins-instance>.

La commande suivante définit une variable d’environnement pour l’URL d’instance que votre fonction utilisera chaque fois qu’elle aura besoin d’accéder à l’instance.

az functionapp config appsettings set --resource-group <your-resource-group> --name <your-function-app-name> --settings "ADT_SERVICE_URL=https://<your-Azure-Digital-Twins-instance-host-name>"

Connecter la fonction à IoT Hub

Dans cette section, vous allez configurer votre fonction comme destination d’événement pour les données de l’appareil IoT Hub. Configurer ainsi votre fonction permet de veiller à ce que les données du thermostat dans IoT Hub soient envoyées à la fonction Azure à des fins de traitement.

Utilisez la commande CLI suivante pour créer un abonnement aux événements qu’IoT Hub utilisera pour envoyer des données d’événement à la fonction IoTHubtoTwins. Un espace réservé vous permet de saisir un nom pour l'abonnement à l'événement, ainsi que l'ID de l'abonnement, le groupe de ressources, le nom du hub IoT et le nom de votre application de fonction.

az eventgrid event-subscription create --name <name-for-hub-event-subscription> --event-delivery-schema eventgridschema --source-resource-id /subscriptions/<your-subscription-ID>/resourceGroups/<your-resource-group>/providers/Microsoft.Devices/IotHubs/<your-IoT-hub> --included-event-types Microsoft.Devices.DeviceTelemetry --endpoint-type azurefunction --endpoint /subscriptions/<your-subscription-ID>/resourceGroups/<your-resource-group>/providers/Microsoft.Web/sites/<your-function-app>/functions/IoTHubtoTwins

La sortie affiche des informations sur l’abonnement aux événements qui a été créé. Vous pouvez confirmer que l’opération s’est terminée correctement en vérifiant la valeur provisioningState dans le résultat :

"provisioningState": "Succeeded",

Tester avec des données IoT simulées

Vous pouvez tester votre nouvelle fonction d’entrée en utilisant le simulateur d’appareil à partir de Connecter une solution de bout en bout. Le projet DeviceSimulator contient un thermostat simulé qui envoie des exemples de données de température. Pour configurer le simulateur d’appareil, procédez comme suit :

Accédez au référentiel de projet d’exemple de projet Azure Digital Twins de bout en bout. Pour obtenir l’exemple de projet sur votre machine en sélectionnant le bouton Parcourir le code sous le titre. Vous accédez alors au dépôt GitHub d’exemples, que vous pouvez télécharger sous forme de fichier .zip en sélectionnant le bouton Code, puis Télécharger le ZIP.

Cela entraîne le téléchargement d’un fichier nommé digital-twins-samples-main.zip sur votre machine. Décompressez le dossier et extrayez les fichiers. Vous utiliserez le dossier du projet DeviceSimulator.
Inscrire l’appareil simulé auprès d’IoT Hub
Configurer et exécuter la simulation

Une fois ces étapes terminées, vous devez disposer d’une fenêtre de console de projet en cours d’exécution et d’envoi de données de télémétrie d’appareil simulées à votre hub IoT.

Screenshot of the output from the device simulator project.

Valider les résultats

Lors de l’exécution du simulateur d’appareil ci-dessus, la valeur de température du thermostat de votre jumeau numérique sera modifiée. Dans Azure CLI, exécutez la commande suivante pour afficher la valeur de la température. 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 twin query --query-command "SELECT * FROM digitaltwins WHERE \$dtId = 'thermostat67'" --dt-name <instance-hostname-or-name>

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 le caractère $ dans la requête différemment afin qu’il soit analysé correctement. Pour plus d’informations, consultez Utiliser des caractères spéciaux dans différents shells.

Votre sortie doit afficher les détails du jumeau thermostat67, y compris une valeur de température, comme suit :

{
  "result": [
    {
      "$dtId": "thermostat67",
      "$etag": "W/\"dbf2fea8-d3f7-42d0-8037-83730dc2afc5\"",
      "$metadata": {
        "$model": "dtmi:contosocom:DigitalTwins:Thermostat;1",
        "Temperature": {
          "lastUpdateTime": "2021-06-03T17:05:52.0062638Z"
        }
      },
      "Temperature": 70.20518558807913
    }
  ]
}

Pour voir la modification de la valeur Temperature, exécutez à plusieurs reprises la commande de requête ci-dessus.

Étapes suivantes

Pour en savoir plus sur l’entrée et la sortie de données avec Azure Digital Twins :

Entrée et sortie des données

Partager via

Ingérer des données de télémétrie IoT Hub dans Azure Digital Twins

Prérequis

Exemple de scénario de télémétrie

Ajouter un modèle et un jumeau

Créer la fonction Azure

Configurer l’application de fonction

Attribuer un rôle d’accès

Configurer les paramètres de l’application

Connecter la fonction à IoT Hub

Tester avec des données IoT simulées

Valider les résultats

Étapes suivantes

Commentaires

Ressources supplémentaires