Kurz: Vytvoření grafu Azure Digital Twins pomocí ukázkové klientské aplikace

  • Článek

V tomto kurzu vytvoříte graf ve službě Azure Digital Twins pomocí modelů, dvojčat a relací. Nástroj pro tento kurz je ukázková klientská aplikace příkazového řádku pro interakci s instancí služby Azure Digital Twins. Klientská aplikace se podobá klientské aplikaci napsané v kódu klientské aplikace.

Pomocí této ukázky můžete provádět základní akce Služby Azure Digital Twins, jako je nahrávání modelů, vytváření a úpravy dvojčat a vytváření relací. Můžete se také podívat na kód ukázky , kde se dozvíte o rozhraních API služby Azure Digital Twins a procvičíte si implementaci vlastních příkazů úpravou ukázkového projektu, ale chcete.

V tomto kurzu budete...

  • Modelování prostředí
  • Vytvoření digitálních dvojčat
  • Přidání relací k vytvoření grafu
  • Dotazování grafu na odpovědi na otázky

Požadavky

Než začnete s tímto kurzem, začněte s těmito požadavky:

  • Pokud ještě nemáte předplatné Azure, vytvořte si napřed bezplatný účet.
  • Tento kurz používá .NET. Nejnovější verzi sady .NET SDK pro více platforem si můžete stáhnout z webu Download .NET.

Pak pokračujte ve zbývající části tohoto oddílu a nastavte zbývající požadavky.

Získání ukázkových prostředků

Kurz je řízený kompletním ukázkovým projektem Azure Digital Twins napsaným v jazyce C#. Získejte ukázkový projekt na svém počítači tak, že přejdete na ukázkový odkaz a vyberete tlačítko Procházet kód pod názvem.

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.

Screenshot of the digital-twins-samples repo on GitHub, highlighting the steps to download it as a zip.

Tím stáhnete složku .zip do počítače jako digital-twins-samples-main.zip. Rozbalte složku a extrahujte soubory.

Příprava instance Služby Azure Digital Twins

Pokud chcete pracovat se službou Azure Digital Twins v tomto článku, budete potřebovat instanci služby Azure Digital Twins a požadovaná oprávnění k jeho použití. Pokud už máte nastavenou instanci Služby Azure Digital Twins, můžete tuto instanci použít a přeskočit k další části. V opačném případě postupujte podle pokynů v části Nastavení instance a ověřování. Pokyny obsahují informace, které vám pomůžou ověřit, že jste každý krok úspěšně dokončili.

Po nastavení instance si poznamenejte název hostitele instance. Název hostitele najdete na webu Azure Portal.

Konfigurace ukázkového projektu

Dále nastavte ukázkovou klientskou aplikaci, která bude komunikovat s vaší instancí Azure Digital Twins.

Na počítači přejděte do složky, kterou jste si stáhli dříve z kompletních ukázek služby Azure Digital Twins (a rozbalte ji, pokud jste to ještě neudělali).

Ve složce přejděte do souboru digital-twins-samples-main\AdtSampleApp\SampleClientApp a otevřete soubor appsettings.json . Tento soubor JSON obsahuje konfigurační proměnnou, která je nutná ke spuštění projektu.

V textu souboru změňte instanceUrl adresu URL hostitele instance služby Azure Digital Twins (přidáním https:// před název hostitele, jak je znázorněno níže).

{
  "instanceUrl": "https://<your-Azure-Digital-Twins-instance-host-name>"
}

Soubor uložte a zavřete.

Nastavení místních přihlašovacích údajů Azure

Tato ukázka používá defaultAzureCredential (součást Azure.Identity knihovny) k ověřování uživatelů s instancí Služby Azure Digital Twins, když ji spustíte na místním počítači. Další informace o různých způsobech ověřování klientské aplikace pomocí služby Azure Digital Twins najdete v tématu Psaní ověřovacího kódu aplikace.

Pomocí DefaultAzureCredentialtéto ukázky vyhledáte přihlašovací údaje ve vašem místním prostředí, jako je přihlášení k Azure v místním Azure CLI nebo v sadě Visual Studio nebo Visual Studio Code. Z tohoto důvodu byste se měli k Azure přihlásit místně prostřednictvím jednoho z těchto mechanismů, abyste pro ukázku nastavili přihlašovací údaje.

Pokud ke spouštění ukázek kódu používáte Visual Studio nebo Visual Studio Code, ujistěte se, že jste k ho editoru přihlášeni pomocí stejných přihlašovacích údajů Azure, které chcete použít pro přístup k vaší instanci Azure Digital Twins. Pokud používáte místní okno rozhraní příkazového řádku, spusťte az login příkaz pro přihlášení ke svému účtu Azure. Potom byste při spuštění ukázky kódu měli být automaticky ověřeni.

Spuštění ukázkového projektu

Teď, když je aplikace a ověřování nastavené, otevřete okno místní konzoly, které použijete ke spuštění projektu. Přejděte v konzole do složky digital-twins-samples-main\AdtSampleApp\SampleClientApp a spusťte projekt pomocí tohoto příkazu dotnet:

dotnet run

Projekt se spustí, provede ověření a počká na příkaz.

Tady je snímek obrazovky s tím, jak vypadá konzola projektu:

Screenshot of the welcome message from the command-line app.

Tip

Seznam všech možných příkazů, které můžete použít s tímto projektem, zadejte help do konzoly projektu a stiskněte klávesu Return.

Jakmile ověříte, že je aplikace úspěšně spuštěná, můžete ukončit spuštění projektu. Znovu ho spustíte později v kurzu.

Modelování fyzického prostředí pomocí DTDL

Teď, když je instance Azure Digital Twins a ukázková aplikace nastavené, můžete začít vytvářet graf scénáře.

Prvním krokem při vytváření řešení Azure Digital Twins je definování modelů dvojčat pro vaše prostředí.

Modely jsou podobné třídám v objektově orientovaných programovacích jazycích; jedná se o uživatelsky definované šablony, které můžete vytvořit instancí pro vytváření digitálních dvojčat. Modely pro Azure Digital Twins jsou napsané v jazyce podobném formátu JSON, kterému se říká DTDL (Digital Twins Definition Language) a definují typ dvojčete z hlediska jeho vlastností, relací a komponent.

Poznámka:

DTDL také umožňuje definovat příkazy pro digitální dvojčata. Příkazy se ale v současné době ve službě Azure Digital Twins nepodporují.

Ve složce ukázkového projektu, kterou jste si stáhli dříve, přejděte do složky digital-twins-samples-main\AdtSampleApp\SampleClientApp\Models . Tato složka obsahuje ukázkové modely.

Otevřete Soubor Room.json pro úpravy a proveďte následující změny kódu:

  1. Aktualizujte číslo verze, abyste označili, že poskytujete aktualizovanou verzi tohoto modelu. Uděláte to tak , že změníte hodnotu 1 na konci @id hodnoty na 2. Bude fungovat také libovolné číslo větší než aktuální číslo verze.

  2. Umožňuje upravit vlastnost. Změňte název vlastnosti na VlhkostLevel (nebo něco jinéhoHumidity, pokud chcete. Pokud používáte něco jiného než Vlhkostlevel, nezapomeňte, co jste použili, a pokračujte v používání, místo vlhkostiLevel v průběhu kurzu).

  3. Přidejte vlastnost. HumidityLevel Pod vlastnost, která končí na řádku 15, vložte následující kód pro přidání RoomName vlastnosti do místnosti:

    ,{
  "@type": "Property",
  "name": "RoomName",
  "schema": "string"
}

  4. Přidání vztahu. RoomName Pod vlastnost, kterou jste právě přidali, vložte následující kód pro přidání možnosti tohoto typu dvojčete vytvořit contains relace s jinými dvojčaty:

    ,{
  "@type": "Relationship",
  "name": "contains"
}

Po dokončení by aktualizovaný model měl odpovídat tomuto:

{
    "@id": "dtmi:example:Room;2",
    "@type": "Interface",
    "displayName": "Room",
    "contents": [
      {
        "@type": "Property",
        "name": "Temperature",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "HumidityLevel",
        "schema": "double"
      }
      ,{
        "@type": "Property",
        "name": "RoomName",
        "schema": "string"
      }
      ,{
        "@type": "Relationship",
        "name": "contains"
      }
    ],
    "@context": "dtmi:dtdl:context;3"
  }

Než budete pokračovat, nezapomeňte soubor uložit.

Nahrání modelů do služby Azure Digital Twins

Po návrhu modelů je potřeba je nahrát do instance Služby Azure Digital Twins. Tím nakonfigurujete instanci služby Azure Digital Twins s vlastním slovníkem domény. Po nahrání modelů můžete vytvořit instance dvojčat, které je používají.

  1. Vraťte se do okna konzoly, které je otevřené pro složku digital-twins-samples-main\AdtSampleApp\SampleClientApp a spusťte znovu konzolovou aplikaci pomocí dotnet run.

  2. V okně konzoly projektu spusťte následující příkaz, kterým nahrajete aktualizovaný model místnosti spolu s modelem podlahy, který použijete také v další části k vytvoření různých typů dvojčat.

    CreateModels Room Floor

    Výstup by měl indikovat, že se modely úspěšně vytvořily.

  3. Spuštěním příkazu GetModels trueověřte, že modely byly vytvořeny. Tento příkaz vytiskne úplné informace pro všechny modely nahrané do vaší instance Služby Azure Digital Twins. Ve výsledcích vyhledejte upravený model místnosti:

    Screenshot of the result from GetModels, showing the updated Room model.

Nechte konzolovou aplikaci spuštěnou pro další kroky.

Chyby

Ukázková aplikace také zpracovává chyby ze služby.

Pokud to chcete otestovat, spusťte CreateModels znovu příkaz a zkuste znovu nahrát model místnosti, který jste už nahráli:

CreateModels Room

Protože modely nelze přepsat, tento příkaz teď vrátí chybu služby, která značí, že některá ID modelu, která se pokoušíte vytvořit, již existují.

Podrobnosti o tom, jak odstranit existující modely, najdete v tématu Správa modelů DTDL.

Vytvoření digitálních dvojčat

Teď, když se některé modely nahrály do vaší instance Azure Digital Twins, můžete vytvořit digitální dvojčata na základě definic modelu. Digitální dvojčata představují entity ve vašem obchodním prostředí – například senzory ve farmě, místnosti v budově nebo světla v autě.

K vytvoření digitálního dvojčete použijte CreateDigitalTwin příkaz. Na model, na který je dvojče založené, musíte odkazovat a volitelně můžete definovat počáteční hodnoty pro všechny vlastnosti v modelu. V této fázi nemusíte předávat žádné informace o relacích.

  1. Spuštěním tohoto kódu v konzole spuštěného projektu vytvořte několik dvojčat na základě modelu místnosti, který jste aktualizovali dříve, a jiného modelu Floor. Vzpomeňte si, že Místnost má tři vlastnosti, takže můžete zadat argumenty s počátečními hodnotami pro tyto vlastnosti. (Inicializace hodnot vlastností je obecně volitelná, ale pro účely tohoto kurzu jsou potřeba.)

    CreateDigitalTwin dtmi:example:Room;2 room0 RoomName string Room0 Temperature double 70 HumidityLevel double 30
CreateDigitalTwin dtmi:example:Room;2 room1 RoomName string Room1 Temperature double 80 HumidityLevel double 60
CreateDigitalTwin dtmi:example:Floor;1 floor0
CreateDigitalTwin dtmi:example:Floor;1 floor1

    Výstup z těchto příkazů by měl znamenat, že dvojčata byla úspěšně vytvořena.

    Screenshot showing an excerpt from the result of the CreateDigitalTwin commands, which includes floor0, floor1, room0, and room1.

  2. Spuštěním Query příkazu můžete ověřit, že dvojčata byla vytvořena. Tento příkaz se dotazuje instance služby Azure Digital Twins pro všechna digitální dvojčata, která obsahuje. Ve výsledcích vyhledejte pokoj0, pokoj1, podlaha0 a dvojčata patra1.

Poznámka:

Po provedení změny dat v grafu může docházet k latenci až 10 sekund, než se změny projeví v dotazech.

Rozhraní API DigitalTwins okamžitě odráží změny, takže pokud potřebujete okamžitou odpověď, použijte požadavek rozhraní API (DigitalTwins GetById) nebo volání sady SDK (GetDigitalTwin) k získání dat dvojčat místo dotazu.

Úprava digitálního dvojčete

Můžete také upravit vlastnosti dvojčete, které jste vytvořili.

Poznámka:

Základní rozhraní REST API používá formát opravy JSON k definování aktualizací dvojčete. Aplikace příkazového řádku také používá tento formát, aby poskytla pravdivý zážitek s tím, co podkladová rozhraní API očekávají.

  1. Spuštěním tohoto příkazu změňte název room0 z "Room0" na "PresidentSuite":

    UpdateDigitalTwin room0 add /RoomName string PresidentialSuite

    Výstup by měl indikovat, že se dvojče úspěšně aktualizovalo.

  2. Úspěšnou aktualizaci můžete ověřit spuštěním tohoto příkazu a zobrazit informace o místnosti 0:

    GetDigitalTwin room0

    Výstup by měl odrážet aktualizovaný název.

Vytvoření grafu přidáním relací

Dále můžete vytvořit některé relace mezi těmito dvojčaty a propojit je s grafem dvojčete. Grafy dvojčat se používají k reprezentaci celého prostředí.

Typy relací, které můžete vytvořit z jednoho dvojčete do druhého, jsou definovány v modelech , které jste nahráli dříve. Definice modelu pro Floor určuje, že podlahy mohou mít typ relace volaný contains, což umožňuje vytvořit containsrelaci typu z každého dvojčete podlahy do odpovídající místnosti, kterou obsahuje.

Pokud chcete přidat relaci, použijte CreateRelationship příkaz. Zadejte dvojče, ze kterého relace pochází, typ relace a dvojče, ke kterému se relace připojuje. Nakonec dejte relaci jedinečné ID.

  1. Spuštěním následujících příkazů přidejte contains relaci z každé dvojčete floor, která jste vytvořili dříve, k odpovídajícímu dvojčeti místnosti. Relace jsou pojmenované relace0 a relace1.

    CreateRelationship floor0 contains room0 relationship0
CreateRelationship floor1 contains room1 relationship1

    Tip

    Relace contains v modelu floor byla také definována se dvěma vlastnostmi řetězce, ownershipUser takže ownershipDepartmentmůžete také zadat argumenty s počátečními hodnotami pro tyto hodnoty při vytváření relací. Tady je alternativní verze výše uvedeného příkazu pro vytvoření relace0, která také určuje počáteční hodnoty pro tyto vlastnosti:

    CreateRelationship floor0 contains room0 relationship0 ownershipUser string MyUser ownershipDepartment string myDepartment

    Výstup z těchto příkazů potvrzuje, že se relace úspěšně vytvořily:

    Screenshot of an excerpt from the result of the CreateRelationship commands, which includes relationship0 and relationship1.

  2. Relace můžete ověřit pomocí některého z následujících příkazů, které vytisknou relace ve vaší instanci Azure Digital Twins.

    • Chcete-li zobrazit všechny vztahy přicházející z každého patra (zobrazení relací z jedné strany): 
      GetRelationships floor0
GetRelationships floor1
    • Pokud chcete zobrazit všechny relace přicházející do každé místnosti (zobrazení relace z druhé strany): 
      GetIncomingRelationships room0
GetIncomingRelationships room1
    • Pokud chcete tyto relace vyhledat jednotlivě, podle ID: 
      GetRelationship floor0 relationship0
GetRelationship floor1 relationship1

Dvojčata a relace, které jste nastavili v tomto kurzu, tvoří následující koncepční graf:

A diagram showing a conceptual graph. floor0 is connected via relationship0 to room0, and floor1 is connected via relationship1 to room1.

Dotazování grafu dvojčete na odpovědi na otázky k prostředí

Hlavní funkcí služby Azure Digital Twins je možnost snadno a efektivně dotazovat graf dvojčete na otázky týkající se vašeho prostředí.

Poznámka:

Po provedení změny dat v grafu může docházet k latenci až 10 sekund, než se změny projeví v dotazech.

Rozhraní API DigitalTwins okamžitě odráží změny, takže pokud potřebujete okamžitou odpověď, použijte požadavek rozhraní API (DigitalTwins GetById) nebo volání sady SDK (GetDigitalTwin) k získání dat dvojčat místo dotazu.

Spuštěním následujících příkazů v konzole spuštěného projektu odpovězte na některé otázky týkající se ukázkového prostředí.

  1. Jaké jsou všechny entity z mého prostředí reprezentované ve službě Azure Digital Twins? (dotaz na vše)

    Query

    Tento příkaz vám umožní na první pohled zkontrolovat prostředí a ujistit se, že všechno je reprezentované tak, jak chcete, aby bylo v Rámci služby Azure Digital Twins. Výsledkem tohoto příkazu je výstup obsahující každé digitální dvojče s podrobnostmi. Tady je výňatek:

    Screenshot showing a partial result from the twin query, including room0 and floor1.

    Tip

    V ukázkovém projektu je příkaz Query bez dalších argumentů ekvivalentem Query SELECT * FROM DIGITALTWINS. Pokud chcete dotazovat všechna dvojčata ve vaší instanci pomocí rozhraní API dotazů nebo příkazů rozhraní příkazového řádku, použijte delší (úplný) dotaz.

  2. Jaké jsou všechny místnosti v mém prostředí? (dotazování podle modelu)

    Query SELECT * FROM DIGITALTWINS T WHERE IS_OF_MODEL(T, 'dtmi:example:Room;2')

    Pokud chcete získat konkrétnější informace o tom, co je reprezentováno, můžete dotaz omezit na dvojčata určitého typu. Výsledek ukazuje místnost0 a místnost1, ale nezobrazuje podlahu0 nebo podlahu1 (protože jsou podlahy, ne místnosti).

    Screenshot of the result from the model query, showing only room0 and room1.

  3. Jaké jsou všechny pokoje v patře0? (dotaz podle relace)

    Query SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.$dtId = 'floor0'

    Můžete se dotazovat na základě relací v grafu, abyste získali informace o tom, jak jsou dvojčata připojená, nebo omezit dotaz na určitou oblast. Pouze místnost0 je na patře0, takže je to jediná místnost ve výsledku.

    Screenshot of the result from the relationship query, showing room0.

  4. Co jsou všechna dvojčata v mém prostředí s teplotou nad 75? (dotaz podle vlastnosti)

    Query SELECT * FROM DigitalTwins T WHERE T.Temperature > 75

    Graf můžete dotazovat na základě vlastností a odpovídat na různé otázky, včetně vyhledání odlehlých hodnot ve vašem prostředí, které by mohly vyžadovat pozornost. Podporují se také jiné relační operátory (<,>, =nebo !=). Místnost1 se zobrazí ve výsledcích, protože má teplotu 80.

    Screenshot of the result from the property query, showing only room1.

  5. Jaké jsou všechny pokoje v patře0 s teplotou nad 75? (složený dotaz)

    Query SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.$dtId = 'floor0' AND IS_OF_MODEL(room, 'dtmi:example:Room;2') AND room.Temperature > 75

    Můžete také zkombinovat dřívější dotazy, jako byste v SQL, pomocí kombinací operátorů, jako ANDje , OR, NOT. Tento dotaz používá AND k tomu, aby byl předchozí dotaz o teplotách dvojčat konkrétnější. Výsledek teď zahrnuje pouze místnosti s teplotami nad 75, které jsou ve podlahách0 , což v tomto případě není žádný z nich. Sada výsledků je prázdná.

    Screenshot of the result from the compound query, showing no results.

Teď, když jste spustili několik dotazů ve scénáři, který jste nastavili, je kurz dokončený. Ukončete spuštění projektu a zavřete okno konzoly.

Vyčištění prostředků

Po dokončení tohoto kurzu můžete v závislosti na tom, co chcete udělat dál, vybrat, které prostředky chcete odebrat.

  • Pokud máte v plánu pokračovat k dalšímu kurzu, můžete zachovat prostředky, které tady nastavíte, abyste mohli pokračovat v používání této instance služby Azure Digital Twins a nakonfigurovanou ukázkovou aplikaci pro další kurz.

  • Pokud chcete pokračovat v používání instance služby Azure Digital Twins, ale vymazejte všechny její modely, dvojčata a vztahy, můžete pomocí ukázkových aplikací DeleteAllTwins a DeleteAllModels příkazů vymazat dvojčata a modely ve vaší instanci.

  • Pokud nepotřebujete žádné prostředky, které jste vytvořili v tomto kurzu, můžete pomocí příkazu az group delete CLI odstranit instanci Azure Digital Twins a všechny ostatní prostředky z tohoto článku. Tím se odstraní všechny prostředky Azure ve skupině prostředků i samotná skupina prostředků.

    Důležité

    Odstranění skupiny prostředků je nevratné. Skupina prostředků i všechny prostředky v ní obsažené se trvale odstraní. Ujistěte se, že nechtěně neodstraníte nesprávnou skupinu prostředků nebo prostředky.

    Otevřete Azure Cloud Shell nebo místní okno rozhraní příkazového řádku a spuštěním následujícího příkazu odstraňte skupinu prostředků a vše, co obsahuje.

    az group delete --name <your-resource-group>

Můžete také z místního počítače odstranit staženou složku projektu.

Další kroky

V tomto kurzu jste začali s Azure Digital Twins vytvořením grafu ve vaší instanci pomocí ukázkové klientské aplikace. Vytvořili jste modely, digitální dvojčata a relace pro vytvoření grafu. Spustili jste také některé dotazy v grafu, abyste získali představu o typech otázek, na které může Azure Digital Twins odpovědět na prostředí.

Pokračujte dalším kurzem pro kombinování služby Azure Digital Twins s dalšími službami Azure a dokončete kompletní scénář řízený daty:

Připojení uceleného řešení