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

  • Статья

Важно!

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

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

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

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

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

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

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

  • Развертывание Digital Twins.
  • Предоставление разрешений приложению.
  • Изменение примера приложения Digital Twins.
  • Подготовка сборки.

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

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

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

  • Пакет SDK для .NET Core. Примеры Azure Digital Twins, используемые в этих руководствах, написаны на C#. Убедитесь, что установили пакет SDK для .NET Core версии 2.1.403 или более поздней на компьютере разработки. Он нужен для выполнения сборки и запуска примера. Проверьте, установлена ​​ли на вашем компьютере правильная версия, запустив dotnet --version в окне команд.

  • Visual Studio Code для изучения примера кода.

развертывание Azure Digital Twins;

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

  1. Войдите на портал Azure.

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

    Разверните боковую панель домашней страницы, а затем выберите + Создать ресурс.

  3. Выполните поиск по фразе Digital Twins и выберите Digital Twins.

    Выбор для создания нового экземпляра Digital Twins

    Кроме того, выберите Интернет вещей, а затем щелкните Digital Twins (preview) (Digital Twins (предварительная версия)).

  4. Нажмите кнопку Создать, чтобы начать развертывание.

    Создание и подтверждение развертывания ресурса

  5. В области Digital Twins введите следующие сведения:

    • Имя ресурса. Задайте уникальное имя для экземпляра Digital Twins.

    • Подписка. Выберите подписку, в которой будет создан экземпляр Digital Twins.

    • Группа ресурсов. Выберите или создайте группу ресурсов для экземпляра Digital Twins.

    • Расположение. Выберите ближайшее расположение к устройствам.

      Панель Digital Twins с введенными сведениями

  6. Проверьте сведения, указанные для Digital Twins, и щелкните Создать. Создание экземпляра Digital Twins может занять несколько минут. Ход создания можно отслеживать на панели уведомлений.

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

    Общие сведения об API управления

предоставление разрешений приложению;

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

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

Примечание

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

  1. На портале Azure выберите Azure Active Directory в развертываемом меню слева, а затем откройте область Регистрация приложений.

    Выбор области Azure Active Directory

  2. Нажмите кнопку + Новая регистрация.

    Нажмите кнопку Создать регистрацию.

  3. Задайте понятное имя для этой регистрации приложения в поле Имя.

    1. Введите https://microsoft.com в текстовое поле в разделе URI перенаправления (необязательно).

    2. Проверьте, какие учетные записи и клиенты поддерживаются приложением Azure Active Directory.

    3. Выберите Зарегистрировать.

    Создание области

  4. В колонке Аутентификация указаны важные параметры конфигурации аутентификации.

    1. Добавьте URI перенаправления и настройте Маркеры доступа, выбрав + Add a platform (+ Добавить платформу).

    2. Выберите Да, чтобы указать, что приложение является общедоступным клиентом.

    3. Проверьте, какие учетные записи и клиенты поддерживаются приложением Azure Active Directory.

    Параметр конфигурации общедоступного клиента

  5. Выбрав нужную платформу, настройте URI перенаправления и Маркеры доступа на боковой панели справа от пользовательского интерфейса.

    1. URI перенаправления должны соответствовать адресу, указанному в запросе аутентификации.

      • Для приложений, размещенных в локальной среде разработки, выберите Public client (mobile & desktop) (Общедоступный клиент (мобильный и классический)). Не забудьте задать для общедоступного клиента значение Да.
      • Для одностраничных приложений, размещенных в Службе приложений Azure, выберите Интернет.

    2. Определите, подходит ли URL-адрес выхода.

    3. Включите поток неявного предоставления разрешения, проверив маркеры доступа или токены идентификатора.

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

    Щелкните Настроить, а затем Сохранить.

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

    • Идентификатор приложения (клиента)
    • Идентификатор каталога (клиента)

    Идентификатор приложения Azure Active Directory

  7. Откройте область Разрешения API для регистрации приложения. Нажмите кнопку + Add a permission (+ Добавить разрешение). В области Запрос разрешений API щелкните вкладку Интерфейсы API, используемые моей организацией, а затем выполните поиск по одному из следующих запросов:

    1. Azure Digital Twins. Выберите API Azure Digital Twins.

      API поиска или Azure Digital Twins

    2. Кроме того, можно выполнить поиск Azure Smart Spaces Service. Выберите API Azure Smart Spaces Service.

      API поиска для Azure Smart Spaces

    Важно!

    Имя и идентификатор API Azure AD, которые будут отображаться, зависят от вашего клиента:

    • Для тестовых клиентов и учетных записей клиентов следует искать Azure Digital Twins.
    • Для других учетных записей Майкрософт следует искать Azure Smart Spaces Service.

  8. Выбранный API появится как Azure Digital Twins в той же области Запрос разрешений API. Выберите параметр Чтение из раскрывающегося списка, а затем установите флажок Read.Write. Нажмите кнопку Add permissions (Добавить разрешения).

    Добавление разрешений API

  9. В зависимости от параметров вашей организации вам может потребоваться предпринять дополнительные шаги для предоставления доступа администратора к этому API. Для получения дополнительной информации обратитесь к администратору. Как только доступ администратора будет утвержден, в столбце Admin Consent Required (Требуется согласие администратора) в области Разрешения API будут отображаться ваши разрешения.

    утверждение согласия Администратор

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

Настройка примера Digital Twins

В этом разделе рассматривается приложение Azure Digital Twins, которое обменивается данными с REST API Digital Twins.

Скачивание примера приложения

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

  1. Скачайте примеры Digital Twins на .NET.
  2. Извлеките содержимое папки ZIP на свой компьютер.

Анализ примера

В извлеченной папке с примерами откройте файл digital-twins-samples-csharp\digital-twins-samples.code-workspace в Visual Studio Code. Этот файл содержит два проекта:

  • Вы можете использовать пример подготовки occupancy-quickstart для настройки и подготовки пространственного интеллектуального графа. Этот граф представляет собой цифровое изображение физических пространств и ресурсов в них. В этом примере используется объектная модель, которая определяет объекты для интеллектуального здания. Полный список объектов Digital Twins и интерфейсов REST API см. в этой документации по REST API или по URL-адресу API управления, который был создан для вашего экземпляра.

    Чтобы изучить пример и понять, как он связывается с имеющимся экземпляром Digital Twins, можно начать с папки src\actions. Файлы в этой папке реализуют команды, которые вы будете использовать в этих руководствах:

    • Файл provisionSample.cs показывает, как подготовить пространственный граф.
    • Файл getSpaces.cs получает информацию о подготовленных помещениях.
    • Файл getAvailableAndFreshSpaces.cs получает результаты пользовательской функции.
    • Файл createEndpoints.cs создает конечные точки для взаимодействия с другими службами.

  • Пример моделирования device-connectivity имитирует данные датчиков и отправляет их в центр Интернета вещей, подготовленный для вашего экземпляра Digital Twins. Вы будете использовать этот пример в следующем руководстве после подготовки пространственного графа. Идентификаторы датчиков и устройств, используемые для настройки этого примера, должны быть такими же, как и для вашего графа.

Настройка подготовленного примера

  1. Откройте окно команд и перейдите к скачанному примеру. Выполните следующую команду:

    cd occupancy-quickstart/src

  2. Восстановите зависимости в примере проекта, выполнив эту команду:

    dotnet restore

  3. В Visual Studio Code откройте файл appSettings.json в проекте occupancy-quickstart. Измените следующие значения:

    • ClientId: введите идентификатор приложения из регистрации приложения Azure AD. Вы записали этот идентификатор в разделе, в котором устанавливали разрешения приложения.
    • Tenant: введите идентификатор каталога своего клиента Azure AD. Вы также записали этот идентификатор в разделе, в котором устанавливали разрешения приложения.
    • BaseUrl: введите URL-адрес экземпляра Digital Twins. Чтобы получить этот URL-адрес, замените заполнители в этом URL-адресе значениями для вашего экземпляра: https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/. Вы также можете получить этот URL-адрес, изменив URL-адрес API управления, указанный в разделе развертывания. Замените swagger/ на api/v1.0/.

  4. Просмотрите список функций Digital Twins, которые вы можете исследовать с помощью примера. Выполните следующую команду:

    dotnet run

Сведения о процессе подготовки

В этом разделе показано, как пример положения подготавливает пространственный граф здания.

В Visual Studio Code перейдите в папку occupancy-quickstart\src\actions и откройте файл provisionSample.cs. Обратите внимание на следующую функцию:

public static async Task<IEnumerable<ProvisionResults.Space>> ProvisionSample(HttpClient httpClient, ILogger logger)
{
    IEnumerable<SpaceDescription> spaceCreateDescriptions;
    using (var r = new StreamReader("actions/provisionSample.yaml"))
    {
        spaceCreateDescriptions = await GetProvisionSampleTopology(r);
    }

    var results = await CreateSpaces(httpClient, logger, spaceCreateDescriptions, Guid.Empty);

    Console.WriteLine($"Completed Provisioning: {JsonConvert.SerializeObject(results, Formatting.Indented)}");

    return results;
}

Эта функция использует файл provisionSample.yaml в той же папке. Откройте этот файл и обратите внимание на иерархию офисного здания: место проведения, этаж, область и комнаты. В любой из этих физических областей могут быть устройства и датчики. У каждой записи есть предопределенная typeзапись, например Этаж, Комната.

В файле yaml показан пространственный граф, использующий объектную модель Digital Twins Default. Эта модель предоставляет универсальные имена для большинства типов, чего вполне достаточно для здания. Например, Temperature для SensorDataType, Map для SpaceBlobType и Room с подтипами FocusRoom, ConferenceRoom и т. д. для типов пространств.

Если вам нужно создать пространственный граф для другого типа помещения, например фабрики, вам может потребоваться другая объектная модель. Можно выяснить, какие модели доступны для использования, выполнив команду dotnet run GetOntologies в командной строке в примере подготовки.

Дополнительные сведения о пространственных графах и объектных моделях Digital Twins см. в этой статье.

Изменение примера пространственного графа

Файл provisionSample.yaml содержит следующие узлы:

  • resources: узел resources создает ресурс Центра Интернета вещей для взаимодействия с устройствами в вашем экземпляре настройки. Центр Интернета вещей в корневом узле графа может взаимодействовать со всеми устройствами и датчиками в графе.

  • spaces: в объектной модели Digital Twins объект spaces представляет физические расположения. Каждое Typeпространство имеет ( например, регион, место проведения или клиент) и понятное Name. Пространства могут принадлежать другим пространствам, в связи с чем формируется иерархическая структура. Файл provisionSample.yaml имеет пространственный граф воображаемого здания. Обратите внимание на логические вложения пространств типа Floor в Venue, Area на этаже и узлы Room в области.

  • devices: пространства могут содержать объекты devices (устройства), которые являются физическими или виртуальными сущностями, управляющими рядом датчиков. Например, устройство может быть телефоном пользователя, модулем pod датчика Raspberry Pi или шлюзом. В воображаемом здании в вашем примере комната с названием Focus Room содержит устройство Raspberry Pi 3 A1. Каждый узел устройства определяется уникальным идентификатором hardwareId, который жестко задан в примере. Чтобы настроить этот пример для фактической рабочей среды, замените их на значения из вашего экземпляра настройки.

  • sensors: устройство может содержать несколько датчиков (sensors). Они могут обнаруживать и записывать изменения физических показателей, таких как температура, движение, уровень заряда батареи. Каждый узел датчика определяется уникальным идентификатором hardwareId, который жестко задан в примере. Для реального приложения замените их уникальными идентификаторами датчиков в вашем экземпляре настройки. Файл provisionSample.yaml содержит два датчика для записи: Motion и CarbonDioxide. Добавьте еще один датчик для регистрации Temperature, добавив следующие строки под строками для датчика CarbonDioxide. Они предоставлены в файле provisionSample.yaml в виде закомментированных строк. Чтобы раскомментировать их, удалите символ # в начале каждой строки.

            - dataType: Temperature
          hardwareId: SAMPLE_SENSOR_TEMPERATURE

    Примечание

    Убедитесь, что ключи dataType и hardwareId совпадают с инструкциями над этим фрагментом кода. Кроме того, проверьте, что ваш редактор не заменяет пространства символами табуляции.

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

Совет

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

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

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

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

    Совет

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

  2. При необходимости удалите пример приложения на компьютере.

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

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

Руководство по подготовке примера здания и мониторинге условий работы с помощью Azure Digital Twins