Azure Digital Twins integreren met Azure Time Series Insights

Artikel
03/09/2023

In dit artikel leert u hoe u Azure Digital Twins integreert met Azure Time Series Insights (TSI).

De oplossing die in dit artikel wordt beschreven, maakt gebruik van Time Series Insights om historische gegevens over uw IoT-oplossing te verzamelen en te analyseren. Azure Digital Twins is geschikt voor het invoeren van gegevens in Time Series Insights, omdat u hiermee meerdere gegevensstromen kunt correleren en uw informatie kunt standaardiseren voordat u deze naar Time Series Insights verzendt.

Tip

De eenvoudigste manier om historische dubbelgegevens in de loop van de tijd te analyseren, is door de functie gegevensgeschiedenis te gebruiken om een Azure Digital Twins-exemplaar te verbinden met een Azure Data Explorer-cluster, zodat graafupdates automatisch worden historiseerd naar Azure Data Explorer. Vervolgens kunt u een query uitvoeren op deze gegevens in Azure Data Explorer met behulp van de Azure Digital Twins-queryinvoegtoepassing voor Azure Data Explorer. Als u Time Series Insights niet specifiek hoeft te gebruiken, kunt u dit alternatief overwegen voor een eenvoudigere integratie-ervaring.

Vereisten

Voordat u een relatie met Time Series Insights kunt instellen, moet u de volgende resources instellen:

Een Azure Digital Twins-exemplaar. Zie Een Azure Digital Twins-exemplaar en verificatie instellen voor instructies.
Een model en een dubbel in het Azure Digital Twins-exemplaar. U moet de gegevens van de tweeling een paar keer bijwerken om te zien dat die gegevens worden bijgehouden in Time Series Insights. Zie Een model en dubbel toevoegen voor instructies.

Tip

In dit artikel worden de veranderende digitale dubbelwaarden die worden weergegeven in Time Series Insights, handmatig bijgewerkt voor het gemak. Als u dit artikel echter wilt voltooien met live gesimuleerde gegevens, kunt u een Azure-functie instellen waarmee digitale dubbels worden bijgewerkt op basis van IoT-telemetriegebeurtenissen van een gesimuleerd apparaat. Voor instructies volgt u Gegevens opnemen IoT Hub, inclusief de laatste stappen voor het uitvoeren van de apparaatsimulator en valideren dat de gegevensstroom werkt.

Zoek later nog een TIP om te laten zien waar u kunt beginnen met het uitvoeren van de apparaatsimulator en laat uw Azure-functies de tweelingen automatisch bijwerken in plaats van handmatige opdrachten voor het bijwerken van digitale dubbels te verzenden.

Architectuur voor de oplossing

U koppelt Time Series Insights aan Azure Digital Twins via het volgende pad.

De Event Hubs-naamruimte maken

Voordat u de Event Hubs maakt, maakt u eerst een Event Hubs-naamruimte die gebeurtenissen van uw Azure Digital Twins-exemplaar ontvangt. U kunt de onderstaande Azure CLI-instructies gebruiken of de Azure Portal gebruiken door Een Event Hub maken met behulp van Azure Portal te volgen. Als u wilt zien welke regio's Ondersteuning bieden voor Event Hubs, gaat u naar Beschikbare Azure-producten per regio.

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

Tip

Als u een foutmelding krijgt met de melding BadRequest: The specified service namespace is invalid., controleert u of de naam die u hebt gekozen voor uw naamruimte voldoet aan de naamgevingsvereisten die worden beschreven in dit referentiedocument: Naamruimte maken.

U gebruikt deze Event Hubs-naamruimte voor het opslaan van de twee Event Hubs die nodig zijn voor dit artikel:

Twins Hub - Event Hub voor het ontvangen van dubbele wijzigingsgebeurtenissen
Time Series Hub - Event Hub om gebeurtenissen te streamen naar Time Series Insights

In de volgende secties wordt uitgelegd hoe u deze hubs maakt en configureert binnen uw Event Hub-naamruimte.

Twins-hub maken

De eerste Event Hub die u in dit artikel maakt, is de twins-hub. Deze Event Hub ontvangt dubbele wijzigingsevenementen van Azure Digital Twins. Als u de twins-hub wilt instellen, voert u de volgende stappen in deze sectie uit:

De twins-hub maken
Een autorisatieregel maken om machtigingen voor de hub te beheren
Een eindpunt maken in Azure Digital Twins dat gebruikmaakt van de autorisatieregel voor toegang tot de hub
Een route maken in Azure Digital Twins waarmee de gebeurtenis voor tweelingupdates naar het eindpunt en de verbonden twins-hub wordt verzonden
De twins hub ophalen connection string

Maak de twins-hub met de volgende CLI-opdracht. Geef een naam op voor de twins-hub.

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

Autorisatieregel voor Twins Hub maken

Maak een autorisatieregel met machtigingen voor verzenden en ontvangen. Geef een naam op voor de regel.

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>

Twins Hub-eindpunt maken

Maak een Azure Digital Twins-eindpunt dat uw Event Hub koppelt aan uw Azure Digital Twins-exemplaar. Geef een naam op voor het eindpunt van de twins-hub.

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>

Twins Hub-gebeurtenisroute maken

Azure Digital Twins-exemplaren kunnen dubbele update-gebeurtenissen verzenden wanneer de status van een tweeling wordt bijgewerkt. In deze sectie maakt u een Azure Digital Twins-gebeurtenisroute die deze update-gebeurtenissen naar de twins-hub stuurt voor verdere verwerking.

Maak een route in Azure Digital Twins om van bovenaf update-gebeurtenissen voor tweelingen naar uw eindpunt te verzenden. Met het filter in deze route kunnen alleen updateberichten van dubbels worden doorgegeven aan uw eindpunt. Geef een naam op voor de gebeurtenisroute van de twins-hub. Voor de tijdelijke aanduiding voor de naam van het Azure Digital Twins-exemplaar in deze opdracht kunt u de beschrijvende naam of de hostnaam gebruiken voor een betere prestaties.

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

Twins Hub-connection string ophalen

Haal de twins Event Hub-connection string op met behulp van de autorisatieregels die u hierboven hebt gemaakt voor de twins-hub.

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>

Noteer de waarde primaryConnectionString uit het resultaat om de app-instelling voor de twins-hub verderop in dit artikel te configureren.

Time Series-hub maken

De tweede Event Hub die u in dit artikel maakt, is de time series-hub. Deze Event Hub is degene die de Azure Digital Twins-gebeurtenissen naar Time Series Insights streamt. Voer de volgende stappen uit om de time series-hub in te stellen:

De time series-hub maken
Een autorisatieregel maken om machtigingen voor de hub te beheren
De time series-hub ophalen connection string

Wanneer u later het Time Series Insights-exemplaar maakt, maakt u verbinding met deze time series-hub als gebeurtenisbron voor het Time Series Insights-exemplaar.

Maak de time series-hub met behulp van de volgende opdracht. Geef een naam op voor de tijdreekshub.

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

Autorisatieregel voor time series-hubs maken

Maak een autorisatieregel met machtigingen voor verzenden en ontvangen. Geef een naam op voor de verificatieregel voor de time series-hub.

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>

Time Series Hub-connection string ophalen

Haal de time series hub connection string op met behulp van de autorisatieregels die u hierboven hebt gemaakt voor de time series-hub:

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>

Noteer de waarde primaryConnectionString in het resultaat om de instelling voor de time series hub-app verderop in dit artikel te configureren.

Noteer ook de volgende waarden om deze later te gebruiken om een Time Series Insights-exemplaar te maken.

Event hub-naamruimte
Naam van time series-hub
Verificatieregel voor Time Series Hub

Een functie maken

In deze sectie maakt u een Azure-functie die update-gebeurtenissen van tweelingen converteert van hun oorspronkelijke vorm als JSON-patchdocumenten naar JSON-objecten die alleen bijgewerkte en toegevoegde waarden van uw tweelingen bevatten.

Maak eerst een nieuw functie-app-project.

U kunt dit doen met behulp van Visual Studio (zie Ontwikkelen Azure Functions met Visual Studio), Visual Studio Code (zie Een C#-functie maken in Azure met Visual Studio Code) of de Azure CLI (zie Een C#-functie maken in Azure vanaf de opdrachtregel voor instructies).
Maak een nieuwe Azure-functie met de naam ProcessDTUpdatetoTSI.cs om telemetrie-gebeurtenissen van apparaten bij te werken naar Time Series Insights. Het functietype is Event Hub-trigger.
Voeg de volgende pakketten toe aan uw project (u kunt Visual Studio NuGet-pakketbeheer of de opdracht dotnet add package gebruiken in een opdrachtregelprogramma).

Vervang de code in het bestand ProcessDTUpdatetoTSI.cs door de volgende code:

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

Sla uw functiecode op.

Publiceer het project met de functie ProcessDTUpdatetoTSI.cs naar een functie-app in Azure.

Zie Ontwikkelen Azure Functions met Visual Studio voor instructies over het publiceren van de functie met Behulp van Visual Studio. Zie Een C#-functie maken in Azure met behulp van Visual Studio Code voor instructies over het publiceren van de functie met Behulp van Visual Studio Code. Zie Een C#-functie maken in Azure vanaf de opdrachtregel voor instructies over het publiceren van de functie met behulp van de Azure CLI.

Sla de naam van de functie-app op voor later gebruik om app-instellingen voor de twee Event Hubs te configureren.

De functie-app configureren

Wijs vervolgens een toegangsrol toe voor de functie en configureer de toepassingsinstellingen zodat deze toegang heeft tot uw resources.

Voer de volgende opdrachten uit in Azure Cloud Shell of een lokale Azure CLI.

Notitie

Deze sectie moet worden voltooid door een Azure-gebruiker die machtigingen heeft voor het beheren van gebruikerstoegang tot Azure-resources, waaronder het verlenen en delegeren van machtigingen. Veelvoorkomende rollen die aan deze vereiste voldoen, zijn Eigenaar, Accountbeheerder of de combinatie van Beheerder voor gebruikerstoegang en Inzender. Zie Een exemplaar en verificatie instellen voor meer informatie over de machtigingsvereisten voor Azure Digital Twins-rollen.

Een toegangsrol toewijzen

Voor de Azure-functie moet een Bearer-token worden doorgegeven. Om ervoor te zorgen dat het Bearer-token wordt doorgegeven, verleent u de functie-app de rol Azure Digital Twins-gegevenseigenaar voor uw Azure Digital Twins-exemplaar, waardoor de functie-app toestemming krijgt om gegevensvlakactiviteiten uit te voeren op het exemplaar.

Gebruik de volgende opdracht om een door het systeem beheerde identiteit voor uw functie te maken (als de functie er al een heeft, worden met deze opdracht de details afgedrukt). Noteer het principalId veld in de uitvoer. U gebruikt deze id om te verwijzen naar de functie, zodat u deze in de volgende stap machtigingen kunt verlenen.
```
az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
```
Gebruik de principalId waarde in de volgende opdracht om de functie de rol Azure Digital Twins-gegevenseigenaar te geven voor uw Azure Digital Twins-exemplaar.
```
az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"
```

Toepassingsinstellingen configureren

Maak vervolgens de URL van uw Azure Digital Twins-exemplaar toegankelijk voor uw functie door hiervoor een omgevingsvariabele in te stellen.

Tip

De URL van het Azure Digital Twins-exemplaar wordt gemaakt door https:// toe te voegen aan het begin van de hostnaam van uw exemplaar. Voer az dt show --dt-name <your-Azure-Digital-Twins-instance>uit om de hostnaam en alle eigenschappen van uw exemplaar te zien.

Met de volgende opdracht stelt u een omgevingsvariabele in voor de URL van uw exemplaar die uw functie gebruikt wanneer deze toegang nodig heeft tot het exemplaar.

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

Voeg vervolgens omgevingsvariabelen toe aan de instellingen van de functie-app, zodat deze toegang heeft tot de twins-hub en time series-hub.

Gebruik de waarde van twins hub primaryConnectionString die u eerder hebt opgeslagen om een app-instelling te maken in uw functie-app die de twins hub bevat connection string:

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

Gebruik de waarde van time series hub primaryConnectionString die u eerder hebt opgeslagen om een app-instelling te maken in uw functie-app die de time series-hub bevat connection string:

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

Een Time Series Insights-instantie maken en verbinden

In deze sectie stelt u het Time Series Insights-exemplaar in om gegevens te ontvangen van uw time series-hub. Zie Een Azure Time Series Insights Gen2 PAYG-omgeving instellen voor meer informatie over dit proces. Volg de onderstaande stappen om een Time Series Insights-omgeving te maken.

Zoek in de Azure Portal naar Time Series Insights-omgevingen en selecteer de knop Maken. Kies de volgende opties om de tijdreeksomgeving te maken.
- Abonnement : kies uw abonnement.
  - Resourcegroep : kies uw resourcegroep.
- Omgevingsnaam : geef een naam op voor uw tijdreeksomgeving.
- Locatie : kies een locatie.
- Laag: kies de prijscategorie Gen2(L1).
- Naam van eigenschap : voer $dtId in (meer informatie over het selecteren van een id-waarde in Aanbevolen procedures voor het kiezen van een tijdreeks-id).
- Naam van opslagaccount : geef een opslagaccountnaam op.
- Warm archief inschakelen : laat dit veld ingesteld op Ja.
U kunt standaardwaarden voor andere eigenschappen op deze pagina laten staan. Selecteer de knop Volgende: Gebeurtenisbron > .
Kies op het tabblad Gebeurtenisbron de volgende velden:
- Een gebeurtenisbron maken - Kies Ja.
- Brontype : kies Event Hub.
- Naam : geef een naam op voor de gebeurtenisbron.
- Abonnement : kies uw Azure-abonnement.
- Event Hub-naamruimte : kies de naamruimte die u eerder in dit artikel hebt gemaakt.
- Event Hub-naam : kies de naam van de tijdreekshub die u eerder in dit artikel hebt gemaakt.
- Naam van het Event Hub-toegangsbeleid : kies de verificatieregel voor de time series-hub die u eerder in dit artikel hebt gemaakt.
- Event Hub-consumentengroep : selecteer Nieuw en geef een naam op voor de event hub-consumentengroep. Selecteer vervolgens Toevoegen.
- Eigenschapsnaam : laat dit veld leeg.
Kies de knop Controleren en maken om alle details te bekijken. Selecteer vervolgens opnieuw de knop Beoordelen en maken om de tijdreeksomgeving te maken.

IoT-gegevens verzenden naar Azure Digital Twins

Als u wilt beginnen met het verzenden van gegevens naar Time Series Insights, moet u beginnen met het bijwerken van de eigenschappen van de digitale dubbel in Azure Digital Twins met het wijzigen van gegevenswaarden.

Gebruik de CLI-opdracht az dt twin update om een eigenschap bij te werken op de tweeling die u hebt toegevoegd in de sectie Vereisten . Als u de instructies voor het maken van tweelingen uit Telemetrie opnemen van IoT Hub) hebt gebruikt, kunt u de volgende opdracht in de lokale CLI of de Cloud Shell bash-terminal gebruiken om de temperatuureigenschap op de thermostat67-tweeling bij te werken. Er is één tijdelijke aanduiding voor de hostnaam van het Azure Digital Twins-exemplaar (u kunt ook de beschrijvende naam van het exemplaar gebruiken met een lichte afname van de prestaties).

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

Herhaal de opdracht nog minstens vier keer met verschillende eigenschapswaarden om verschillende gegevenspunten te maken die later kunnen worden waargenomen in de Time Series Insights-omgeving.

Tip

Als u dit artikel wilt voltooien met live gesimuleerde gegevens in plaats van de waarden van de digitale dubbel handmatig bij te werken, moet u eerst de TIP uit de sectie Vereisten voltooien om een Azure-functie in te stellen waarmee tweelingen vanaf een gesimuleerd apparaat worden bijgewerkt. Daarna kunt u het apparaat nu uitvoeren om te beginnen met het verzenden van gesimuleerde gegevens en het bijwerken van uw digitale dubbel via die gegevensstroom.

Uw gegevens in Time Series Insights weergeven

Nu stromen gegevens naar uw Time Series Insights-exemplaar, klaar om te worden geanalyseerd. Volg de onderstaande stappen om de binnenkomende gegevens te verkennen.

Zoek in de Azure Portal naar de naam van de tijdreeksomgeving die u eerder hebt gemaakt. Selecteer overzicht in de menuopties aan de linkerkant om de URL van Time Series Insights Explorer weer te geven. Selecteer de URL om de temperatuurwijzigingen weer te geven die worden weergegeven in de Time Series Insights-omgeving.
In de verkenner ziet u de tweelingen in het Azure Digital Twins-exemplaar aan de linkerkant. Selecteer de dubbel waarvoor u eigenschappen hebt bewerkt, kies de eigenschap die u hebt gewijzigd en selecteer Toevoegen.
U ziet nu de wijzigingen in de eigenschap die u hebt aangebracht, weergegeven in de grafiek, zoals hieronder wordt weergegeven.

Als u een simulatie veel langer laat uitvoeren, ziet uw visualisatie er ongeveer als volgt uit:

Volgende stappen

Nadat u een gegevenspijplijn hebt ingesteld voor het verzenden van tijdreeksgegevens van Azure Digital Twins naar Time Series Insights, wilt u misschien nadenken over het omzetten van assetmodellen die zijn ontworpen voor Azure Digital Twins in assetmodellen voor Time Series Insights. Zie Modelsynchronisatie tussen Azure Digital Twins en Time Series Insights Gen2 voor een zelfstudie over deze volgende stap in het integratieproces.

Share via