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

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

С помощью этих команд CLI можно выполнять базовые действия Azure Digital Twins, такие как отправка моделей, создание и изменение двойников, а также создание связей. Вы также можете просмотреть справочную документацию по az dt command set, чтобы просмотреть полный набор команд CLI.

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

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

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

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

Скачивание примеров моделей

В этом руководстве используются две предзаписанные модели, которые являются частью комплексного проекта C# для Azure Digital Twins. Файлы модели находятся здесь:

• Room.json
• Floor.json

Чтобы получить файлы на компьютере, используйте ссылки навигации в предыдущем списке и скопируйте их в локальные файлы на компьютере с теми же именами (Room.json и Floor.json).

Подготовка среды к работе с Azure CLI

• Используйте среду Bash в Azure Cloud Shell. Дополнительные сведения см. в статье "Начало работы с Azure Cloud Shell".

  

• Если вы предпочитаете локально запускать справочные команды CLI, установите Azure CLI. Если вы работаете в Windows или macOS, Azure CLI можно запустить в контейнере Docker. Дополнительные сведения см. в статье о запуске Azure CLI в контейнере Docker.

  • Если вы используете локальную установку, войдите в Azure CLI с помощью команды az login . Чтобы выполнить аутентификацию, следуйте инструкциям в окне терминала. Сведения о других параметрах входа см. в статье "Проверка подлинности в Azure с помощью Azure CLI".

  • Установите расширение Azure CLI при первом использовании, когда появится соответствующий запрос. Дополнительные сведения о расширениях см. в статье "Использование расширений и управление ими" с помощью Azure CLI.

  • Запустите az version , чтобы найти установленные версии и зависимые библиотеки. Чтобы обновить до последней версии, выполните az upgrade.

Настройка сеанса CLI

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

az login
az account set --subscription "<your-Azure-subscription-ID>"

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

az provider register --namespace 'Microsoft.DigitalTwins'

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

az extension add --upgrade --name azure-iot

Теперь вы готовы к работе с Azure Digital Twins в Azure CLI.

Вы можете проверить это состояние, выполнив команду az dt --help в любое время, чтобы увидеть список доступных команд верхнего уровня Azure Digital Twins.

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

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

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

После настройки экземпляра Azure Digital Twins запишите следующие значения, которые потребуются вам позднее при подключении к экземпляру:

• Имя хоста экземпляра
• Подписка Azure, используемая для создания экземпляра

az dt show --dt-name <Azure-Digital-Twins-instance-name>

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

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

Первым шагом в создании решения Azure Digital Twins является определение моделей двойников для вашей среды.

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

Перейдите на вашем компьютере к файлу 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. Если вы используете локальную установку Azure CLI, можно пропустить этот шаг. Если вы используете Cloud Shell, необходимо передать файлы модели в хранилище Cloud Shell, чтобы файлы были доступны при выполнении команды Cloud Shell, которая использует их. Выберите "Управление файлами " и " Отправить".

   

   Перейдите к файлуRoom.json на компьютере и выберите "Открыть". Затем повторите этот шаг для Floor.json.

2. Затем используйте команду az dt model create , как показано в следующем примере, чтобы отправить обновленную модель комнаты в экземпляр Azure Digital Twins. Вторая команда отправляет другую модель (Floor), которую также можно использовать в следующем разделе для создания различных типов двойников. Существует заполнитель для имени хоста экземпляра (можно также использовать удобочитаемое имя экземпляра с небольшим снижением производительности), а также заполнитель для пути к каждому модельному файлу. Если вы используете Cloud Shell, Room.json и Floor.json находятся в основном каталоге хранилища, поэтому вы можете просто использовать имена файлов непосредственно в следующих командах, где требуется путь.

   az dt model create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --models <path-to-Room.json>
   az dt model create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --models <path-to-Floor.json>
   

   Выходные данные каждой команды показывают сведения о успешно отправленной модели.

   Совет

   Вы также можете отправить все модели в каталоге одновременно, используя параметр команды создания модели --from-directory. Дополнительные сведения см. в разделе "Необязательные параметры" для az dt model create.

3. Убедитесь, что модели были созданы с помощью команды az dt model list , как показано в следующем примере. В результате выводится список всех моделей, отправленных в экземпляр Azure Digital Twins, с полной информацией о них. Существует один шаблон для имени узла экземпляра (можно также использовать удобочитаемое имя экземпляра с небольшим снижением производительности).

   az dt model list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --definition
   

   Найдите отредактированную модель комнаты в результатах.

   

ошибки

CLI также обрабатывает ошибки службы.

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

az dt model create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --models Room.json

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

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

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

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

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

   az dt twin create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --dtmi "dtmi:example:Room;2" --twin-id room0 --properties '{"RoomName":"Room0", "Temperature":70, "HumidityLevel":30}'
   az dt twin create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --dtmi "dtmi:example:Room;2" --twin-id room1 --properties '{"RoomName":"Room1", "Temperature":80, "HumidityLevel":60}'
   az dt twin create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --dtmi "dtmi:example:Floor;1" --twin-id floor0
   az dt twin create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --dtmi "dtmi:example:Floor;1" --twin-id floor1
   

   Примечание.

   Если вы используете что-либо, отличное от Cloud Shell в среде Bash, может потребоваться экранировать определенные символы в встроенном формате JSON, чтобы он правильно анализировался.

   Дополнительные сведения см. в разделе "Использование специальных символов в разных оболочках".

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

2. Вы можете убедиться, что двойники были созданы с помощью команды az dt twin query , как показано в следующем примере. Запрос, показанный выше, находит все цифровые двойники в вашем экземпляре Azure Digital Twins. Существует один шаблон для имени узла экземпляра (можно также использовать удобочитаемое имя экземпляра с небольшим снижением производительности).

   az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT * FROM DIGITALTWINS"
   

   Проверьте наличие в результатах двойников room0, room1, floor0 и floor1. Ниже приведен фрагмент, показывающий часть результата этого запроса.

   

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

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

1. Выполните следующую команду az dt twin update , чтобы изменить имя room0 с Room0 на PresidentialSuite. Существует один шаблон для имени узла экземпляра (можно также использовать удобочитаемое имя экземпляра с небольшим снижением производительности).

   az dt twin update --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id room0 --json-patch '{"op":"add", "path":"/RoomName", "value": "PresidentialSuite"}'
   

   Примечание.

   Мы рекомендуем использовать интерфейс командной строки в среде Bash для этого руководства. Если вы используете среду PowerShell, может потребоваться экранировать символы-кавычки, чтобы --json-patch значение JSON было правильно проанализировано.

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

   

2. Вы можете проверить, что обновление прошло успешно, выполнив команду az dt twin show, чтобы просмотреть сведения о комнате. Существует один шаблон для имени узла экземпляра (можно также использовать удобочитаемое имя экземпляра с небольшим снижением производительности).

   az dt twin show --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id room0
   

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

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

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

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

Чтобы добавить связь, используйте команду az dt twin relationship create . Укажите двойник, от которого исходит связь, тип этой связи и двойник, к которому она присоединяется. Наконец, присвойте связи уникальный идентификатор. Если связь определена как имеющая свойства, можно также инициализировать свойства связи в этой команде.

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

   az dt twin relationship create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --relationship-id relationship0 --relationship contains --twin-id floor0 --target room0
   az dt twin relationship create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --relationship-id relationship1 --relationship contains --twin-id floor1 --target room1
   

   Совет

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

   ... --properties '{"ownershipUser":"MyUser", "ownershipDepartment":"MyDepartment"}'
   

   Выходные данные каждой команды показывают сведения о успешно созданной связи.

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

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

     az dt twin relationship list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id floor0
     az dt twin relationship list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id floor1
     

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

     az dt twin relationship list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id room0 --incoming
     az dt twin relationship list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id room1 --incoming
     

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

     az dt twin relationship show --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id floor0 --relationship-id relationship0
     az dt twin relationship show --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id floor1 --relationship-id relationship1
     

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

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

Основная функция Azure Digital Twins — это простой и эффективный способ запрашивать граф системы двойников и отвечать на вопросы о вашей среде. В Azure CLI запрос выполняется с помощью команды az dt twin query .

Выполните следующие запросы в ИНТЕРФЕЙСе командной строки, чтобы ответить на некоторые вопросы о примере среды. Каждая команда имеет одно место для параметра имени хоста экземпляра (можно также использовать дружественное имя экземпляра, с небольшим снижением производительности).

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

   az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT * FROM DIGITALTWINS"
   

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

   

   Совет

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

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

   az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT * FROM DIGITALTWINS T WHERE IS_OF_MODEL(T, 'dtmi:example:Room;2')"
   

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

   

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

   az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.\$dtId = 'floor0'"
   

   Вы можете выполнять запросы в вашем графе на основе связей, чтобы получить информацию о том, как связаны цифровые двойники, или чтобы ограничить запрос определенной областью. Этот запрос также показывает, что идентификатор двойника (например, floor0 в предыдущем запросе) запрашивается с помощью поля $dtIdметаданных. Только комната0 находится на этаже 0, поэтому это единственная комната в результате этого запроса.

   

   Примечание.

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

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

   az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT * FROM DigitalTwins T WHERE T.Temperature > 75"
   

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

   

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

   az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "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 из этой статьи, но удалите все его модели, двойники и связи, выполните следующую команду az dt job deletion CLI:

  az dt job deletion create -n <name-of-Azure-Digital-Twins-instance> -y
  

  Если требуется удалить только некоторые из этих элементов, можно использовать az dt twin relationship delete, az dt twin delete и az dt model delete для выборочного удаления нужных элементов.

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

  Внимание

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

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

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

Вы также можете удалить файлы модели, созданные на локальном компьютере.

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

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

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