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

Статья
01/10/2020

Важно!

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

Чтобы просмотреть документацию по новой службе, перейдите к активной документации по Azure Digital Twins.

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

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

В следующем видео дана краткая инструкция по настройке.

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

Если у вас нет учетной записи Azure, создайте бесплатную учетную запись, прежде чем начинать работу.
Два консольных приложения, запускаемые в рамках этого краткого руководства, написаны на языке C#. Установите на компьютере разработки пакет SDK для .NET Core версии 2.1.403 или более поздней. Если пакет SDK для .NET Core уже установлен, проверьте текущую версию C# на компьютере разработки. В командной строке выполните команду dotnet --version.
Скачайте пример проекта C#. Извлеките архив digital-twins-samples-csharp-master.zip.

Создание экземпляра Digital Twins

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

Войдите на портал Azure.
На боковой панели домашней страницы выберите + Создать ресурс.
Выполните поиск по фразе Digital Twins и выберите Digital Twins.

Кроме того, выберите Интернет вещей, а затем щелкните Digital Twins (preview) (Digital Twins (предварительная версия)).
Нажмите кнопку Создать, чтобы начать развертывание.
В области Digital Twins введите следующие сведения:
- Имя ресурса. Задайте уникальное имя для экземпляра Digital Twins.
- Подписка. Выберите подписку, в которой будет создан экземпляр Digital Twins.
- Группа ресурсов. Выберите или создайте группу ресурсов для экземпляра Digital Twins.
- Расположение. Выберите ближайшее расположение к устройствам.
Проверьте сведения, указанные для Digital Twins, и щелкните Создать. Создание экземпляра Digital Twins может занять несколько минут. Ход создания можно отслеживать на панели уведомлений.
Откройте область Общие сведения для созданного экземпляра Digital Twins. Обратите внимание на ссылку, которая отображается под элементом API управления. URL-адрес API управления имеет следующий вид:
```
https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swagger
```
По этому URL-адресу находится документация по REST API для Azure Digital Twins, которая относится к созданному экземпляру. См. сведения об использовании Azure Digital Twins , чтобы получить представление о том, как изучать и применять эту документацию по API. Копируйте и измените URL-адрес API управления следующим образом:
```
https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/
```
Этот измененный URL-адрес станет базовым адресом для доступа вашего приложения к экземпляру Digital Twins. Скопируйте измененный URL-адрес во временный файл. Этот URL-адрес понадобится вам в следующих разделах.

Настройка разрешений для приложения

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

Примечание

В этом разделе приводятся инструкции по регистрации приложения Azure AD.

На портале Azure выберите Azure Active Directory в развертываемом меню слева, а затем откройте область Регистрация приложений.
Нажмите кнопку + Новая регистрация.
Задайте понятное имя для этой регистрации приложения в поле Имя.
1. Введите https://microsoft.com в текстовое поле в разделе URI перенаправления (необязательно).
2. Проверьте, какие учетные записи и клиенты поддерживаются приложением Azure Active Directory.
3. Выберите Зарегистрировать.
В колонке Аутентификация указаны важные параметры конфигурации аутентификации.
1. Добавьте URI перенаправления и настройте Маркеры доступа, выбрав + Add a platform (+ Добавить платформу).
2. Выберите Да, чтобы указать, что приложение является общедоступным клиентом.
3. Проверьте, какие учетные записи и клиенты поддерживаются приложением Azure Active Directory.
Выбрав нужную платформу, настройте URI перенаправления и Маркеры доступа на боковой панели справа от пользовательского интерфейса.
1. URI перенаправления должны соответствовать адресу, указанному в запросе аутентификации.
  - Для приложений, размещенных в локальной среде разработки, выберите Public client (mobile & desktop) (Общедоступный клиент (мобильный и классический)). Не забудьте задать для общедоступного клиента значение Да.
  - Для одностраничных приложений, размещенных в Службе приложений Azure, выберите Интернет.
2. Определите, подходит ли URL-адрес выхода.
3. Включите поток неявного предоставления разрешения, проверив маркеры доступа или токены идентификатора.
Щелкните Настроить, а затем Сохранить.
Откройте область Обзор зарегистрированного приложения и скопируйте значения следующих сущностей во временный файл. Эти значения будут использоваться для настройки примера приложения в следующих разделах.
- Идентификатор приложения (клиента)
- Идентификатор каталога (клиента)
Откройте область Разрешения API для регистрации приложения. Нажмите кнопку + Add a permission (+ Добавить разрешение). В области Запрос разрешений API щелкните вкладку Интерфейсы API, используемые моей организацией, а затем выполните поиск по одному из следующих запросов:
1. Azure Digital Twins. Выберите API Azure Digital Twins.
2. Кроме того, можно выполнить поиск Azure Smart Spaces Service. Выберите API Azure Smart Spaces Service.
Важно!

Имя и идентификатор API Azure AD, которые будут отображаться, зависят от вашего клиента:
- Для тестовых клиентов и учетных записей клиентов следует искать Azure Digital Twins.
- Для других учетных записей Майкрософт следует искать Azure Smart Spaces Service.
Выбранный API появится как Azure Digital Twins в той же области Запрос разрешений API. Выберите параметр Чтение из раскрывающегося списка, а затем установите флажок Read.Write. Нажмите кнопку Add permissions (Добавить разрешения).
В зависимости от параметров вашей организации вам может потребоваться предпринять дополнительные шаги для предоставления доступа администратора к этому API. Для получения дополнительной информации обратитесь к администратору. Как только доступ администратора будет утвержден, в столбце Admin Consent Required (Требуется согласие администратора) в области Разрешения API будут отображаться ваши разрешения.

Проверьте, отображается ли Azure Digital Twins.

Сборка приложения

Запустите сборку приложения помещения, выполнив следующие шаги.

Откройте командную строку. Перейдите к папке, в которую были извлечены файлы digital-twins-samples-csharp-master.zip.
Выполните команду cd occupancy-quickstart/src.
Выполните dotnet restore.
Измените файл appSettings.json, чтобы обновить следующие переменные:
- ClientId: введите идентификатор приложения из регистрации приложения Azure AD, записанный при работе с предыдущим разделом.
- Tenant: введите идентификатор каталога клиента Azure AD, записанный при работе с предыдущим разделом.
- BaseUrl: URL-адрес API управления экземпляра Digital Twins в формате https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/. Замените заполнители в этом URL-адресе значениями для своего экземпляра из предыдущего раздела.
Сохраните обновленный файл.

Подготовка графа

На этом шаге подготавливается пространственный граф Digital Twins со следующими элементами:

несколько пространств;
одно устройство;
два датчика;
пользовательская функция;
одно назначение роли.

Пространственный граф подготовлен с помощью файла provisionSample.yaml.

Выполните dotnet run ProvisionSample.

Примечание

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

Совет

Если при выполнении этого шага возникает ошибка EXIT: Unexpected error: The input is not a valid Base-64 string ..., проверьте, правильно ли скопированы переменные.
Шаг по подготовке может занять несколько минут. В экземпляре Digital Twins будет также подготовлен Центр Интернета вещей. Он проходит цикл, пока Центр Интернета вещей не перейдет в состояние Running.
В конце выполнения скопируйте строку устройства ConnectionString, чтобы использовать ее в примере симулятора устройства. Скопируйте только ту строку, которая выделена на этом рисунке.

Совет

Вы можете просмотреть и изменить пространственный граф с помощью средства просмотра графов Azure Digital Twins.

Не закрывайте окно консоли. Вы будете использовать его позже.

Отправка данных датчиков

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

Откройте новую командную строку. Перейдите к скачанному проекту в папке digital-twins-samples-csharp-master.
Выполните команду cd device-connectivity.
Выполните dotnet restore.
Измените файл appsettings.json, чтобы обновить строку DeviceConnectionString строкой ConnectionString, приведенной выше. Сохраните обновленный файл.
Запустите dotnet run, чтобы начать отправку данных датчиков. Их отправка в службу Azure Digital Twins должна выполняться, как показано ниже.
Пусть этот симулятор работает, чтобы вы могли просматривать результаты параллельно с окном, где выполняются дальнейшие действия. В этом окне появятся данные смоделированных датчиков, отправленные в службу Digital Twins. На следующем шаге в режиме реального времени будет выполнен запрос для поиска свободных помещений со свежим воздухом.

Совет

Если при выполнении этого шага возникает ошибка EXIT: Unexpected error: The input is not a valid Base-64 string ..., проверьте, правильно ли скопирована строка DeviceConnectionString.

Поиск свободного пространства со свежим воздухом

Пример с датчиками имитирует значения случайных данных для двух датчиков — движения и углекислого газа. Свободные пространства со свежим воздухом определяются в примере отсутствием людей в помещении, а также уровнем углекислого газа ниже 1000 ppm. Если условие не выполняется, то пространство недоступно или качество воздуха плохое.

Откройте командную строку, которая использовалась на предыдущем этапе подготовки.
Выполните команду dotnet run GetAvailableAndFreshSpaces.
Разместите эту командную строку и командную строку данных датчиков рядом.

Командная строка данных датчика отправляет смоделированные данные о движении и углекислом газе в Digital Twins каждые пять секунд. В другой командной строке в режиме реального времени считывается граф для поиска свободных помещений со свежим воздухом на основе случайных смоделированных данных. В зависимости от того, какие данные датчиков были отправлены последними, в этой строке в режиме реального времени отобразится одно из следующих условий:
- Room is available and air is fresh
- Room is not available or air quality is poor

Чтобы понять, что описано в этом кратком руководстве и какие API-интерфейсы были вызваны, откройте Visual Studio Code с проектом рабочей области кода, доступным в digital-twins-samples-csharp. Используйте следующую команду:

<path>\occupancy-quickstart\src>code ..\..\digital-twins-samples.code-workspace

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

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger

Имя	Заменить на
YOUR_INSTANCE_NAME	Имя экземпляра Digital Twins
YOUR_LOCATION	Регион сервера, в котором размещен ваш экземпляр

Дополнительные сведения об API управления службы Digital Twins.

Очистка ресурсов

В руководствах этой серии подробно рассматриваются такие темы:

Создание приложения для менеджеров объектов, позволяющее повысить эффективность работы сотрудников.
Более эффективное эксплуатирование здания.

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

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

Совет

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

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

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

Руководство по развертыванию Azure Digital Twins и настройке пространственного графа