Inserire hub IoT dati di telemetria in Gemelli digitali di Azure

Articolo
01/04/2024

Questa guida illustra il processo di scrittura di una funzione in grado di inserire i dati di telemetria dei dispositivi da hub IoT e inviarli a un'istanza di Gemelli digitali di Azure.

Gemelli digitali di Azure è basato sui dati dei dispositivi IoT e di altre origini. Un'origine comune per i dati dei dispositivi da usare in Gemelli digitali di Azure è hub IoT.

Il processo per l'inserimento di dati in Gemelli digitali di Azure consiste nel configurare una risorsa di calcolo esterna, ad esempio una funzione creata usando Funzioni di Azure. La funzione riceve i dati e usa le API DigitalTwins per impostare le proprietà o generare eventi di telemetria sui gemelli digitali di conseguenza.

Questo documento di procedura illustra il processo di scrittura di una funzione in grado di inserire dati di telemetria del dispositivo da hub IoT.

Prerequisiti

Prima di continuare con questo esempio, è necessario configurare le risorse seguenti come prerequisiti:

Un hub IoT. Per istruzioni, vedere la sezione Creare un hub IoT di questa guida introduttiva hub IoT.
Istanza di Gemelli digitali di Azure che riceverà i dati di telemetria del dispositivo. Per istruzioni, vedere Configurare un'istanza e l'autenticazione di Gemelli digitali di Azure.

Scenario di telemetria di esempio

Questa procedura illustra come inviare messaggi da hub IoT a Gemelli digitali di Azure usando una funzione in Azure. Esistono molte possibili configurazioni e strategie di corrispondenza che è possibile usare per l'invio di messaggi, ma l'esempio per questo articolo contiene le parti seguenti:

Un dispositivo termostato in hub IoT, con un ID dispositivo noto
Un gemello digitale per rappresentare il dispositivo, con un ID corrispondente

Nota

In questo esempio viene usata una corrispondenza ID semplice tra l'ID del dispositivo e l'ID del gemello digitale corrispondente, ma è possibile definire mapping più sofisticati dal dispositivo al gemello, ad esempio con una tabella di mapping.

Ogni volta che un evento di telemetria della temperatura viene inviato dal dispositivo termostato, una funzione elabora i dati di telemetria e la Temperature proprietà del gemello digitale deve essere aggiornata. Questo scenario è descritto in un diagramma seguente:

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.

Aggiungere un modello e un gemello

In questa sezione verrà configurato un gemello digitale in Gemelli digitali di Azure che rappresenterà il dispositivo termostato e verrà aggiornato con le informazioni di hub IoT.

Per creare un dispositivo gemello di tipo termostato, è prima necessario caricare il modello di termostato nell'istanza, che descrive le proprietà di un termostato e verrà usato in un secondo momento per creare il gemello.

Il modello ha un aspetto simile al seguente:

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

Per caricare questo modello nell'istanza di gemelli, eseguire il comando seguente dell'interfaccia della riga di comando di Azure, che carica il modello precedente come JSON inline. È possibile eseguire il comando in Azure Cloud Shell nel browser (usare l'ambiente Bash) o nel computer se l'interfaccia della riga di comando è installata in locale. Esiste un segnaposto per il nome host dell'istanza(è anche possibile usare il nome descrittivo dell'istanza con un lieve calo delle prestazioni).

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"    }  ]}'

Nota

Se si usa qualcosa di diverso da Cloud Shell nell'ambiente Bash, potrebbe essere necessario eseguire l'escape di determinati caratteri nel codice JSON inline in modo che venga analizzato correttamente. Per altre informazioni, vedere Usare caratteri speciali in shell diverse.

Sarà quindi necessario creare un gemello usando questo modello. Usare il comando seguente per creare un gemello termostato denominato thermostat67 e impostare 0,0 come valore di temperatura iniziale. Esiste un segnaposto per il nome host dell'istanza(è anche possibile usare il nome descrittivo dell'istanza con un lieve calo delle prestazioni).

az dt twin create  --dt-name <instance-hostname-or-name> --dtmi "dtmi:contosocom:DigitalTwins:Thermostat;1" --twin-id thermostat67 --properties '{"Temperature": 0.0}'

Quando il gemello viene creato correttamente, l'output dell'interfaccia della riga di comando del comando dovrebbe essere simile al seguente:

{
  "$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
}

Creare la funzione di Azure

In questa sezione si creerà una funzione di Azure per accedere a Gemelli digitali di Azure e aggiornare i gemelli in base agli eventi di telemetria dei dispositivi IoT ricevuti. Seguire questa procedura per creare e pubblicare la funzione.

Creare prima di tutto un nuovo progetto di Funzioni di Azure di tipo trigger di Griglia di eventi.

A tale scopo, usare Visual Studio (per istruzioni, vedere Sviluppare Funzioni di Azure con Visual Studio), Visual Studio Code (per istruzioni, vedere Creare una funzione C# in Azure con Visual Studio Code) o l'interfaccia della riga di comando di Azure (per istruzioni, vedere Creare una funzione C# in Azure dalla riga di comando).
Aggiungere i pacchetti seguenti al progetto (è possibile usare Gestione pacchetti NuGet di Visual Studio o il comando dotnet add package in uno strumento da riga di comando).

Creare una funzione all'interno del progetto denominato IoTHubtoTwins.cs. Incollare il codice seguente nel file di funzione:

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

Salvare il codice della funzione.

Pubblicare il progetto con la funzione IoTHubtoTwins.cs in un'app per le funzioni in Azure.

Per istruzioni su come pubblicare la funzione con Visual Studio, vedere Sviluppare Funzioni di Azure con Visual Studio. Per istruzioni su come pubblicare la funzione con Visual Studio Code, vedere Creare una funzione C# in Azure con Visual Studio Code. Per istruzioni su come pubblicare la funzione usando l'interfaccia della riga di comando di Azure, vedere Creare una funzione C# in Azure dalla riga di comando.

Al termine del processo di pubblicazione della funzione, è possibile usare questo comando dell'interfaccia della riga di comando di Azure per verificare che la pubblicazione abbia avuto esito positivo. Sono disponibili segnaposto per il gruppo di risorse e il nome dell'app per le funzioni. Il comando stampa informazioni sulla funzione IoTHubToTwins .

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

Configurare l'app per le funzioni

Per accedere a Gemelli digitali di Azure, l'app per le funzioni necessita di un'identità gestita assegnata dal sistema con autorizzazioni per accedere all'istanza di Gemelli digitali di Azure. Questa sezione verrà configurata assegnando un ruolo di accesso per la funzione e configurando le impostazioni dell'applicazione in modo che possa accedere all'istanza di Gemelli digitali di Azure.

Eseguire i comandi seguenti in Azure Cloud Shell o in un'interfaccia della riga di comando di Azure locale.

Nota

Questa sezione deve essere completata da un utente di Azure che dispone delle autorizzazioni per gestire l'accesso utente alle risorse di Azure, inclusa la concessione e la delega delle autorizzazioni. I ruoli comuni che soddisfano questo requisito sono Proprietario, Amministratore account o combinazione di Accesso utenti Amministrazione istrator e Collaboratore. Per altre informazioni sui requisiti di autorizzazione per i ruoli di Gemelli digitali di Azure, vedere Configurare un'istanza e l'autenticazione.

Assegnare un ruolo di accesso

La funzione di Azure richiede il passaggio di un token di connessione. Per assicurarsi che il token di connessione venga passato, concedere all'app per le funzioni il ruolo Proprietario dati di Gemelli digitali di Azure per l'istanza di Gemelli digitali di Azure, che consentirà all'app per le funzioni di eseguire attività del piano dati nell'istanza.

Usare il comando seguente per creare un'identità gestita dal sistema per la funzione ( se la funzione ne ha già una, questo comando ne stamperà i dettagli). Prendere nota del principalId campo nell'output. Questo ID verrà usato per fare riferimento alla funzione in modo che sia possibile concedere le autorizzazioni nel passaggio successivo.
```
az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
```
Usare il principalId valore nel comando seguente per assegnare alla funzione il ruolo Proprietario dati di Gemelli digitali di Azure per l'istanza di Gemelli digitali di Azure.
```
az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"
```

Configurare le impostazioni dell'applicazione

Rendere quindi accessibile l'URL dell'istanza di Gemelli digitali di Azure alla funzione impostando una variabile di ambiente.

Suggerimento

L'URL dell'istanza di Gemelli digitali di Azure viene creato aggiungendo https:// all'inizio del nome host dell'istanza. Per visualizzare il nome host, insieme a tutte le proprietà dell'istanza, eseguire az dt show --dt-name <your-Azure-Digital-Twins-instance>.

Il comando seguente imposta una variabile di ambiente per l'URL dell'istanza che verrà usata dalla funzione ogni volta che deve accedere all'istanza.

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>"

Connessione la funzione da hub IoT

In questa sezione si configurerà la funzione come destinazione eventi per i dati del dispositivo dell'hub IoT. La configurazione della funzione in questo modo garantisce che i dati del dispositivo termostato in hub IoT verranno inviati alla funzione di Azure per l'elaborazione.

Usare il comando dell'interfaccia della riga di comando seguente per creare una sottoscrizione di eventi che verrà usata dal hub IoT per inviare i dati dell'evento alla funzione IoTHubtoTwins. È disponibile un segnaposto per immettere un nome per la sottoscrizione di eventi e sono disponibili anche segnaposto per immettere l'ID sottoscrizione, il gruppo di risorse, il nome dell'hub IoT e il nome dell'app per le funzioni.

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

L'output mostrerà informazioni sulla sottoscrizione di eventi creata. È possibile verificare che l'operazione sia stata completata correttamente verificando il provisioningState valore nel risultato:

"provisioningState": "Succeeded",

Eseguire test con dati IoT simulati

È possibile testare la nuova funzione di ingresso usando il simulatore di dispositivi da Connessione una soluzione end-to-end. Il progetto DeviceSimulator contiene un dispositivo termostato simulato che invia dati di temperatura di esempio. Per configurare il simulatore di dispositivi, seguire questa procedura:

Passare al repository di progetti end-to-end di Gemelli digitali di Azure. Ottenere il progetto di esempio nel computer selezionando il pulsante Sfoglia codice sotto il titolo. Verrà visualizzato il repository GitHub per gli esempi, che è possibile scaricare come file ZIP selezionando il pulsante Codice seguito da Scarica ZIP.

Verrà scaricata una cartella zip nel computer come digital-twins-samples-main.zip. Decomprimere la cartella ed estrarre i file. Si userà la cartella del progetto DeviceSimulator .
Registrare il dispositivo simulato con hub IoT
Configurare ed eseguire la simulazione

Dopo aver completato questi passaggi, dovrebbe essere in esecuzione una finestra della console del progetto e l'invio di dati di telemetria dei dispositivi simulati all'hub IoT.

Screenshot of the output from the device simulator project.

Convalidare i risultati

Durante l'esecuzione del simulatore di dispositivi precedente, il valore della temperatura del gemello digitale termostato cambierà. Nell'interfaccia della riga di comando di Azure eseguire il comando seguente per visualizzare il valore della temperatura. Esiste un segnaposto per il nome host dell'istanza(è anche possibile usare il nome descrittivo dell'istanza con un lieve calo delle prestazioni).

az dt twin query --query-command "SELECT * FROM digitaltwins WHERE \$dtId = 'thermostat67'" --dt-name <instance-hostname-or-name>

Nota

Se si usa qualcosa di diverso da Cloud Shell nell'ambiente Bash, potrebbe essere necessario eseguire l'escape del $ carattere nella query in modo diverso in modo che venga analizzato correttamente. Per altre informazioni, vedere Usare caratteri speciali in shell diverse.

L'output dovrebbe mostrare i dettagli del gemello thermostat67, incluso un valore di temperatura, come illustrato di seguito:

{
  "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
    }
  ]
}

Per visualizzare la modifica del Temperature valore, eseguire ripetutamente il comando di query precedente.

Passaggi successivi

Informazioni sull'ingresso e l'uscita dei dati con Gemelli digitali di Azure:

Ingresso e uscita dei dati

Inserire hub IoT dati di telemetria in Gemelli digitali di Azure

Prerequisiti

Scenario di telemetria di esempio

Aggiungere un modello e un gemello

Creare la funzione di Azure

Configurare l'app per le funzioni

Assegnare un ruolo di accesso

Configurare le impostazioni dell'applicazione

Connessione la funzione da hub IoT

Eseguire test con dati IoT simulati

Convalidare i risultati

Passaggi successivi

Risorse aggiuntive