Integrera Azure Digital Twins med Azure Time Series Insights

  • Artikel

I den här artikeln lär du dig att integrera Azure Digital Twins med Azure Time Series Insights (TSI).

Lösningen som beskrivs i den här artikeln använder Time Series Insights för att samla in och analysera historiska data om din IoT-lösning. Azure Digital Twins passar bra för att mata in data i Time Series Insights, eftersom du kan korrelera flera dataströmmar och standardisera din information innan du skickar den till Time Series Insights.

Tips

Det enklaste sättet att analysera historiska tvillingdata över tid är att använda funktionen för datahistorik för att ansluta en Azure Digital Twins-instans till ett Azure Data Explorer-kluster, så att grafuppdateringar automatiskt historiseras till Azure Data Explorer. Du kan sedan köra frågor mot dessa data i Azure Data Explorer med hjälp av Azure Digital Twins-frågeplugin-programmet för Azure Data Explorer. Om du inte behöver använda Time Series Insights specifikt kan du överväga det här alternativet för en enklare integreringsupplevelse.

Förutsättningar

Innan du kan konfigurera en relation med Time Series Insights måste du konfigurera följande resurser:

Tips

I den här artikeln uppdateras de föränderliga digitala tvillingvärdena som visas i Time Series Insights manuellt för enkelhetens skull. Men om du vill slutföra den här artikeln med realtidssimulerade data kan du konfigurera en Azure-funktion som uppdaterar digitala tvillingar baserat på IoT-telemetrihändelser från en simulerad enhet. Instruktioner finns i Mata in IoT Hub data, inklusive de sista stegen för att köra enhetssimulatorn och verifiera att dataflödet fungerar.

Leta senare efter ett annat TIPS som visar var du kan börja köra enhetssimulatorn och låta dina Azure-funktioner uppdatera tvillingarna automatiskt, i stället för att skicka manuella uppdateringskommandon för digitala tvillingar.

Lösningsarkitektur

Du kommer att koppla Time Series Insights till Azure Digital Twins via följande sökväg.

Diagram över Azure-tjänster i ett scenario från slutpunkt till slutpunkt som visar Time Series Insights.

Skapa en namnrymd för Event Hubs

Innan du skapar händelsehubbarna skapar du först ett Event Hubs-namnområde som tar emot händelser från din Azure Digital Twins-instans. Du kan antingen använda Azure CLI-anvisningarna nedan eller använda Azure Portal genom att följa Skapa en händelsehubb med hjälp av Azure Portal. Om du vill se vilka regioner som stöder Event Hubs går du till Tillgängliga Azure-produkter per region.

az eventhubs namespace create --name <name-for-your-Event-Hubs-namespace> --resource-group <your-resource-group> --location <region>

Tips

Om du får felmeddelandet BadRequest: The specified service namespace is invalid.kontrollerar du att namnet som du har valt för namnområdet uppfyller namngivningskraven som beskrivs i det här referensdokumentet: Skapa namnområde.

Du kommer att använda det här Event Hubs-namnområdet för att lagra de två händelsehubbar som behövs för den här artikeln:

  1. Twins Hub – Händelsehubb för att ta emot tvillingändringshändelser
  2. Tidsseriehubb – Händelsehubb för att strömma händelser till Time Series Insights

I nästa avsnitt går vi igenom hur du skapar och konfigurerar dessa hubbar i händelsehubbens namnområde.

Skapa en twins-hubb

Den första händelsehubben som du skapar i den här artikeln är twins-hubben. Den här händelsehubben tar emot dubbla ändringshändelser från Azure Digital Twins. Om du vill konfigurera twins-hubben utför du följande steg i det här avsnittet:

  1. Skapa tvillinghubben
  2. Skapa en auktoriseringsregel för att styra behörigheter till hubben
  3. Skapa en slutpunkt i Azure Digital Twins som använder auktoriseringsregeln för att få åtkomst till hubben
  4. Skapa en väg i Azure Digital Twins som skickar tvillinguppdateringshändelsen till slutpunkten och den anslutna twins-hubben
  5. Hämta anslutningssträngen för twins-hubben

Skapa twins-hubben med följande CLI-kommando. Ange ett namn för din twins-hubb.

az eventhubs eventhub create --name <name-for-your-twins-hub> --resource-group <your-resource-group> --namespace-name <your-Event-Hubs-namespace-from-earlier>

Skapa en auktoriseringsregel för twins-hubb

Skapa en auktoriseringsregel med behörighet att skicka och ta emot. Ange ett namn för regeln.

az eventhubs eventhub authorization-rule create --rights Listen Send --name <name-for-your-twins-hub-auth-rule> --resource-group <your-resource-group> --namespace-name <your-Event-Hubs-namespace-from-earlier> --eventhub-name <your-twins-hub-from-earlier>

Skapa hubbslutpunkt för tvillingar

Skapa en Azure Digital Twins-slutpunkt som länkar din händelsehubb till din Azure Digital Twins-instans. Ange ett namn för din twins-hubbslutpunkt.

az dt endpoint create eventhub --dt-name <your-Azure-Digital-Twins-instance-name> --eventhub-resource-group <your-resource-group> --eventhub-namespace <your-Event-Hubs-namespace-from-earlier> --eventhub <your-twins-hub-name-from-earlier> --eventhub-policy <your-twins-hub-auth-rule-from-earlier> --endpoint-name <name-for-your-twins-hub-endpoint>

Skapa händelseväg för Twins Hub

Azure Digital Twins-instanser kan generera dubbla uppdateringshändelser när en tvillings tillstånd uppdateras. I det här avsnittet skapar du en Azure Digital Twins-händelseväg som dirigerar dessa uppdateringshändelser till twins-hubben för vidare bearbetning.

Skapa en väg i Azure Digital Twins för att skicka tvillinguppdateringshändelser till slutpunkten ovan. Filtret i den här vägen tillåter endast att tvillinguppdateringsmeddelanden skickas till slutpunkten. Ange ett namn för händelsevägen för twins-hubben. För platshållaren för Azure Digital Twins-instansnamn i det här kommandot kan du använda det egna namnet eller värdnamnet för att få bättre prestanda.

az dt route create --dt-name <your-Azure-Digital-Twins-instance-hostname-or-name> --endpoint-name <your-twins-hub-endpoint-from-earlier> --route-name <name-for-your-twins-hub-event-route> --filter "type = 'Microsoft.DigitalTwins.Twin.Update'"

Hämta anslutningssträng för twins-hubb

Hämta anslutningssträngen för twins-händelsehubben med hjälp av de auktoriseringsregler som du skapade ovan för twins-hubben.

az eventhubs eventhub authorization-rule keys list --resource-group <your-resource-group> --namespace-name <your-Event-Hubs-namespace-from-earlier> --eventhub-name <your-twins-hub-from-earlier> --name <your-twins-hub-auth-rule-from-earlier>

Anteckna värdet primaryConnectionString från resultatet för att konfigurera inställningen för twins hub-appen senare i den här artikeln.

Skapa tidsseriehubben

Den andra händelsehubben som du skapar i den här artikeln är tidsseriehubben. Den här händelsehubben kommer att strömma Azure Digital Twins-händelser till Time Series Insights. Du konfigurerar tidsseriehubben genom att utföra följande steg:

  1. Skapa tidsseriehubben
  2. Skapa en auktoriseringsregel för att styra behörigheter till hubben
  3. Hämta anslutningssträngen för tidsseriehubben

Senare, när du skapar Time Series Insights-instansen, ansluter du den här tidsseriehubben som händelsekälla för Time Series Insights-instansen.

Skapa tidsseriehubben med följande kommando. Ange ett namn för tidsseriehubben.

 az eventhubs eventhub create --name <name-for-your-time-series-hub> --resource-group <your-resource-group> --namespace-name <your-Event-Hub-namespace-from-earlier>

Skapa auktoriseringsregel för tidsseriehubben

Skapa en auktoriseringsregel med behörighet att skicka och ta emot. Ange ett namn för autentiseringsregeln för tidsseriehubben.

az eventhubs eventhub authorization-rule create --rights Listen Send --name <name-for-your-time-series-hub-auth-rule> --resource-group <your-resource-group> --namespace-name <your-Event-Hub-namespace-from-earlier> --eventhub-name <your-time-series-hub-name-from-earlier>

Hämta anslutningssträng för tidsseriehubben

Hämta anslutningssträngen för tidsseriehubben med hjälp av de auktoriseringsregler som du skapade ovan för tidsseriehubben:

az eventhubs eventhub authorization-rule keys list --resource-group <your-resource-group> --namespace-name <your-Event-Hub-namespace-from-earlier> --eventhub-name <your-time-series-hub-name-from-earlier> --name <your-time-series-hub-auth-rule-from-earlier>

Anteckna värdet primaryConnectionString från resultatet för att konfigurera appinställningen för time series hub senare i den här artikeln.

Anteckna även följande värden för att använda dem senare för att skapa en Time Series Insights-instans.

  • Namnområde för händelsehubb
  • Namn på tidsseriehubben
  • Autentiseringsregel för tidsseriehubben

Skapa en funktion

I det här avsnittet skapar du en Azure-funktion som konverterar tvillinguppdateringshändelser från deras ursprungliga formulär som JSON-korrigeringsdokument till JSON-objekt som bara innehåller uppdaterade och tillagda värden från dina tvillingar.

  1. Skapa först ett nytt funktionsappprojekt.

    Du kan göra detta med hjälp av Visual Studio (instruktioner finns i Utveckla Azure Functions med Visual Studio), Visual Studio Code (anvisningar finns i Skapa en C#-funktion i Azure med Visual Studio Code) eller Azure CLI (instruktioner finns i Skapa en C#-funktion i Azure från kommandoraden).

  2. Skapa en ny Azure-funktion med namnet ProcessDTUpdatetoTSI.cs för att uppdatera enhetens telemetrihändelser till Time Series Insights. Funktionstypen är Händelsehubbutlösare.

    Skärmbild av Visual Studio för att skapa en ny Azure-funktion av typen händelsehubbutlösare.

  3. Lägg till följande paket i projektet (du kan använda Visual Studio NuGet-pakethanteraren eller kommandot dotnet add package i ett kommandoradsverktyg).

  4. Ersätt koden i filen ProcessDTUpdatetoTSI.cs med följande kod:

    using System.Collections.Generic;
using System.Threading.Tasks;
using System.Text;
using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using Azure.Messaging.EventHubs;

namespace UpdateTSI
{
    public static class ProcessDTUpdatetoTSI
    { 
        [FunctionName("ProcessDTUpdatetoTSI")]
        public static async Task Run(
            [EventHubTrigger("twins-event-hub", Connection = "EventHubAppSetting-Twins")]EventData myEventHubMessage,
            [EventHub("tsi-event-hub", Connection = "EventHubAppSetting-TSI")]IAsyncCollector<string> outputEvents,
            ILogger log)
        {
            JObject message = (JObject)JsonConvert.DeserializeObject(Encoding.UTF8.GetString(myEventHubMessage.Body));
            log.LogInformation($"Reading event: {message}");

            // Read values that are replaced or added
            var tsiUpdate = new Dictionary<string, object>();
            foreach (var operation in message["patch"])
            {
                if (operation["op"].ToString() == "replace" || operation["op"].ToString() == "add")
                {
                    //Convert from JSON patch path to a flattened property for TSI
                    //Example input: /Front/Temperature
                    //        output: Front.Temperature
                    string path = operation["path"].ToString().Substring(1);
                    path = path.Replace("/", ".");
                    tsiUpdate.Add(path, operation["value"]);
                }
            }
            // Send an update if updates exist
            if (tsiUpdate.Count > 0)
            {
                tsiUpdate.Add("$dtId", myEventHubMessage.Properties["cloudEvents:subject"]);
                await outputEvents.AddAsync(JsonConvert.SerializeObject(tsiUpdate));
            }
        }
    }
}

    Spara funktionskoden.

  5. Publicera projektet med funktionen ProcessDTUpdatetoTSI.cs till en funktionsapp i Azure.

    Anvisningar om hur du publicerar funktionen med Visual Studio finns i Utveckla Azure Functions med Visual Studio. Anvisningar om hur du publicerar funktionen med Visual Studio Code finns i Skapa en C#-funktion i Azure med Visual Studio Code. Anvisningar om hur du publicerar funktionen med hjälp av Azure CLI finns i Skapa en C#-funktion i Azure från kommandoraden.

Spara funktionsappens namn som ska användas senare för att konfigurera appinställningar för de två händelsehubbarna.

Konfigurera funktionsappen

Tilldela sedan en åtkomstroll för funktionen och konfigurera programinställningarna så att den kan komma åt dina resurser.

Kör följande kommandon i Azure Cloud Shell eller ett lokalt Azure CLI.

Anteckning

Det här avsnittet måste slutföras av en Azure-användare som har behörighet att hantera användaråtkomst till Azure-resurser, inklusive att bevilja och delegera behörigheter. Vanliga roller som uppfyller detta krav är ägare, kontoadministratör eller kombinationen av administratör och deltagare för användaråtkomst. Mer information om behörighetskrav för Azure Digital Twins-roller finns i Konfigurera en instans och autentisering.

Tilldela en åtkomstroll

Azure-funktionen kräver att en ägartoken skickas till den. För att kontrollera att ägartoken skickas beviljar du funktionsappen rollen Azure Digital Twins-dataägare för din Azure Digital Twins-instans, vilket ger funktionsappen behörighet att utföra dataplansaktiviteter på instansen.

  1. Använd följande kommando för att skapa en systemhanterad identitet för funktionen (om funktionen redan har en, skriver det här kommandot ut dess information). Anteckna fältet principalId i utdata. Du använder det här ID:t för att referera till funktionen så att du kan ge den behörighet i nästa steg.

    az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>

  2. principalId Använd värdet i följande kommando för att ge funktionen rollen Azure Digital Twins-dataägare för din Azure Digital Twins-instans.

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

Konfigurera programinställningar

Gör sedan URL:en för din Azure Digital Twins-instans tillgänglig för din funktion genom att ange en miljövariabel för den.

Tips

Azure Digital Twins-instansens URL görs genom att lägga till https:// i början av instansens värdnamn. Om du vill se värdnamnet, tillsammans med alla egenskaper för din instans, kör du az dt show --dt-name <your-Azure-Digital-Twins-instance>.

Följande kommando anger en miljövariabel för instansens URL som din funktion ska använda när den behöver åtkomst till instansen.

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

Lägg sedan till miljövariabler i funktionsappens inställningar som gör att den kan komma åt tvillinghubben och tidsseriehubben.

Använd värdet för twins hub primaryConnectionString som du sparade tidigare för att skapa en appinställning i funktionsappen som innehåller anslutningssträngen för Twins Hub:

az functionapp config appsettings set --settings "EventHubAppSetting-Twins=<your-twins-hub-primaryConnectionString>" --resource-group <your-resource-group> --name <your-function-app-name>

Använd värdet för time series hub primaryConnectionString som du sparade tidigare för att skapa en appinställning i funktionsappen som innehåller anslutningssträngen för tidsseriehubben:

az functionapp config appsettings set --settings "EventHubAppSetting-TSI=<your-time-series-hub-primaryConnectionString>" --resource-group <your-resource-group> --name <your-function-app-name>

Skapa och ansluta en Time Series Insights-instans

I det här avsnittet konfigurerar du Time Series Insights-instansen för att ta emot data från din tidsseriehubb. Mer information om den här processen finns i Konfigurera en Azure Time Series Insights Gen2 PAYG-miljö. Följ stegen nedan för att skapa en Time Series Insights-miljö.

  1. I Azure Portal söker du efter Time Series Insights-miljöer och väljer knappen Skapa. Välj följande alternativ för att skapa tidsseriemiljön.

    • Prenumeration – Välj din prenumeration.
      • Resursgrupp – Välj din resursgrupp.
    • Miljönamn – Ange ett namn för tidsseriemiljön.
    • Plats – Välj en plats.
    • Nivå – Välj prisnivån Gen2(L1).
    • Egenskapsnamn – Ange $dtId (Läs mer om att välja ett ID-värde i Metodtips för att välja ett Tidsserie-ID).
    • Lagringskontonamn – Ange ett lagringskontonamn.
    • Aktivera varmt lager – Lämna fältet inställt på Ja.

    Du kan lämna standardvärden för andra egenskaper på den här sidan. Välj knappen Nästa: Händelsekälla > .

    Skärmbild av Azure Portal som visar hur du skapar Time Series Insights-miljön (del 1/3).

    Skärmbild av Azure Portal som visar hur du skapar Time Series Insights-miljön (del 2/3).

  2. På fliken Händelsekälla väljer du följande fält:

    • Vill du skapa en händelsekälla? – Välj Ja.
    • Källtyp – Välj Händelsehubb.
    • Namn – Ange ett namn för händelsekällan.
    • Prenumeration – Välj din Azure-prenumeration.
    • Event Hub-namnområde – Välj det namnområde som du skapade tidigare i den här artikeln.
    • Event Hub-namn – Välj namnet på tidsseriehubben som du skapade tidigare i den här artikeln.
    • Namn på händelsehubbens åtkomstprincip – Välj den autentiseringsregel för tidsseriehubben som du skapade tidigare i den här artikeln.
    • Händelsehubbens konsumentgrupp – Välj Ny och ange ett namn för din konsumentgrupp för händelsehubben. Välj sedan Lägg till.
    • Egenskapsnamn – Lämna fältet tomt.

    Välj knappen Granska + skapa för att granska all information. Välj sedan knappen Granska + skapa igen för att skapa tidsseriemiljön.

    Skärmbild av Azure Portal som visar hur du skapar Time Series Insights-miljön (del 3/3).

Skicka IoT-data till Azure Digital Twins

Om du vill börja skicka data till Time Series Insights måste du börja uppdatera egenskaperna för digitala tvillingar i Azure Digital Twins med att ändra datavärden.

Använd cli-kommandot az dt twin update för att uppdatera en egenskap på tvillingen som du lade till i avsnittet Förutsättningar . Om du har använt instruktionerna för tvillingskapande från Mata in telemetri från IoT Hub) kan du använda följande kommando i den lokala CLI- eller Cloud Shell bash-terminalen för att uppdatera temperaturegenskapen på termostat67-tvillingen. Det finns en platshållare för Azure Digital Twins-instansens värdnamn (du kan också använda instansens eget namn med en liten minskning av prestanda).

az dt twin update --dt-name <your-Azure-Digital-Twins-instance-hostname-or-name> --twin-id thermostat67 --json-patch '{"op":"replace", "path":"/Temperature", "value": 20.5}'

Upprepa kommandot minst 4 gånger till med olika egenskapsvärden för att skapa flera datapunkter som kan observeras senare i Time Series Insights-miljön.

Tips

Om du vill slutföra den här artikeln med realtidssimulerade data i stället för att uppdatera värdena för digitala tvillingar manuellt kontrollerar du först att du har slutfört TIPS från avsnittet Förutsättningar för att konfigurera en Azure-funktion som uppdaterar tvillingar från en simulerad enhet. Därefter kan du köra enheten nu för att börja skicka simulerade data och uppdatera din digitala tvilling via det dataflödet.

Visualisera dina data i Time Series Insights

Nu bör data flöda till din Time Series Insights-instans, redo att analyseras. Följ stegen nedan för att utforska de data som kommer in.

  1. I Azure Portal söker du efter namnet på tidsseriemiljön som du skapade tidigare. I menyalternativen till vänster väljer du Översikt för att se URL:en för Time Series Insights Explorer. Välj URL:en för att visa temperaturändringarna som återspeglas i Time Series Insights-miljön.

    Skärmbild av Azure Portal som visar Time Series Insights-utforskarens URL på översiktsfliken i Time Series Insights-miljön.

  2. I utforskaren visas tvillingarna i Azure Digital Twins-instansen till vänster. Välj den tvilling som du har redigerat egenskaper för, välj den egenskap som du har ändrat och välj Lägg till.

    Skärmbild av Time Series Insights-utforskaren med stegen för att välja termostat67, välj egenskapstemperatur och välj Lägg till markerat.

  3. Nu bör du se de egenskapsändringar som du har gjort i diagrammet, enligt nedan.

    Skärmbild av Time Series Insights-utforskaren med inledande temperaturdata som visar en rad slumpmässiga värden mellan 68 och 85.

Om du tillåter att en simulering körs mycket längre ser visualiseringen ut ungefär så här:

Skärmbild av Time Series Insights-utforskaren där temperaturdata för varje tvilling visas i tre parallella rader med olika färger.

Nästa steg

När du har upprättat en datapipeline för att skicka tidsseriedata från Azure Digital Twins till Time Series Insights kanske du vill tänka på hur du översätter tillgångsmodeller som är utformade för Azure Digital Twins till tillgångsmodeller för Time Series Insights. En självstudie om nästa steg i integreringsprocessen finns i Modellsynkronisering mellan Azure Digital Twins och Time Series Insights Gen2.