Oktatóanyag: Azure Digital Twins-diagram létrehozása mintaügyfél-alkalmazás használatával

Ebben az oktatóanyagban egy gráfot hoz létre az Azure Digital Twinsben modellek, ikerpéldányok és kapcsolatok használatával. Az oktatóanyag eszköze az Azure Digital Twins-példányokkal való interakcióhoz használható parancssori ügyfélalkalmazás. Az ügyfélalkalmazás az ügyfélalkalmazás kódjában írthoz hasonló.

Ez a minta olyan alapvető Azure Digital Twins-műveletek végrehajtására használható, mint a modellek feltöltése, az ikerpéldányok létrehozása és módosítása, valamint a kapcsolatok létrehozása. A minta kódját is megvizsgálva megismerheti az Azure Digital Twins API-kat, és saját parancsok implementálását gyakorolhatja úgy, hogy tetszés szerint módosítja a mintaprojektet.

Ebben az oktatóanyagban...

Előfeltételek

Az oktatóanyag megkezdése előtt kezdje az alábbi előfeltételekkel:

• Ha még nincs Azure-előfizetése, kezdés előtt hozzon létre egy ingyenes fiókot.
• Ez az oktatóanyag a .NET-et használja. A .NET SDK legújabb verzióját több platformra is letöltheti a .NET letöltéséből.

Ezután folytassa a szakasz többi részével a fennmaradó előfeltételek beállításához.

Mintaerőforrások lekérése

Az oktatóanyagot egy C#-ban írt, teljes körű Azure Digital Twins-mintaprojekt vezérli. A mintaprojekt lekéréséhez navigáljon a mintahivatkozásra, és válassza a cím alatti Kód tallózása gombot.

Ez a művelet a minták GitHub-adattárát nyitja meg, amelyet .zip ként tölthet le a Kód gombra kattintva, majd a ZIP letöltése gombra kattintva.

Ez a művelet letölt egy .zip mappát a gépére digital-twins-samples-main.zip. Bontsa ki a mappát, és bontsa ki a fájlokat.

Azure Digital Twins-példány előkészítése

Az Azure Digital Twins jelen cikkben való használatához azure Digital Twins-példányra és a használatához szükséges engedélyekre van szüksége. Ha már beállított egy Azure Digital Twins-példányt, használhatja ezt a példányt, és ugorjon a következő szakaszra. Ellenkező esetben kövesse a példány és a hitelesítés beállítása című témakör utasításait. Az utasítások olyan információkat tartalmaznak, amelyek segítenek ellenőrizni, hogy sikeresen végrehajtotta-e az egyes lépéseket.

A példány beállítása után jegyezze fel a példány állomásnevét. A gazdagép nevét az Azure Portalon találja.

A mintaprojekt konfigurálása

Ezután állítson be egy mintaügyfél-alkalmazást, amely az Azure Digital Twins-példányt fogja használni.

Navigáljon a számítógépen a korábban letöltött mappára az Azure Digital Twins végpontok közötti mintáiból (és bontsa ki, ha még nem tette meg).

A mappában lépjen a digital-twins-samples-main\AdtSampleApp\SampleClientApp területre, és nyissa meg a appsettings.json fájlt. Ez a JSON-fájl egy konfigurációs változót tartalmaz, amely a projekt futtatásához szükséges.

A fájl törzsében módosítsa az instanceUrl Azure Digital Twins-példány gazdagépnevének URL-címét (ha https:// a gazdagép neve előtt adja hozzá, ahogy az alább látható).

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

Mentse és zárja be a fájlt.

Helyi Azure-hitelesítő adatok beállítása

Ez a minta a DefaultAzureCredential (a tár része) használatával hitelesíti a Azure.Identity felhasználókat az Azure Digital Twins-példánysal, amikor a helyi gépen futtatja. Az ügyfélalkalmazások Azure Digital Twins-hitelesítésének különböző módjairól az alkalmazáshitelesítési kód írása című témakörben olvashat bővebben.

Ezzel DefaultAzureCredentiala példával a minta hitelesítő adatokat keres a helyi környezetben, például egy Azure-bejelentkezést egy helyi Azure CLI-ben vagy a Visual Studióban vagy a Visual Studio Code-ban. Ezért helyileg kell bejelentkeznie az Azure-ba ezen mechanizmusok egyikével a minta hitelesítő adatainak beállításához.

Ha a Visual Studio vagy a Visual Studio Code használatával futtat kódmintákat, győződjön meg arról , hogy ugyanazokkal az Azure-hitelesítő adatokkal jelentkezett be a szerkesztőbe , amelyeket az Azure Digital Twins-példány eléréséhez használni szeretne. Ha helyi CLI-ablakot használ, futtassa a parancsot az az login Azure-fiókba való bejelentkezéshez. Ezt követően a kódminta futtatásakor automatikusan hitelesíteni kell.

A mintaprojekt futtatása

Most, hogy az alkalmazás és a hitelesítés be van állítva, nyisson meg egy helyi konzolablakot a projekt futtatásához. Navigáljon a konzolablakban a digital-twins-samples-main\AdtSampleApp\SampleClientApp mappához, és futtassa a projektet ezzel a dotnet paranccsal:

dotnet run

A projekt elindul, elvégzi a hitelesítést, és vár egy parancsra.

Íme egy képernyőkép a projektkonzol megjelenéséről:

Miután meggyőződött arról, hogy az alkalmazás sikeresen fut, leállíthatja a projekt futtatását. Az oktatóanyag későbbi részében újra futtathatja.

Fizikai környezet modellezése DTDL-vel

Most, hogy beállította az Azure Digital Twins-példányt és a mintaalkalmazást, megkezdheti egy forgatókönyv diagramjának elkészítését.

Az Azure Digital Twins-megoldás létrehozásának első lépése az ikermodellek meghatározása a környezet számára.

A modellek hasonlóak az objektumorientált programozási nyelvek osztályaihoz; ezek felhasználó által definiált sablonok, amelyeket létrehozhat digitális ikerpéldányok létrehozásához. Az Azure Digital Twins modelljei egy JSON-szerű, Digital Twins Definition Language (DTDL) nevű nyelven íródnak, és tulajdonságaik, kapcsolataik és összetevőik szempontjából meghatároznak egy ikerpéldánytípust.

A korábban letöltött mintaprojekt mappában lépjen a digital-twins-samples-main\AdtSampleApp\SampleClientApp\Models mappába. Ez a mappa mintamodelleket tartalmaz.

Nyissa meg a Room.json szerkesztésre, és végezze el a következő módosításokat a kódon:

1. Frissítse a verziószámot, hogy jelezze, hogy a modell frissítettebb verzióját adja meg. Ezt úgy teheti meg, hogy az érték végén @id lévő 1-et 2-re módosítja. Az aktuális verziószámnál nagyobb szám is működni fog.

2. Tulajdonság szerkesztése. Módosítsa a tulajdonság nevét Humidity Páratartalomszintre (vagy ha szeretné, valami másra). Ha valami mást használ, mint a HumidityLevel, jegyezze meg, mit használt, és folytassa a használatát a Páratartalomszint helyett az oktatóanyag során).

3. Adjon hozzá egy tulajdonságot. HumidityLevel A 15. sorban végződő tulajdonság alatt illessze be a következő kódot, hogy hozzáadjon egy RoomName tulajdonságot a helyiséghez:

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

4. Adjon hozzá egy kapcsolatot. RoomName Az imént hozzáadott tulajdonság alá illessze be a következő kódot, hogy hozzáadja az ikerpéldányok contains ilyen típusú kapcsolatának lehetőségét más ikerpéldányokkal:

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

Ha végzett, a frissített modellnek a következőnek kell megfelelnie:

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

Mielőtt továbblépne, mentse a fájlt.

Modellek feltöltése az Azure Digital Twinsbe

A modellek tervezése után fel kell töltenie őket az Azure Digital Twins-példányba. Ezzel konfigurálja az Azure Digital Twins szolgáltatáspéldányt saját egyéni tartománykincsével. Miután feltöltötte a modelleket, létrehozhat azokat használó ikerpéldányokat.

1. Térjen vissza a digital-twins-samples-main\AdtSampleApp\SampleClientApp mappához megnyitott konzolablakhoz, és futtassa újra a konzolalkalmazást a következőveldotnet run: .

2. A projektkonzol ablakában futtassa a következő parancsot a frissített szobamodell és egy padlómodell feltöltéséhez, amelyet a következő szakaszban a különböző típusú ikerpéldányok létrehozásához is használni fog.

   CreateModels Room Floor
   

   A kimenetnek azt kell jeleznie, hogy a modellek sikeresen létrejöttek.

3. Ellenőrizze, hogy a modellek létre lettek-e hozva a parancs futtatásával GetModels true. Ez a parancs kinyomtatja az Azure Digital Twins-példányba feltöltött összes modell teljes adatait. Keresse meg a szerkesztett szobamodellt az eredmények között:

   

A következő lépések végrehajtásához futtassa a konzolalkalmazást.

Hibák

A mintaalkalmazás a szolgáltatás hibáit is kezeli.

A hibakezelés teszteléséhez futtassa újra a parancsot a CreateModels már feltöltött szobamodell újbóli betöltéséhez:

CreateModels Room

Mivel a modellek nem írhatók felül, ez a parancs most egy szolgáltatáshibát ad vissza, amely azt jelzi, hogy a létrehozni kívánt modellazonosítók némelyike már létezik.

A meglévő modellek törlésének részleteiért lásd : DTDL-modellek kezelése.

Digitális ikerpéldányok létrehozása

Most, hogy néhány modell fel lett töltve az Azure Digital Twins-példányba, létrehozhat digitális ikerpéldányokat a modelldefiníciók alapján. A digitális ikerpéldányok az üzleti környezeten belüli entitásokat jelölik– ilyenek például a farm érzékelői, az épület helyiségei vagy az autó fényei.

Digitális ikerpéldány létrehozásához használja a CreateDigitalTwin parancsot. Hivatkoznia kell arra a modellre, amelyen az ikerpéldány alapul, és megadhat kezdeti értékeket a modell bármely tulajdonságához. Ebben a szakaszban nem kell semmilyen kapcsolati információt átadnia.

1. Futtassa ezt a kódot a futó projektkonzolon, hogy több ikerpéldányt hozzon létre a korábban frissített Szoba modell és egy másik modell, a Floor alapján. Ne feledje, hogy a Helyiség három tulajdonsággal rendelkezik, így argumentumokat adhat meg ezeknek a tulajdonságoknak a kezdeti értékeivel. (A tulajdonságértékek inicializálása általában nem kötelező, de ehhez az oktatóanyaghoz szükség van rájuk.)

   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
   

   A parancsok kimenetének azt kell jeleznie, hogy az ikerpéldányok sikeresen létrejöttek.

   

2. A parancs futtatásával Query ellenőrizheti, hogy az ikerpéldányok létre lettek-e hozva. Ez a parancs lekérdezi az Azure Digital Twins-példányt az összes benne lévő digitális ikerpéldányhoz. Keresse meg a room0, room1, floor0, és floor1 ikerpéldányokat az eredményekben.

Digitális ikerpéldány módosítása

A létrehozott ikerpéldány tulajdonságait is módosíthatja.

1. Futtassa ezt a parancsot a room0 RoomName elemének "Room0" értékről "PresidentialSuite" értékre való módosításához:

   UpdateDigitalTwin room0 add /RoomName string PresidentialSuite
   

   A kimenetnek azt kell jeleznie, hogy az ikerpéldány sikeresen frissült.

2. A frissítés sikerességét az alábbi parancs futtatásával ellenőrizheti a Room0 információinak megtekintéséhez:

   GetDigitalTwin room0
   

   A kimenetnek tükröznie kell a frissített nevet.

Diagram létrehozása kapcsolatok hozzáadásával

Ezután létrehozhat néhány kapcsolatot ezek között az ikerpéldányok között, hogy összekapcsolja őket egy ikergráfban. Az ikergráfok egy teljes környezetet jelölnek.

Az ikerpéldányról a másikra létrehozható kapcsolatok típusai a korábban feltöltött modelleken belül vannak definiálva. A Floor modelldefiníciója azt határozza meg, hogy a padlók rendelkezhetnek egy úgynevezett containskapcsolattípussal, amely lehetővé teszi egy contains-type kapcsolat létrehozását az egyes emeleti ikerpéldányok és a benne található megfelelő helyiség között.

Kapcsolat hozzáadásához használja a CreateRelationship parancsot. Adja meg azt az ikerpéldányt, amelyből a kapcsolat származik, a kapcsolat típusát és azt az ikerpéldányt, amelyhez a kapcsolat kapcsolódik. Végül adjon meg egy egyedi azonosítót a kapcsolatnak.

1. Futtassa az alábbi parancsokat, contains ha kapcsolatot szeretne hozzáadni a korábban létrehozott egyes emeleti ikerpéldányokból egy megfelelő szobai ikerpéldányhoz. A kapcsolatok neve relationship0 és relationship1.

   CreateRelationship floor0 contains room0 relationship0
   CreateRelationship floor1 contains room1 relationship1
   

   Tipp.

   A contains Floor modellben lévő kapcsolatot két sztringtulajdonság is definiálta, ownershipUser így ownershipDepartmenta kapcsolatok létrehozásakor argumentumokat is megadhat ezeknek a tulajdonságoknak a kezdeti értékeivel. Az előző parancs relationship0 egy másik verziója, amely az alábbi tulajdonságok kezdeti értékeit is megadja:

   CreateRelationship floor0 contains room0 relationship0 ownershipUser string MyUser ownershipDepartment string myDepartment
   

   Az alábbi parancsok kimenete megerősíti, hogy a kapcsolatok sikeresen létrejöttek:

   

2. A kapcsolatokat az alábbi parancsok bármelyikével ellenőrizheti, amelyek kinyomtatják a kapcsolatokat az Azure Digital Twins-példányban.

   • Ha látni szeretné, hogy minden kapcsolat lejön az egyes emeletekről (a kapcsolatokat az egyik oldalról tekintheti meg):

     GetRelationships floor0
     GetRelationships floor1
     

   • Az egyes szobákba érkező összes kapcsolat megtekintése (a kapcsolat megtekintése a "másik" oldalról):

     GetIncomingRelationships room0
     GetIncomingRelationships room1
     

   • Ha ezeket a kapcsolatokat egyenként szeretné megkeresni, azonosító szerint:

     GetRelationship floor0 relationship0
     GetRelationship floor1 relationship1
     

Az oktatóanyagban beállított ikerpéldányok és kapcsolatok a következő fogalmi gráfot alkotják:

Az ikergráf lekérdezése környezeti kérdések megválaszolásához

Az Azure Digital Twins fő funkciója az ikergráf egyszerű és hatékony lekérdezése a környezettel kapcsolatos kérdések megválaszolásához.

Futtassa a következő parancsokat a futó projektkonzolon a mintakörnyezettel kapcsolatos kérdések megválaszolásához.

1. Mik a környezetem összes entitása az Azure Digital Twinsben? (az összes lekérdezése)

   Query
   

   Ez a parancs lehetővé teszi, hogy egy pillantással áttekintse a környezetet, és győződjön meg arról, hogy minden úgy jelenik meg, ahogy szeretné, hogy az Azure Digital Twinsben legyen. Ennek a parancsnak az eredménye egy olyan kimenet, amely az egyes digitális ikerpéldányokat tartalmazza annak részleteivel. Íme egy részlet:

   

   Tipp.

   A mintaprojektben a többi argumentum nélküli parancs Query a megfelelője Query SELECT * FROM DIGITALTWINS. Ha le szeretné kérdezni a példány összes ikerpéldányát a Lekérdezés API-k vagy a CLI-parancsok használatával, használja a hosszabb (teljes) lekérdezést.

2. Mik a környezetemben lévő összes szoba? (lekérdezés modell szerint)

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

   A lekérdezést egy bizonyos típusú ikerpéldányra korlátozhatja, hogy pontosabb információkat kapjon a képviselt adatokról. Ennek eredménye a room0 és a room1, de nem a floor0 vagy a floor1 (mivel ezek emeletek, nem szobák).

   

3. Mik azok a szobák a padlón? (lekérdezés kapcsolat szerint)

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

   A gráfban lévő kapcsolatok alapján lekérdezheti az ikerpéldányok kapcsolatát, vagy korlátozhatja a lekérdezést egy adott területre. Csak a 0 szoba van a padlón, tehát ez az egyetlen helyiség az eredményben.

   

4. Milyen ikerpéldányok vannak a környezetemben 75 fölötti hőmérséklettel? (lekérdezés tulajdonság szerint)

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

   A gráfot tulajdonságok alapján kérdezheti le különböző kérdések megválaszolásához, beleértve a környezetében lévő olyan kiugró értékek megkeresését, amelyek figyelmet igényelhetnek. Más összehasonlító operátorok (<,>, =vagy !=) is támogatottak. room1 jelenik meg az eredmények itt, mert a hőmérséklete 80.

   

5. Mik azok a szobák a padlón, amelyek hőmérséklete 75 felett van? (összetett lekérdezés)

   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
   

   Kombinálhatja a korábbi lekérdezéseket is, mint az SQL-ben, olyan kombinációs operátorok használatával, mint a AND, OR. NOT Ez a lekérdezés az AND ikerhőmérsékletekkel kapcsolatos előző lekérdezés pontosabbá tétele. Az eredmény most már csak a 75-ösnél magasabb hőmérsékletű helyiségeket tartalmazza, amelyek a padlón vannak – ami ebben az esetben egyik sem. Az eredményhalmaz üres.

   

Most, hogy több lekérdezést is futtatott a beállított forgatókönyvben, az oktatóanyag befejeződött. Állítsa le a projekt futtatását, és zárja be a konzolablakot.

Az erőforrások eltávolítása

Az oktatóanyag elvégzése után kiválaszthatja, hogy mely erőforrásokat szeretné eltávolítani a következő lépéstől függően.

• Ha a következő oktatóanyag folytatását tervezi, megtarthatja az itt beállított erőforrásokat, hogy továbbra is használhassa ezt az Azure Digital Twins-példányt, és konfigurálja a mintaalkalmazást a következő oktatóanyaghoz

• Ha továbbra is az Azure Digital Twins-példányt szeretné használni, de törli az összes modellt, ikerpéldányt és kapcsolatot, a mintaalkalmazás DeleteAllTwins és DeleteAllModels a parancsok használatával törölheti a példányban lévő ikerpéldányokat és modelleket.

• Ha nincs szüksége az oktatóanyagban létrehozott erőforrások egyikére sem, törölheti az Azure Digital Twins-példányt és az összes többi erőforrást ebből a cikkből az az group delete CLI paranccsal. Ez törli az erőforráscsoport összes Azure-erőforrását, valamint magát az erőforráscsoportot is.

  Fontos

  Az erőforráscsoport törlése nem vonható vissza. Az erőforráscsoport és a benne foglalt erőforrások véglegesen törlődnek. Figyeljen, nehogy véletlenül rossz erőforráscsoportot vagy erőforrásokat töröljön.

  Nyissa meg az Azure Cloud Shellt vagy egy helyi CLI-ablakot, és futtassa a következő parancsot az erőforráscsoport és a benne található elemek törléséhez.

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

Előfordulhat, hogy a letöltött projektmappát is törölni szeretné a helyi gépről.

Következő lépések

Ebben az oktatóanyagban az Azure Digital Twins használatának első lépéseit egy mintaügyfél-alkalmazás használatával készített gráf használatával a példányban. Modelleket, digitális ikerpéldányokat és kapcsolatokat hozott létre egy gráf létrehozásához. A gráfon is futtatott néhány lekérdezést, hogy képet kapjon arról, hogy az Azure Digital Twins milyen típusú kérdésekre tud válaszolni egy környezettel kapcsolatban.

Folytassa a következő oktatóanyaggal az Azure Digital Twins más Azure-szolgáltatásokkal való kombinálásához egy adatvezérelt, teljes körű forgatókönyv végrehajtásához: