Ingestování telemetrie IoT Hubu do Azure Digital Twins

Článek
01/04/2024

Tato příručka vás provede procesem zápisu funkce, která dokáže ingestovat telemetrii zařízení ze služby IoT Hub a odeslat ji do instance služby Azure Digital Twins.

Azure Digital Twins se řídí daty ze zařízení IoT a dalších zdrojů. Běžným zdrojem dat zařízení, která se užijí ve službě Azure Digital Twins, je IoT Hub.

Proces ingestování dat do služby Azure Digital Twins spočívá v nastavení externího výpočetního prostředku, například funkce vytvořené pomocí Azure Functions. Funkce přijímá data a používá rozhraní API Služby DigitalTwins k nastavení vlastností nebo vyvolání událostí telemetrie na digitálních dvojčatech odpovídajícím způsobem.

Tento dokument s postupy vás provede procesem zápisu funkce, která dokáže ingestovat telemetrii zařízení ze služby IoT Hub.

Požadavky

Než budete pokračovat v tomto příkladu, budete muset podle požadavků nastavit následující prostředky:

IoT Hub. Pokyny najdete v části Vytvoření ioT Hubu v tomto rychlém startu pro IoT Hub.
Instance Azure Digital Twins, která bude přijímat telemetrii zařízení. Pokyny najdete v tématu Nastavení instance a ověřování služby Azure Digital Twins.

Ukázkový scénář telemetrie

Tento postup popisuje, jak odesílat zprávy ze služby IoT Hub do služby Azure Digital Twins pomocí funkce v Azure. Existuje mnoho možných konfigurací a odpovídajících strategií, které můžete použít pro odesílání zpráv, ale příklad tohoto článku obsahuje následující části:

Termostat zařízení ve službě IoT Hub se známým ID zařízení
Digitální dvojče představující zařízení s odpovídajícím ID

Poznámka:

Tento příklad používá jednoduchou shodu ID mezi ID zařízení a odpovídajícím ID digitálního dvojčete, ale je možné poskytnout sofistikovanější mapování ze zařízení na jeho dvojče (například s tabulkou mapování).

Při každém odeslání události telemetrie teploty zařízením termostatu by se měla aktualizovat funkce, která zpracovává telemetrii a Temperature vlastnost digitálního dvojčete. Tento scénář je popsaný v následujícím diagramu:

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.

Přidání modelu a digitálního dvojčete

V této části nastavíte digitální dvojče ve službě Azure Digital Twins, které bude představovat termostatické zařízení a budou aktualizovány informacemi ze služby IoT Hub.

Pokud chcete vytvořit dvojče typu termostatu, musíte nejprve nahrát termostatický model do vaší instance, který popisuje vlastnosti termostatu a použije se později k vytvoření dvojčete.

Model vypadá takto:

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

Pokud chcete tento model nahrát do instance dvojčat, spusťte následující příkaz Azure CLI, který nahraje výše uvedený model jako vložený JSON. Příkaz můžete spustit v Azure Cloud Shellu v prohlížeči (použít prostředí Bash) nebo na počítači, pokud máte rozhraní příkazového řádku nainstalované místně. Pro název hostitele instance existuje jeden zástupný symbol (můžete také použít popisný název instance s mírným snížením výkonu).

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

Poznámka:

Pokud v prostředí Bash používáte cokoli jiného než Cloud Shell, budete možná muset utéct určitými znaky ve vloženém kódu JSON, aby se správně parsoval. Další informace naleznete v tématu Použití speciálních znaků v různých prostředích.

Pak budete muset vytvořit jedno dvojče pomocí tohoto modelu. Pomocí následujícího příkazu vytvořte dvojče termostatu s názvem termostat67 a nastavte hodnotu 0,0 jako počáteční hodnotu teploty. Pro název hostitele instance existuje jeden zástupný symbol (můžete také použít popisný název instance s mírným snížením výkonu).

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

Po úspěšném vytvoření dvojčete by výstup rozhraní příkazového řádku z příkazu měl vypadat přibližně takto:

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

Vytvoření funkce Azure

V této části vytvoříte funkci Azure pro přístup ke službě Azure Digital Twins a aktualizaci dvojčat na základě událostí telemetrie zařízení IoT, které přijímá. Pomocí následujícího postupu vytvořte a publikujte funkci.

Nejprve vytvořte nový projekt Azure Functions typu triggeru Event Gridu.

Můžete to udělat pomocí sady Visual Studio (pokyny najdete v tématu Vývoj funkcí Azure pomocí sady Visual Studio), Visual Studio Code (pokyny najdete v tématu Vytvoření funkce jazyka C# v Azure pomocí editoru Visual Studio Code) nebo Azure CLI (pokyny najdete v tématu Vytvoření funkce jazyka C# v Azure z příkazového řádku).
Do projektu přidejte následující balíčky (můžete použít správce balíčků NuGet sady Visual Studio nebo příkaz dotnet add package v nástroji příkazového řádku).

Vytvořte funkci v projektu s názvem IoTHubtoTwins.cs. Do souboru funkce vložte následující kód:

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

Uložte kód funkce.

Publikujte projekt pomocí funkce IoTHubtoTwins.cs do aplikace funkcí v Azure.

Pokyny k publikování funkce pomocí sady Visual Studio najdete v tématu Vývoj azure Functions pomocí sady Visual Studio. Pokyny k publikování funkce pomocí editoru Visual Studio Code najdete v tématu Vytvoření funkce jazyka C# v Azure pomocí editoru Visual Studio Code. Pokyny k publikování funkce pomocí Azure CLI najdete v tématu Vytvoření funkce jazyka C# v Azure z příkazového řádku.

Po dokončení procesu publikování funkce můžete pomocí tohoto příkazu Azure CLI ověřit, že publikování proběhlo úspěšně. Pro vaši skupinu prostředků jsou zástupné symboly a název vaší aplikace funkcí. Příkaz zobrazí informace o funkci IoTHubToTwins .

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

Konfigurace aplikace Function App

Pro přístup ke službě Azure Digital Twins potřebuje vaše aplikace funkcí spravovanou identitu přiřazenou systémem s oprávněními pro přístup k vaší instanci služby Azure Digital Twins. Nastavíte to v této části tak, že funkci přiřadíte přístupovou roli a nakonfigurujete nastavení aplikace tak, aby mělo přístup k vaší instanci Azure Digital Twins.

V Azure Cloud Shellu nebo místním Azure CLI spusťte následující příkazy.

Poznámka:

Tuto část musí dokončit uživatel Azure, který má oprávnění ke správě přístupu uživatelů k prostředkům Azure, včetně udělení a delegování oprávnění. Mezi běžné role, které splňují tento požadavek, patří vlastník, správce účtu nebo kombinace uživatelských přístupů Správa istrator a přispěvatel. Další informace o požadavcích na oprávnění pro role Azure Digital Twins najdete v tématu Nastavení instance a ověřování.

Přiřazení přístupové role

Funkce Azure vyžaduje předání nosného tokenu. Aby se zajistilo předání nosného tokenu, udělte aplikaci funkcí roli Vlastník dat Azure Digital Twins pro vaši instanci služby Azure Digital Twins, která aplikaci funkcí udělí oprávnění k provádění aktivit roviny dat v instanci.

Pomocí následujícího příkazu vytvořte identitu spravovanou systémem pro vaši funkci (pokud ji už funkce obsahuje, vytiskne tento příkaz jeho podrobnosti). Poznamenejte si principalId pole ve výstupu. Toto ID použijete k odkazování na funkci, abyste jí mohli udělit oprávnění v dalším kroku.
```
az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
```

principalId Pomocí hodnoty v následujícím příkazu dejte funkci roli Vlastník dat Azure Digital Twins pro vaši instanci Azure Digital Twins.

az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"

Konfigurace nastavení aplikace

Dále nastavte adresu URL vaší instance Azure Digital Twins, která bude přístupná vaší funkci nastavením proměnné prostředí.

Tip

Adresa URL instance Azure Digital Twins se provádí přidáním https:// na začátek názvu hostitele vaší instance. Pokud chcete zobrazit název hostitele spolu se všemi vlastnostmi vaší instance, spusťte az dt show --dt-name <your-Azure-Digital-Twins-instance>příkaz .

Následující příkaz nastaví proměnnou prostředí pro adresu URL vaší instance, kterou bude vaše funkce používat při každém přístupu k instanci.

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

Připojení funkce do IoT Hubu

V této části nastavíte funkci jako cíl události pro data zařízení IoT Hubu. Nastavením funkce tímto způsobem zajistíte, že se data ze zařízení termostatu ve službě IoT Hub odešlou do funkce Azure ke zpracování.

Pomocí následujícího příkazu rozhraní příkazového řádku vytvořte odběr událostí, které ioT Hub použije k odesílání dat událostí do funkce IoTHubtoTwins . Existuje zástupný symbol, který můžete zadat název odběru událostí a můžete také zadat ID předplatného, skupinu prostředků, název centra IoT a název vaší aplikace funkcí.

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

Výstup zobrazí informace o vytvořeném odběru událostí. Ověřením hodnoty ve výsledku můžete ověřit, že se operace úspěšně provisioningState dokončila:

"provisioningState": "Succeeded",

Testování pomocí simulovaných dat IoT

Novou funkci příchozího přenosu dat můžete otestovat pomocí simulátoru zařízení z Připojení kompletního řešení. Projekt DeviceSimulator obsahuje simulované termostatické zařízení, které odesílá ukázková data o teplotě. Pokud chcete nastavit simulátor zařízení, postupujte takto:

Přejděte do kompletního úložiště ukázkových projektů Azure Digital Twins. Ukázkový projekt na svém počítači získáte tak , že pod názvem vyberete tlačítko Procházet kód . Tím přejdete do úložiště GitHubu pro ukázky, které si můžete stáhnout jako soubor .zip tak , že vyberete tlačítko Kód následované stažením SOUBORU ZIP.

Tím stáhnete složku .zip do počítače jako digital-twins-samples-main.zip. Rozbalte složku a extrahujte soubory. Budete používat složku projektu DeviceSimulator .
Registrace simulovaného zařízení ve službě IoT Hub
Konfigurace a spuštění simulace

Po dokončení těchto kroků byste měli mít spuštěné okno konzoly projektu a odesílat telemetrická data simulovaných zařízení do centra IoT.

Screenshot of the output from the device simulator project.

Ověření výsledků

Při spuštění simulátoru zařízení výše se změní hodnota teploty vašeho termostatu digitálního dvojčete. Spuštěním následujícího příkazu v Azure CLI zobrazte hodnotu teploty. Pro název hostitele instance existuje jeden zástupný symbol (můžete také použít popisný název instance s mírným snížením výkonu).

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

Poznámka:

Pokud v prostředí Bash používáte cokoli jiného než Cloud Shell, možná budete muset uchvátit $ znak v dotazu jinak, aby se správně parsoval. Další informace naleznete v tématu Použití speciálních znaků v různých prostředích.

Výstup by měl zobrazit podrobnosti dvojčete termostatu67, včetně hodnoty teploty, například takto:

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

Pokud chcete zobrazit Temperature změnu hodnoty, opakovaně spusťte výše uvedený příkaz dotazu.

Další kroky

Přečtěte si informace o příchozím a výchozím přenosu dat pomocí služby Azure Digital Twins:

Příchozí a výchozí přenos dat

Sdílet prostřednictvím

Ingestování telemetrie IoT Hubu do Azure Digital Twins

Požadavky

Ukázkový scénář telemetrie

Přidání modelu a digitálního dvojčete

Vytvoření funkce Azure

Konfigurace aplikace Function App

Přiřazení přístupové role

Konfigurace nastavení aplikace

Připojení funkce do IoT Hubu

Testování pomocí simulovaných dat IoT

Ověření výsledků

Další kroky

Váš názor

Další materiály