Pozyskiwanie danych telemetrycznych usługi IoT Hub do usługi Azure Digital Twins

Artykuł
01/04/2024

W tym przewodniku przedstawiono proces pisania funkcji, która może pozyskiwać dane telemetryczne urządzenia z usługi IoT Hub i wysyłać je do wystąpienia usługi Azure Digital Twins.

Usługa Azure Digital Twins jest oparta na danych z urządzeń IoT i innych źródeł. Typowym źródłem danych urządzenia do użycia w usłudze Azure Digital Twins jest usługa IoT Hub.

Proces pozyskiwania danych do usługi Azure Digital Twins polega na skonfigurowaniu zewnętrznego zasobu obliczeniowego, takiego jak funkcja wykonywana przy użyciu usługi Azure Functions. Funkcja odbiera dane i używa interfejsów API Usługi DigitalTwins do ustawiania właściwości lub wyzwalania zdarzeń telemetrycznych odpowiednio dla cyfrowych reprezentacji bliźniaczych .

Ten dokument z instrukcjami przeprowadzi cię przez proces pisania funkcji, która może pozyskiwać dane telemetryczne urządzenia z usługi IoT Hub.

Wymagania wstępne

Przed kontynuowaniem pracy z tym przykładem należy skonfigurować następujące zasoby jako wymagania wstępne:

Centrum IoT. Aby uzyskać instrukcje, zobacz sekcję Tworzenie centrum IoT Hub w tym przewodniku Szybki start usługi IoT Hub.
Wystąpienie usługi Azure Digital Twins, które będzie odbierać dane telemetryczne urządzenia. Aby uzyskać instrukcje, zobacz Konfigurowanie wystąpienia i uwierzytelniania usługi Azure Digital Twins.

Przykładowy scenariusz telemetrii

W tym przewodniku opisano sposób wysyłania komunikatów z usługi IoT Hub do usługi Azure Digital Twins przy użyciu funkcji na platformie Azure. Istnieje wiele możliwych konfiguracji i pasujących strategii, których można użyć do wysyłania komunikatów, ale na przykład w tym artykule znajdują się następujące części:

Urządzenie termostatu w usłudze IoT Hub ze znanym identyfikatorem urządzenia
Reprezentacja cyfrowej reprezentacji bliźniaczej do reprezentowania urządzenia z zgodnym identyfikatorem

Uwaga

W tym przykładzie użyto prostego dopasowania identyfikatora między identyfikatorem urządzenia a odpowiadającym mu identyfikatorem cyfrowej reprezentacji bliźniaczej, ale istnieje możliwość zapewnienia bardziej zaawansowanych mapowań z urządzenia do bliźniaczej reprezentacji (na przykład z tabelą mapowania).

Za każdym razem, gdy urządzenie termostatu wysyła zdarzenie telemetrii temperatury, funkcja przetwarza dane telemetryczne, a Temperature właściwość cyfrowej reprezentacji bliźniaczej powinna zostać zaktualizowana. Ten scenariusz został opisany na poniższym diagramie:

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.

Dodawanie modelu i reprezentacji bliźniaczej

W tej sekcji skonfigurujesz cyfrową reprezentację bliźniaczą w usłudze Azure Digital Twins, która będzie reprezentować urządzenie termostatu i zostanie zaktualizowana o informacje z usługi IoT Hub.

Aby utworzyć bliźniaczą reprezentację termostatu, najpierw musisz przekazać model termostatu do wystąpienia, który opisuje właściwości termostatu i będzie używany później do utworzenia bliźniaczej reprezentacji bliźniaczej.

Model wygląda następująco:

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

Aby przekazać ten model do wystąpienia reprezentacji bliźniaczych, uruchom następujące polecenie interfejsu wiersza polecenia platformy Azure, które przekazuje powyższy model jako wbudowany kod JSON. Możesz uruchomić polecenie w usłudze Azure Cloud Shell w przeglądarce (użyj środowiska powłoki Bash) lub na komputerze, jeśli interfejs wiersza polecenia jest zainstalowany lokalnie. Istnieje jeden symbol zastępczy nazwy hosta wystąpienia (można również użyć przyjaznej nazwy wystąpienia z niewielkim spadkiem wydajności).

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

Uwaga

Jeśli używasz niczego innego niż usługa Cloud Shell w środowisku powłoki Bash, może być konieczne ucieczka niektórych znaków w wbudowanym formacie JSON, aby była poprawnie analizowana. Aby uzyskać więcej informacji, zobacz Używanie znaków specjalnych w różnych powłokach.

Następnie należy utworzyć jedną reprezentację bliźniacze przy użyciu tego modelu. Użyj następującego polecenia, aby utworzyć bliźniaczą reprezentację termostatu o nazwie termostat67 i ustawić wartość 0,0 jako początkową wartość temperatury. Istnieje jeden symbol zastępczy nazwy hosta wystąpienia (można również użyć przyjaznej nazwy wystąpienia z niewielkim spadkiem wydajności).

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

Po pomyślnym utworzeniu reprezentacji bliźniaczej dane wyjściowe interfejsu wiersza polecenia powinny wyglądać mniej więcej tak:

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

Tworzenie funkcji platformy Azure

W tej sekcji utworzysz funkcję platformy Azure w celu uzyskania dostępu do usługi Azure Digital Twins i zaktualizujesz bliźniacze reprezentacje bliźniacze na podstawie odbieranych zdarzeń telemetrycznych urządzenia IoT. Wykonaj poniższe kroki, aby utworzyć i opublikować funkcję.

Najpierw utwórz nowy projekt usługi Azure Functions typu wyzwalacza usługi Event Grid.

Możesz to zrobić przy użyciu programu Visual Studio (aby uzyskać instrukcje, zobacz Tworzenie usługi Azure Functions przy użyciu programu Visual Studio), Visual Studio Code (aby uzyskać instrukcje, zobacz Tworzenie funkcji języka C# na platformie Azure przy użyciu programu Visual Studio Code) lub interfejs wiersza polecenia platformy Azure (aby uzyskać instrukcje, zobacz Tworzenie funkcji języka C# na platformie Azure z poziomu wiersza polecenia).
Dodaj następujące pakiety do projektu (możesz użyć menedżera pakietów NuGet programu Visual Studio lub polecenia dotnet add package w narzędziu wiersza polecenia).

Utwórz funkcję w projekcie o nazwie IoTHubtoTwins.cs. Wklej następujący kod do pliku funkcji:

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

Zapisz kod funkcji.

Opublikuj projekt za pomocą funkcji IoTHubtoTwins.cs w aplikacji funkcji na platformie Azure.

Aby uzyskać instrukcje dotyczące publikowania funkcji przy użyciu programu Visual Studio, zobacz Tworzenie usługi Azure Functions przy użyciu programu Visual Studio. Aby uzyskać instrukcje dotyczące publikowania funkcji przy użyciu programu Visual Studio Code, zobacz Tworzenie funkcji języka C# na platformie Azure przy użyciu programu Visual Studio Code. Aby uzyskać instrukcje dotyczące publikowania funkcji przy użyciu interfejsu wiersza polecenia platformy Azure, zobacz Tworzenie funkcji języka C# na platformie Azure z poziomu wiersza polecenia.

Po zakończeniu procesu publikowania funkcji możesz użyć tego polecenia interfejsu wiersza polecenia platformy Azure, aby sprawdzić, czy publikowanie zakończyło się pomyślnie. Istnieją symbole zastępcze dla grupy zasobów i nazwa aplikacji funkcji. Polecenie wyświetli informacje o funkcji IoTHubToTwins .

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

Konfigurowanie aplikacji funkcji

Aby uzyskać dostęp do usługi Azure Digital Twins, aplikacja funkcji wymaga przypisanej przez system tożsamości zarządzanej z uprawnieniami dostępu do wystąpienia usługi Azure Digital Twins. Skonfigurujesz tę funkcję w tej sekcji, przypisując rolę dostępu dla funkcji i konfigurując ustawienia aplikacji, aby mogła uzyskiwać dostęp do wystąpienia usługi Azure Digital Twins.

Uruchom następujące polecenia w usłudze Azure Cloud Shell lub lokalnym interfejsie wiersza polecenia platformy Azure.

Uwaga

Ta sekcja musi zostać ukończona przez użytkownika platformy Azure, który ma uprawnienia do zarządzania dostępem użytkowników do zasobów platformy Azure, w tym udzielania i delegowania uprawnień. Typowe role spełniające to wymaganie to właściciel, administrator konta lub kombinacja Administracja istratora dostępu użytkowników i współautora. Aby uzyskać więcej informacji na temat wymagań dotyczących uprawnień dla ról usługi Azure Digital Twins, zobacz Konfigurowanie wystąpienia i uwierzytelniania.

Przypisywanie roli dostępu

Funkcja platformy Azure wymaga przekazania do niego tokenu elementu nośnego. Aby upewnić się, że token elementu nośnego został przekazany, przyznaj aplikacji funkcji rolę Właściciela danych usługi Azure Digital Twins dla wystąpienia usługi Azure Digital Twins, która da aplikacji funkcji uprawnienie do wykonywania działań płaszczyzny danych w wystąpieniu.

Użyj następującego polecenia, aby utworzyć tożsamość zarządzaną przez system dla funkcji (jeśli funkcja ma już tę funkcję , to polecenie wyświetli jego szczegóły). Zanotuj principalId pole w danych wyjściowych. Użyjesz tego identyfikatora, aby odwołać się do funkcji, aby można było udzielić jej uprawnień w następnym kroku.
```
az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
```
principalId Użyj wartości w poniższym poleceniu, aby nadać funkcji rolę Właściciela danych usługi Azure Digital Twins dla wystąpienia usługi Azure Digital Twins.
```
az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"
```

Konfigurowanie ustawień aplikacji

Następnie ustaw dla niej adres URL wystąpienia usługi Azure Digital Twins, ustawiając dla niego zmienną środowiskową.

Napiwek

Adres URL wystąpienia usługi Azure Digital Twins jest wprowadzany przez dodanie https:// na początku nazwy hosta wystąpienia. Aby wyświetlić nazwę hosta wraz ze wszystkimi właściwościami wystąpienia, uruchom polecenie az dt show --dt-name <your-Azure-Digital-Twins-instance>.

Następujące polecenie ustawia zmienną środowiskową dla adresu URL wystąpienia, którego będzie używać funkcja zawsze, gdy będzie ona potrzebna do uzyskania dostępu do wystąpienia.

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

Połączenie funkcji w usłudze IoT Hub

W tej sekcji skonfigurujesz funkcję jako miejsce docelowe zdarzenia dla danych urządzenia usługi IoT Hub. Skonfigurowanie funkcji w ten sposób zapewni, że dane z urządzenia termostatu w usłudze IoT Hub zostaną wysłane do funkcji platformy Azure na potrzeby przetwarzania.

Użyj następującego polecenia interfejsu wiersza polecenia, aby utworzyć subskrypcję zdarzeń używaną przez usługę IoT Hub do wysyłania danych zdarzeń do funkcji IoTHubtoTwins . Istnieje symbol zastępczy umożliwiający wprowadzenie nazwy subskrypcji zdarzeń, a także symbole zastępcze umożliwiające wprowadzenie identyfikatora subskrypcji, grupy zasobów, nazwy centrum IoT oraz nazwy aplikacji funkcji.

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

Dane wyjściowe będą zawierać informacje o utworzonej subskrypcji zdarzeń. Możesz potwierdzić, że operacja została ukończona pomyślnie, sprawdzając provisioningState wartość w wyniku:

"provisioningState": "Succeeded",

Testowanie przy użyciu symulowanych danych IoT

Nową funkcję ruchu przychodzącego można przetestować przy użyciu symulatora urządzenia z poziomu Połączenie kompleksowego rozwiązania. Projekt DeviceSimulator zawiera symulowane urządzenie termostatu, które wysyła przykładowe dane temperatury. Aby skonfigurować symulator urządzenia, wykonaj następujące kroki:

Przejdź do kompleksowego repozytorium przykładowego projektu usługi Azure Digital Twins. Pobierz przykładowy projekt na maszynie, wybierając przycisk Przeglądaj kod poniżej tytułu. Spowoduje to przejście do repozytorium GitHub dla przykładów, które można pobrać jako plik zip, wybierając przycisk Kod , a następnie pobierz plik ZIP.

Spowoduje to pobranie folderu zip na maszynę jako digital-twins-samples-main.zip. Rozpakuj folder i wyodrębnij pliki. Będziesz używać folderu projektu DeviceSimulator .
Rejestrowanie symulowanego urządzenia w usłudze IoT Hub
Konfigurowanie i uruchamianie symulacji

Po wykonaniu tych kroków powinno zostać uruchomione okno konsoli projektu i wysłanie danych telemetrycznych symulowanego urządzenia do centrum IoT.

Screenshot of the output from the device simulator project.

Sprawdzanie poprawności wyników

Podczas uruchamiania symulatora urządzenia powyżej wartość temperatury termostatu cyfrowej reprezentacji bliźniaczej zmieni się. W interfejsie wiersza polecenia platformy Azure uruchom następujące polecenie, aby wyświetlić wartość temperatury. Istnieje jeden symbol zastępczy nazwy hosta wystąpienia (można również użyć przyjaznej nazwy wystąpienia z niewielkim spadkiem wydajności).

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

Uwaga

Jeśli używasz niczego innego niż usługa Cloud Shell w środowisku powłoki Bash, może być konieczne ucieczka $ znaku w zapytaniu w inny sposób, aby została poprawnie przeanalizowana. Aby uzyskać więcej informacji, zobacz Używanie znaków specjalnych w różnych powłokach.

Dane wyjściowe powinny zawierać szczegóły bliźniaczej reprezentacji termostat67, w tym wartość temperatury, w następujący sposób:

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

Aby wyświetlić zmianę Temperature wartości, wielokrotnie uruchamiaj powyższe polecenie zapytania.

Następne kroki

Przeczytaj o ruchu przychodzącym i wychodzącym danych za pomocą usługi Azure Digital Twins:

Ruch przychodzący i wychodzący danych

Pozyskiwanie danych telemetrycznych usługi IoT Hub do usługi Azure Digital Twins

Wymagania wstępne

Przykładowy scenariusz telemetrii

Dodawanie modelu i reprezentacji bliźniaczej

Tworzenie funkcji platformy Azure

Konfigurowanie aplikacji funkcji

Przypisywanie roli dostępu

Konfigurowanie ustawień aplikacji

Połączenie funkcji w usłudze IoT Hub

Testowanie przy użyciu symulowanych danych IoT

Sprawdzanie poprawności wyników

Następne kroki

Dodatkowe zasoby