Integrace služby Azure Digital Twins s Azure Time Series Insights

  • Článek

V tomto článku se dozvíte, jak integrovat Azure Digital Twins s Azure Time Series Insights (TSI).

Řešení popsané v tomto článku používá Time Series Insights ke shromažďování a analýze historických dat o řešení IoT. Služba Azure Digital Twins je vhodná pro předávání dat do Time Series Insights, protože umožňuje korelovat více datových proudů a standardizovat informace před jejich odesláním do Time Series Insights.

Tip

Nejjednodušší způsob, jak analyzovat historická data dvojčat v průběhu času, je použít funkci historie dat k připojení instance Služby Azure Digital Twins ke clusteru Azure Data Explorer, aby se aktualizace grafů automaticky historizovaly do Azure Data Explorer. Na tato data se pak můžete dotazovat v Azure Data Explorer pomocí modulu plug-in dotazů Azure Digital Twins pro Azure Data Explorer. Pokud nepotřebujete používat Time Series Insights speciálně, můžete zvážit tuto alternativu pro jednodušší prostředí integrace.

Požadavky

Než budete moct nastavit relaci s Time Series Insights, budete muset nastavit následující zdroje informací:

Tip

V tomto článku se pro zjednodušení ručně aktualizují hodnoty digitálního dvojčete, které se zobrazují v Time Series Insights. Pokud ale chcete tento článek dokončit s živými simulovanými daty, můžete nastavit funkci Azure, která aktualizuje digitální dvojčata na základě událostí telemetrie IoT ze simulovaného zařízení. Pokyny najdete v tématu Ingestování IoT Hub dat, včetně konečných kroků ke spuštění simulátoru zařízení a ověření, že tok dat funguje.

Později vyhledejte další TIP, který vám ukáže, kde začít spouštět simulátor zařízení a nechat funkce Azure aktualizovat dvojčata automaticky, místo aby se odesílaly ruční příkazy pro aktualizaci digitálních dvojčat.

Architektura řešení

Time Series Insights připojíte ke službě Azure Digital Twins pomocí následující cesty.

Diagram služeb Azure v kompletním scénáři se zvýrazněním Time Series Insights

Vytvoření oboru názvů Event Hubs

Před vytvořením služby Event Hubs nejprve vytvoříte obor názvů služby Event Hubs, který bude přijímat události z vaší instance Služby Azure Digital Twins. Můžete buď použít následující pokyny k Azure CLI, nebo použít Azure Portal podle pokynů v tématu Vytvoření centra událostí pomocí Azure Portal. Pokud chcete zjistit, které oblasti podporují službu Event Hubs, navštivte produkty Azure dostupné v jednotlivých oblastech.

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

Tip

Pokud se zobrazí chyba s oznámením BadRequest: The specified service namespace is invalid., ujistěte se, že název, který jste zvolili pro váš obor názvů, splňuje požadavky na vytváření názvů popsané v tomto referenčním dokumentu: Vytvoření oboru názvů.

Tento obor názvů služby Event Hubs budete používat k uložení dvou center událostí, která jsou potřebná pro tento článek:

  1. Twins Hub – centrum událostí pro příjem událostí změn dvojčat
  2. Centrum time series – centrum událostí pro streamování událostí do Time Series Insights

Další části vás provedou vytvořením a konfigurací těchto center v oboru názvů centra událostí.

Vytvoření centra dvojčat

Prvním centrem událostí, které vytvoříte v tomto článku, je centrum dvojčat. Toto centrum událostí bude přijímat události změn dvojčat z Azure Digital Twins. Pokud chcete nastavit centrum dvojčat, proveďte následující kroky v této části:

  1. Vytvoření centra dvojčat
  2. Vytvoření autorizačního pravidla pro řízení oprávnění k centru
  3. Vytvoření koncového bodu v Azure Digital Twins, který používá autorizační pravidlo pro přístup k centru
  4. Vytvoření trasy v Azure Digital Twins, která odesílá událost aktualizací dvojčat do koncového bodu a centra připojených dvojčat
  5. Získání připojovacího řetězce centra dvojčat

Pomocí následujícího příkazu rozhraní příkazového řádku vytvořte centrum dvojčat. Zadejte název centra dvojčat.

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

Vytvoření autorizačního pravidla centra dvojčat

Vytvořte autorizační pravidlo s oprávněními pro odesílání a přijímání. Zadejte název pravidla.

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>

Vytvoření koncového bodu centra dvojčat

Vytvořte koncový bod Azure Digital Twins, který prováže centrum událostí s vaší instancí Služby Azure Digital Twins. Zadejte název koncového bodu centra dvojčat.

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>

Vytvoření trasy událostí centra dvojčat

Instance Azure Digital Twins můžou generovat události aktualizace dvojčat při každé aktualizaci stavu dvojčete. V této části vytvoříte trasu událostí Azure Digital Twins, která tyto události aktualizace přesměruje do centra dvojčat k dalšímu zpracování.

Ve službě Azure Digital Twins vytvořte trasu pro odesílání událostí aktualizace dvojčat do koncového bodu shora. Filtr v této trase povolí pouze předávání zpráv o aktualizaci dvojčat do vašeho koncového bodu. Zadejte název trasy událostí centra dvojčat. V případě zástupného symbolu názvu instance Azure Digital Twins v tomto příkazu můžete pro zvýšení výkonu použít popisný název nebo název hostitele.

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

Získání připojovacího řetězce centra dvojčat

Získejte připojovací řetězec centra událostí twins pomocí autorizačních pravidel, která jste vytvořili výše pro centrum dvojčat.

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>

Poznamenejte si hodnotu primaryConnectionString z výsledku a nakonfigurujte nastavení aplikace centra dvojčat dále v tomto článku.

Vytvoření centra časových řad

Druhým centrem událostí, které vytvoříte v tomto článku, je centrum časové řady. Toto centrum událostí bude streamovat události Azure Digital Twins do Time Series Insights. Pokud chcete nastavit centrum časové řady, proveďte tyto kroky:

  1. Vytvoření centra časových řad
  2. Vytvoření autorizačního pravidla pro řízení oprávnění k centru
  3. Získání připojovacího řetězce centra časové řady

Později, když vytvoříte instanci Time Series Insights, připojíte toto centrum časové řady jako zdroj událostí pro instanci Time Series Insights.

Pomocí následujícího příkazu vytvořte centrum časové řady. Zadejte název centra časové řady.

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

Vytvoření autorizačního pravidla centra časových řad

Vytvořte autorizační pravidlo s oprávněními pro odesílání a přijímání. Zadejte název pravidla ověřování centra časových řad.

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>

Získání připojovacího řetězce centra časové řady

Získejte připojovací řetězec centra časové řady pomocí autorizačních pravidel, která jste vytvořili výše pro centrum časových řad:

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>

Poznamenejte si hodnotu primaryConnectionString z výsledku a nakonfigurujte nastavení aplikace centra časové řady dále v tomto článku.

Poznamenejte si také následující hodnoty, které později použijete k vytvoření instance Time Series Insights.

  • Obor názvů centra událostí
  • Název centra časové řady
  • Pravidlo ověřování centra časové řady

Vytvoření funkce

V této části vytvoříte funkci Azure, která převede události aktualizace dvojčat z původní podoby jako dokumenty opravy JSON na objekty JSON, které obsahují pouze aktualizované a přidané hodnoty z vašich dvojčat.

  1. Nejprve vytvořte nový projekt aplikace funkcí.

    Můžete to udělat pomocí sady Visual Studio (pokyny najdete v tématu Vývoj Azure Functions 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).

  2. Vytvořte novou funkci Azure s názvem ProcessDTUpdatetoTSI.cs , která aktualizuje události telemetrie zařízení na Time Series Insights. Typ funkce bude trigger centra událostí.

    Snímek obrazovky sady Visual Studio pro vytvoření nové funkce Azure typu trigger centra událostí

  3. 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).

  4. Nahraďte kód v souboru ProcessDTUpdatetoTSI.cs následujícím kódem:

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

    Uložte kód funkce.

  5. Publikujte projekt pomocí funkce ProcessDTUpdatetoTSI.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.

Uložte název aplikace funkcí, abyste mohli později nakonfigurovat nastavení aplikace pro tato dvě centra událostí.

Konfigurace aplikace Function App

Dále funkci přiřaďte přístupovou roli a nakonfigurujte nastavení aplikace tak, aby k vašim prostředkům přistupovala.

V Azure Cloud Shell nebo v 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ělování a delegování oprávnění. Mezi běžné role, které tento požadavek splňují, patří vlastník, správce účtu nebo kombinace správce uživatelských přístupů a přispěvatele. 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. Pokud chcete zajistit předání nosného tokenu, udělte aplikaci funkcí roli Vlastník dat azure Digital Twins pro vaši instanci Azure Digital Twins, která aplikaci funkcí udělí oprávnění k provádění aktivit roviny dat v instanci.

  1. Pomocí následujícího příkazu vytvořte identitu spravovanou systémem pro funkci (pokud ji funkce už má, tento příkaz vytiskne její podrobnosti). Poznamenejte si principalId pole ve výstupu. Toto ID použijete k odkazu 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>

  2. principalId Pomocí hodnoty v následujícím příkazu přidělte 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 zpřístupněte adresu URL instance služby Azure Digital Twins vaší funkci tak, že pro ni nastavíte proměnnou prostředí .

Tip

Adresa URL instance Služby Azure Digital Twins se vytvoří 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 příkaz az dt show --dt-name <your-Azure-Digital-Twins-instance>.

Následující příkaz nastaví proměnnou prostředí pro adresu URL vaší instance, kterou vaše funkce použije, kdykoli bude potřebovat přístup 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>"

V dalším kroku přidejte do nastavení aplikace funkcí proměnné prostředí, které jí umožní přístup k centru dvojčat a centru časových řad.

Pomocí hodnoty primaryConnectionString centra dvojčat, kterou jste si uložili dříve, vytvořte v aplikaci funkcí nastavení aplikace, která obsahuje připojovací řetězec centra dvojčat:

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

Použijte hodnotu primaryConnectionString centra časové řady, kterou jste si uložili dříve, a vytvořte v aplikaci funkcí nastavení aplikace, která bude obsahovat připojovací řetězec centra časové řady:

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

Vytvořit a připojit instanci Time Series Insights

V této části nastavíte instanci Služby Time Series Insights pro příjem dat z centra časové řady. Další informace o tomto procesu najdete v tématu Nastavení prostředí Azure Time Series Insights Gen2 PAYG. Postupujte podle následujících kroků a vytvořte prostředí Time Series Insights.

  1. V Azure Portal vyhledejte prostředí Time Series Insights a vyberte tlačítko Vytvořit. Zvolte následující možnosti a vytvořte prostředí časové řady.

    • Předplatné – Zvolte své předplatné.
      • Skupina prostředků – Zvolte skupinu prostředků.
    • Název prostředí – Zadejte název prostředí časové řady.
    • Umístění – Zvolte umístění.
    • Úroveň – zvolte cenovou úroveň Gen2(L1 ).
    • Název vlastnosti – zadejte $dtId (Další informace o výběru hodnoty ID najdete v tématu Osvědčené postupy pro volbu ID časové řady).
    • Název účtu úložiště – Zadejte název účtu úložiště.
    • Povolit teplé úložiště – Nechte toto pole nastavené na Ano.

    Na této stránce můžete ponechat výchozí hodnoty pro ostatní vlastnosti. Vyberte tlačítko Další: Zdroj >události.

    Snímek obrazovky s Azure Portal ukazující, jak vytvořit prostředí Time Series Insights (část 1/3)

    Snímek obrazovky s Azure Portal ukazující, jak vytvořit prostředí Time Series Insights (část 2/3)

  2. Na kartě Zdroj událostí zvolte následující pole:

    • Chcete vytvořit zdroj událostí? - Zvolte Ano.
    • Typ zdroje – Zvolte Centrum událostí.
    • Název – Zadejte název zdroje událostí.
    • Předplatné – zvolte své předplatné Azure.
    • Obor názvů centra událostí – Zvolte obor názvů, který jste vytvořili dříve v tomto článku.
    • Název centra událostí – Zvolte název centra časové řady, který jste vytvořili dříve v tomto článku.
    • Název zásad přístupu k centru událostí – Zvolte pravidlo ověřování centra časové řady, které jste vytvořili dříve v tomto článku.
    • Skupina uživatelů centra událostí – Vyberte Nový a zadejte název skupiny uživatelů centra událostí. Pak vyberte Přidat.
    • Název vlastnosti – Toto pole nechejte prázdné.

    Kliknutím na tlačítko Zkontrolovat a vytvořit zkontrolujte všechny podrobnosti. Potom znovu vyberte tlačítko Zkontrolovat a vytvořit a vytvořte prostředí časové řady.

    Snímek obrazovky s Azure Portal ukazující, jak vytvořit prostředí Time Series Insights (část 3/3)

Odesílání dat IoT do Služby Azure Digital Twins

Pokud chcete začít odesílat data do Time Series Insights, budete muset začít aktualizovat vlastnosti digitálního dvojčete ve službě Azure Digital Twins změnou hodnot dat.

Pomocí příkazu az dt twin update cli aktualizujte vlastnost dvojčete, které jste přidali v části Požadavky . Pokud jste použili pokyny k vytvoření dvojčete z Ingestování telemetrie z IoT Hub), můžete pomocí následujícího příkazu v místním rozhraní příkazového řádku nebo v terminálu Cloud Shell Bash aktualizovat vlastnost temperature na dvojčeti termostatu67. Existuje jeden zástupný symbol pro název hostitele instance služby Azure Digital Twins (můžete také použít popisný název instance s mírným snížením výkonu).

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

Opakujte příkaz ještě alespoň 4krát s různými hodnotami vlastností, abyste vytvořili několik datových bodů, které můžete v prostředí Time Series Insights pozorovat později.

Tip

Pokud chcete tento článek dokončit s živými simulovanými daty místo ruční aktualizace hodnot digitálních dvojčat, nejprve se ujistěte, že jste dokončili TIP v části Požadavky a nastavili funkci Azure, která aktualizuje dvojčata ze simulovaného zařízení. Potom můžete zařízení spustit a začít odesílat simulovaná data a aktualizovat digitální dvojče prostřednictvím daného toku dat.

Vizualizace dat v Time Series Insights

Teď by data měla přitékat do vaší instance Time Series Insights a měla by být připravená k analýze. Při zkoumání příchozích dat postupujte podle následujících kroků.

  1. V Azure Portal vyhledejte název prostředí časové řady, které jste vytvořili dříve. V možnostech nabídky na levé straně vyberte Přehled a zobrazte adresu URL průzkumníka Služby Time Series Insights. Výběrem adresy URL zobrazíte změny teploty, které se projeví v prostředí Time Series Insights.

    Snímek obrazovky s Azure Portal s adresou URL průzkumníka Time Series Insights na kartě Přehled prostředí Time Series Insights

  2. V průzkumníkovi uvidíte dvojčata v instanci Azure Digital Twins zobrazená na levé straně. Vyberte dvojče, pro které jste upravili vlastnosti, zvolte vlastnost, kterou jste změnili, a vyberte Přidat.

    Snímek obrazovky s průzkumníkem Time Series Insights s kroky pro výběr termostatu67, výběrem vlastnosti temperature a zvýrazněným výběrem možnosti Přidat

  3. Teď byste měli vidět změny vlastností, které jste provedli v grafu, jak je znázorněno níže.

    Snímek obrazovky s průzkumníkem Time Series Insights s počátečními údaji o teplotě a řádkou náhodných hodnot mezi 68 a 85

Pokud simulaci necháte běžet mnohem déle, bude vizualizace vypadat přibližně takto:

Snímek obrazovky průzkumníka Time Series Insights, kde jsou údaje o teplotě pro každé dvojče v grafu ve třech paralelních čarách různých barev

Další kroky

Po vytvoření datového kanálu pro odesílání dat časových řad z Azure Digital Twins do Time Series Insights se můžete zamyslet nad tím, jak převést modely aktiv navržené pro Azure Digital Twins na modely aktiv pro Time Series Insights. Kurz k tomuto dalšímu kroku procesu integrace najdete v tématu Synchronizace modelů mezi Azure Digital Twins a Time Series Insights Gen2.