IoT Hub-telemetrie opnemen in Azure Digital Twins

Artikel
01/04/2024

In deze handleiding wordt uitgelegd hoe u een functie schrijft die telemetriegegevens van apparaten van IoT Hub kan opnemen en naar een exemplaar van Azure Digital Twins kan verzenden.

Azure Digital Twins wordt aangestuurd met gegevens van IoT-apparaten en andere bronnen. Een algemene bron voor apparaatgegevens die moeten worden gebruikt in Azure Digital Twins is IoT Hub.

Het proces voor het opnemen van gegevens in Azure Digital Twins is het instellen van een externe rekenresource, zoals een functie die wordt gemaakt met behulp van Azure Functions. De functie ontvangt de gegevens en gebruikt de DigitalTwins-API's om eigenschappen in te stellen of telemetrie-gebeurtenissen op digitale dubbels dienovereenkomstig in te stellen.

In dit proceduredocument wordt het proces voor het schrijven van een functie beschreven waarmee telemetriegegevens van apparaten uit IoT Hub kunnen worden opgenomen.

Vereisten

Voordat u verdergaat met dit voorbeeld, moet u de volgende resources instellen als vereisten:

Een IoT-hub. Zie de sectie Een IoT Hub maken van deze quickstart voor IoT Hub voor instructies.
Een Azure Digital Twins-exemplaar dat telemetriegegevens van uw apparaat ontvangt. Zie Een Azure Digital Twins-exemplaar en -verificatie instellen voor instructies.

Voorbeeld van telemetriescenario

In deze instructies wordt beschreven hoe u berichten verzendt van IoT Hub naar Azure Digital Twins met behulp van een functie in Azure. Er zijn veel mogelijke configuraties en overeenkomende strategieën die u kunt gebruiken voor het verzenden van berichten, maar het voorbeeld voor dit artikel bevat de volgende onderdelen:

Een thermostaatapparaat in IoT Hub, met een bekende apparaat-id
Een digitale dubbel die het apparaat vertegenwoordigt, met een overeenkomende id

Notitie

In dit voorbeeld wordt een eenvoudige id-overeenkomst gebruikt tussen de apparaat-id en de bijbehorende id van een digitale dubbel, maar het is mogelijk om geavanceerdere toewijzingen van het apparaat aan de bijbehorende dubbel te bieden (bijvoorbeeld met een toewijzingstabel).

Wanneer een temperatuurtelemetrie-gebeurtenis door het thermostaatapparaat wordt verzonden, verwerkt een functie de telemetrie en de Temperature eigenschap van de digitale dubbel. Dit scenario wordt beschreven in een diagram hieronder:

Diagram of IoT Hub device sending Temperature telemetry to a function in Azure, which updates a Temperature property on a twin in Azure Digital Twins.

Een model en een dubbel toevoegen

In deze sectie stelt u een digitale dubbel in Azure Digital Twins in die het thermostaatapparaat vertegenwoordigt en wordt bijgewerkt met informatie van IoT Hub.

Als u een thermostaattypedubbel wilt maken, moet u eerst het thermostaatmodel uploaden naar uw exemplaar, waarin de eigenschappen van een thermostaat worden beschreven en later worden gebruikt om de tweeling te maken.

Het model ziet er als volgt uit:

{
    "@id": "dtmi:contosocom:DigitalTwins:Thermostat;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;3",
    "contents": [
      {
        "@type": "Property",
        "name": "Temperature",
        "schema": "double"
      }
    ]
  }

Als u dit model wilt uploaden naar uw twins-exemplaar, voert u de volgende Azure CLI-opdracht uit, waarmee het bovenstaande model als inline-JSON wordt geüpload. U kunt de opdracht uitvoeren in Azure Cloud Shell in uw browser (gebruik de Bash-omgeving) of op uw computer als u de CLI lokaal hebt geïnstalleerd. Er is één tijdelijke aanduiding voor de hostnaam van het exemplaar (u kunt ook de beschrijvende naam van het exemplaar gebruiken met een lichte afname van de prestaties).

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"    }  ]}'

Notitie

Als u iets anders gebruikt dan Cloud Shell in de Bash-omgeving, moet u mogelijk bepaalde tekens in de inline-JSON escapen, zodat deze correct wordt geparseerd. Zie Speciale tekens gebruiken in verschillende shells voor meer informatie.

Vervolgens moet u één dubbel maken met behulp van dit model. Gebruik de volgende opdracht om een thermostaatdubbel met de naam thermostat67 te maken en 0,0 in te stellen als een initiële temperatuurwaarde. Er is één tijdelijke aanduiding voor de hostnaam van het exemplaar (u kunt ook de beschrijvende naam van het exemplaar gebruiken met een lichte afname van de prestaties).

az dt twin create  --dt-name <instance-hostname-or-name> --dtmi "dtmi:contosocom:DigitalTwins:Thermostat;1" --twin-id thermostat67 --properties '{"Temperature": 0.0}'

Wanneer de dubbel is gemaakt, ziet de CLI-uitvoer van de opdracht er ongeveer als volgt uit:

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

De Azure-functie maken

In deze sectie maakt u een Azure-functie voor toegang tot Azure Digital Twins en werkt u tweelingen bij op basis van telemetrie-gebeurtenissen van IoT-apparaten die worden ontvangen. Volg de onderstaande stappen om de functie te maken en te publiceren.

Maak eerst een nieuw Azure Functions-project van het type Event Grid-trigger.

U kunt dit doen met Behulp van Visual Studio (zie Azure Functions ontwikkelen met Visual Studio), Visual Studio Code (zie Een C#-functie maken in Azure met behulp van Visual Studio Code) of de Azure CLI (zie Een C#-functie maken in Azure vanaf de opdrachtregel) voor instructies.
Voeg de volgende pakketten toe aan uw project (u kunt Visual Studio NuGet-pakketbeheer gebruiken of de dotnet-opdracht pakket toevoegen in een opdrachtregelprogramma).

Maak een functie in het project met de naam IoTHubtoTwins.cs. Plak de volgende code in het functiebestand:

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}");
            }
        }
    }
}

Sla de functiecode op.

Publiceer het project met de functie IoTHubtoTwins.cs naar een functie-app in Azure.

Zie Azure Functions ontwikkelen met Behulp van Visual Studio voor instructies over het publiceren van de functie met behulp van Visual Studio. Zie Een C#-functie maken in Azure met behulp van Visual Studio Code voor instructies over het publiceren van de functie met behulp van Visual Studio Code. Zie Een C#-functie maken in Azure vanaf de opdrachtregel voor instructies over het publiceren van de functie met behulp van de Azure CLI.

Zodra het publiceren van de functie is voltooid, kunt u deze Azure CLI-opdracht gebruiken om te controleren of het publiceren is geslaagd. Er zijn tijdelijke aanduidingen voor uw resourcegroep en de naam van uw functie-app. Met de opdracht wordt informatie over de functie IoTHubToTwins afgedrukt.

az functionapp function show --resource-group <your-resource-group> --name <your-function-app> --function-name IoTHubToTwins

De functie-app configureren

Voor toegang tot Azure Digital Twins heeft uw functie-app een door het systeem toegewezen beheerde identiteit nodig met machtigingen voor toegang tot uw Azure Digital Twins-exemplaar. U stelt dit in deze sectie in door een toegangsrol toe te wijzen voor de functie en de toepassingsinstellingen te configureren, zodat deze toegang heeft tot uw Azure Digital Twins-exemplaar.

Voer de volgende opdrachten uit in Azure Cloud Shell of een lokale Azure CLI.

Notitie

Deze sectie moet worden voltooid door een Azure-gebruiker met machtigingen voor het beheren van gebruikerstoegang tot Azure-resources, waaronder het verlenen en delegeren van machtigingen. Algemene rollen die aan deze vereiste voldoen, zijn Eigenaar, Accountbeheerder of de combinatie van Gebruikerstoegang Beheer istrator en Inzender. Zie Een exemplaar en verificatie instellen voor meer informatie over machtigingsvereisten voor Azure Digital Twins-rollen.

Een toegangsrol toewijzen

Voor de Azure-functie moet een Bearer-token worden doorgegeven. Om ervoor te zorgen dat het Bearer-token wordt doorgegeven, verleent u de functie-app de rol Azure Digital Twins-gegevenseigenaar voor uw Azure Digital Twins-exemplaar, waarmee de functie-app toestemming geeft om activiteiten in het gegevensvlak op het exemplaar uit te voeren.

Gebruik de volgende opdracht om een door het systeem beheerde identiteit voor uw functie te maken (als de functie al een identiteit heeft, worden de details van deze opdracht afgedrukt). Noteer het principalId veld in de uitvoer. U gebruikt deze id om naar de functie te verwijzen, zodat u deze in de volgende stap machtigingen kunt verlenen.
```
az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
```
Gebruik de principalId waarde in de volgende opdracht om de functie de rol Azure Digital Twins-gegevenseigenaar te geven voor uw Azure Digital Twins-exemplaar.
```
az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"
```

Toepassingsinstellingen configureren

Maak vervolgens de URL van uw Azure Digital Twins-exemplaar toegankelijk voor uw functie door er een omgevingsvariabele voor in te stellen.

Tip

De URL van het Azure Digital Twins-exemplaar wordt gemaakt door https:// toe te voegen aan het begin van de hostnaam van uw exemplaar. Als u de hostnaam, samen met alle eigenschappen van uw exemplaar, wilt zien, voert u deze uit az dt show --dt-name <your-Azure-Digital-Twins-instance>.

Met de volgende opdracht wordt een omgevingsvariabele ingesteld voor de URL van uw exemplaar die door uw functie wordt gebruikt wanneer deze toegang nodig heeft tot het exemplaar.

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>"

Verbinding maken de functie naar IoT Hub

In deze sectie stelt u uw functie in als een gebeurtenisbestemming voor de IoT Hub-apparaatgegevens. Als u uw functie op deze manier instelt, zorgt u ervoor dat de gegevens van het thermostaatapparaat in IoT Hub worden verzonden naar de Azure-functie voor verwerking.

Gebruik de volgende CLI-opdracht om een gebeurtenisabonnement te maken dat door de IoT Hub wordt gebruikt om gebeurtenisgegevens naar de IoTHubtoTwins-functie te verzenden. Er is een tijdelijke aanduiding voor u om een naam in te voeren voor het gebeurtenisabonnement en er zijn ook tijdelijke aanduidingen voor het invoeren van uw abonnements-id, resourcegroep, IoT-hubnaam en de naam van uw functie-app.

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

In de uitvoer wordt informatie weergegeven over het gebeurtenisabonnement dat is gemaakt. U kunt controleren of de bewerking is voltooid door de provisioningState waarde in het resultaat te controleren:

"provisioningState": "Succeeded",

Testen met gesimuleerde IoT-gegevens

U kunt uw nieuwe toegangsbeheerfunctie testen met behulp van de apparaatsimulator van Verbinding maken een end-to-end-oplossing. Het DeviceSimulator-project bevat een gesimuleerd thermostaatapparaat waarmee voorbeeldtemperatuurgegevens worden verzonden. Voer de volgende stappen uit om de apparaatsimulator in te stellen:

Navigeer naar de end-to-end-voorbeeldprojectopslagplaats van Azure Digital Twins. Haal het voorbeeldproject op uw computer op door 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. U gebruikt de projectmap DeviceSimulator .
Het gesimuleerde apparaat registreren bij IoT Hub
De simulatie configureren en uitvoeren

Nadat u deze stappen hebt voltooid, moet er een projectconsolevenster worden uitgevoerd en gesimuleerde apparaattelemetriegegevens naar uw IoT-hub worden verzonden.

Screenshot of the output from the device simulator project.

Resultaten valideren

Terwijl u de apparaatsimulator hierboven uitvoert, verandert de temperatuurwaarde van de digitale dubbel van de thermostaat. Voer in de Azure CLI de volgende opdracht uit om de temperatuurwaarde te bekijken. Er is één tijdelijke aanduiding voor de hostnaam van het exemplaar (u kunt ook de beschrijvende naam van het exemplaar gebruiken met een lichte afname van de prestaties).

az dt twin query --query-command "SELECT * FROM digitaltwins WHERE \$dtId = 'thermostat67'" --dt-name <instance-hostname-or-name>

Notitie

Als u iets anders gebruikt dan Cloud Shell in de Bash-omgeving, moet u mogelijk het teken in de query anders ontsnappen $ , zodat het correct wordt geparseerd. Zie Speciale tekens gebruiken in verschillende shells voor meer informatie.

De uitvoer moet de details van de thermostaat67-dubbel weergeven, inclusief een temperatuurwaarde, zoals deze:

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

Als u de Temperature waardewijziging wilt zien, voert u de bovenstaande queryopdracht herhaaldelijk uit.

Volgende stappen

Meer informatie over inkomend en uitgaand verkeer van gegevens met Azure Digital Twins:

Gegevens voor inkomend en uitgaand verkeer

Delen via

IoT Hub-telemetrie opnemen in Azure Digital Twins

Vereisten

Voorbeeld van telemetriescenario

Een model en een dubbel toevoegen

De Azure-functie maken

De functie-app configureren

Een toegangsrol toewijzen

Toepassingsinstellingen configureren

Verbinding maken de functie naar IoT Hub

Testen met gesimuleerde IoT-gegevens

Resultaten valideren

Volgende stappen

Feedback

Aanvullende resources