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

  • Статья

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

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

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

  • Моделирование среды
  • Создание цифровых двойников
  • Добавление связей для формирования графа
  • Запрос графа для получения ответов

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

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

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

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

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

Вы попадете в репозиторий GitHub с примерами, которые можно скачать в виде ZIP-архива, нажав кнопку Код и выбрав Скачать ZIP-архив.

Screenshot of the digital-twins-samples repo on GitHub, highlighting the steps to download it as a 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

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

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

Screenshot of the welcome message from the command-line app.

Совет

Чтобы получить список команд, которые вы можете использовать с этим проектом, введите help в консоли проекта и нажмите клавишу ВВОД.

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

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

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

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

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

Примечание.

DTDL также позволяет определять команды в цифровых двойниках. Однако в настоящее время в службе Azure Digital Twins команды не поддерживаются.

В папке примера проекта, скачаемой ранее, перейдите в папку 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 в результатах команды:

    Screenshot of the result from GetModels, showing the updated Room model.

Сохраните консольное приложение для выполнения следующих действий.

ошибки

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

Чтобы проверить это, выполните команду 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

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

    Screenshot showing an excerpt from the result of the CreateDigitalTwin commands, which includes floor0, floor1, room0, and room1.

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

Примечание.

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

API DigitalTwins отражает изменения немедленно, поэтому, если вам нужен мгновенный ответ, используйте запрос API (DigitalTwins GetById) или вызов пакета SDK (GetDigitalTwin) для получения данных двойника вместо запроса.

Изменение цифровых двойников

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

Примечание.

Для определения вносимых в двойник изменений в используемом REST API применяется формат JSON Patch. Этот же формат используется в приложении командной строки для более точного соответствия принципам работы текущего API.

  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

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

    Screenshot of an excerpt from the result of the CreateRelationship commands, which includes relationship0 and relationship1.

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

    • Чтобы увидеть все связи с каждым полом (просмотр отношений с одной стороны): 
      GetRelationships floor0
GetRelationships floor1
    • Чтобы увидеть все отношения, поступающие в каждую комнату (просмотр отношения с другой стороны): 
      GetIncomingRelationships room0
GetIncomingRelationships room1
    • Чтобы искать эти связи по отдельности, по идентификатору: 
      GetRelationship floor0 relationship0
GetRelationship floor1 relationship1

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

A diagram showing a conceptual graph. floor0 is connected via relationship0 to room0, and floor1 is connected via relationship1 to room1.

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

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

Примечание.

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

API DigitalTwins отражает изменения немедленно, поэтому, если вам нужен мгновенный ответ, используйте запрос API (DigitalTwins GetById) или вызов пакета SDK (GetDigitalTwin) для получения данных двойника вместо запроса.

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

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

    Query

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

    Screenshot showing a partial result from the twin query, including room0 and floor1.

    Совет

    В примере проекта команда 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 (так как они полы, а не комнаты).

    Screenshot of the result from the model query, showing only room0 and room1.

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

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

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

    Screenshot of the result from the relationship query, showing room0.

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

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

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

    Screenshot of the result from the property query, showing only room1.

  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 — в данном случае таких комнат нет. В результате мы получим пустой набор.

    Screenshot of the result from the compound query, showing no results.

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

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

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

  • Если вы собираетесь перейти к следующему руководству, то можете сохранить настроенные здесь ресурсы, чтобы продолжить работу с этим экземпляром 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:

Подключение комплексное решение