Создайте подключение для записи истории данных в Azure Digital Twins

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

Эта статья показывает, как настроить рабочее соединение для истории данных между Azure Digital Twins и Azure Data Explorer. Он использует Azure CLI и Azure портал для настройки и подключения необходимых ресурсов истории данных, включая:

• экземпляр Azure Digital Twins
• Пространство имен Event Hubs, содержащее концентратор событий
• кластер Azure Data Explorer, содержащий базу данных

Он также содержит пример двойного графа, который вы можете использовать, чтобы увидеть обновления историзированного графа в Azure Data Explorer.

Предпосылки

Подготовка среды к работе с Azure CLI

• Используйте среду Bash в Azure Cloud Shell. Дополнительные сведения см. в статье "Начало работы с Azure Cloud Shell".

  

• Если вы предпочитаете запускать справочные команды CLI локально, установите Azure CLI. Если вы работаете в Windows или macOS, попробуйте запустить Azure CLI в контейнере Docker. Дополнительные сведения см. в статье Как запустить Azure CLI в контейнере Docker.

  • Если вы используете локальную установку, выполните вход в Azure CLI с помощью команды az login. Чтобы завершить процесс проверки подлинности, выполните действия, отображаемые в терминале. Сведения о других параметрах входа см. в статье "Проверка подлинности в Azure с помощью Azure CLI".

  • Установите расширение Azure CLI при первом использовании, когда появится соответствующий запрос. Дополнительные сведения о расширениях см. в статье Использование расширений и управление ими с помощью Azure CLI.

  • Выполните команду az version, чтобы узнать установленную версию и зависимые библиотеки. Чтобы обновиться до последней версии, выполните команду az upgrade.

Настройка сеанса CLI

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

az login
az account set --subscription "<your-Azure-subscription-ID>"

Если вы впервые используете эту подписку с Azure Digital Twins, выполните следующую команду, чтобы зарегистрировать пространство имен Azure Digital Twins. (Если вы не уверены, ничего страшного, если вы запустите его снова, даже если вы запускали его ранее.)

az provider register --namespace 'Microsoft.DigitalTwins'

Затем добавьте расширение Интернета вещей Microsoft Azure для Azure CLI, чтобы включить команды для взаимодействия с Azure Digital Twins и другими службами Интернета вещей. Выполните следующую команду, чтобы убедиться, что используется последняя версия расширения:

az extension add --upgrade --name azure-iot

Теперь вы готовы к работе с Azure Digital Twins в Azure CLI.

Вы можете проверить это состояние, выполнив команду az dt --help в любое время, чтобы увидеть список доступных команд верхнего уровня Azure Digital Twins.

Настройте локальные переменные для сеанса CLI

В этой статье представлены команды CLI, которые можно использовать для создания ресурсов истории данных. Чтобы облегчить копирование и выполнение этих команд позже, вы можете сейчас задать локальные переменные в вашей сессии CLI, а затем ссылаться на эти переменные в командах CLI при создании ваших ресурсов. Чтобы создать переменные, обновите заполнители (обозначенные скобками <...>) в следующих командах, а затем выполните команды. Убедитесь, что вы соблюдаете правила наименования, описанные в комментариях. Эти значения используются позже при создании новых ресурсов.

## General Setup
location="<your-resource-region>"
resourcegroup="<your-resource-group-name>"

## Azure Digital Twins Setup
# Instance name can contain letters, numbers, and hyphens. It must start and end with a letter or number, and be between 4 and 62 characters long.
dtname="<name-for-your-digital-twins-instance>"
# Connection name can contain letters, numbers, and hyphens. It must contain at least one letter, and be between 3 and 50 characters long.
connectionname="<name-for-your-data-history-connection>"

## Event Hub Setup
# Namespace can contain letters, numbers, and hyphens. It must start with a letter, end with a letter or number, and be between 6 and 50 characters long.
eventhubnamespace="<name-for-your-event-hub-namespace>"
# Event hub name can contain only letters, numbers, periods, hyphens and underscores. It must start and end with a letter or number.
eventhub="<name-for-your-event-hub>"

## Azure Data Explorer Setup
# Cluster name can contain only lowercase alphanumeric characters. It must start with a letter, and be between 4 and 22 characters long.
clustername="<name-for-your-cluster>"  
# Database name can contain only alphanumeric, spaces, dash and dot characters, and be up to 260 characters in length.
databasename="<name-for-your-database>"

# Enter a name for the table where relationship create and delete events are stored.
relationshiplifecycletablename="<name-for-your-relationship-lifecycle-events-table>"
# Enter a name for the table where twin create and delete events are stored.
twinlifecycletablename="<name-for-your-twin-lifecycle-events-table>"
# Optionally, enter a custom name for the table where twin property updates are stored. If not provided, the table is named AdtPropertyEvents.
twinpropertytablename="<name-for-your-twin-property-events-table>"

Создайте экземпляр Azure Digital Twins с управляемой идентификацией

Если у вас уже есть экземпляр Azure Digital Twins, убедитесь, что для него включена система управления идентичностью.

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

Затем убедитесь, что у вас есть роль Azure Digital Twins Data Owner на экземпляре. Инструкции можно найти в Set up user access permissions.

Если вы хотите добавить имя вашего экземпляра в локальные переменные CLI, чтобы его можно было автоматически подключать к более поздним командам, скопированным из этой статьи, сохраните его в переменной dtname следующим образом:

dtname="<name-of-your-instance>"

Создать пространство имен Event Hubs и концентратор событий

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

Позже, в рамках настройки подключения истории данных, вы предоставляете экземпляру Azure Digital Twins роль Azure Event Hubs Data Owner на ресурсе концентратор событий.

Для получения дополнительной информации о возможностях Event Hubs см. документацию по Event Hubs.

az eventhubs namespace create --name $eventhubnamespace --resource-group $resourcegroup --location $location

az eventhubs eventhub create --name $eventhub --resource-group $resourcegroup --namespace-name $eventhubnamespace

Создайте кластер и базу данных Kusto (Azure Data Explorer)

Далее создайте кластер и базу данных Kusto (Azure Data Explorer), чтобы получать данные от Azure Digital Twins.

В рамках настройки подключения истории данных в дальнейшем вы предоставите экземпляру Azure Digital Twins роль участника как минимум для базы данных (она также может быть назначена кластеру) и роль администратора для базы данных.

az extension add --name kusto

az kusto cluster create --cluster-name $clustername --sku name="Dev(No SLA)_Standard_E2a_v4" tier="Basic" --resource-group $resourcegroup --location $location --type SystemAssigned

az kusto database create --cluster-name $clustername --database-name $databasename --resource-group $resourcegroup --read-write-database soft-delete-period=P365D hot-cache-period=P31D location=$location

Настройка соединения с историей данных

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

Эта команда также создаёт три таблицы в вашей базе данных Azure Data Explorer для хранения обновлений свойств двойников, событий жизненного цикла отношений и событий жизненного цикла двойников соответственно. Для получения дополнительной информации об этих типах историзируемых данных и соответствующих таблицах Azure Data Explorer см. Типы данных и схемы.

az dt data-history connection create adx --dt-name $dtname --cn $connectionname --adx-cluster-name $clustername --adx-database-name $databasename --eventhub $eventhub --eventhub-namespace $eventhubnamespace --adx-property-events-table $twinpropertytablename --adx-twin-events-table $twinlifecycletablename --adx-relationship-events-table $relationshiplifecycletablename --adx-record-removals true

После настройки подключения истории данных вы можете по желанию удалить роли, предоставленные вашему экземпляру Azure Digital Twins для доступа к ресурсам Event Hubs и Azure Data Explorer. Чтобы использовать историю данных, единственной ролью, необходимой экземпляру, является Отправитель данных Azure Event Hubs (или более высокая роль, включающая эти разрешения, например, Владелец данных Azure Event Hubs) на ресурсе Event Hubs.

Ограничить сетевой доступ к ресурсам истории данных

Если вы хотите ограничить сетевой доступ к ресурсам, связанным с историей данных (вашему экземпляру Azure Digital Twins, концентраторам событий или кластеру Azure Data Explorer), вы должны установить эти ограничения после настройки соединения для истории данных. Эти ограничения включают отключение локального доступа к вашим ресурсам среди прочих мер по снижению сетевого доступа.

Чтобы удостовериться, что ваши ресурсы истории данных могут взаимодействовать друг с другом, вам следует также изменить подключение данных для базы данных Azure Data Explorer, чтобы использовать управляющую идентичность, назначенную системой.

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

1. Убедитесь, что локальная авторизация включена на ваших ресурсах истории данных (ваш экземпляр Azure Digital Twins, узел событий и кластер Azure Data Explorer).
2. Создать подключение истории данных
3. Обновите подключение данных для базы данных Azure Data Explorer, чтобы использовать управляемую системой назначенную идентичность. В портале Azure вы можете обновить подключение к данным, перейдя к кластеру Azure Data Explorer и используя пункт Базы данных в меню для перехода к базе данных истории данных. В меню базы данных выберите Подключения данных. В записи таблицы для вашего подключения к истории данных вы должны увидеть опцию Назначить управляемую идентичность, где вы можете выбрать Системно назначенная.
4. Теперь вы можете отключить локальную авторизацию или установить другие сетевые ограничения для нужных ресурсов, изменив настройки доступа в вашей экземпляре Azure Digital Twins, концентраторе событий или кластере Azure Data Explorer.

Устранение неполадок настройки подключения

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

• Если у вас отключен доступ к общедоступной сети для вашего кластера Azure Data Explorer, вы получите ошибку, что службе не удалось создать соединение с историей данных, с сообщением "Ресурс не смог выполнить действие из-за внутренней ошибки сервера." Настройка истории данных не удается, если у кластера Azure Data Explorer отключён доступ к общедоступной сети, поскольку Azure Digital Twins не может настроить таблицы и другие необходимые артефакты.
• (Пользователи CLI) Если вы столкнулись с ошибкой "Не удалось создать подключение к экземпляру Azure Digital Twins." Невозможно создать таблицу и правило сопоставления в базе данных. Проверьте свои разрешения для Azure Database Explorer и выполните az login, чтобы обновить свои учетные данные. Устраните ошибку, добавив себя в качестве AllDatabasesAdmin в разделе Разрешения вашего кластера Azure Data Explorer.
• (Пользователи Cloud Shell) Если вы используете Cloud Shell и сталкиваетесь с ошибкой "Не удалось подключиться к MSI. Пожалуйста, убедитесь, что MSI настроен правильно, и попробуйте вместо этого выполнить команду с локальной установкой Azure CLI.

Проверьте с помощью образцового графа-близнеца

Теперь, когда ваше подключение к истории данных настроено, вы можете протестировать его с данными от ваших цифровых двойников.

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

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

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

Создайте образец графика

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

Начните с открытия Azure Digital Twins Data Simulator в вашем браузере. Установите эти поля:

• URL-адрес экземпляра: введите имя узла экземпляра Azure Digital Twins. Имя хоста можно найти на странице портала для вашего экземпляра, и оно имеет формат, подобный <Azure-Digital-Twins-instance-name>.api.<region-code>.digitaltwins.azure.net.
• Тип симуляции: Выберите молочное предприятие из выпадающего меню.

Выберите Создать среду.

Вы видите сообщения с подтверждением на экране, когда в вашей среде создаются модели, двойники и отношения. Этот процесс также генерирует события создания двойников и взаимоотношений, которые архивируются в Azure Data Explorer как события жизненного цикла двойников и взаимоотношений соответственно.

Когда симуляция готова, кнопка Начать симуляцию становится активной. Прокрутите вниз и выберите Начать симуляцию, чтобы отправить смоделированные данные в ваш экземпляр Azure Digital Twins. Чтобы постоянно обновлять близнецов в вашем экземпляре Azure Digital Twins, держите это окно браузера на переднем плане на вашем рабочем столе и выполняйте другие действия в браузере в отдельном окне. Это окно непрерывно генерирует события обновления двойных свойств, которые сохраняются в историческое хранилище Azure Data Explorer.

Просмотрите историзированные обновления в Azure Data Explorer

Этот раздел показывает, как просмотреть все три типа историзованных обновлений, сгенерированных симулятором и сохраненных в таблицах Azure Data Explorer.

Начните с портала Azure и перейдите к кластеру Azure Data Explorer, который вы создали ранее. Выберите панель Запрос в разделе Данные в меню слева, чтобы открыть окно запроса.

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

Проверьте записи таблицы

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

.alter table <relationship-lifecycle-events-table-name> policy ingestionbatching @'{"MaximumBatchingTimeSpan":"00:00:10", "MaximumNumberOfItems": 500, "MaximumRawDataSizeMB": 1024}'

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

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

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

<twin-property-updates-table-name>
| count

<relationship-lifecycle-events-table-name>
| count

<twin-lifecycle-events-table-name>
| count

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

Изучите таблицу обновлений свойств двойника

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

Сначала выполните следующую команду, чтобы просмотреть 100 записей в таблице:

<twin-property-updates-table-name>
| limit 100

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

Используйте следующий запрос, чтобы построить график оттока всех солевых машин-близнецов на образцовом молочном заводе в Осло. Этот запрос Kusto использует плагин Azure Digital Twins для выбора интересующих близнецов, объединяет этих близнецов с временными рядами истории данных в Azure Data Explorer, а затем строит графики результатов. Убедитесь, что вы заменили заполнитель <ADT-instance-host-name> на имя хоста вашего экземпляра, а заполнитель <table-name> на имя таблицы обновлений свойств двойника.

let ADTendpoint = "https://<ADT-instance-host-name>";
let ADTquery = ```SELECT SALT_MACHINE.$dtId as tid
FROM DIGITALTWINS FACTORY 
JOIN SALT_MACHINE RELATED FACTORY.contains 
WHERE FACTORY.$dtId = 'OsloFactory'
AND IS_OF_MODEL(SALT_MACHINE , 'dtmi:assetGen:SaltMachine;1')```;
evaluate azure_digital_twins_query_request(ADTendpoint, ADTquery)
| extend Id = tostring(tid)
| join kind=inner (<table-name>) on Id
| extend val_double = todouble(Value)
| where Key == "OutFlow"
| render timechart with (ycolumns = val_double)

Результаты должны показывать изменение численности оттока с течением времени.

Устранение неполадок подключения

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

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

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

Чтобы создать панели управления Grafana, визуализирующие производительность молочной операции, прочитайте Создание панелей управления с Azure Digital Twins, Azure Data Explorer и Grafana.

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