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

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

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

В этом учебнике вам предстоит выполнить следующее.

Необходимые компоненты

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

• Если у вас нет подписки Azure, создайте бесплатную учетную запись, прежде чем приступить к работе.
• В этом руководстве используется .NET. Последняя версия пакета SDK для .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 (или что-то другое, если вы хотите. Если вы используете что-то отличается от влажностиLevel, помните, что вы использовали и продолжаете использовать это вместо влажностиLevel на протяжении всего учебника).

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

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

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

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

Теперь, когда несколько моделей отправлено в ваш экземпляр 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 связь с каждым из двойников Пола, созданных ранее в соответствующий двойник комнаты. Связи называются relationship0 и relationship1.

   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: