Zelfstudie: Een Azure Digital Twins-grafiek maken met behulp van een voorbeeldclient-app

• Voorbeeldclient-app
• CLI

In deze zelfstudie bouwt u een grafiek in Azure Digital Twins met behulp van modellen, tweelingen en relaties. Het hulpprogramma voor deze zelfstudie is de voorbeeldclienttoepassing voor opdrachtregels voor interactie met een Azure Digital Twins-exemplaar. De client-app is vergelijkbaar met de app die is geschreven in Code a client-app.

U kunt dit voorbeeld gebruiken om essentiële Azure Digital Twins-acties uit te voeren, zoals het uploaden van modellen, het maken en wijzigen van tweelingen en het maken van relaties. U kunt ook de code van het voorbeeld bekijken voor meer informatie over de Azure Digital Twins-API's en oefenen met het implementeren van uw eigen opdrachten door het voorbeeldproject naar wens te wijzigen.

In deze zelfstudie gaat u...

• Een omgeving modelleren
• Digitale tweelingen maken
• Relaties toevoegen om een grafiek te vormen
• Query's uitvoeren op de grafiek om vragen te beantwoorden

Vereisten

Voordat u aan deze zelfstudie begint, begint u met deze vereisten:

• Als u geen Azure-abonnement hebt, maakt u een gratis account voordat u begint.
• In deze zelfstudie wordt .NET gebruikt. U kunt de nieuwste versie van de .NET SDK voor meerdere platforms downloaden via .NET downloaden.

Ga vervolgens door met de rest van deze sectie om de resterende vereisten in te stellen.

Voorbeeldbronnen ophalen

De zelfstudie wordt aangestuurd door een end-to-end azure Digital Twins-voorbeeldproject dat is geschreven in C#. Haal het voorbeeldproject op uw computer op door naar de voorbeeldkoppeling te navigeren en de knop Code bladeren onder de titel te selecteren.

Hiermee gaat u naar de GitHub-opslagplaats voor de voorbeelden, die u kunt downloaden als een .zip-bestand door de knop Code te selecteren, gevolgd door ZIP downloaden.

Hiermee wordt een .zip-map naar uw computer gedownload als digital-twins-samples-main.zip. Pak de map uit en extraheer de bestanden.

Een Azure Digital Twins-exemplaar voorbereiden

Als u met Azure Digital Twins in dit artikel wilt werken, hebt u een Azure Digital Twins-exemplaar en de vereiste machtigingen nodig om deze te gebruiken. Als u al een Azure Digital Twins-exemplaar hebt ingesteld, kunt u dat exemplaar gebruiken en doorgaan naar de volgende sectie. Volg anders de instructies in Een instantie en verificatie instellen. De instructies bevatten informatie om te controleren of u elke stap hebt voltooid.

Nadat u uw exemplaar hebt ingesteld, noteert u de hostnaam van het exemplaar. U vindt de hostnaam in Azure Portal.

Het voorbeeldproject configureren

Stel vervolgens een voorbeeldclienttoepassing in die gaat communiceren met uw instantie van Azure Digital Twins.

Navigeer op uw computer naar de map die u eerder hebt gedownload van end-to-end-voorbeelden van Azure Digital Twins (en pak deze uit als u dat nog niet hebt gedaan).

Navigeer in de map naar digital-twins-samples-main\AdtSampleApp\SampleClientApp en open het bestand appsettings.json . Dit JSON-bestand bevat een configuratievariabele die nodig is om het project uit te voeren.

Wijzig in de hoofdtekst van het bestand de URL van de instanceUrl hostnaam van uw Azure Digital Twins-exemplaar (door https:// toe te voegen vóór de hostnaam, zoals hieronder wordt weergegeven).

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

Sla het bestand op en sluit het bestand.

Lokale Azure-referenties instellen

In dit voorbeeld wordt gebruikgemaakt van DefaultAzureCredential (onderdeel van de Azure.Identity-bibliotheek) om gebruikers te verifiëren bij de Azure Digital Twins-instantie wanneer u deze uitvoert op uw lokale machine. Voor meer informatie over verschillende manieren waarop een client-app kan verifiëren met Azure Digital Twins, raadpleegt u Verificatiecode voor app schrijven.

Met DefaultAzureCredential zoekt het voorbeeld naar referenties in uw lokale omgeving, zoals een Azure-aanmelding in een lokale Azure-CLI of in Visual Studio of Visual Studio Code. Daarom moet u zich lokaal aanmelden bij Azure via een van deze mechanismen om referenties in te stellen voor het voorbeeld.

Als u Visual Studio of Visual Studio Code gebruikt om codevoorbeelden uit te voeren, moet u ervoor zorgen dat u bent aangemeld bij die editor met dezelfde Azure-referenties die u wilt gebruiken voor toegang tot uw Azure Digital Twins-exemplaar. Als u een lokaal CLI-venster gebruikt, voert u de az login opdracht uit om u aan te melden bij uw Azure-account. Daarna moet u, wanneer u het codevoorbeeld uitvoert, automatisch worden geverifieerd.

Het voorbeeldproject uitvoeren

Nu de app en verificatie zijn ingesteld, opent u een lokaal consolevenster dat u gaat gebruiken om het project uit te voeren. Navigeer in de console naar de map digital-twins-samples-main\AdtSampleApp\SampleClientApp en voer het project uit met deze dotnet-opdracht:

dotnet run

Het project wordt uitgevoerd, voert verificatie uit en wacht op een opdracht.

Hier volgt een schermopname van hoe de projectconsole eruitziet:

Tip

Voer in de projectconsole help in en druk op Enter voor een lijst met alle mogelijke opdrachten die u bij dit project kunt gebruiken.

Zodra u hebt bevestigd dat de app met succes wordt uitgevoerd, kunt u het project niet meer uitvoeren. U voert deze later in de zelfstudie opnieuw uit.

Een fysieke omgeving modelleren met DTDL

Nu de Azure Digital Twins-instantie en de voorbeeld-app zijn ingesteld, kunt u beginnen met het bouwen van een grafiek van een scenario.

De eerste stap bij het maken van een Azure Digital Twins-oplossing is het definiëren van tweelingmodellen voor uw omgeving.

Modellen zijn vergelijkbaar met klassen in objectgeoriënteerde programmeertalen; ze zijn door de gebruiker gedefinieerde sjablonen die u kunt instantiëren om digitale dubbels te maken. Modellen voor Azure Digital Twins worden geschreven in een JSON-achtige taal met de naam Digital Twins Definition Language (DTDL) en ze definiëren een type dubbel in termen van de eigenschappen, relaties en onderdelen.

Notitie

Met DTDL kunnen ook opdrachten op digitale tweelingen worden gedefinieerd. Opdrachten worden momenteel echter niet ondersteund in de Azure Digital Twins-service.

Navigeer in de voorbeeldprojectmap die u eerder hebt gedownload naar de map digital-twins-samples-main\AdtSampleApp\SampleClientApp\Models . Deze map bevat voorbeeldmodellen.

Open Room.json om te bewerken en breng de volgende wijzigingen aan in de code:

1. Werk het versienummer bij om aan te geven dat u een meer up-to-date versie van dit model maakt. U doet dit door de 1 aan het einde van de @id-waarde rte veranderen in een 2. Elk nummer dat hoger is dan het huidige versienummer werkt ook.

2. Wijzig een eigenschap. Wijzig de naam van de Humidity eigenschap in HumidityLevel (of iets anders als u wilt. Als u iets anders gebruikt dan HumidityLevel, moet u onthouden wat u hebt gebruikt en dat blijven gebruiken in plaats van Vochtigheidsniveau in de hele zelfstudie).

3. Voeg een eigenschap toe. Plak onder de eigenschap HumidityLevel die eindigt op regel 15 de volgende code om de eigenschap RoomName toe te voegen aan de ruimte:

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

4. Een relatie toevoegen. Plak onder de RoomName eigenschap die u zojuist hebt toegevoegd de volgende code om de mogelijkheid voor dit type dubbel toe te voegen om relaties met andere tweelingen te vormen contains :

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

Wanneer u klaar bent, zou het bijgewerkte model moeten overeenkomen met:

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

Vergeet niet het bestand op te slaan voordat u verdergaat.

Modellen uploaden naar Azure Digital Twins

Na het ontwerpen van modellen moet u deze uploaden naar uw Azure Digital Twins-instantie. Hiermee configureert u uw Azure Digital Twins-service-exemplaar met uw eigen aangepaste domeinwoordenlijst. Zodra u de modellen hebt geüpload, kunt u dubbelexemplaren maken die deze gebruiken.

1. Ga terug naar het consolevenster dat is geopend naar de map digital-twins-samples-main\AdtSampleApp\SampleClientApp en voer de console-app opnieuw uit met dotnet run.

2. Voer in het venster van de projectconsole de volgende opdracht uit om uw bijgewerkte ruimtemodel te uploaden, samen met een Floor-model dat u ook in de volgende sectie gaat gebruiken om verschillende typen tweelingen te maken.

   CreateModels Room Floor
   

   De uitvoer zou moeten aangeven dat de modellen met succes zijn gemaakt.

3. Controleer of de modellen zijn gemaakt door de opdracht GetModels true uit te voeren. Met deze opdracht wordt de volledige informatie afgedrukt voor alle modellen die zijn geüpload naar uw Azure Digital Twins-exemplaar. Bekijk het bewerkte Room-model in de resultaten:

   

Houd de console-app actief voor de volgende stappen.

Fouten

De voorbeeldtoepassing handelt ook fouten van de service af.

Als u dit wilt testen, voert u de CreateModels opdracht opnieuw uit om het Ruimtemodel dat u al hebt geüpload opnieuw te uploaden:

CreateModels Room

Omdat modellen niet kunnen worden overschreven, retourneert deze opdracht nu een servicefout die aangeeft dat sommige model-id's die u probeert te maken, al bestaan.

Zie DTDL-modellen beheren voor meer informatie over het verwijderen van bestaande modellen.

Digitale tweelingen maken

Nu er een paar modellen zijn geüpload naar uw instantie van Azure Digital Twins, kunt u digitale tweelingen maken op basis van de modeldefinities. Digitale tweelingen vertegenwoordigen de entiteiten in uw bedrijfsomgeving: dingen als sensoren op een boerderij, ruimten in een gebouw, of lichten in een auto.

U gebruikt de opdracht CreateDigitalTwin om een digitale tweeling te maken. U moet verwijzen naar het model waarop de tweeling is gebaseerd, en kunt desgewenst aanvangswaarden definiëren voor alle eigenschappen in het model. U hoeft in deze fase geen relatiegegevens door te geven.

1. Voer deze code uit in de actieve projectconsole om een aantal tweelingen te maken op basis van het Room-model dat u eerder hebt bijgewerkt en een ander model, Floor. Zoals u weet, heeft Room drie eigenschappen, zodat u argumenten kunt opgeven met de initiële waarden voor deze eigenschappen. (Het initialiseren van eigenschapswaarden is in het algemeen optioneel, maar deze zijn nodig voor deze zelfstudie.)

   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
   

   De uitvoer van deze opdrachten zou moeten aangeven dat de tweelingen met succes zijn gemaakt.

   

2. U kunt controleren of de tweelingen zijn gemaakt door de opdracht uit te Query voeren. Deze opdracht voert een query uit op uw Azure Digital Twins-instantie naar alle digitale tweelingen die deze bevat. Zoek de kamer0, room1, floor0 en floor1 twins in de resultaten.

Notitie

Nadat u een wijziging hebt aangebracht in de gegevens in uw grafiek, kan er een latentie van maximaal 10 seconden zijn voordat de wijzigingen worden doorgevoerd in query's.

De DigitalTwins-API weerspiegelt wijzigingen onmiddellijk, dus als u een direct antwoord nodig hebt, gebruikt u een API-aanvraag (DigitalTwins GetById) of een SDK-aanroep (GetDigitalTwin) om dubbelgegevens op te halen in plaats van een query.

Een digital twin wijzigen

U kunt de eigenschappen van een digitale dubbel die u hebt gemaakt, ook wijzigen.

Notitie

De onderliggende REST API maakt gebruik van de JSON Patch-indeling om updates voor een dubbel te definiëren. De opdrachtregel-app gebruikt deze indeling ook om een echte ervaring te bieden met wat de onderliggende API's verwachten.

1. Voer deze opdracht uit om room0's RoomName te wijzigen van 'Room0' in 'PresidentialSuite':

   UpdateDigitalTwin room0 add /RoomName string PresidentialSuite
   

   De uitvoer zou moeten aangeven dat de tweeling met succes is bijgewerkt.

2. U kunt controleren of de update is voltooid door deze opdracht uit te voeren om de informatie van room0 weer te geven:

   GetDigitalTwin room0
   

   De uitvoer zou de bijgewerkte naam moeten weerspiegelen.

Maak een grafiek door relaties toe te voegen

Vervolgens kunt u enkele relaties tussen deze tweelingen maken om ze te verbinden met een tweelinggrafiek. Tweelinggrafieken worden gebruikt om een gehele omgeving voor te stellen.

De typen relaties die u van de ene dubbel naar de andere kunt maken, worden gedefinieerd in de modellen die u eerder hebt geüpload. De modeldefinitie voor Floor geeft aan dat verdiepingen een type relatie kunnen hebben, containswaardoor het mogelijk is om een contains-type-relatie te maken van elke verdiepingsdubbel naar de bijbehorende ruimte die deze bevat.

Gebruik de opdracht CreateRelationship om een relatie toe te voegen. Geef de dubbel op waaruit de relatie afkomstig is, het type relatie en de tweeling waarmee de relatie verbinding maakt. Geef ten slotte de relatie een unieke id.

1. Voer de volgende opdrachten uit om een contains relatie toe te voegen van elk van de floordubbels die u eerder hebt gemaakt met een bijbehorende kamerdubbel. De relaties hebben de naam relatie0 en relatie1.

   CreateRelationship floor0 contains room0 relationship0
   CreateRelationship floor1 contains room1 relationship1
   

   Tip

   De contains relatie in het floor-model is ook gedefinieerd met twee tekenreekseigenschappen. ownershipUserownershipDepartmentU kunt dus ook argumenten opgeven met de initiële waarden voor deze waarden wanneer u de relaties maakt. Hier volgt een alternatieve versie van de bovenstaande opdracht om relatie0 te maken waarmee ook de initiële waarden voor deze eigenschappen worden opgegeven:

   CreateRelationship floor0 contains room0 relationship0 ownershipUser string MyUser ownershipDepartment string myDepartment
   

   De uitvoer van deze opdrachten bevestigt dat de relaties met succes zijn gemaakt:

   

2. U kunt de relaties met een van de volgende opdrachten controleren, waarmee de relaties in uw Azure Digital Twins-exemplaar worden afgedrukt.

   • Als u alle relaties van elke verdieping wilt zien (de relaties vanaf één zijde bekijken):

     GetRelationships floor0
     GetRelationships floor1
     

   • Als u alle relaties wilt zien die in elke ruimte binnenkomen (de relatie vanaf de andere kant bekijken):

     GetIncomingRelationships room0
     GetIncomingRelationships room1
     

   • Ga als volgt te werk om naar deze relaties afzonderlijk te zoeken, op id:

     GetRelationship floor0 relationship0
     GetRelationship floor1 relationship1
     

De tweelingen en relaties die u in deze zelfstudie hebt ingesteld vormen de volgende conceptuele grafiek:

Query uitvoeren op de tweelinggrafiek om vragen over de omgeving te beantwoorden

Een hoofdfunctie van Azure Digital Twins is de mogelijkheid om gemakkelijk en efficiënt query's uit te voeren op uw tweelinggrafiek om vragen over uw omgeving te beantwoorden.

Notitie

Nadat u een wijziging hebt aangebracht in de gegevens in uw grafiek, kan er een latentie van maximaal 10 seconden zijn voordat de wijzigingen worden doorgevoerd in query's.

De DigitalTwins-API weerspiegelt wijzigingen onmiddellijk, dus als u een direct antwoord nodig hebt, gebruikt u een API-aanvraag (DigitalTwins GetById) of een SDK-aanroep (GetDigitalTwin) om dubbelgegevens op te halen in plaats van een query.

Voer de volgende opdrachten uit in de actieve projectconsole om enkele vragen over de voorbeeldomgeving te beantwoorden.

1. Wat zijn alle entiteiten uit mijn omgeving die worden weergegeven in Azure Digital Twins? (alles opvragen)

   Query
   

   Met deze opdracht kunt u uw omgeving in één oogopslag op een rijtje zetten en ervoor zorgen dat alles wordt weergegeven zoals u wilt dat deze zich in Azure Digital Twins bevindt. Het resultaat van deze opdracht is een uitvoer met elke digitale dubbel met de details. Hier volgt een fragment:

   

   Tip

   In het voorbeeldproject is de opdracht Query zonder aanvullende argumenten het equivalent van Query SELECT * FROM DIGITALTWINS. Gebruik de langere (volledige) query om alle apparaatdubbels in uw exemplaar op te vragen met behulp van de query-API's of de CLI-opdrachten.

2. Wat zijn alle ruimten in mijn omgeving? (query op model)

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

   U kunt uw query beperken tot tweelingen van een bepaald type om meer specifieke informatie te verkrijgen over wat er wordt weergegeven. Het resultaat hiervan toont room0 en room1, maar geeft geen floor0 of floor1 weer (omdat ze verdiepingen zijn, niet kamers).

   

3. Wat zijn alle ruimten op floor0? (query op relatie)

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

   U kunt query's uitvoeren op basis van relaties in uw grafiek, om informatie te krijgen over de manier waarop tweelingen zijn verbonden of om uw query te beperken tot een bepaald gebied. Alleen room0 bevindt zich op floor0, dus is dit de enige ruimte in het resultaat.

   

4. Welke tweelingen in mijn omgeving hebben een temperatuur van meer dan 75 °F? (query op eigenschap)

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

   U kunt query's uitvoeren op de grafiek op basis van eigenschappen om verschillende vragen te beantwoorden, waaronder het vinden van uitbijters in uw omgeving die mogelijk aandacht nodig hebben. Andere vergelijkingsoperators (<,>, = of !=) worden ook ondersteund. room1 wordt hier weergegeven in de resultaten, omdat deze een temperatuur van 80 °F heeft.

   

5. Wat zijn alle ruimten op floor0 met een temperatuur van meer dan 75 °F? (samengestelde query)

   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
   

   U kunt de eerdere query's ook combineren zoals u dat in SQL zou doen, met behulp van combinatie-operatoren zoals AND, OR, NOT. Deze query maakt gebruik van AND om de vorige query over tweelingtemperaturen specifieker te maken. Het resultaat bevat nu alleen ruimten met een temperatuur van meer dan 75 °F op floor0; in dit geval geen. De resultatenset is leeg.

   

Nu u verschillende query's hebt uitgevoerd voor het scenario dat u hebt ingesteld, is de zelfstudie voltooid. Stop met het uitvoeren van het project en sluit het consolevenster.

Resources opschonen

Nadat u deze zelfstudie hebt voltooid, kunt u kiezen welke resources u wilt verwijderen, afhankelijk van wat u hierna wilt doen.

• Als u van plan bent om door te gaan met de volgende zelfstudie, kunt u de resources die u hier hebt ingesteld behouden om door te gaan met het gebruik van dit Azure Digital Twins-exemplaar en de geconfigureerde voorbeeld-app voor de volgende zelfstudie

• Als u het Azure Digital Twins-exemplaar wilt blijven gebruiken, maar alle modellen, tweelingen en relaties wilt wissen, kunt u de voorbeeld-app DeleteAllTwins en DeleteAllModels opdrachten gebruiken om de dubbels en modellen in uw exemplaar te wissen.

• Als u geen van de resources nodig hebt die u in deze zelfstudie hebt gemaakt, kunt u het Azure Digital Twins-exemplaar en alle andere resources uit dit artikel verwijderen met de opdracht az group delete CLI. Hiermee verwijdert u alle Azure-resources in een resourcegroep, evenals de resourcegroep zelf.

  Belangrijk

  Het verwijderen van een resourcegroep kan niet ongedaan worden gemaakt. De resourcegroep en alle resources daarin worden permanent verwijderd. Zorg ervoor dat u niet per ongeluk de verkeerde resourcegroep of resources verwijdert.

  Open Azure Cloud Shell of een lokaal CLI-venster en voer de volgende opdracht uit om de resourcegroep en alles wat deze bevat te verwijderen.

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

U kunt ook de gedownloade projectmap van uw lokale computer verwijderen.

Volgende stappen

In deze zelfstudie hebt u aan de slag gegaan met Azure Digital Twins door een grafiek in uw exemplaar te bouwen met behulp van een voorbeeldclienttoepassing. U hebt modellen, digitale dubbels en relaties gemaakt om een grafiek te vormen. U hebt ook enkele query's uitgevoerd in de grafiek om een idee te krijgen van de soorten vragen die Azure Digital Twins over een omgeving kan beantwoorden.

Ga verder met de volgende zelfstudie om Azure Digital Twins te combineren met andere Azure-services om een end-to-end scenario op basis van gegevens te voltooien:

een end-to-end-oplossing Verbinding maken