Учебник. Создание графа Azure Digital Twins с помощью примера клиентского приложения

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

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

В этом руководстве вы узнаете.

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

Перед началом работы с этим руководством начните с следующих предварительных требований:

• Если у вас нет подписки Azure, создайте бесплатную учетную запись, прежде чем приступить к работе.
• В этом руководстве используется .NET. Последнюю версию пакета SDK для .NET можно скачать для нескольких платформ с Download .NET.

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

Получение примеров ресурсов

Это учебное руководство основано на комплексном примере проекта Azure Digital Twins, выполненном на C#. Получите пример проекта на компьютере, перейдя по ссылке образца и нажав кнопку "Обзор кода " под заголовком.

Это действие перемещает вас в репозиторий GitHub с образцами, которые можно скачать как .zip, нажав кнопку "Код", а затем скачать ZIP-файл.

Это действие загружает папку .zip на компьютер как digital-twins-samples-main.zip. Распакуйте папку и извлеките файлы.

Подготовьте экземпляр Azure Digital Twins

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

После настройки экземпляра запомните имя хоста экземпляра. Вы можете найти имя хоста на портале Azure.

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

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

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

Перейдите в папку digital-twins-samples-main\AdtSampleApp\SampleClientApp и откройте файл appsettings.json . Этот JSON-файл содержит переменную конфигурации, необходимую для запуска проекта.

В теле файла измените instanceUrl на URL-адрес имени хоста вашего экземпляра Azure Digital Twins, добавив https:// перед именем хоста, как показано ниже.

{
  "instanceUrl": "https://<your-Azure-Digital-Twins-instance-host-name>"
}

Сохранить и закрыть файл.

Настройка локальных учетных данных Azure

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

В DefaultAzureCredentialэтом примере выполняется поиск учетных данных в локальной среде, таких как вход Azure в локальную Azure CLI или в Visual Studio или Visual Studio Code. Поэтому вам нужно войти в Azure локально с помощью одного из этих механизмов, чтобы настроить учетные данные для примера.

Если вы используете Visual Studio или Visual Studio Code для выполнения примеров кода, убедитесь, что вы вошли в этот редактор с теми же учетными данными Azure, которые вы хотите использовать для доступа к экземпляру Azure Digital Twins. Если вы используете локальное окно CLI, выполните az login команду, чтобы войти в учетную запись Azure. После входа при запуске примера кода необходимо автоматически пройти проверку подлинности.

Запуск примера проекта

Теперь, когда приложение и проверка подлинности настроены, откройте локальное окно консоли для запуска проекта. Перейдите в окно консоли в папку digital-twins-samples-main\AdtSampleApp\SampleClientApp и запустите проект с помощью этой команды dotnet:

dotnet run

Проект запускается, выполняет проверку подлинности и ожидает выполнения команды.

Ниже приведен снимок экрана, показывающий, как выглядит консоль проекта.

После успешного запуска приложения можно остановить запуск проекта. Позже в уроке вы снова запустите его.

Моделирование физической среды с помощью DTDL

Подготовив экземпляр Azure Digital Twins и пример приложения, приступим к созданию графа сценария.

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

Модели похожи на классы на языках программирования на объектно-ориентированном языке; они — это пользовательские шаблоны, которые можно создать для создания цифровых двойников. Модели для Azure Digital Twins написаны на языке JSON, например языке определения Цифровых двойников (DTDL), и они определяют тип двойника с точки зрения его свойств, связей и компонентов.

В папке примера проекта, скачаемой ранее, перейдите в папку digital-twins-samples-main\AdtSampleApp\SampleClientApp\Models . В этой папке содержатся примеры моделей.

Откройте Room.json для редактирования и внесите следующие изменения в код:

1. Обновите номер версии, чтобы указать, что вы предоставляете более новую версию этой модели. Для этого измените 1 в конце значения @id на 2. Можно указать любое число больше текущего номера версии.

2. Измените свойство. Измените имя свойства Humidity на HumidityLevel (или что-то другое, если вы хотите. Если вы используете что-то отличное от HumidityLevel, запомните, что вы выбрали, и продолжайте использовать это вместо HumidityLevel на протяжении всего учебника).

3. Добавьте свойство. Под свойством HumidityLevel, которое заканчивается на строке 15, вставьте следующий код, чтобы добавить свойство RoomName к объекту room.

   ,{
     "@type": "Property",
     "name": "RoomName",
     "schema": "string"
   }
   

4. Добавьте связь. Под только что добавленным свойством RoomName вставьте следующий код, чтобы добавить возможность для этого типа двойника формировать contains связи с другими двойниками:

   ,{
     "@type": "Relationship",
     "name": "contains"
   }
   

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

{
    "@id": "dtmi:example:Room;2",
    "@type": "Interface",
    "displayName": "Room",
    "contents": [
      {
        "@type": "Property",
        "name": "Temperature",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "HumidityLevel",
        "schema": "double"
      }
      ,{
        "@type": "Property",
        "name": "RoomName",
        "schema": "string"
      }
      ,{
        "@type": "Relationship",
        "name": "contains"
      }
    ],
    "@context": "dtmi:dtdl:context;3"
  }

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

Отправка моделей в Azure Digital Twins

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

1. Вернитесь в окно консоли, которая открыта в папке digital-twins-samples-main\AdtSampleApp\SampleClientApp, и снова запустите консольное приложение с помощью dotnet run.

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

   CreateModels Room Floor
   

   Выходные данные должны показать, что модели успешно созданы.

3. Убедитесь, что модели успешно созданы, выполнив команду GetModels true. Эта команда отображает полную информацию для всех моделей, загруженных в экземпляр Azure Digital Twins. Найдите отредактированную модель "Room" в результатах.

   

Оставьте консольное приложение запущенным для выполнения следующих шагов.

ошибки

Пример приложения также обрабатывает ошибки сервиса.

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

CreateModels Room

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

Дополнительные сведения о том, как удалить существующие модели, см. в разделе Управление моделями DTDL.

Создание цифровых двойников

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

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

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

   CreateDigitalTwin dtmi:example:Room;2 room0 RoomName string Room0 Temperature double 70 HumidityLevel double 30
   CreateDigitalTwin dtmi:example:Room;2 room1 RoomName string Room1 Temperature double 80 HumidityLevel double 60
   CreateDigitalTwin dtmi:example:Floor;1 floor0
   CreateDigitalTwin dtmi:example:Floor;1 floor1
   

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

   

2. Вы можете проверить создание двойников, выполнив команду Query. Эта команда запрашивает в вашем экземпляре Azure Digital Twins все содержащиеся в нем цифровые близнецы. Проверьте наличие в результатах двойников room0, room1, floor0 и floor1.

Изменение цифрового двойника

Вы также можете изменить свойства созданного двойника.

1. Выполните эту команду, чтобы изменить RoomName у room0 с "Room0" на "PresidentialSuite".

   UpdateDigitalTwin room0 add /RoomName string PresidentialSuite
   

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

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

   GetDigitalTwin room0
   

   В выходных данных должно быть указано обновленное имя.

Создание графа путем добавления связей

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

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

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

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

   CreateRelationship floor0 contains room0 relationship0
   CreateRelationship floor1 contains room1 relationship1
   

   Совет

   Связь contains в модели Floor также была определена с двумя строковыми свойствами, ownershipUser и ownershipDepartment, поэтому при создании связей можно также предоставить аргументы с предварительными значениями этих свойств. Ниже приведена альтернативная версия предыдущей команды, которую вы использовали для создания relationship0 , которая также задает начальные значения для этих свойств:

   CreateRelationship floor0 contains room0 relationship0 ownershipUser string MyUser ownershipDepartment string myDepartment
   

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

   

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

   • Чтобы увидеть все связи, идущие с каждого этажа (в просмотре связей с одной точки зрения):

     GetRelationships floor0
     GetRelationships floor1
     

   • Чтобы увидеть все связи, поступающие в каждую комнату (рассматривая связь с "другой" стороны):

     GetIncomingRelationships room0
     GetIncomingRelationships room1
     

   • Чтобы искать эти связи по отдельности, по идентификатору:

     GetRelationship floor0 relationship0
     GetRelationship floor1 relationship1
     

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

Запрос двойного графа для получения ответов на вопросы об окружающей среде

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

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

1. Каковы все сущности из моей среды, представленные в Azure Digital Twins? (запрос всех)

   Query
   

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

   

   Совет

   В примере проекта команда Query без других аргументов эквивалентна Query SELECT * FROM DIGITALTWINS. Чтобы запросить данные о всех двойниках в экземпляре с помощью интерфейсов API для запросов или команд CLI, используйте более длинный (полный) запрос.

2. Какие комнаты находятся в моем окружении? (запрос по модели)

   Query SELECT * FROM DIGITALTWINS T WHERE IS_OF_MODEL(T, 'dtmi:example:Room;2')
   

   Вы можете ограничить свой запрос объектами определенного типа, чтобы получить более конкретную информацию о том, что представлено. Результат этого показывает комнаты0 и комнаты1, но не показывает этаж0 или этаж1 (так как они этажи, а не комнаты).

   

3. Какие комнаты есть на этаже floor0? (запрос по взаимоотношениям)

   Query SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.$dtId = 'floor0'
   

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

   

4. Какие близнецы в моем окружении имеют температуру выше 75? (запрос по свойству)

   Query SELECT * FROM DigitalTwins T WHERE T.Temperature > 75
   

   Вы можете выполнять запросы к графу на основе свойств, чтобы получать ответы на различные вопросы, включая обнаружение аномалий в вашей среде, которые могут требовать внимания. Поддерживаются также и другие операторы сравнения (<,>, = и !=). В результатах отображается комната room1, так как она имеет температуру 80.

   

5. Какие комнаты на этаже floor0 имеют температуру выше 75? (составной запрос)

   Query SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.$dtId = 'floor0' AND IS_OF_MODEL(room, 'dtmi:example:Room;2') AND room.Temperature > 75
   

   Вы можете сочетать предыдущие запросы, как это делается в SQL, с помощью логических операторов, таких как AND, OR, NOT. В этом запросе используется AND, чтобы уточнить предыдущий запрос о температурах двойников. Теперь результат включает только комнаты с температурой выше 75, находящиеся на этаже floor0, — в этом случае таких комнат нет. В результате мы получим пустой набор.

   

Теперь, когда вы выполнили несколько запросов в сценарии, который вы настроили, учебник завершен. Остановите выполнение проекта и закройте окно консоли.

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

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

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

• Если вы хотите продолжить использование экземпляра Azure Digital Twins, но очистить все его модели, двойники и связи, можно использовать команды DeleteAllTwins и DeleteAllModels приложения-примера для очистки двойников и моделей в вашем экземпляре соответственно.

• Если вам не нужен какой-либо из ресурсов, созданных в этом руководстве, можно удалить экземпляр Azure Digital Twins и все остальные ресурсы из этой статьи с помощью команды az group delete CLI. При этом будут удалены все ресурсы Azure в группе ресурсов, а также сама группа.

  Внимание

  Удаление группы ресурсов — процесс необратимый. Группа ресурсов и все содержащиеся в ней ресурсы удаляются без возможности восстановления. Будьте внимательны, чтобы случайно не удалить не ту группу ресурсов или не те ресурсы.

  Откройте Azure Cloud Shell или локальное окно CLI и выполните следующую команду, чтобы удалить группу ресурсов и все, что она содержит.

  az group delete --name <your-resource-group>
  

Также может потребоваться удалить скачаемую папку проекта с локального компьютера.

Следующие шаги

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

Переходите к следующему учебнику, в котором вы реализуете комплексный сценарий на основе данных, объединив Azure Digital Twins с другими службами Azure: