Dela via

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

  • Artikel

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 exempelprogrammet för kommandoradsklienten för att interagera med en Azure Digital Twins-instans. Klientappen liknar den som skrivits i Koda en klientapp.

Du kan använda det här exemplet 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å koden i exemplet för att lära dig mer om Azure Digital Twins-API:erna och öva på att implementera dina egna kommandon genom att ändra exempelprojektet hur du vill.

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

Innan du påbörjar den här självstudien börjar du med följande krav:

  • Om du inte har någon Azure-prenumeration skapar du ett kostnadsfritt konto innan du börjar.
  • I den här självstudien används .NET. Du kan ladda ned den senaste versionen av .NET SDK för flera plattformar från Ladda ned .NET.

Fortsätt sedan med resten av det här avsnittet för att konfigurera de återstående förutsättningarna.

Hämta exempelresurser

Självstudien drivs av ett Azure Digital Twins-exempelprojekt från slutpunkt till slutpunkt som skrivits i C#. Hämta exempelprojektet på datorn genom att gå till exempellänken och välja knappen Bläddra kod under rubriken.

Detta tar dig till GitHub-lagringsplatsen för exemplen, som du kan ladda ned som en .zip genom att välja knappen Kod följt av Ladda ned ZIP.

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

Då laddas en .zip-mapp ned till datorn som digital-twins-samples-main.zip. Packa upp mappen och extrahera filerna.

Förbereda en Azure Digital Twins-instans

För att arbeta med Azure Digital Twins i den här artikeln behöver du 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 kan du använda den instansen och gå vidare till nästa avsnitt. Annars följer du anvisningarna i Konfigurera en instans och autentisering. Anvisningarna innehåller information som hjälper dig att kontrollera att du har slutfört varje steg.

När du har konfigurerat instansen antecknar du instansens värdnamn. Du hittar värdnamnet i Azure-portalen.

Konfigurera exempelprojektet

Konfigurera sedan ett exempelklientprogram som interagerar med din Azure Digital Twins-instans.

Navigera på datorn till mappen som du laddade ned tidigare från Azure Digital Twins-exempel från slutpunkt till slutpunkt (och packa upp den om du inte redan har gjort det).

I mappen navigerar du till digital-twins-samples-main\AdtSampleApp\SampleClientApp och öppnar filen appsettings.json . Den här JSON-filen innehåller en konfigurationsvariabel som krävs för att köra projektet.

I filtexten ändrar du till webbadressen instanceUrl till azure Digital Twins-instansens värdnamn (genom att lägga till https:// framför värdnamnet enligt nedan).

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

Spara och stäng filen.

Konfigurera lokala Azure-autentiseringsuppgifter

Det här exemplet använder DefaultAzureCredential (en del av biblioteket) för att autentisera Azure.Identity användare med Azure Digital Twins-instansen när du kör den på den lokala datorn. Mer information om olika sätt som en klientapp kan autentisera med Azure Digital Twins finns i Skriva kod för appautentisering.

Med DefaultAzureCredentialsöker exemplet efter autentiseringsuppgifter i din lokala miljö, till exempel en Azure-inloggning i ett lokalt Azure CLI eller i Visual Studio eller Visual Studio Code. Därför bör du logga in på Azure lokalt via någon av dessa mekanismer för att konfigurera autentiseringsuppgifter för exemplet.

Om du använder Visual Studio eller Visual Studio Code för att köra kodexempel kontrollerar du att du är inloggad i redigeringsprogrammet med samma Azure-autentiseringsuppgifter som du vill använda för att komma åt din Azure Digital Twins-instans. Om du använder ett lokalt CLI-fönster kör az login du kommandot för att logga in på ditt Azure-konto. När du sedan kör kodexemplet bör du autentiseras automatiskt.

Kör exempelprojektet

Nu när appen och autentiseringen har konfigurerats öppnar du ett lokalt konsolfönster som du ska använda för att köra projektet. Navigera i konsolen till mappen digital-twins-samples-main\AdtSampleApp\SampleClientApp och kör projektet med det här dotnet-kommandot:

dotnet run

Projektet börjar köras, utföra autentisering och vänta på ett kommando.

Här är en skärmbild av hur projektkonsolen ser ut:

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

Dricks

Om du vill ha en lista över alla möjliga kommandon som du kan använda med det här projektet anger du help i projektkonsolen och trycker på Retur.

När du har bekräftat att appen körs kan du sluta köra projektet. Du kör den igen senare i självstudien.

Modellera en fysisk miljö med DTDL

Nu när Azure Digital Twins-instansen och exempelappen 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 är användardefinierade mallar som du kan instansiera för att skapa digitala tvillingar. Modeller för Azure Digital Twins skrivs på ett JSON-liknande språk med namnet Digital Twins Definition Language (DTDL) och de definierar en typ av tvilling när det gäller dess 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.

I exempelprojektmappen som du laddade ned tidigare navigerar du till mappen digital-twins-samples-main\AdtSampleApp\SampleClientApp\Models . Den här mappen innehåller exempelmodeller.

Öppna Room.json för redigering och gör följande ändringar i koden:

  1. 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å.

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

  3. 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"
}

  4. 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.

  1. Gå tillbaka till konsolfönstret som är öppet för mappen digital-twins-samples-main\AdtSampleApp\SampleClientApp och kör konsolappen igen med dotnet run.

  2. I projektkonsolfönstret kör du följande kommando för att ladda upp din uppdaterade rumsmodell tillsammans med en golvmodell som du också använder i nästa avsnitt för att skapa olika typer av tvillingar.

    CreateModels Room Floor

    Utdata bör indikera att modellerna har skapats.

  3. Kontrollera att modellerna har skapats genom att köra kommandot GetModels true. Det här kommandot skriver ut fullständig information för alla modeller som har laddats upp till din Azure Digital Twins-instans. Leta efter den redigerade rumsmodellen i resultatet:

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

Håll konsolappen igång för nästa steg.

Fel

Exempelprogrammet hanterar även fel från tjänsten.

Testa detta genom att köra CreateModels kommandot igen för att försöka ladda upp rumsmodellen som du redan har laddat upp:

CreateModels Room

Eftersom modeller inte kan skrivas över returnerar det här kommandot nu ett tjänstfel som anger att vissa av de modell-ID:t som du försöker skapa redan finns.

Mer information om hur du tar bort befintliga modeller finns i Hantera DTDL-modeller.

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 CreateDigitalTwin du kommandot . 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.

  1. Kör den här koden i projektkonsolen som körs 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.)

    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

    Utdata från dessa kommandon bör indikera att tvillingarna har skapats.

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

  2. Du kan kontrollera att tvillingarna skapades genom att Query köra kommandot . Det här kommandot frågar din Azure Digital Twins-instans efter alla digitala tvillingar som den innehåller. Leta efter tvillingarna room0, room1, floor0 och floor1 i resultaten.

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.

Kommentar

Det underliggande REST-API:et använder JSON Patch-format för att definiera uppdateringar till en tvilling. Kommandoradsappen använder också det här formatet för att ge en sannare upplevelse av vad de underliggande API:erna förväntar sig.

  1. Kör det här kommandot för att ändra Room0s RoomName från "Room0" till "PresidentialSuite":

    UpdateDigitalTwin room0 add /RoomName string PresidentialSuite

    Utdata bör indikera att tvillingen har uppdaterats.

  2. Du kan kontrollera att uppdateringen lyckades genom att köra det här kommandot för att se room0-information:

    GetDigitalTwin 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, vilket gö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 CreateRelationship kommandot . 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.

  1. Kör följande kommandon för att lägga till en relation från var och en contains av de Floor-tvillingar som du skapade tidigare till en motsvarande Rumstvilling. Relationerna heter relationship0 och relationship1.

    CreateRelationship floor0 contains room0 relationship0
CreateRelationship floor1 contains room1 relationship1

    Dricks

    Relationen contains i golvmodellen definierades också med två strängegenskaper och ownershipUserownershipDepartment, så att du även kan ange argument med de inledande värdena för dessa när du skapar relationerna. Här är en alternativ version av kommandot ovan för att skapa relation0 som också anger initiala värden för dessa egenskaper:

    CreateRelationship floor0 contains room0 relationship0 ownershipUser string MyUser ownershipDepartment string myDepartment

    Utdata från dessa kommandon bekräftar att relationerna har skapats:

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

  2. Du kan kontrollera relationerna med något av följande kommandon, som skriver ut relationerna i din Azure Digital Twins-instans.

    • Om du vill se alla relationer som kommer från varje våning (visa relationerna från en sida): 
      GetRelationships floor0
GetRelationships floor1
    • Om du vill se alla relationer som kommer till varje rum (visa relationen från den "andra" sidan): 
      GetIncomingRelationships room0
GetIncomingRelationships room1
    • Om du vill söka efter dessa relationer individuellt, efter ID: 
      GetRelationship floor0 relationship0
GetRelationship floor1 relationship1

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

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

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ö.

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.

Kör följande kommandon i projektkonsolen som körs för att besvara några frågor om exempelmiljön.

  1. Vilka är alla entiteter från min miljö som representeras i Azure Digital Twins? (fråga alla)

    Query

    Med det här kommandot 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 det här kommandot är en utdata som innehåller varje digital tvilling med dess information. Här är ett utdrag:

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

    Dricks

    I exempelprojektet motsvarar kommandot Query utan ytterligare argument .Query SELECT * FROM DIGITALTWINS Om du vill köra frågor mot alla tvillingar i din instans med hjälp av fråge-API:erna eller CLI-kommandona använder du den längre (fullständiga) frågan.

  2. Vilka är alla rum i min miljö? (fråga efter modell)

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

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

  3. Vad är alla rum på våning 0? (fråga efter relation)

    Query 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. Endast rum0 är på våning 0, så det är det enda rummet i resultatet.

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

  4. Vad är alla tvillingar i min miljö med en temperatur över 75? (fråga efter egenskap)

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

    Du kan fråga grafen baserat på egenskaper för att besvara olika 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.

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

  5. Vad är alla rum på golv0 med en temperatur över 75? (sammansatt fråga)

    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

    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.

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

Nu när du har kört flera frågor om det scenario som du har konfigurerat är självstudien klar. Sluta köra projektet och stäng konsolfönstret.

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 för att fortsätta använda den här Azure Digital Twins-instansen och konfigurerat exempelappen för nästa självstudie

  • Om du vill fortsätta använda Azure Digital Twins-instansen, men ta bort alla dess modeller, tvillingar och relationer, kan du använda exempelappens DeleteAllTwins och DeleteAllModels kommandona för att rensa tvillingarna respektive modellerna i din instans.

  • 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 den nedladdade projektmappen från 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 ett exempelklientprogram. 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:

Anslut en lösning från slutpunkt till slutpunkt