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

В этом руководстве описывается процесс написания функции, которая может получать данные телеметрии устройства из Центр Интернета вещей и отправлять их в экземпляр 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 свойство цифрового двойника должно обновляться. Этот сценарий описан в схеме ниже:

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

В этом разделе вы настроите цифровой двойник в 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"    }  ]}' 

Затем необходимо создать один двойник с помощью этой модели. Создайте двойник термостата с названием 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 и обновлению двойников на основе событий телеметрии устройства Интернета вещей, которые он получает. Чтобы создать и опубликовать функцию, выполните следующие действия.

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

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

2. Добавьте в проект следующие пакеты (диспетчер пакетов NuGet Visual Studio или команду dotnet add package в средстве командной строки).

   • Azure.DigitalTwins.Core
   • Azure.Identity
   • Microsoft.Azure.WebJobs.Extensions.EventGrid

3. Создайте функцию в проекте с именем 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}");
               }
           }
       }
   }
   

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

4. Опубликуйте проект с функцией 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 Digital Twins для своего экземпляра Azure Digital Twins, который предоставит приложению-функции разрешение на выполнение действий на плоскости данных в экземпляре.

1. Используйте следующую команду, чтобы создать управляемое системой удостоверение для функции (если функция уже имеет одну, эта команда будет выводить сведения о ней). Запишите principalId поле в выходных данных. Этот идентификатор будет использоваться для обращения к функции, чтобы вы могли предоставить ей разрешения на следующем шаге.

   az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
   

2. Используйте значение 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-адреса экземпляра, который будет использоваться функцией при попытке доступа к экземпляру.

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 содержит имитированное устройство термостата, которое отправляет образец данных температуры. Чтобы настроить симулятор устройства, выполните следующие действия.

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

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

2. Регистрация имитированного устройства с помощью Центр Интернета вещей

3. Настройка и запуск имитации

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

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

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

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

Выходные данные должны отображать сведения двойника термостат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:

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