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

I den här självstudien skapar du en graf i Azure Digital Twins modeller, tvillingar och relationer. Verktyget för den här självstudien är exempelklientprogrammet på kommandoraden 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 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:er och öva på att implementera egna kommandon genom att ändra exempelprojektet hur du vill.

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

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 kan du skapa ett kostnadsfritt konto innan du börjar.

Hämta nödvändiga resurser

För att slutföra den här självstudien Visual Studio 2019, version 16.5 eller senare på utvecklingsdatorn. Om du redan har en äldre version installerad kan du öppna Visual Studio Installer-appen på datorn och följa anvisningarna för att uppdatera installationen.

Självstudien drivs av ett Azure Digital Twins exempelprojekt från slutet till slut som skrivits i C#. Hämta exempelprojektet på datorn genom att gå till exempellänken och välja knappen Bläddra efter kod under rubriken. Då kommer du till lagringsplatsen GitHub för exemplen, som du kan ladda ned som en .zip genom att välja knappen Kod följt av Ladda ned ZIP.

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

Förbereda en Azure Digital Twins instans

Om du vill Azure Digital Twins den här artikeln måste du först konfigurera en Azure Digital Twins instans. Du behöver också de behörigheter som krävs för att använda den. Om du redan har Azure Digital Twins en instans kan du använda den i stället.

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 ställt in din instans anteckning du följande värden. Du behöver dessa värden för att ansluta till instansen senare:

• Instansens värdnamn. Du hittar värdnamnet i Azure Portal.
• Den Azure-prenumeration som du använde för att skapa instansen. Antingen dess namn eller dess ID fungerar. Du hittar prenumerationen på sidan Översikt för din instans i Azure Portal.

Konfigurera exempelprojektet

Konfigurera sedan ett exempelklientprogram som ska interagera med din Azure Digital Twins instans.

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

När du är i mappen navigerar du till AdtSampleApp. Öppna AdtE2ESample.sln i Visual Studio 2019.

I Visual Studio väljer du filen SampleClientApp > appsettings.jsför att öppna den i redigeringsfönstret. Detta fungerar som en förinställt JSON-fil med de konfigurationsvariabler som krävs för att köra projektet.

I filens brödtext ändrar du till din Azure Digital Twins-instansens instanceUrl värdnamns-URL (genom att lägga https:// framför värdnamnet, enligt nedan).

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

Spara och stäng filen.

Konfigurera sedan filen appsettings.jssom ska kopieras till utdatakatalogen när du skapar SampleClientApp. Det gör du genom att högerklicka appsettings.jspå filen och välja Egenskaper. I egenskapskontrollen letar du upp egenskapen Kopiera till utdatakatalog. Ändra värdet till Kopiera om det är nyare om det inte redan har angetts till det.

Håll projektet AdtE2ESample öppet i Visual Studio att fortsätta använda det i självstudien.

Konfigurera lokala Azure-autentiseringsuppgifter

I det här exemplet används DefaultAzureCredential (en del av biblioteket) för att autentisera användare med Azure Digital Twins-instansen när du kör Azure.Identity 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 DefaultAzureCredential söker exemplet efter autentiseringsuppgifter i din lokala miljö, t. ex. 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 metoder för att ställa in autentiseringsuppgifter för exemplet.

Om du använder Visual Studio eller Visual Studio Code för att köra kod exemplet måste du kontrol lera att du är inloggad i redigeraren med samma Azure-autentiseringsuppgifter som du vill använda för att få åtkomst till Azure Digitals-instansen.

Annars kan du installera den lokala Azure CLI, starta en kommando tolk på datorn och köra az login kommandot för att logga in på ditt Azure-konto. När du har loggat in när du kör kod exemplet ska du logga in automatiskt.

Kör exempelprojektet

Nu när appen och autentiseringen har ställts in kör du projektet med den här knappen i verktygsfältet:

Ett konsolfönster öppnas, utför autentisering och väntar på ett kommando.

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

När du har bekräftat att appen körs stänger du konsolfönstret för att sluta köra appen för tillfället. Du kör den igen senare i artikeln.

Modellera en fysisk miljö med DTDL

Nu när Azure Digital Twins-instansen och exempelappen har ställts in kan du börja skapa ett diagram över ett scenario.

Det första steget i att skapa 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 i ett JSON-liknande språk som kallas Digital Twins Definition Language (DTDL) och kan definiera en tvillings egenskaper , telemetri, relationer och komponenter.

I ditt Visual Studio där projektet AdtE2ESample är öppet använder du Solution Explorer-fönstret för att navigera till mappen AdtSampleApp\SampleClientApp\Models. Den här mappen innehåller exempelmodeller.

Välj Room.json för att öppna det i redigeringsfönstret och ändra det på följande sätt:

1. Uppdatera versionsnumret för att ange att du tillhandahåller en mer uppdaterad version av den här modellen. Gör detta genom att ändra 1 i slutet av @id värdet till 2. Alla tal som är större än det aktuella versionsnumret fungerar också.

2. Redigera en egenskap. Ändra namnet på egenskapen Humidity 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 egenskap i RoomName rummet:

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

4. Lägg till en relation. Under egenskapen som du just lade till klistrar du in följande kod för att lägga till möjligheten för den här typen av tvilling att RoomName skapa innehåller 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;2"
  }

Se till att spara filen innan du fortsätter.

Upload modeller till Azure Digital Twins

När du har designar modeller måste du ladda upp dem till din Azure Digital Twins instans. När du gör det konfigureras din Azure Digital Twins-tjänstinstans med din egen vokabulär för anpassade domäner. När du har laddat upp modellerna kan du skapa tvillinginstanser som använder dem.

1. När du har redigerat room.json-filen i föregående avsnitt börjar du köra konsolappen igen.

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 den fullständiga informationen för alla modeller som har laddats upp till din Azure Digital Twins instans. Leta efter den redigerade rumsmodellen i resultatet:

   

Fel

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

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

CreateModels Room

Eftersom modeller inte kan skrivas över returnerar det här kommandot nu ett tjänstfel. Mer information om hur du tar bort befintliga modeller finns i Hantera DTDL-modeller.

Response 409: Service request failed.
Status: 409 (Conflict)

Content:
{"error":{"code":"ModelAlreadyExists","message":"Could not add model dtmi:example:Room;2 as it already exists. Use Model_List API to view models that already exist. See the Swagger example.(http://aka.ms/ModelListSwSmpl)"}}

Headers:
Strict-Transport-Security: REDACTED
Date: Wed, 20 May 2020 00:53:49 GMT
Content-Length: 223
Content-Type: application/json; charset=utf-8

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ö – saker som sensorer på en farm, rum i en byggnad eller lampor i en bil.

Om du vill skapa en digital tvilling använder du CreateDigitalTwin kommandot . Du måste referera till modellen som tvillingen baseras på och du kan även definiera inledande 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å rumsmodellen som du uppdaterade tidigare och en annan modell, Floor. Kom ihåg att Rum 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.

   

2. Du kan kontrollera att tvillingarna har skapats genom att köra Query kommandot . Det här kommandot frågar Azure Digital Twins instansen efter alla digital twins som den innehåller. Leta efter tvillingarna room0, room1, floor0 och floor1 i resultatet.

Ändra en digital tvilling

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

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

   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:s information:

   GetDigitalTwin room0
   

   Utdata bör återspegla det uppdaterade namnet.

Skapa en graf genom att lägga till relationer

Därefter kan du skapa vissa 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 Golv anger att golv kan ha en typ av relation som kallas 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 tvillingen som relationen kommer från, typen av relation och den tvilling som relationen ansluter till. Ge slutligen relationen ett unikt ID.

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

   CreateRelationship floor0 contains room0 relationship0
   CreateRelationship floor1 contains room1 relationship1
   

   Tips

   Contains-relationen i floor-modellen definierades också med två strängegenskaper, och , så du kan också ange argument med inledande värden för dessa när ownershipUser du skapar ownershipDepartment relationerna. Här är en alternativ version av kommandot ovan för att skapa relation0 som också anger inledande 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:

   

2. Du kan verifiera relationerna med något av följande kommandon, vilket 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
     

   • Så här visar du 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 ställt in 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 köra frågor mot din tvillinggraf enkelt och effektivt för att besvara frågor om din miljö.

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

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

   Query
   

   Med det här kommandot kan du snabbt se din miljö och se till att allt visas som du vill att det ska finnas i Azure Digital Twins. Resultatet av det här kommandot är utdata som innehåller varje digital tvilling med information. Här är ett utdrag:

   

   Tips

   I exempelprojektet motsvarar kommandot Query utan några ytterligare argument Query SELECT * FROM DIGITALTWINS . Om du vill fråga alla tvillingar i din instans med hjälp av Fråge-API:er eller CLI-kommandonanvänder du den längre (fullständiga) frågan.

2. Vad ä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 room0 och room1, men visar inte floor0 eller floor1 (eftersom de är golv, inte rum).

   

3. Vad är alla rum på floor0? (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 grafen för att få information om hur tvillingar är anslutna eller begränsa din fråga till ett visst område. Endast room0 är på floor0, så det är det enda rummet i resultatet.

   

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 köra frågor i grafen baserat på egenskaper för att besvara olika frågor, inklusive att hitta extremvärden i din miljö som kan behöva åtgärder. Andra jämförelseoperatorer ( < > , , eller = !=) stöds också. room1 visas i resultatet här, eftersom den har en temperatur på 80.

   

5. Vad är alla rum på floor0 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 på samma sätt som i SQL med hjälp av kombinationsoperatorer som AND , OR , NOT . Den här frågan AND använder för att göra den tidigare frågan om tvillingtemperaturer mer specifik. Resultatet innehåller nu bara rum med temperaturer över 75 som finns på golv0, vilket i det här fallet inte är någon 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 för att fortsätta använda den här Azure Digital Twins-instansen och konfigurerade exempelappen för nästa självstudie

• Om du vill fortsätta att använda Azure Digital Twins-instansen, men ta bort alla dess modeller, tvillingar och relationer, kan du använda exempelappens och kommandon för att rensa tvillingarna och modellerna i din DeleteAllTwins DeleteAllModels 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. 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 Shelloch kör följande kommando för att ta bort resursgruppen och allt som den innehåller.

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

Du kanske också vill ta bort projektmappen från den lokala datorn.

Nästa steg

I den här självstudien har du kommit igång Azure Digital Twins genom att skapa en graf i din instans med hjälp av ett exempelklientprogram. Du skapade modeller, digitala tvillingar och relationer för att skapa en graf. 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 svara på 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 start till slut: