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

  • Cikk

Ebben az oktatóanyagban egy gráfot fog létrehozni 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...

  • Környezet modellezése
  • Digitális ikerpéldányok létrehozása
  • Kapcsolatok hozzáadása gráf létrehozásához
  • A gráf lekérdezése a kérdések megválaszolásához

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.

Ekkor megnyílik a minták GitHub-adattára, amelyet .zip formátumban tölthet le a Kód gombra kattintva, majd a ZIP letöltése gombra kattintva.

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

Ez letölt egy .zip mappát a gépére digital-twins-samples-main.zip formátumban. 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 ebben a cikkben való használatához szüksége lesz egy Azure Digital Twins-példányra és a használatához szükséges engedélyekre. 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 mappába, és nyissa meg az 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 , amelyet a projekt futtatásához fog használni. Navigáljon a konzolon 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 parancsot.

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

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

Tipp.

A projekttel használható összes lehetséges parancs listájához írja be help a projektkonzolt, és nyomja le a Return billentyűt.

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

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.

Megjegyzés:

A DTDL lehetővé teszi a digitális ikerpéldányok parancsainak meghatározását is. Az Azure Digital Twins szolgáltatás azonban jelenleg nem támogatja a parancsokat.

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 fájlt 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 az Azure Digital Twins-példányba feltöltött összes modell teljes adatait kinyomtatja. Keresse meg a szerkesztett szobamodellt az eredmények között:

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

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.

Ennek teszteléséhez futtassa újra a parancsot a CreateModels már feltöltött szobamodell újbóli feltö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.

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

  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.

Megjegyzés:

A gráf adatainak módosítása után akár 10 másodperces késés is előfordulhat, mielőtt a módosítások megjelennek a lekérdezésekben.

A DigitalTwins API azonnal tükrözi a változásokat, ezért ha azonnali válaszra van szüksége, lekérdezés helyett használjon EGY API-kérést (DigitalTwins GetById) vagy egy SDK-hívást (GetDigitalTwin).

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

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

Megjegyzés:

A mögöttes REST API JSON Patch-formátummal határozza meg az ikerpéldány frissítéseit. A parancssori alkalmazás is ezt a formátumot használja, hogy igazító élményt nyújtson a mögöttes API-k elvárásaival kapcsolatban.

  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 ezek kezdeti értékeivel. A fenti parancs egy másik verziója a kapcsolatok0 létrehozásához, amely a 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:

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

  2. A kapcsolatokat az alábbi parancsok bármelyikével ellenőrizheti, amely kinyomtatja 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 grafikont alkotják:

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

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.

Megjegyzés:

A gráf adatainak módosítása után akár 10 másodperces késés is előfordulhat, mielőtt a módosítások megjelennek a lekérdezésekben.

A DigitalTwins API azonnal tükrözi a változásokat, ezért ha azonnali válaszra van szüksége, lekérdezés helyett használjon EGY API-kérést (DigitalTwins GetById) vagy egy SDK-hívást (GetDigitalTwin).

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:

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

    Tipp.

    A mintaprojektben a további argumentumok 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).

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

  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.

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

  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.

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

  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.

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

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.

Clean up resources

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.

További 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:

végpontok közötti megoldás Csatlakozás