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

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

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

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

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

Для работы с этим учебником требуется следующее.

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

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

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

• Room.json
• Floor.json

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

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

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

  

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

  • Если вы используете локальную установку, выполните вход в Azure CLI с помощью команды az login. Чтобы выполнить аутентификацию, следуйте инструкциям в окне терминала. Сведения о других возможностях, доступных при входе, см. в статье Вход с помощью 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 и CLI приступим к созданию графа сценария.

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

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

На компьютере перейдите к файлу 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. Если вы используете локальную установку 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
   

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

   

ошибки

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, чтобы он правильно был проанализирован.

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

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

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. Какие комнаты есть на этаже floor0? (запрос по связи)

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

   

   Примечание.

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

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: