Kurz: Vytvoření grafu Azure Digital Twins pomocí Azure CLI

V tomto kurzu vytvoříte graf ve službě Azure Digital Twins pomocí modelů, dvojčat a relací. Nástrojem pro tento kurz je sada příkazů Azure Digital Twins pro Azure CLI.

Pomocí příkazů rozhraní příkazového řádku můžete provádět základní akce 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 referenční dokumentaci pro az dt command set a zobrazit úplnou sadu příkazů rozhraní příkazového řádku.

V tomto kurzu budete...

Požadavky

Abyste mohli dokončit kroky v tomto kurzu, musíte nejprve splnit následující požadavky.

Pokud ještě nemáte předplatné Azure, vytvořte si napřed bezplatný účet.

Stažení ukázkových modelů

Tento kurz používá dva předem napsané modely, které jsou součástí kompletního projektu C# pro Azure Digital Twins. Soubory modelu jsou umístěné tady:

• Room.json
• Floor.json

Pokud chcete získat soubory na vašem počítači, použijte výše uvedené navigační odkazy a zkopírujte těla souborů do místních souborů na vašem počítači se stejnými názvy (Room.json a Floor.json).

Příprava prostředí pro rozhraní příkazového řádku Azure

• Použijte prostředí Bash v Azure Cloud Shellu. Další informace najdete v tématu Rychlý start pro Bash v Azure Cloud Shellu.

  

• Pokud dáváte přednost místnímu spouštění referenčních příkazů rozhraní příkazového řádku, nainstalujte Azure CLI. Pokud používáte Windows nebo macOS, zvažte spuštění Azure CLI v kontejneru Docker. Další informace najdete v tématu Jak spustit Azure CLI v kontejneru Dockeru.

  • Pokud používáte místní instalaci, přihlaste se k Azure CLI pomocí příkazu az login. Pokud chcete dokončit proces ověřování, postupujte podle kroků zobrazených na terminálu. Další možnosti přihlášení najdete v tématu Přihlášení pomocí Azure CLI.

  • Po zobrazení výzvy nainstalujte rozšíření Azure CLI při prvním použití. Další informace o rozšířeních najdete v tématu Využití rozšíření v Azure CLI.

  • Spuštěním příkazu az version zjistěte verzi a závislé knihovny, které jsou nainstalované. Pokud chcete upgradovat na nejnovější verzi, spusťte az upgrade.

Nastavení relace rozhraní příkazového řádku

Pokud chcete začít pracovat s Azure Digital Twins v rozhraní příkazového řádku, je první věc, kterou je potřeba udělat, přihlásit se a nastavit kontext rozhraní příkazového řádku pro vaše předplatné pro tuto relaci. V okně rozhraní příkazového řádku spusťte tyto příkazy:

az login
az account set --subscription "<your-Azure-subscription-ID>"

Pokud jste toto předplatné použili s Azure Digital Twins poprvé, spusťte tento příkaz a zaregistrujte se v oboru názvů Azure Digital Twins. (Pokud si nejste jistí, můžete ho znovu spustit, i když jste to někdy udělali v minulosti.)

az provider register --namespace 'Microsoft.DigitalTwins'

Dále přidáte rozšíření Microsoft Azure IoT pro Azure CLI, které povolí příkazy pro interakci se službou Azure Digital Twins a dalšími službami IoT. Spuštěním tohoto příkazu se ujistěte, že máte nejnovější verzi rozšíření:

az extension add --upgrade --name azure-iot

Teď jste připraveni pracovat s Azure Digital Twins v Azure CLI.

Můžete to ověřit spuštěním az dt --help kdykoli a zobrazit seznam příkazů Azure Digital Twins nejvyšší úrovně, které jsou k dispozici.

Příprava instance Služby Azure Digital Twins

Abyste mohli pracovat se službou Azure Digital Twins v tomto článku, musíte nejprve nastavit instanci služby Azure Digital Twins a požadovaná oprávnění pro jeho použití. Pokud už máte instanci Azure Digital Twins nastavenou z předchozí práce, můžete tuto instanci použít.

V opačném případě postupujte podle pokynů v části Nastavení instance a ověřování. Pokyny také obsahují kroky k ověření, že jste každý krok úspěšně dokončili a jste připraveni přejít k používání nové instance.

Po nastavení instance Azure Digital Twins si poznamenejte následující hodnoty, které budete později muset připojit k instanci:

• Název hostitele instance
• Předplatné Azure, které jste použili k vytvoření instance

az dt show --dt-name <Azure-Digital-Twins-instance-name>

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

Teď, když je nastavené rozhraní příkazového řádku a instance Azure Digital Twins, 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; poskytují uživatelsky definované šablony pro digitální dvojčata, které budou později sledovat a vytvořit instanci. Jsou napsané v jazyce podobném formátu JSON s názvem DTDL (Digital Twins Definition Language) a mohou definovat vlastnosti, vztahy a komponenty dvojčete.

Na počítači přejděte do Room.json souboru, který jste vytvořili v části Požadavky . Otevřete ho v editoru kódu a změňte ho následujícími způsoby:

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. Pokud používáte místní instalaci Azure CLI, můžete tento krok přeskočit. Pokud používáte Cloud Shell, budete muset nahrát soubory modelu do úložiště Cloud Shellu, aby byly soubory dostupné při spuštění příkazu Cloud Shellu, který je používá. Uděláte to tak, že vyberete ikonu Nahrát nebo Stáhnout soubory a zvolíte Nahrát.

   

   Na počítači přejděte do souboru Room.json a vyberte Otevřít. Potom tento krok opakujte pro Floor.json.

2. Dále pomocí příkazu az dt model create , jak je znázorněno níže, nahrajte aktualizovaný model místnosti do vaší instance Azure Digital Twins. Druhý příkaz nahraje jiný model Floor, který použijete také v další části k vytvoření různých typů dvojčat. Pro název hostitele instance je zástupný symbol (můžete také použít popisný název instance s mírným snížením výkonu) a zástupný symbol pro cestu ke každému souboru modelu. Pokud používáte Cloud Shell, Room.json a Floor.json jsou v hlavním adresáři úložiště, takže stačí použít názvy souborů přímo v příkazu níže, kde se vyžaduje cesta.

   az dt model create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --models <path-to-Room.json>
   az dt model create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --models <path-to-Floor.json>
   

   Výstup z každého příkazu zobrazí informace o úspěšně nahraném modelu.

   Tip

   Všechny modely můžete také nahrát v rámci adresáře najednou pomocí --from-directory možnosti pro příkaz create modelu. Další informace najdete v tématu Volitelné parametry pro az dt model create.

3. Pomocí příkazu az dt model list ověřte, že se modely vytvořily, jak je znázorněno níže. Tím se vytiskne seznam všech modelů, které byly nahrané do instance služby Azure Digital Twins, s úplnými informacemi. 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 list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --definition
   

   Ve výsledcích vyhledejte upravený model místnosti:

   

Chyby

Rozhraní příkazového řádku také zpracovává chyby ze služby.

Spusťte az dt model create znovu příkaz a zkuste znovu nahrát jeden ze stejných modelů, které jste nahráli, a to ještě jednou:

az dt model create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --models Room.json

Protože modely nelze přepsat, spuštění tohoto příkazu na stejném modelu nyní vrátí kód ModelIdAlreadyExistschyby .

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 příkaz az dt twin create . 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 rozhraní příkazového řádku 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.) 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 <Azure-Digital-Twins-instance-hostname-or-name> --dtmi "dtmi:example:Room;2" --twin-id room0 --properties '{"RoomName":"Room0", "Temperature":70, "HumidityLevel":30}'
   az dt twin create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --dtmi "dtmi:example:Room;2" --twin-id room1 --properties '{"RoomName":"Room1", "Temperature":80, "HumidityLevel":60}'
   az dt twin create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --dtmi "dtmi:example:Floor;1" --twin-id floor0
   az dt twin create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --dtmi "dtmi:example:Floor;1" --twin-id floor1
   

   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.

   Výstup z každého příkazu zobrazí informace o úspěšně vytvořeném dvojčeti (včetně vlastností pro dvojčata místnosti, která byla s nimi inicializována).

2. Pomocí příkazu az dt twin query můžete ověřit, že dvojčata byla vytvořena, jak je znázorněno níže. Zobrazený dotaz najde všechna digitální dvojčata ve vaší instanci Služby Azure Digital Twins. 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 --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT * FROM DIGITALTWINS"
   

   Ve výsledcích vyhledejte pokoj0, pokoj1, podlaha0 a dvojčata patra1. Tady je výňatek zobrazující část výsledku tohoto dotazu.

   

Úprava digitálního dvojčete

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

1. Spuštěním následujícího příkazu az dt twin update změňte název room0's RoomName z Room0 na PresidentSuite. 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 update --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id room0 --json-patch '{"op":"add", "path":"/RoomName", "value": "PresidentialSuite"}'
   

   Poznámka:

   Pro účely tohoto kurzu doporučujeme použít rozhraní příkazového řádku v prostředí Bash. Pokud používáte prostředí PowerShell, možná budete muset uvozovky uvozovky použít, aby --json-patch se hodnota JSON správně parsovala.

   Výstup z tohoto příkazu zobrazí aktuální informace dvojčete a měli byste vidět novou hodnotu výsledku RoomName .

   

2. Úspěšnou aktualizaci můžete ověřit spuštěním příkazu az dt twin show a zobrazit informace o místnosti0. 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 show --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id 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. Vzhledem k tomu, že definice modelu určuje tuto relaci, je možné 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 příkaz az dt twin relationship create . 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. Pokud byla relace definována tak, aby měla vlastnosti, můžete také inicializovat vlastnosti relace v tomto příkazu.

1. Spuštěním následujícího kódu přidejte containsrelaci typu -type z každé dvojčete floor, která jste vytvořili dříve, do odpovídající dvojčete místnosti. Relace jsou pojmenované relace0 a relace1. 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 relationship create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --relationship-id relationship0 --relationship contains --twin-id floor0 --target room0
   az dt twin relationship create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --relationship-id relationship1 --relationship contains --twin-id floor1 --target room1
   

   Tip

   Relace contains v modelu floor byla také definována se dvěma vlastnostmi, ownershipUser a ownershipDepartmentproto můžete také zadat argumenty s počátečními hodnotami pro tyto hodnoty při vytváření relací. Pokud chcete vytvořit relaci s těmito inicializovanými vlastnostmi, přidejte --properties možnost do některého z výše uvedených příkazů, například takto:

   ... --properties '{"ownershipUser":"MyUser", "ownershipDepartment":"MyDepartment"}'
   

   Výstup z každého příkazu zobrazí informace o úspěšně vytvořené relaci.

2. Relace můžete ověřit pomocí některého z následujících příkazů, které vytisknou relace v instanci služby Azure Digital Twins. Každý příkaz má jeden zástupný symbol pro název hostitele instance (můžete také použít popisný název instance s mírným snížením výkonu).

   • Chcete-li zobrazit všechny vztahy přicházející z každého patra (zobrazení relací z jedné strany):

     az dt twin relationship list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id floor0
     az dt twin relationship list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id floor1
     

   • Pokud chcete zobrazit všechny relace přicházející do každé místnosti (zobrazení relace z druhé strany):

     az dt twin relationship list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id room0 --incoming
     az dt twin relationship list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id room1 --incoming
     

   • Pokud chcete tyto relace vyhledat jednotlivě, podle ID:

     az dt twin relationship show --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id floor0 --relationship-id relationship0
     az dt twin relationship show --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id floor1 --relationship-id relationship1
     

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

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í. V Azure CLI se dotazování provádí pomocí příkazu az dt twin query .

Spuštěním následujících dotazů v rozhraní příkazového řádku odpovězte na některé otázky týkající se ukázkového prostředí. Každý příkaz má jeden zástupný symbol pro název hostitele instance (můžete také použít popisný název instance s mírným snížením výkonu).

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

   az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT * FROM DIGITALTWINS"
   

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

   

   Tip

   Možná poznáte, že se jedná o stejný příkaz, který jste použili v části Vytvořit digitální dvojčata dříve, abyste našli všechny služby Azure Digital Twins v instanci.

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

   az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "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).

   

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

   az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "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. Tento dotaz také ukazuje, že ID dvojčete (například floor0 v dotazu výše) se dotazuje pomocí pole $dtIdmetadat . Pouze místnost0 je na patře0, takže je to jediná místnost ve výsledku pro tento dotaz.

   

   Poznámka:

   Při použití Cloud Shellu ke spuštění dotazu s poli metadat, jako je tato $, byste měli utéct $ zpětným lomítkem, aby cloud Shell věděl, že se nejedná o proměnnou a měl by být spotřebován jako literál v textu dotazu. To se projeví na výše uvedeném snímku obrazovky.

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

   az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT * FROM DigitalTwins T WHERE T.Temperature > 75"
   

   Graf můžete dotazovat na základě vlastností a odpovídat na různé druhy otázek, včetně hledá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.

   

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

   az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "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á.

   

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, a znovu použít instanci Azure Digital Twins, aniž byste museli vymazat cokoli mezi tím.

• Pokud chcete dál používat instanci azure Digital Twins z tohoto článku, ale vymazejte všechny její modely, dvojčata a relace, spusťte následující příkaz az dt job deletion CLI:

  az dt job deletion create -n <name-of-Azure-Digital-Twins-instance> -y
  

  Pokud chcete odstranit jenom některé z těchto prvků, můžete k selektivnímu odstranění pouze prvků, které chcete odebrat, použít az dt twin relationship delete, az dt twin delete a az dt model delete.

• 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é odstranit soubory modelu, které jste vytvořili na místním počítači.

Další kroky

V tomto kurzu jste začali s Azure Digital Twins vytvořením grafu ve vaší instanci pomocí Azure CLI. 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: