Прием данных телеметрии из Центра Интернета вещей в Azure Digital Twins

Статья
01/04/2024

В этом руководстве описывается процесс написания функции, которая может получать данные телеметрии устройства из Центр Интернета вещей и отправлять их в экземпляр Azure Digital Twins.

Azure Digital Twins управляется данными, которые поступают из IoT и других источников. Популярным источником данных устройств для Azure Digital Twins является Центр Интернета вещей.

Для приема данных в Azure Digital Twins нужно настроить внешний вычислительный ресурс, например функцию, построенную с помощью Функций Azure. Функция получает данные и через API DigitalTwins задает свойства или инициирует события телеметрии в цифровых двойниках, соответственно.

В этом руководстве описывается процесс написания функции, которая может получать данные телеметрии устройства из Центр Интернета вещей.

Необходимые компоненты

Прежде чем продолжить работу с этим примером, необходимо настроить следующие ресурсы:

Центр Интернета вещей. Инструкции см. в разделе "Создание Центр Интернета вещей" этого краткого руководства по Центр Интернета вещей.
Экземпляр Azure Digital Twins, который будет принимать данные телеметрии устройств. Инструкции см. в статье Настройка экземпляра Azure Digital Twins и проверки подлинности в нем.

Пример работы с данными телеметрии

В этой инструкции показано, как отправлять сообщения из Центра Интернета вещей в Azure Digital Twins с помощью функции в Microsoft Azure. Существует множество возможных конфигураций и стратегий сопоставления для отправки сообщений, но в рассматриваемом примере используются следующие компоненты:

термостат в Центре Интернета вещей с известным идентификатором устройства;
цифровой двойник этого устройства с таким же идентификатором.

Примечание.

В этом примере используется непосредственное сопоставление идентификатора устройства с соответствующим идентификатором цифрового двойника, однако для сопоставления устройств и двойников можно использовать более сложные варианты (например, с помощью таблицы сопоставлений).

Всякий раз, когда событие телеметрии температуры отправляется устройством термостата, функция обрабатывает данные телеметрии и Temperature свойство цифрового двойника должно обновляться. Этот сценарий описан в схеме ниже:

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.

Добавление модели и двойника

В этом разделе вы настроите цифровой двойник в Azure Digital Twins, который представляет термостат и обновляется с использованием данных из Центра Интернета вещей.

Чтобы создать двойник типа «термостат», сначала нужно передать в экземпляр модель термостата, которая содержит описание свойств термостата и будет использоваться позже для создания двойника.

Модель выглядит следующим образом:

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

Чтобы передать эту модель в экземпляр двойников, выполните следующую команду Azure CLI, которая передает указанную выше модель в виде встроенного JSON. Вы можете выполнить команду в Azure Cloud Shell в браузере (использовать среду Bash) или на компьютере, если у вас установлен интерфейс командной строки локально. Существует один заполнитель для имени узла экземпляра (можно также использовать понятное имя экземпляра с небольшим снижением производительности).

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

Примечание.

Если вы используете что-либо, отличное от Cloud Shell в среде Bash, может потребоваться экранировать определенные символы в встроенном формате JSON, чтобы он правильно был проанализирован. Дополнительные сведения см. в разделе "Использование специальных символов в разных оболочках".

Затем необходимо создать один двойник с помощью этой модели. Создайте двойник термостата с названием thermostat67 и установите для него начальное значение температуры 0,0 с помощью следующей команды. Существует один заполнитель для имени узла экземпляра (можно также использовать понятное имя экземпляра с небольшим снижением производительности).

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

После создания двойника выходные данные команды в интерфейсе командной строки выглядят примерно следующим образом:

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

Создание функции Azure

В этом разделе вы создадите функцию Azure для доступа к Azure Digital Twins и обновлению двойников на основе событий телеметрии устройства Интернета вещей, которые он получает. Чтобы создать и опубликовать функцию, выполните следующие действия.

Сначала создайте проект Функции Azure типа триггера сетки событий.

Это можно сделать с помощью Visual Studio (инструкции см. в статье "Разработка Функции Azure с помощью Visual Studio"), Visual Studio Code (инструкции см . в статье "Создание функции C# в Azure с помощью Visual Studio Code") или Azure CLI (инструкции см. в статье "Создание функции C# в Azure из командной строки").
Добавьте в проект следующие пакеты (диспетчер пакетов NuGet Visual Studio или команду dotnet add package в средстве командной строки).

Создайте функцию в проекте с именем IoTHubtoTwins.cs. Вставьте следующий код в файл функции:

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

Сохраните код функции.

Опубликуйте проект с функцией IoTHubtoTwins.cs в приложении-функции Azure.

Инструкции по публикации функции с помощью Visual Studio см. в статье "Разработка Функции Azure с помощью Visual Studio". Инструкции по публикации функции с помощью Visual Studio Code см. в статье "Создание функции C# в Azure с помощью Visual Studio Code". Инструкции по публикации функции с помощью Azure CLI см. в статье "Создание функции C# в Azure из командной строки".

После завершения публикации функции можно использовать эту команду Azure CLI для проверки успешной публикации. Заполнители для группы ресурсов и имя приложения-функции. Команда выводит сведения о функции IoTHubToTwins .

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

Настройка приложения-функции

Чтобы получить доступ к Azure Digital Twins, приложению-функции требуется управляемое удостоверение , назначаемое системой, с разрешениями для доступа к экземпляру Azure Digital Twins. Вы настроите это в этом разделе, назначив роль доступа для функции и настроив параметры приложения, чтобы получить доступ к экземпляру Azure Digital Twins.

Выполните указанные ниже команды в Azure Cloud Shell или локальном экземпляре Azure CLI.

Примечание.

Данный раздел должен быть заполнен пользователем Azure, у которого имеются разрешения на управление доступом пользователей к ресурсам Azure, включая предоставление и делегирование разрешений. Общие роли, отвечающие этому требованию: Владелец или Администратор учетной записи либо сочетание ролей Администратор доступа пользователей и Участник. Дополнительные сведения о требованиях к разрешениям для ролей Azure Digital Twins см. в разделе Настройка экземпляра и аутентификации.

Назначение роли доступа

В функцию Azure необходимо передать токен носителя. Чтобы гарантированно передать токен носителя, предоставьте приложению-функции роль владельца данных Azure Digital Twins для своего экземпляра Azure Digital Twins, который предоставит приложению-функции разрешение на выполнение действий на плоскости данных в экземпляре.

Используйте следующую команду, чтобы создать управляемое системой удостоверение для функции (если функция уже имеет одну, эта команда будет выводить сведения о ней). Запишите principalId поле в выходных данных. Этот идентификатор будет использоваться для обращения к функции, чтобы вы могли предоставить ей разрешения на следующем шаге.
```
az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
```
Используйте значение principalId в следующей команде, чтобы предоставить функции роль владельца Azure Digital Twins для вашего экземпляра Azure Digital Twins.
```
az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"
```

Настройка параметров приложения

Затем сделайте URL-адрес экземпляра Azure Digital Twins доступным для функции, задав переменную среды для нее.

Совет

URL-адрес экземпляра Azure Digital Twins создается путем добавления префикса https:// к значению имени узла вашего экземпляра. Чтобы просмотреть имя узла, а также все свойства экземпляра, выполните команду az dt show --dt-name <your-Azure-Digital-Twins-instance>.

Следующая команда задает переменную среды для URL-адреса экземпляра, который будет использоваться функцией при попытке доступа к экземпляру.

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

Подключение функции Центр Интернета вещей

В этом разделе вы настроите функцию в качестве назначения события для данных устройства в Центре Интернета вещей. Настройка функции таким образом обеспечит отправку данных с устройства термостата в Центр Интернета вещей в функцию Azure для обработки.

Используйте следующую команду CLI, чтобы создать подписку на события, которую Центр Интернета вещей будет использовать для отправки данных событий в функцию IoTHubtoTwins. Существует заполнитель для ввода имени подписки на события, а также заполнители для ввода идентификатора подписки, группы ресурсов, имени центра Интернета вещей и имени приложения-функции.

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

Выходные данные будут отображать сведения о созданной подписке на события. Вы можете убедиться, что операция выполнена успешно, проверив provisioningState значение в результате:

"provisioningState": "Succeeded",

Тестирование с помощью имитированных данных Интернета вещей

Вы можете протестировать новую функцию входящего трафика с помощью симулятора устройства из Подключение комплексного решения. Проект DeviceSimulator содержит имитированное устройство термостата, которое отправляет образец данных температуры. Чтобы настроить симулятор устройства, выполните следующие действия.

Перейдите к комплексному репозиторию проекта Azure Digital Twins. Получите пример проекта на компьютере, нажав кнопку "Обзор кода " под заголовком. Вы попадете в репозиторий GitHub с примерами, которые можно скачать в виде ZIP-архива, нажав кнопку Код и выбрав Скачать ZIP-архив.

Вы скачайте ZIP-папку на компьютер как digital-twins-samples-main.zip. Распакуйте папку и извлеките файлы. Вы будете использовать папку проекта DeviceSimulator .
Регистрация имитированного устройства с помощью Центр Интернета вещей
Настройка и запуск имитации

После выполнения этих действий в центре Интернета вещей должна быть запущена окно консоли проекта и отправка имитированных данных телеметрии устройства в Центр Интернета вещей.

Screenshot of the output from the device simulator project.

Проверка результатов

При запуске симулятора устройства выше значение температуры цифрового двойника термостата изменится. В Azure CLI выполните следующую команду, чтобы увидеть значение температуры. Существует один заполнитель для имени узла экземпляра (можно также использовать понятное имя экземпляра с небольшим снижением производительности).

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

Примечание.

Если вы используете что-либо, отличное от Cloud Shell в среде Bash, может потребоваться экранировать $ символ в запросе по-другому, чтобы он правильно анализировался. Дополнительные сведения см. в разделе "Использование специальных символов в разных оболочках".

Выходные данные должны отображать сведения двойника термостат67, включая значение температуры, как показано ниже:

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

Чтобы увидеть Temperature изменение значения, повторно выполните приведенную выше команду запроса.

Следующие шаги

Ознакомьтесь с входящим и исходящим трафиком Azure Digital Twins:

Входящий трафик данных и исходящий трафик

Прием данных телеметрии из Центра Интернета вещей в Azure Digital Twins

Необходимые компоненты

Пример работы с данными телеметрии

Добавление модели и двойника

Создание функции Azure

Настройка приложения-функции

Назначение роли доступа

Настройка параметров приложения

Подключение функции Центр Интернета вещей

Тестирование с помощью имитированных данных Интернета вещей

Проверка результатов

Следующие шаги

Дополнительные ресурсы