IoT Hub telemetriai adatok betöltése az Azure Digital Twinsbe
Ez az útmutató végigvezet egy olyan függvény írásának folyamatán, amely betöltheti az eszköz telemetriáját az IoT Hubról, és elküldheti azt az Azure Digital Twins egy példányának.
Az Azure Digital Twins IoT-eszközökről és más forrásokból származó adatokkal van vezérelve. Az Azure Digital Twinsben használható eszközadatok gyakori forrása az IoT Hub.
Az adatok Azure Digital Twinsbe való betöltésének folyamata egy külső számítási erőforrás, például az Azure Functions használatával létrehozott függvény beállítása. A függvény megkapja az adatokat, és a DigitalTwins API-kkal ennek megfelelően beállítja a tulajdonságokat, vagy telemetriaeseményeket aktivál a digitális ikerpéldányokon .
Ez az útmutató dokumentum végigvezet egy olyan függvény írásának folyamatán, amely betöltheti az eszköz telemetriáját az IoT Hubról.
Előfeltételek
A példa folytatása előtt a következő erőforrásokat kell előfeltételként beállítania:
- Egy IoT Hub. Útmutatásért tekintse meg az IoT Hub rövid útmutatójának IoT Hub létrehozása szakaszát.
- Egy Azure Digital Twins-példány, amely megkapja az eszköz telemetriáját. Útmutatásért lásd : Azure Digital Twins-példány és -hitelesítés beállítása.
Példa telemetriaforgatókönyvre
Ez az útmutató bemutatja, hogyan küldhet üzeneteket az IoT Hubról az Azure Digital Twinsbe egy Azure-függvény használatával. Az üzenetek küldéséhez számos konfiguráció és egyező stratégia használható, de a jelen cikk példája a következő részeket tartalmazza:
- Termosztátos eszköz az IoT Hubban, ismert eszközazonosítóval
- Az eszközt jelképezendő digitális ikerpéldány egyező azonosítóval
Megjegyzés:
Ez a példa az eszközazonosító és a megfelelő digitális ikerpéldány azonosítója közötti egyszerű azonosító-egyezést használja, de kifinomultabb leképezéseket is biztosíthat az eszközről az ikerpéldányra (például egy leképezési táblával).
Amikor a termosztát-eszköz hőmérsékleti telemetriai eseményt küld, egy függvény feldolgozza a telemetriát, és Temperature frissítenie kell a digitális ikerpéldány tulajdonságát. Ezt a forgatókönyvet az alábbi diagram ismerteti:
Modell és ikerpéldány felvétele
Ebben a szakaszban egy olyan digitális ikerpéldányt fog beállítani az Azure Digital Twinsben, amely a termosztát eszközt képviseli, és az IoT Hub információival frissül.
Termosztát típusú ikerpéldány létrehozásához először fel kell töltenie a termosztátmodellt a példányra, amely leírja a termosztát tulajdonságait, és később az ikerpéldány létrehozásához lesz felhasználva.
A modell így néz ki:
{
"@id": "dtmi:contosocom:DigitalTwins:Thermostat;1",
"@type": "Interface",
"@context": "dtmi:dtdl:context;3",
"contents": [
{
"@type": "Property",
"name": "Temperature",
"schema": "double"
}
]
}
A modell ikerpéldányba való feltöltéséhez futtassa a következő Azure CLI-parancsot, amely a fenti modellt beágyazott JSON-ként tölti fel. Futtathatja a parancsot az Azure Cloud Shellben a böngészőben (használja a Bash-környezetet), vagy a számítógépen, ha a parancssori felület helyileg van telepítve. A példány gazdagépneve egyetlen helyőrzővel rendelkezik (a példány rövid nevét is használhatja a teljesítmény enyhe csökkenésével).
az dt model create --dt-name <instance-hostname-or-name> --models '{ "@id": "dtmi:contosocom:DigitalTwins:Thermostat;1", "@type": "Interface", "@context": "dtmi:dtdl:context;2", "contents": [ { "@type": "Property", "name": "Temperature", "schema": "double" } ]}'
Megjegyzés:
Ha a Cloud Shellen kívül mást is használ a Bash-környezetben, előfordulhat, hogy a beágyazott JSON bizonyos karaktereit meg kell szabadulnia a helyes elemzéshez. További információ: Speciális karakterek használata különböző rendszerhéjakban.
Ezután létre kell hoznia egy ikerpéldányt ezzel a modellel. Az alábbi paranccsal hozzon létre egy termosztát-ikerpéldányt, amelyet termosztát67 néven használ, és állítsa be a 0,0-t kezdeti hőmérséklet-értékként. A példány gazdagépneve egyetlen helyőrzővel rendelkezik (a példány rövid nevét is használhatja a teljesítmény enyhe csökkenésével).
az dt twin create --dt-name <instance-hostname-or-name> --dtmi "dtmi:contosocom:DigitalTwins:Thermostat;1" --twin-id thermostat67 --properties '{"Temperature": 0.0}'
Az ikerpéldány sikeres létrehozásakor a parancs parancssori felületi kimenetének a következőképpen kell kinéznie:
{
"$dtId": "thermostat67",
"$etag": "W/\"0000000-9735-4f41-98d5-90d68e673e15\"",
"$metadata": {
"$model": "dtmi:contosocom:DigitalTwins:Thermostat;1",
"Temperature": {
"lastUpdateTime": "2021-09-09T20:32:46.6692326Z"
}
},
"Temperature": 0.0
}
Az Azure-függvény létrehozása
Ebben a szakaszban egy Azure-függvényt fog létrehozni az Azure Digital Twins eléréséhez és az ikerpéldányok frissítéséhez az általa kapott IoT-eszköztelemetria-események alapján. A függvény létrehozásához és közzétételéhez kövesse az alábbi lépéseket.
Először hozzon létre egy új, Event Grid-eseményindító típusú Azure Functions-projektet.
Ezt a Visual Studióval (útmutatásért lásd: Azure Functions fejlesztése a Visual Studióval), Visual Studio Code (útmutatásért lásd: C#-függvény létrehozása az Azure-ban a Visual Studio Code használatával) vagy az Azure CLI (útmutatásért lásd: C# függvény létrehozása az Azure-ban a parancssorból).
Adja hozzá a következő csomagokat a projekthez (használhatja a Visual Studio NuGet csomagkezelőt, vagy a dotnet add package parancsot egy parancssori eszközben).
Hozzon létre egy függvényt az IoTHubtoTwins.cs nevű projektben. Illessze be a következő kódot a függvényfájlba:
using System; using Azure; using System.Net.Http; using Azure.Core.Pipeline; using Azure.DigitalTwins.Core; using Azure.Identity; using Microsoft.Azure.WebJobs; using Microsoft.Azure.WebJobs.Extensions.EventGrid; using Microsoft.Extensions.Logging; using Newtonsoft.Json; using Newtonsoft.Json.Linq; using Azure.Messaging.EventGrid; namespace IotHubtoTwins { public class IoTHubtoTwins { private static readonly string adtInstanceUrl = Environment.GetEnvironmentVariable("ADT_SERVICE_URL"); private static readonly HttpClient httpClient = new HttpClient(); [FunctionName("IoTHubtoTwins")] // While async void should generally be used with caution, it's not uncommon for Azure function apps, since the function app isn't awaiting the task. #pragma warning disable AZF0001 // Suppress async void error public async void Run([EventGridTrigger] EventGridEvent eventGridEvent, ILogger log) #pragma warning restore AZF0001 // Suppress async void error { if (adtInstanceUrl == null) log.LogError("Application setting \"ADT_SERVICE_URL\" not set"); try { // Authenticate with Digital Twins var cred = new DefaultAzureCredential(); var client = new DigitalTwinsClient(new Uri(adtInstanceUrl), cred); log.LogInformation($"ADT service client connection created."); if (eventGridEvent != null && eventGridEvent.Data != null) { log.LogInformation(eventGridEvent.Data.ToString()); // <Find_device_ID_and_temperature> JObject deviceMessage = (JObject)JsonConvert.DeserializeObject(eventGridEvent.Data.ToString()); string deviceId = (string)deviceMessage["systemProperties"]["iothub-connection-device-id"]; var temperature = deviceMessage["body"]["Temperature"]; // </Find_device_ID_and_temperature> log.LogInformation($"Device:{deviceId} Temperature is:{temperature}"); // <Update_twin_with_device_temperature> var updateTwinData = new JsonPatchDocument(); updateTwinData.AppendReplace("/Temperature", temperature.Value<double>()); await client.UpdateDigitalTwinAsync(deviceId, updateTwinData); // </Update_twin_with_device_temperature> } } catch (Exception ex) { log.LogError($"Error in ingest function: {ex.Message}"); } } } }Mentse a függvénykódot.
Tegye közzé a projektet az IoTHubtoTwins.cs függvénnyel egy Azure-beli függvényalkalmazásban.
A függvény Visual Studióval való közzétételére vonatkozó utasításokért lásd: Azure Functions fejlesztése a Visual Studióval. A függvény Visual Studio Code-tal való közzétételére vonatkozó utasításokért lásd: C#-függvény létrehozása az Azure-ban a Visual Studio Code használatával. A függvény Azure CLI-vel való közzétételére vonatkozó utasításokért lásd: C#-függvény létrehozása az Azure-ban a parancssorból.
Miután a függvény közzétételének folyamata befejeződött, ezzel az Azure CLI-paranccsal ellenőrizheti, hogy a közzététel sikeres volt-e. Vannak helyőrzők az erőforráscsoporthoz és a függvényalkalmazás nevéhez. A parancs kinyomtatja az IoTHubToTwins függvény adatait.
az functionapp function show --resource-group <your-resource-group> --name <your-function-app> --function-name IoTHubToTwins
A függvényalkalmazás konfigurálása
Az Azure Digital Twins eléréséhez a függvényalkalmazásnak egy rendszer által hozzárendelt felügyelt identitásra van szüksége, amely engedélyekkel rendelkezik az Azure Digital Twins-példány eléréséhez. Ezt ebben a szakaszban állíthatja be úgy, hogy hozzárendel egy hozzáférési szerepkört a függvényhez, és konfigurálja az alkalmazásbeállításokat, hogy hozzáférhessen az Azure Digital Twins-példányhoz.
Futtassa az alábbi parancsokat az Azure Cloud Shellben vagy egy helyi Azure CLI-ben.
Megjegyzés:
Ezt a szakaszt egy Olyan Azure-felhasználónak kell kitöltenie, aki jogosult az Azure-erőforrásokhoz való felhasználói hozzáférés kezelésére, beleértve az engedélyek megadását és delegálását. A követelménynek megfelelő gyakori szerepkörök a tulajdonos, a fiókadminisztrátor vagy a felhasználói hozzáférés Rendszergazda istrator és a közreműködő kombinációja. További információ az Azure Digital Twins-szerepkörök engedélykövetelményeiről: Példány és hitelesítés beállítása.
Hozzáférési szerepkör hozzárendelése
Az Azure-függvényhez egy tulajdonosi jogkivonatot kell átadni. A tulajdonosi jogkivonat átadásához adja meg a függvényalkalmazásnak az Azure Digital Twins-példány Azure Digital Twins-adattulajdonosi szerepkörét, amely engedélyt ad a függvényalkalmazásnak az adatsík-tevékenységek végrehajtására a példányon.
A következő paranccsal hozzon létre egy rendszer által felügyelt identitást a függvényhez (ha a függvény már rendelkezik ilyenrel, ez a parancs kinyomtatja annak részleteit). Jegyezze fel a
principalIdkimenet mezőjét. Ezzel az azonosítóval hivatkozhat a függvényre, így a következő lépésben engedélyeket adhat neki.az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>principalIdAz alábbi paranccsal adja meg a függvény Azure Digital Twins-adattulajdonosi szerepkörét az Azure Digital Twins-példányhoz.az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"
Alkalmazásbeállítások konfigurálása
Ezután tegye elérhetővé az Azure Digital Twins-példány URL-címét a függvény számára egy környezeti változó beállításával.
Tipp.
Az Azure Digital Twins-példány URL-címe úgy jön létre , hogy hozzáadja a https:// a példány gazdagépnevének elejéhez. A gazdagép nevének és a példány összes tulajdonságának megtekintéséhez futtassa a parancsot az dt show --dt-name <your-Azure-Digital-Twins-instance>.
Az alábbi parancs beállít egy környezeti változót a példány URL-címéhez, amelyet a függvény minden alkalommal használni fog, amikor hozzá kell férnie a példányhoz.
az functionapp config appsettings set --resource-group <your-resource-group> --name <your-function-app-name> --settings "ADT_SERVICE_URL=https://<your-Azure-Digital-Twins-instance-host-name>"
A függvény Csatlakozás az IoT Hubra
Ebben a szakaszban az IoT Hub-eszközadatok eseménycéljaként fogja beállítani a függvényt. Ha így állítja be a függvényt, az biztosítja, hogy az IoT Hub termosztát-eszközéről származó adatok feldolgozás céljából az Azure-függvénybe kerülnek.
Az alábbi CLI-paranccsal hozzon létre egy esemény-előfizetést, amellyel az IoT Hub eseményadatokat küld az IoTHubtoTwins függvénynek . Egy helyőrzővel megadhatja az esemény-előfizetés nevét, és vannak helyőrzők is, amelyek segítségével megadhatja az előfizetés azonosítóját, az erőforráscsoportot, az IoT Hub nevét és a függvényalkalmazás nevét.
az eventgrid event-subscription create --name <name-for-hub-event-subscription> --event-delivery-schema eventgridschema --source-resource-id /subscriptions/<your-subscription-ID>/resourceGroups/<your-resource-group>/providers/Microsoft.Devices/IotHubs/<your-IoT-hub> --included-event-types Microsoft.Devices.DeviceTelemetry --endpoint-type azurefunction --endpoint /subscriptions/<your-subscription-ID>/resourceGroups/<your-resource-group>/providers/Microsoft.Web/sites/<your-function-app>/functions/IoTHubtoTwins
A kimenet a létrehozott esemény-előfizetéssel kapcsolatos információkat jeleníti meg. Az eredményben szereplő érték ellenőrzésével provisioningState ellenőrizheti, hogy a művelet sikeresen befejeződött-e:
"provisioningState": "Succeeded",
Tesztelés szimulált IoT-adatokkal
Az új bejövőforgalom-függvény teszteléséhez használja az eszközszimulátort Csatlakozás egy végpontok közötti megoldásból. A DeviceSimulator projekt egy szimulált termosztát-eszközt tartalmaz, amely mintahőmérséklet-adatokat küld. Az eszközszimulátor beállításához kövesse az alábbi lépéseket:
Lépjen az Azure Digital Twins végpontok közötti mintaprojekt-adattárára. Kérje le a mintaprojektet a gépére a cím alatti Tallózás gombra kattintva. 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.
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. A DeviceSimulator projektmappát fogja használni.
A lépések elvégzése után a projektkonzol ablakának futnia kell, és szimulált eszköz telemetriai adatokat kell küldenie az IoT Hubnak.
Eredmények ellenőrzése
A fenti eszközszimulátor futtatása közben a termosztát digitális ikerpéldányának hőmérsékleti értéke megváltozik. Az Azure CLI-ben futtassa a következő parancsot a hőmérséklet értékének megtekintéséhez. A példány gazdagépneve egyetlen helyőrzővel rendelkezik (a példány rövid nevét is használhatja a teljesítmény enyhe csökkenésével).
az dt twin query --query-command "SELECT * FROM digitaltwins WHERE \$dtId = 'thermostat67'" --dt-name <instance-hostname-or-name>
Megjegyzés:
Ha a Cloud Shellen kívül mást is használ a Bash-környezetben, előfordulhat, hogy a lekérdezésben szereplő karaktert másképpen kell kikerülnie $ , hogy megfelelően elemezve legyen. További információ: Speciális karakterek használata különböző rendszerhéjakban.
A kimenetnek a termosztát67 ikerpéldány adatait kell megjelenítenie, beleértve a hőmérsékleti értéket is, például a következőt:
{
"result": [
{
"$dtId": "thermostat67",
"$etag": "W/\"dbf2fea8-d3f7-42d0-8037-83730dc2afc5\"",
"$metadata": {
"$model": "dtmi:contosocom:DigitalTwins:Thermostat;1",
"Temperature": {
"lastUpdateTime": "2021-06-03T17:05:52.0062638Z"
}
},
"Temperature": 70.20518558807913
}
]
}
Az Temperature értékváltozás megtekintéséhez futtassa többször a fenti lekérdezési parancsot.
További lépések
Az Azure Digital Twins szolgáltatással történő adatforgalomról és a kimenő forgalomról itt olvashat: