Интеграция Azure Digital Twins с Аналитикой временных рядов Azure.

Статья
03/09/2023

Эта статья содержит сведения о том, как интегрировать Azure Digital Twins с Аналитикой временных рядов Azure (TSI).

Решение, описанное в этой статье, использует аналитику временных рядов для сбора и анализа исторических данных о решении Интернета вещей. Azure Digital Twins хорошо подходит для передачи данных в Аналитику временных рядов, так как она позволяет сопоставлять несколько потоков данных и стандартизировать данные перед их отправкой в Аналитику временных рядов.

Совет

Самый простой способ анализа исторических данных двойника с течением времени — использовать функцию журнала данных для подключения экземпляра Azure Digital Twins к кластеру Azure Data Explorer, чтобы обновления графов автоматически выполнялись в Azure Data Explorer. Затем вы можете запросить эти данные в Azure Data Explorer с помощью подключаемого модуля запросов Azure Digital Twins для Azure Data Explorer. Если вам не нужно специально использовать Аналитику временных рядов, вы можете рассмотреть эту альтернативу для более простой интеграции.

Предварительные требования

Для настройки связи с Аналитикой временных рядов требуется подготовить перечисленные ниже ресурсы.

Экземпляр Azure Digital Twins. Необходимые инструкции см. в статье Настройка экземпляра Azure Digital Twins и аутентификация (портал).
Модель и двойник в экземпляре Azure Digital Twins. Вам потребуется обновить сведения о двойнике несколько раз, чтобы увидеть соответствующие данные в Аналитике временных рядов. Инструкции см. в статье Добавление модели и двойника.

Совет

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

Затем воспользуйтесь советом по запуску симулятора устройств и настройте функции Azure для автоматического обновления двойников вместо отправки команд обновления двойника вручную.

Архитектура решения

Вы будете присоединять аналитику временных рядов к Azure Digital Twins по следующему пути.

Создание пространства имен Центров событий

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

az eventhubs namespace create --name <name-for-your-Event-Hubs-namespace> --resource-group <your-resource-group> --location <region>

Совет

Если появляется сообщение об ошибке BadRequest: The specified service namespace is invalid., убедитесь, что имя, выбранное для пространства имен, соответствует требованиям к именованию, приведенным в справочном документе Создание пространства имен.

Вы будете использовать это пространство имен Центров событий для хранения двух концентраторов событий, необходимых для этой статьи:

Концентратор двойников — концентратор событий для получения событий изменения двойника.
Концентратор временных рядов — концентратор событий для потоковой передачи событий в аналитику временных рядов

В следующих разделах вы узнаете, как создавать и настраивать эти концентраторы в пространстве имен концентратора событий.

Создание концентратора двойников

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

Создание концентратора двойников
Создание правила авторизации для управления разрешениями для концентратора
Создание в Azure Digital Twins конечной точки, которая использует правило авторизации для доступа к концентратору
Создание в Azure Digital Twins маршрута, который отправляет событие обновления двойника в конечную точку и подключенный концентратор двойников
Получение строки подключения концентратора двойников

Создайте концентратор двойников с помощью следующей команды CLI. Укажите имя концентратора.

az eventhubs eventhub create --name <name-for-your-twins-hub> --resource-group <your-resource-group> --namespace-name <your-Event-Hubs-namespace-from-earlier>

Создание правила авторизации концентратора двойников

Создайте правило авторизации с разрешениями на отправку и получение. Укажите имя для этого правила.

az eventhubs eventhub authorization-rule create --rights Listen Send --name <name-for-your-twins-hub-auth-rule> --resource-group <your-resource-group> --namespace-name <your-Event-Hubs-namespace-from-earlier> --eventhub-name <your-twins-hub-from-earlier>

Создание конечной точки концентратора двойников

Создайте конечную точку Azure Digital Twins, которая связывает Центр событий с вашим экземпляром Azure Digital Twins. Укажите имя конечной точки концентратора двойников.

az dt endpoint create eventhub --dt-name <your-Azure-Digital-Twins-instance-name> --eventhub-resource-group <your-resource-group> --eventhub-namespace <your-Event-Hubs-namespace-from-earlier> --eventhub <your-twins-hub-name-from-earlier> --eventhub-policy <your-twins-hub-auth-rule-from-earlier> --endpoint-name <name-for-your-twins-hub-endpoint>

Создание маршрута событий концентратора двойников

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

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

az dt route create --dt-name <your-Azure-Digital-Twins-instance-hostname-or-name> --endpoint-name <your-twins-hub-endpoint-from-earlier> --route-name <name-for-your-twins-hub-event-route> --filter "type = 'Microsoft.DigitalTwins.Twin.Update'"

Получение строки подключения концентратора двойников

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

az eventhubs eventhub authorization-rule keys list --resource-group <your-resource-group> --namespace-name <your-Event-Hubs-namespace-from-earlier> --eventhub-name <your-twins-hub-from-earlier> --name <your-twins-hub-auth-rule-from-earlier>

Запишите значение primaryConnectionString из результата, чтобы настроить параметр приложения концентратора двойников далее в этой статье.

Создание концентратора временных рядов

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

Создание концентратора временных рядов
Создание правила авторизации для управления разрешениями для концентратора
Получение строки подключения концентратора временных рядов

Позже, при создании экземпляра Аналитики временных рядов, вы подключите этот концентратор в качестве источника событий к данному экземпляру.

Создайте концентратор временных рядов с помощью следующей команды. Укажите имя для концентратора временных рядов.

 az eventhubs eventhub create --name <name-for-your-time-series-hub> --resource-group <your-resource-group> --namespace-name <your-Event-Hub-namespace-from-earlier>

Создание правила авторизации концентратора временных рядов

Создайте правило авторизации с разрешениями на отправку и получение. Укажите имя для правила авторизации концентратора временных рядов.

az eventhubs eventhub authorization-rule create --rights Listen Send --name <name-for-your-time-series-hub-auth-rule> --resource-group <your-resource-group> --namespace-name <your-Event-Hub-namespace-from-earlier> --eventhub-name <your-time-series-hub-name-from-earlier>

Получение строки подключения концентратора временных рядов

Получите строку подключения концентратора временных рядов с помощью правил авторизации, созданных выше для концентратор временных рядов:

az eventhubs eventhub authorization-rule keys list --resource-group <your-resource-group> --namespace-name <your-Event-Hub-namespace-from-earlier> --eventhub-name <your-time-series-hub-name-from-earlier> --name <your-time-series-hub-auth-rule-from-earlier>

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

Кроме того, обратите внимание на следующие значения, которые будете использовать позже для создания экземпляра Аналитики временных рядов.

Пространство имен концентратора событий
Имя концентратора временных рядов
Правило авторизации концентратора временных рядов

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

В этом разделе вы создадите функцию Azure, которая преобразует события обновления двойников из исходной формы в виде документов JSON Patch в объекты JSON, содержащие только обновленные и добавленные значения из двойников.

Сначала создайте проект приложения-функции.

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

Замените код в файле ProcessDTUpdatetoTSI.cs следующим кодом:

using System.Collections.Generic;
using System.Threading.Tasks;
using System.Text;
using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using Azure.Messaging.EventHubs;

namespace UpdateTSI
{
    public static class ProcessDTUpdatetoTSI
    { 
        [FunctionName("ProcessDTUpdatetoTSI")]
        public static async Task Run(
            [EventHubTrigger("twins-event-hub", Connection = "EventHubAppSetting-Twins")]EventData myEventHubMessage,
            [EventHub("tsi-event-hub", Connection = "EventHubAppSetting-TSI")]IAsyncCollector<string> outputEvents,
            ILogger log)
        {
            JObject message = (JObject)JsonConvert.DeserializeObject(Encoding.UTF8.GetString(myEventHubMessage.Body));
            log.LogInformation($"Reading event: {message}");

            // Read values that are replaced or added
            var tsiUpdate = new Dictionary<string, object>();
            foreach (var operation in message["patch"])
            {
                if (operation["op"].ToString() == "replace" || operation["op"].ToString() == "add")
                {
                    //Convert from JSON patch path to a flattened property for TSI
                    //Example input: /Front/Temperature
                    //        output: Front.Temperature
                    string path = operation["path"].ToString().Substring(1);
                    path = path.Replace("/", ".");
                    tsiUpdate.Add(path, operation["value"]);
                }
            }
            // Send an update if updates exist
            if (tsiUpdate.Count > 0)
            {
                tsiUpdate.Add("$dtId", myEventHubMessage.Properties["cloudEvents:subject"]);
                await outputEvents.AddAsync(JsonConvert.SerializeObject(tsiUpdate));
            }
        }
    }
}

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

Опубликуйте проект с помощью функции ProcessDTUpdatetoTSI.cs в приложении-функции в Azure.

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

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

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

Затем назначьте роль доступа для функции и настройте параметры приложения, чтобы оно могло получать доступ к вашим ресурсам.

Выполните указанные ниже команды в 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>"

Далее добавьте в параметры приложения-функции переменные среды, благодаря которым оно сможет получать доступ к концентратору двойников и концентратору временных рядов.

С помощью сохраненного ранее значения primaryConnectionString концентратора двойников создайте в приложении-функции параметр приложения, содержащий строку подключения к этому концентратору:

az functionapp config appsettings set --settings "EventHubAppSetting-Twins=<your-twins-hub-primaryConnectionString>" --resource-group <your-resource-group> --name <your-function-app-name>

С помощью сохраненного ранее значения primaryConnectionString концентратора временных рядов создайте в приложении-функции параметр приложения, содержащий строку подключения к этому концентратору:

az functionapp config appsettings set --settings "EventHubAppSetting-TSI=<your-time-series-hub-primaryConnectionString>" --resource-group <your-resource-group> --name <your-function-app-name>

Создание и подключение экземпляра Аналитики временных рядов

В этом разделе вы настроите экземпляр службы "Аналитика временных рядов" для получения данных от концентратора временных рядов. Дополнительные сведения об этом процессе см. в статье Настройка среды PAYG Аналитика временных рядов Azure 2-го поколения. Выполните приведенные ниже действия, чтобы создать среду Аналитики временных рядов.

На портале Azure выполните поиск сред Аналитики временных рядов Azure и нажмите кнопку Создать. Выберите указанные ниже параметры, чтобы создать среду временных рядов.
- Подписка: выберите свою подписку.
  - Группа ресурсов: выберите свою группу ресурсов.
- Имя среды: укажите имя среды временных рядов.
- Расположение: выберите удобное расположение.
- Уровень: выберите ценовую категорию Gen2 (L1) .
- Имя свойства: введите $dtId (дополнительные сведения о выборе значения идентификатора см. в статье рекомендациях по выбору идентификатора временного ряда).
- Имя учетной записи хранения: укажите имя учетной записи хранения.
- Включить "теплое" хранилище: оставьте для этого поля значение Да.
Для других свойств на этой странице можно оставить значения по умолчанию. Нажмите кнопку Далее: источник >события.
На вкладке Источник событий выберите указанные ниже поля.
- Создать источник событий? выберите Да.
- Тип источника: выберите Концентратор событий.
- Имя: укажите имя источника событий.
- Подписка: выберите свою подписку Azure.
- Пространство имен концентратора событий: выберите пространство имен, созданное ранее в этой статье.
- Имя концентратора событий: выберите имя концентратора временных рядов, созданное ранее в этой статье.
- Имя политики концентратора событий: выберите правило авторизации концентратора временных рядов, созданное ранее в этой статье.
- Группа потребителей концентратора событий: выберите Создать и укажите имя для группы потребителей концентратора событий. а затем щелкните Добавить.
- Имя свойства: оставьте это поле пустым.
Нажмите кнопку Проверить и создать, чтобы проверить все детали. Затем снова нажмите кнопку Проверить и создать, чтобы создать среду временных рядов.

Отправка данных Интернета вещей в Azure Digital Twins

Чтобы начать отправку данных в Аналитику временных рядов, необходимо начать обновление свойств цифрового двойника в Azure Digital Twins с изменения значений данных.

С помощью команды az dt twin update интерфейса командной строки обновите свойство в двойнике, который вы добавили в разделе Предварительные требования. Если вы использовали инструкции по созданию двойников, изложенные в статье Прием данных телеметрии из Центра Интернета вещей в Azure Digital Twins, вы можете обновить свойство температуры в двойнике thermostat67 с помощью указанной ниже команды в локальном интерфейсе командной строки или в терминале bash Cloud Shell. Существует один заполнитель для имени узла экземпляра Azure Digital Twins (можно также использовать понятное имя экземпляра с небольшим снижением производительности).

az dt twin update --dt-name <your-Azure-Digital-Twins-instance-hostname-or-name> --twin-id thermostat67 --json-patch '{"op":"replace", "path":"/Temperature", "value": 20.5}'

Повторите команду еще по крайней мере 4 раза с разными значениями свойств, чтобы создать несколько точек данных, которые можно будет наблюдать позже в среде Аналитики временных рядов.

Совет

Если вы хотите рассмотреть эту статью на примере динамически моделируемых данных вместо обновления значений двойника вручную, сначала выполните совет из раздела Предварительные требования и настройте функцию Azure, которая обновляет цифровые двойники с имитированного устройства. После этого устройство можно запустить, чтобы начать отправку моделируемых данных и обновление цифрового двойника через этот поток.

Визуализация данных в Аналитике временных рядов

Теперь готовые для анализа данные должны передаваться в экземпляр Аналитики временных рядов. Выполните приведенные ниже действия, чтобы изучить входящие данные.

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

Если имитация будет выполняться несколько дольше, визуализация в конечном итоге будет выглядеть примерно так:

Дальнейшие действия

После создания конвейера данных для отправки данных временных рядов из Azure Digital Twins в Аналитику временных рядов вы можете подумать о том, как преобразовать модели активов, разработанные для Azure Digital Twins, в модели активов для Аналитики временных рядов. Руководство по следующему шагу процесса интеграции см. в статье Синхронизация моделей между Azure Digital Twins и Аналитикой временных рядов 2-го поколения.

Интеграция Azure Digital Twins с Аналитикой временных рядов Azure.

Предварительные требования

Архитектура решения

Создание пространства имен Центров событий

Создание концентратора двойников

Создание правила авторизации концентратора двойников

Создание конечной точки концентратора двойников

Создание маршрута событий концентратора двойников

Получение строки подключения концентратора двойников

Создание концентратора временных рядов

Создание правила авторизации концентратора временных рядов

Получение строки подключения концентратора временных рядов

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

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

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

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

Создание и подключение экземпляра Аналитики временных рядов

Отправка данных Интернета вещей в Azure Digital Twins

Визуализация данных в Аналитике временных рядов

Дальнейшие действия

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