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

In deze zelfstudie bouwt u een grafiek in Azure Digital Twins modellen, tweelingen en relaties. Het hulpprogramma voor deze zelfstudie is de voorbeeldopdrachtregelclienttoepassing 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 aan te passen zoals u wilt.

In deze zelfstudie gaat u...

Vereisten

Als u de stappen in deze zelfstudie wilt voltooien, moet u eerst aan de volgende vereisten voltooien.

Als u nog geen abonnement op Azure hebt, maak dan een gratis account aan voordat u begint.

Vereiste resources op halen

Voor het voltooien van deze zelfstudie installeert Visual Studio versie 2019, versie 16.5 of hoger op uw ontwikkelmachine. Als u al een oudere versie hebt geïnstalleerd, kunt u de app Visual Studio Installer op uw machine openen en de prompts volgen om uw installatie bij te werken.

De zelfstudie wordt aangestuurd door Azure Digital Twins end-to-end voorbeeldprojectdat is geschreven in C# . Haal het voorbeeldproject op uw computer op door naar de voorbeeldkoppeling te gaan en de knop Bladeren in code onder de titel te selecteren. Hiermee gaat u naar de GitHub voor de voorbeelden, die u als een .zip kunt downloaden door de knop Code te selecteren, gevolgd door ZIP downloaden.

Hiermee downloadt u .zip map naar uw computer als digital-twins-samples-master.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, moet u eerst een Azure Digital Twins instellen. U hebt ook de vereiste machtigingen nodig om deze te kunnen gebruiken. Als u al een Azure Digital Twins hebt ingesteld, kunt u deze in plaats daarvan gebruiken.

Volg anders de instructies in Een instantie en verificatie instellen. De instructies bevatten informatie om u te helpen controleren of u elke stap met succes hebt voltooid.

Nadat u uw exemplaar hebt ingesteld, noteert u de volgende waarden. U hebt deze waarden later nodig om verbinding te maken met het exemplaar:

• De hostnaam van het exemplaar. U vindt de hostnaam in de Azure Portal.
• Het Azure-abonnement dat u hebt gebruikt om het exemplaar te maken. De naam of id werkt. U vindt het abonnement op de pagina Overzicht van uw exemplaar 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 het bestand dat u eerder hebt gedownload Azure Digital Twins end-to-end-voorbeelden (en los het uit als u dat nog niet hebt gedaan).

Ga in de map naar AdtSampleApp. Open AdtE2ESample.sln in Visual Studio 2019.

Selecteer in Visual Studio SampleClientApp > bestand appSettings.json om het te openen in het bewerkingsvenster. Dit bestand fungeert als een vooraf ingesteld JSON-bestand met de benodigde configuratievariabelen om het project uit te voeren.

Wijzig in de hoofdbalk van het bestand de in de instanceUrl hostnaam-URL 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.

Configureer vervolgens het bestand appsettings.json dat moet worden gekopieerd naar de uitvoermap wanneer u de SampleClientApp compileert. Als u dit wilt doen, selecteert u met deappsettings.jsbestand en kiest u Eigenschappen. Zoek in de inspector Eigenschappen naar de eigenschap Naar uitvoermap kopiëren. Wijzig de waarde in Kopiëren indien nieuwer als deze nog niet is ingesteld op die waarde.

Houd het project AdtE2ESample geopend in Visual Studio om dit in de rest van de zelfstudie te gebruiken.

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 gebruikmaakt van Visual Studio of Visual Studio Code om het codevoorbeeld uit te voeren, moet u ervoor zorgen dat u bent aangemeld bij die editor met dezelfde Azure-referenties die u wilt gebruiken om uw Azure Digital Twins-instantie te openen.

Anders kunt u de Azure-CLI lokaal installeren, de opdrachtprompt uitvoeren op uw machine en de opdracht az login uitvoeren om u aan te melden bij uw Azure-account. Wanneer u hierna uw codevoorbeeld moet uitvoeren, zou u automatisch aangemeld moeten worden.

Het voorbeeldproject uitvoeren

Nu de app en verificatie zijn ingesteld, kunt u het project uitvoeren met deze knop op de werkbalk:

Er wordt een consolevenster geopend, de verificatie wordt uitgevoerd en er wordt gewacht op een opdracht.

Hier ziet u een schermopname van hoe de projectconsole eruitziet:

Nadat u hebt bevestigd dat de app wordt uitgevoerd, sluit u het consolevenster om de app nu niet meer uit te kunnen uitvoeren. U gaat deze later in het artikel opnieuw uitvoeren.

Een fysieke omgeving modelleren met DTDL

Nu de Azure Digital Twins en 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 lijken op klassen in objectgeoriënteerde programmeertalen. Ze bieden door de gebruiker gedefinieerde sjablonen die digitale tweelingen later kunnen volgen en instantiëren. Ze zijn geschreven in een JSON-achtige taal met de naam Digital Twins Definition Language (DTDL) en kunnen de eigenschappen , telemetrie, relaties en onderdelen van een tweeling definiëren.

Gebruik in Visual Studio venster waarin het project AdtE2ESample is geopend het deelvenster Solution Explorer om naar de map AdtSampleApp\SampleClientApp\Models te navigeren. Deze map bevat voorbeeldmodellen.

Selecteer Room.json om het in het bewerkingsvenster te openen, en pas het als volgt aan:

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 Humidity de eigenschap in HumidityLevel (of iets anders als u wilt. Als u iets anders gebruikt dan HumidityLevel, onthoud dan wat u hebt gebruikt en gebruik het overal in de zelfstudie in plaats van HumidityLevel).

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. Voeg een relatie toe. Plak onder de eigenschap RoomName die u zojuist hebt toegevoegd de volgende code om de mogelijkheid toe te voegen dat deze tweeling contains-relaties kan maken met andere tweelingen:

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

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. Nadat u de modellen hebt geüpload, kunt u dubbele exemplaren maken die deze gebruiken.

1. Nadat u het bestand Room.json in de vorige sectie hebt bewerkt, start u opnieuw met het uitvoeren van de console-app.

2. Voer in het venster van de projectconsole de volgende opdracht uit om uw bijgewerkte Room-model 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:

   

Fouten

De voorbeeldtoepassing handelt ook fouten van de service af.

Voer de opdracht opnieuw uit om een van de modellen die u hebt geüpload opnieuw te CreateModels uploaden, voor de tweede keer:

CreateModels Room

Omdat modellen niet kunnen worden overschreven, wordt met deze opdracht nu een servicefout weergegeven. Zie Manage DTDL models (DTDL-modellenbeheren) voor meer informatie over het verwijderen van bestaande modellen.

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

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 verstrekken met de initiële waarden voor deze eigenschappen. (Het initialiseren van eigenschapswaarden is in het algemeen optioneel, maar ze 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 in de resultaten naar de tweelingen room0, room1, floor0 en floor1.

Een digital twin wijzigen

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

1. Voer deze opdracht uit om de RoomName van room0 te wijzigen van Room0 in "SuiteSuite":

   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 geslaagd door deze opdracht uit te voeren om de informatie van room0 te bekijken:

   GetDigitalTwin room0
   

   De uitvoer zou de bijgewerkte naam moeten weerspiegelen.

Maak een grafiek door relaties toe te voegen

Vervolgens kunt u relaties maken tussen deze tweelingen, om ze te verbinden in 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 met de naam contains kunnen hebben, waardoor het mogelijk is om een contains-type-relatie te maken van elke Floor-tweeling naar de bijbehorende ruimte die deze bevat.

Gebruik de opdracht CreateRelationship om een relatie toe te voegen. Geef de tweeling op waar de relatie vandaan komt, het type relatie en de tweeling waar de relatie verbinding mee maakt. Geef ten laatste een unieke id op voor de relatie.

1. Voer de volgende code uit om een 'contains'-relatie toe te voegen van elk van de Floor-tweelingen die u eerder hebt gemaakt naar een overeenkomende Room-tweeling. De relaties hebben de namen relationship0 en relationship1.

   CreateRelationship floor0 contains room0 relationship0
   CreateRelationship floor1 contains room1 relationship1
   

   Tip

   De contains-relatie in het Floor-model is ook gedefinieerd met twee tekenreekseigenschappen, en , zodat u ook argumenten kunt verstrekken met de initiële waarden voor deze waarden wanneer u ownershipUser de relaties ownershipDepartment maakt. Hier is een alternatieve versie van de bovenstaande opdracht om relationship0 te maken, die ook initiële waarden voor deze eigenschappen specificeert:

   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 controleren met een van de volgende opdrachten, waarmee de relaties in uw Azure Digital Twins worden afgedrukt.

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

     GetRelationships floor0
     GetRelationships floor1
     

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

     GetIncomingRelationships room0
     GetIncomingRelationships room1
     

   • Als u deze relaties afzonderlijk wilt 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.

Voer de volgende opdrachten uit in de projectconsole die wordt uitgevoerd 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 in één oogopslag een overzicht van uw omgeving maken en ervoor zorgen dat alles wordt weergegeven zoals u wilt dat deze binnen de Azure Digital Twins. Het resultaat van deze opdracht is een uitvoer met elke digitale tweeling met de details ervan. Hier is 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 niet floor0 of floor1 (omdat het verdiepingen zijn, geen ruimten).

   

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. Wat zijn de tweelingen in mijn omgeving met een temperatuur van meer dan 75 °F? (query op eigenschap)

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

   U kunt een query uitvoeren op de grafiek op basis van eigenschappen om verschillende vragen te beantwoorden, waaronder het vinden van uitschieters 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.

   

Resources opschonen

Nadat u deze zelfstudie hebt doorlopen, 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 deze Azure Digital Twins-instantie en de geconfigureerde voorbeeld-app te blijven gebruiken voor de volgende zelfstudie

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

• Als u de resources die u in deze zelfstudie hebt gemaakt niet nodig hebt, kunt u de Azure Digital Twins-instantie en alle andere resources uit dit artikel verwijderen met de opdracht az group delete. 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 Shellen 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 projectmap van uw lokale computer verwijderen.

Volgende stappen

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

Ga door naar de volgende zelfstudie om Azure Digital Twins met andere Azure-services te combineren om een gegevensgestuurd, end-to-end scenario te voltooien: