Självstudie: Skapa en Azure Digital Twins-graf med hjälp av Azure CLI

Artikel
01/03/2024

I den här självstudien skapar du ett diagram i Azure Digital Twins med hjälp av modeller, tvillingar och relationer. Verktyget för den här självstudien är Azure Digital Twins-kommandouppsättningen för Azure CLI.

Du kan använda CLI-kommandon för att utföra viktiga Azure Digital Twins-åtgärder som att ladda upp modeller, skapa och ändra tvillingar och skapa relationer. Du kan också titta på referensdokumentationen för az dt-kommandouppsättningen för att se den fullständiga uppsättningen CLI-kommandon.

I den här självstudien kommer du...

Modellera en miljö
Skapa digitala tvillingar
Lägga till relationer för att bilda ett diagram
Fråga grafen för att besvara frågor

Förutsättningar

För att slutföra stegen i den här självstudien måste du först slutföra följande krav.

Om du inte har någon Azure-prenumeration skapar du ett kostnadsfritt konto innan du börjar.

Ladda ned exempelmodellerna

Självstudien använder två förskrivna modeller som ingår i C# -exempelprojektet från slutpunkt till slutpunkt för Azure Digital Twins. Modellfilerna finns här:

Om du vill hämta filerna på datorn använder du navigeringslänkarna ovan och kopierar filkropparna till lokala filer på datorn med samma namn (Room.json och Floor.json).

Förbereda din miljö för Azure CLI

Använd Bash-miljön i Azure Cloud Shell. Mer information finns i Snabbstart för Bash i Azure Cloud Shell.
Om du föredrar att köra CLI-referenskommandon lokalt installerar du Azure CLI. Om du kör i Windows eller macOS kan du köra Azure CLI i en Docker-container. Mer information finns i Så här kör du Azure CLI i en Docker-container.
- Om du använder en lokal installation loggar du in på Azure CLI med hjälp av kommandot az login. Slutför autentiseringsprocessen genom att följa stegen som visas i terminalen. Andra inloggningsalternativ finns i Logga in med Azure CLI.
- När du uppmanas att installera Azure CLI-tillägget vid första användningen. Mer information om tillägg finns i Använda tillägg med Azure CLI.
- Kör az version om du vill hitta versionen och de beroende bibliotek som är installerade. Om du vill uppgradera till den senaste versionen kör du az upgrade.

Konfigurera CLI-session

För att börja arbeta med Azure Digital Twins i CLI är det första du behöver göra att logga in och ange CLI-kontexten till din prenumeration för den här sessionen. Kör följande kommandon i CLI-fönstret:

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

Dricks

Du kan också använda ditt prenumerationsnamn i stället för ID:t i kommandot ovan.

Om det är första gången du använder den här prenumerationen med Azure Digital Twins kör du det här kommandot för att registrera dig med Azure Digital Twins-namnområdet. (Om du inte är säker är det ok att köra den igen även om du har gjort det någon gång tidigare.)

az provider register --namespace 'Microsoft.DigitalTwins'

Därefter lägger du till Microsoft Azure IoT-tillägget för Azure CLI för att aktivera kommandon för att interagera med Azure Digital Twins och andra IoT-tjänster. Kör det här kommandot för att kontrollera att du har den senaste versionen av tillägget:

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

Nu är du redo att arbeta med Azure Digital Twins i Azure CLI.

Du kan kontrollera detta genom att köra az dt --help när som helst för att se en lista över de högsta Azure Digital Twins-kommandona som är tillgängliga.

Förbereda en Azure Digital Twins-instans

Om du vill arbeta med Azure Digital Twins i den här artikeln måste du först konfigurera en Azure Digital Twins-instans och de behörigheter som krävs för att använda den. Om du redan har konfigurerat en Azure Digital Twins-instans från tidigare arbete kan du använda den instansen.

Annars följer du anvisningarna i Konfigurera en instans och autentisering. Instruktionerna innehåller också steg för att kontrollera att du har slutfört varje steg och är redo att gå vidare till att använda den nya instansen.

När du har konfigurerat din Azure Digital Twins-instans ska du anteckna följande värden som du måste ansluta till instansen senare:

Instansens värdnamn
Den Azure-prenumeration som du använde för att skapa instansen

Dricks

Om du känner till det egna namnet på din instans kan du använda följande CLI-kommando för att hämta värdnamnet och prenumerationsvärdena:

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

De visas i utdata så här: Skärmbild av Cloud Shell-webbläsarfönstret som visar utdata från kommandot az dt show. Fältet hostName och prenumerations-ID är markerade.

Modellera en fysisk miljö med DTDL

Nu när CLI- och Azure Digital Twins-instansen har konfigurerats kan du börja skapa en graf över ett scenario.

Det första steget i att skapa en Azure Digital Twins-lösning är att definiera tvillingmodeller för din miljö.

Modeller liknar klasser i objektorienterade programmeringsspråk. de tillhandahåller användardefinierade mallar som digitala tvillingar kan följa och instansiera senare. De är skrivna på ett JSON-liknande språk med namnet Digital Twins Definition Language (DTDL) och kan definiera en tvillings egenskaper, relationer och komponenter.

Kommentar

DTDL möjliggör även definition av kommandon på digitala tvillingar. Kommandon stöds dock inte för närvarande i Azure Digital Twins-tjänsten.

Navigera på datorn till den Room.json fil som du skapade i avsnittet Förutsättningar . Öppna den i en kodredigerare och ändra den på följande sätt:

Uppdatera versionsnumret för att indikera att du tillhandahåller en mer uppdaterad version av den här modellen. Gör detta genom att ändra värdet 1 i slutet av @id värdet till 2. Ett tal som är större än det aktuella versionsnumret fungerar också.
Redigera en egenskap. Ändra namnet på Humidity egenskapen till HumidityLevel (eller något annat om du vill. Om du använder något annat än HumidityLevel ska du komma ihåg vad du använde och fortsätta använda det i stället för HumidityLevel under hela självstudien).
Lägg till en egenskap. Under egenskapen HumidityLevel som slutar på rad 15 klistrar du in följande kod för att lägga till en RoomName egenskap i rummet:
```
,{
  "@type": "Property",
  "name": "RoomName",
  "schema": "string"
}
```
Lägg till relation. Under egenskapen RoomName som du precis har lagt till klistrar du in följande kod för att lägga till möjligheten för den här typen av tvilling att skapa contains relationer med andra tvillingar:
```
,{
  "@type": "Relationship",
  "name": "contains"
}
```

När du är klar bör den uppdaterade modellen matcha detta:

{
    "@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"
  }

Spara filen innan du går vidare.

Ladda upp modeller till Azure Digital Twins

När du har skapat modeller måste du ladda upp dem till din Azure Digital Twins-instans. Detta konfigurerar din Azure Digital Twins-tjänstinstans med din egen anpassade domänförråd. När du har laddat upp modellerna kan du skapa tvillinginstanser som använder dem.

Om du använder en lokal installation av Azure CLI kan du hoppa över det här steget. Om du använder Cloud Shell måste du ladda upp dina modellfiler till Cloud Shells lagring så att filerna blir tillgängliga när du kör Cloud Shell-kommandot som använder dem. Om du vill göra det väljer du ikonen "Ladda upp/ladda ned filer" och väljer "Ladda upp".

Gå till filen Room.json på datorn och välj "Öppna". Upprepa sedan det här steget för Floor.json.
Använd sedan kommandot az dt model create enligt nedan för att ladda upp din uppdaterade rumsmodell till din Azure Digital Twins-instans. Det andra kommandot laddar upp en annan modell, Floor, som du också använder i nästa avsnitt för att skapa olika typer av tvillingar. Det finns en platshållare för instansens värdnamn (du kan också använda instansens eget namn med en liten minskning av prestanda) och en platshållare för en sökväg till varje modellfil. Om du använder Cloud Shell finns Room.json och Floor.json i huvudlagringskatalogen, så du kan bara använda filnamnen direkt i kommandot nedan där en sökväg krävs.
```
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>
```
Utdata från varje kommando visar information om den uppladdade modellen.

Dricks

Du kan också ladda upp alla modeller i en katalog samtidigt med hjälp --from-directory av alternativet för kommandot skapa modell. Mer information finns i Valfria parametrar för az dt model create.
Kontrollera att modellerna har skapats med kommandot az dt model list enligt nedan. Om du gör det skrivs en lista över alla modeller som har laddats upp till Azure Digital Twins-instansen med fullständig information. Det finns en platshållare för instansens värdnamn (du kan också använda instansens eget namn med en liten minskning av prestanda).
```
az dt model list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --definition
```
Leta efter den redigerade rumsmodellen i resultatet:

Fel

CLI hanterar också fel från tjänsten.

Kör kommandot igen az dt model create för att försöka ladda upp en av de modeller som du laddade upp igen för en andra gång:

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

Eftersom modeller inte kan skrivas över returnerar körningen av det här kommandot på samma modell nu en felkod på ModelIdAlreadyExists.

Skapa digitala tvillingar

Nu när vissa modeller har laddats upp till din Azure Digital Twins-instans kan du skapa digitala tvillingar baserat på modelldefinitionerna. Digitala tvillingar representerar entiteterna i din företagsmiljö – till exempel sensorer på en gård, rum i en byggnad eller lampor i en bil.

Om du vill skapa en digital tvilling använder du kommandot az dt twin create . Du måste referera till den modell som tvillingen baseras på och du kan också definiera initiala värden för alla egenskaper i modellen. Du behöver inte skicka någon relationsinformation i det här skedet.

Kör den här koden i CLI för att skapa flera tvillingar, baserat på den rumsmodell som du uppdaterade tidigare och en annan modell, Floor. Kom ihåg att Room har tre egenskaper, så du kan ange argument med de inledande värdena för dessa egenskaper. (Det är valfritt att initiera egenskapsvärden i allmänhet, men de behövs för den här självstudien.) Det finns en platshållare för instansens värdnamn (du kan också använda instansens eget namn med en liten minskning av prestanda).
```
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
```
Kommentar

Om du använder något annat än Cloud Shell i Bash-miljön kan du behöva undvika vissa tecken i infogad JSON så att den parsas korrekt.

Mer information finns i Använda specialtecken i olika gränssnitt.

Utdata från varje kommando visar information om den tvilling som skapats (inklusive egenskaper för de rumstvillingar som initierades med dem).
Du kan kontrollera att tvillingarna skapades med kommandot az dt twin query enligt nedan. Frågan som visas hittar alla digitala tvillingar i din Azure Digital Twins-instans. Det finns en platshållare för instansens värdnamn (du kan också använda instansens eget namn med en liten minskning av prestanda).
```
az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT * FROM DIGITALTWINS"
```
Leta efter tvillingarna room0, room1, floor0 och floor1 i resultaten. Här är ett utdrag som visar en del av resultatet av den här frågan.

Kommentar

När du har gjort en ändring av data i diagrammet kan det finnas en svarstid på upp till 10 sekunder innan ändringarna återspeglas i frågor.

DigitalTwins-API:et återspeglar ändringar omedelbart, så om du behöver ett omedelbart svar använder du en API-begäran (DigitalTwins GetById) eller ett SDK-anrop (GetDigitalTwin) för att hämta tvillingdata i stället för en fråga.

Ändra en digital tvilling

Du kan också ändra egenskaperna för en tvilling som du har skapat.

Kör följande az dt twin update-kommando för att ändra Room0s RoomName från Room0 till PresidentialSuite. Det finns en platshållare för instansens värdnamn (du kan också använda instansens eget namn med en liten minskning av prestanda).
```
az dt twin update --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id room0 --json-patch '{"op":"add", "path":"/RoomName", "value": "PresidentialSuite"}'
```
Kommentar

Vi rekommenderar att du använder CLI i Bash-miljön för den här självstudien. Om du använder PowerShell-miljön kan du behöva undvika citattecken --json-patch för att JSON-värdet ska parsas korrekt.

Utdata från det här kommandot visar tvillingens aktuella information och du bör se det nya värdet för RoomName i resultatet.
Du kan kontrollera att uppdateringen lyckades genom att köra kommandot az dt twin show för att se room0s information. Det finns en platshållare för instansens värdnamn (du kan också använda instansens eget namn med en liten minskning av prestanda).
```
az dt twin show --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id room0
```
Utdata bör återspegla det uppdaterade namnet.

Skapa en graf genom att lägga till relationer

Sedan kan du skapa några relationer mellan dessa tvillingar för att ansluta dem till en tvillinggraf. Tvillingdiagram används för att representera en hel miljö.

De typer av relationer som du kan skapa från en tvilling till en annan definieras i de modeller som du laddade upp tidigare. Modelldefinitionen för Floor anger att golv kan ha en typ av relation med namnet contains. Eftersom modelldefinitionen anger den här relationen är det möjligt att skapa en contains-type-relation från varje Golvtvilling till motsvarande rum som den innehåller.

Om du vill lägga till en relation använder du kommandot az dt twin relationship create . Ange den tvilling som relationen kommer från, typen av relation och den tvilling som relationen ansluter till. Slutligen ger du relationen ett unikt ID. Om en relation har definierats för att ha egenskaper kan du även initiera relationsegenskaperna i det här kommandot.

Kör följande kod för att lägga till en -type-relation från var och en containsav de Floor-tvillingar som du skapade tidigare till motsvarande rumstvilling. Relationerna heter relationship0 och relationship1. Det finns en platshållare för instansens värdnamn (du kan också använda instansens eget namn med en liten minskning av prestanda).
```
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
```
Dricks

Relationen contains i golvmodellen definierades också med två egenskaper, ownershipUser och ownershipDepartment, så att du även kan ange argument med de inledande värdena för dessa när du skapar relationerna. Om du vill skapa en relation med de här egenskaperna som initierats lägger du till --properties alternativet i något av ovanstående kommandon, så här:
```
... --properties '{"ownershipUser":"MyUser", "ownershipDepartment":"MyDepartment"}'
```
Utdata från varje kommando visar information om relationen som har skapats.

Du kan kontrollera relationerna med något av följande kommandon, som skriver ut relationerna i din Azure Digital Twins-instans. Varje kommando har en platshållare för instansens värdnamn (du kan också använda instansens eget namn med en liten minskning av prestanda).

Om du vill se alla relationer som kommer från varje våning (visa relationerna från en sida):

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

Om du vill se alla relationer som kommer till varje rum (visa relationen från den "andra" sidan):

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

Om du vill söka efter dessa relationer individuellt, efter 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

De tvillingar och relationer som du har konfigurerat i den här självstudien utgör följande konceptuella diagram:

Fråga tvillingdiagrammet för att besvara miljöfrågor

En viktig funktion i Azure Digital Twins är möjligheten att enkelt och effektivt köra frågor mot tvillingdiagrammet för att besvara frågor om din miljö. I Azure CLI görs frågor med kommandot az dt twin query .

Kommentar

När du har gjort en ändring av data i diagrammet kan det finnas en svarstid på upp till 10 sekunder innan ändringarna återspeglas i frågor.

Kör följande frågor i CLI för att besvara några frågor om exempelmiljön. Varje kommando har en platshållare för instansens värdnamn (du kan också använda instansens eget namn med en liten minskning av prestanda).

Vilka är alla entiteter från min miljö som representeras i Azure Digital Twins? (fråga alla)
```
az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT * FROM DIGITALTWINS"
```
Med den här frågan kan du snabbt utvärdera din miljö och se till att allt representeras som du vill att det ska vara i Azure Digital Twins. Resultatet av den här frågan är ett utdata som innehåller varje digital tvilling med dess information. Här är ett utdrag:

Dricks

Du kanske känner igen att det här är samma kommando som du använde i avsnittet Skapa digitala tvillingar tidigare för att hitta alla Azure Digital Twins i instansen.
Vilka är alla rum i min miljö? (fråga efter modell)
```
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')"
```
Du kan begränsa frågan till tvillingar av en viss typ för att få mer specifik information om vad som representeras. Resultatet av detta visar rum0 och rum1, men visar inte golv0 eller golv1 (eftersom de är golv, inte rum).
Vad är alla rum på våning 0? (fråga efter relation)
```
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'"
```
Du kan fråga baserat på relationer i diagrammet för att få information om hur tvillingar är anslutna eller för att begränsa frågan till ett visst område. Den här frågan visar också att en tvillings ID (t.ex. floor0 i frågan ovan) efterfrågas med hjälp av metadatafältet $dtId. Endast room0 finns på våning 0, så det är det enda rummet i resultatet för den här frågan.

Kommentar

När du använder Cloud Shell för att köra en fråga med metadatafält som det här som börjar med $bör du undvika $ med ett omvänt snedstreck för att låta Cloud Shell veta att det inte är en variabel och bör användas som en literal i frågetexten. Detta visas i skärmbilden ovan.
Vad är alla tvillingar i min miljö med en temperatur över 75? (fråga efter egenskap)
```
az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT * FROM DigitalTwins T WHERE T.Temperature > 75"
```
Du kan fråga grafen baserat på egenskaper för att besvara olika typer av frågor, inklusive att hitta extremvärden i din miljö som kan behöva uppmärksamhet. Andra jämförelseoperatorer (<,>, =eller !=) stöds också. room1 visas i resultaten här, eftersom den har en temperatur på 80.
Vad är alla rum på golv0 med en temperatur över 75? (sammansatt fråga)
```
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"
```
Du kan också kombinera tidigare frågor som du skulle göra i SQL med hjälp av kombinationsoperatorer som AND, OR, NOT. Den här frågan använder AND för att göra den tidigare frågan om tvillingtemperaturer mer specifik. Resultatet innehåller nu endast rum med temperaturer över 75 som ligger på våning 0 , vilket i det här fallet inte är något av dem. Resultatuppsättningen är tom.

Rensa resurser

När du har slutfört den här självstudien kan du välja vilka resurser du vill ta bort, beroende på vad du vill göra härnäst.

Om du planerar att fortsätta till nästa självstudie kan du behålla de resurser som du har konfigurerat här och återanvända Azure Digital Twins-instansen utan att rensa något däremellan.

Om du vill fortsätta använda Azure Digital Twins-instansen från den här artikeln, men rensa alla dess modeller, tvillingar och relationer, kör du följande az dt job deletion CLI-kommando:
```
az dt job deletion create -n <name-of-Azure-Digital-Twins-instance> -y
```
Om du bara vill ta bort vissa av dessa element kan du använda kommandot az dt twin relationship delete, az dt twin delete och az dt model delete för att selektivt ta bort de element som du vill ta bort.

Om du inte behöver någon av de resurser som du skapade i den här självstudien kan du ta bort Azure Digital Twins-instansen och alla andra resurser från den här artikeln med kommandot az group delete CLI. Detta tar bort alla Azure-resurser i en resursgrupp samt själva resursgruppen.

Viktigt!

Att ta bort en resursgrupp kan inte ångras. Resursgruppen och alla resurser som ingår i den tas bort permanent. Var noga så att du inte tar bort fel resursgrupp eller resurser av misstag.

Öppna Azure Cloud Shell eller ett lokalt CLI-fönster och kör följande kommando för att ta bort resursgruppen och allt den innehåller.
```
az group delete --name <your-resource-group>
```

Du kanske också vill ta bort modellfilerna som du skapade på den lokala datorn.

Nästa steg

I den här självstudien kom du igång med Azure Digital Twins genom att skapa en graf i din instans med hjälp av Azure CLI. Du har skapat modeller, digitala tvillingar och relationer för att skapa ett diagram. Du har också kört några frågor i diagrammet för att få en uppfattning om vilka typer av frågor Azure Digital Twins kan besvara om en miljö.

Fortsätt till nästa självstudie för att kombinera Azure Digital Twins med andra Azure-tjänster för att slutföra ett datadrivet scenario från slutpunkt till slutpunkt:

Ansluta en lösning från slutpunkt till slutpunkt

Dela via

Självstudie: Skapa en Azure Digital Twins-graf med hjälp av Azure CLI

Förutsättningar

Ladda ned exempelmodellerna

Förbereda din miljö för Azure CLI

Konfigurera CLI-session

Förbereda en Azure Digital Twins-instans

Modellera en fysisk miljö med DTDL

Ladda upp modeller till Azure Digital Twins

Fel

Skapa digitala tvillingar

Ändra en digital tvilling

Skapa en graf genom att lägga till relationer

Fråga tvillingdiagrammet för att besvara miljöfrågor

Rensa resurser

Nästa steg

Feedback

Ytterligare resurser