Управление моделями Azure Digital Twins

В этой статье описывается, как управлять моделями в экземпляре Azure Digital Twins. К операциям управления относятся передача, проверка, извлечение и удаление моделей.

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

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

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

Интерфейсы для разработчиков

В этой статье объясняется, как выполнять различные операции управления с помощью .NET (C#) SDK. Вы также можете создавать те же вызовы управления с помощью пакетов SDK для других языков, описанных в статье, посвященной API и пакетам SDK для Azure Digital Twins.

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

• Azure Digital Twins Explorer
• Вызовы REST API
• Команды Azure CLI

Примечание.

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

Модели DTDL версии 3 можно просматривать на панели "Модели", а двойники, созданные с помощью моделей DTDL версии 3, можно просматривать и изменять (включая их с свойствами массива). Однако модели DTDL версии 3 не отображаются на панели "Граф моделей", и их нельзя импортировать с помощью Azure Digital Twins Explorer. Чтобы импортировать модели DTDL версии 3 в экземпляр, используйте другой интерфейс разработчика, например API и пакеты SDK или Azure CLI.

Визуализация

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

Сведения о средстве Azure Digital Twins Explorer см. в статье Azure Digital Twins Explorer. Подробные инструкции по использованию его функций см. в статье Использование Azure Digital Twins Explorer.

Вот так выглядят визуализации:

Создание моделей

Вы можете создавать собственные модели с нуля или использовать существующие онтологии, доступные для вашей отрасли.

Создание моделей

Модели для Azure Digital Twins записываются в DTDL и сохраняются в виде JSON-файлов. Существует также расширение DTDL, доступное для Visual Studio Code, которое обеспечивает проверку синтаксиса и другие возможности для упрощения написания документов на DTDL.

Рассмотрим пример. Медицинскому учреждению потребовалось получить цифровое представление о своих помещениях. В каждом из них содержится интеллектуальный распределитель мыла для мониторинга промывки рук и датчики для мониторинга передвижений через помещение.

Первый шаг к решению — создание моделей для представления аспектов больницы. Комнату пациента в этом сценарии можно описать следующим образом.

{
    "@id": "dtmi:com:contoso:PatientRoom;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;3",
    "displayName": "Patient Room",
    "contents": [
      {
        "@type": "Property",
        "name": "visitorCount",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "handWashCount",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "handWashPercentage",
        "schema": "double"
      },
      {
        "@type": "Relationship",
        "name": "hasDevices"
      }
    ]
  }

Примечание.

Это пример текста для JSON-файла, в котором модель определена и сохранена, которую необходимо отправить в рамках клиентского проекта. Вызов REST API, с другой стороны, принимает массив определений модели, аналогичных приведенному выше (который сопоставляется с IEnumerable<string> в пакете SDK для .NET). Поэтому, чтобы использовать эту модель непосредственно в REST API, заключите ее в скобки.

Эта модель определяет имя и уникальный идентификатор палаты, а также свойства для представления количества посетителей и состояния мыла. Эти счетчики будут обновлены с датчиков движения и смарт-диспенсеров мыла, и будут использоваться вместе для вычисления handwash percentage свойства. Модель также определяет связь hasDevices, которая будет использоваться для подключения любых цифровых двойников на основе этой модели комнаты к фактическим устройствам.

Примечание.

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

Следуя этому методу, можно определить модели для больницы, палат, зон или самой больницы.

Если ваша цель состоит в создании комплексного набора моделей, описывающего ваш отраслевый домен, рассмотрите возможность упрощения разработки моделей в существующей отрасли. В следующем разделе подробно описаны отраслевые онтологии.

Использование существующих отраслевых онтологий

Онтология — это набор моделей, которые комплексно описывают данный домен, например производство, строительные структуры, системы Интернета вещей, интеллектуальные города, энергетические сетки, веб-содержимое и многое другое.

Если ваше решение предназначено для определенной отрасли, которая использует любой стандарт моделирования, рассмотрите возможность начать с предварительно существующего набора моделей, предназначенных для вашей отрасли, вместо разработки моделей с нуля. Корпорация Майкрософт сотрудничала с экспертами по домену, чтобы создать модель DTDL на основе отраслевых стандартов, чтобы свести к минимуму повторное развертывание и поощрять согласованность и простоту в отраслевых решениях. Дополнительные сведения об этих онтологиях, в том числе о том, как их использовать и какие онтологии доступны сейчас, в разделе "Что такое онтология?".

Проверка синтаксиса

После создания моделей их рекомендуется проверить в автономном режиме перед отправкой в экземпляр Azure Digital Twins.

Чтобы помочь вам проверить модели, клиентская библиотека анализа DTDL на стороне клиента .NET предоставляется в NuGet: DTDLParser. Библиотеку синтаксического анализа можно использовать непосредственно в коде C#. Вы также можете просмотреть пример использования средства синтаксического анализа в DTDLParserResolveSample в GitHub.

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

После создания моделей их можно передать в экземпляр Azure Digital Twins.

Когда вы будете готовы передать модель, можно будет использовать приведенный ниже фрагмент кода для пакета SDK для .NET:

// 'client' is an instance of DigitalTwinsClient
// Read model file into string (not part of SDK)
// fileName is the name of the JSON model file
string dtdl = File.ReadAllText(fileName);
await client.CreateModelsAsync(new[] { dtdl });

При передаче файлы модели проверяются службой.

Обычно вам потребуется отправить несколько моделей в службу. Существует несколько способов отправки нескольких моделей одновременно в одной транзакции. Чтобы помочь вам выбрать стратегию, рассмотрите размер набора моделей по мере продолжения работы с остальными разделами.

Отправка небольших наборов моделей

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

Если вы используете пакет SDK, то можете передать несколько файлов модели с помощью метода CreateModels следующим образом:

var dtdlFiles = Directory.EnumerateFiles(sourceDirectory, "*.json");

var dtdlModels = new List<string>();
foreach (string fileName in dtdlFiles)
{
    // Read model file into string (not part of SDK)
    string dtdl = File.ReadAllText(fileName);
    dtdlModels.Add(dtdl);
}
await client.CreateModelsAsync(dtdlModels);

Если вы используете ИНТЕРФЕЙСы REST API или Azure CLI, вы можете отправить несколько моделей, разместив несколько определений моделей в одном JSON-файле для отправки вместе. В этом случае модели должны размещаться в массиве JSON в файле, как показано в следующем примере:

[
    {
      "@id": "dtmi:com:contoso:Planet;1",
      "@type": "Interface",
      "@context": "dtmi:dtdl:context;3"
    },
    {
      "@id": "dtmi:com:contoso:Moon;1",
      "@type": "Interface",
      "@context": "dtmi:dtdl:context;3"
    }
]

Отправка больших наборов моделей с помощью API импорта заданий

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

Совет

API заданий импорта также позволяет импортировать двойники и связи в одном вызове для создания всех частей графа одновременно. Дополнительные сведения об этом процессе см. в статье "Отправка моделей, двойников и связей" в массовом режиме с помощью API импорта заданий.

Для массового импорта моделей необходимо структурировать модели (и любые другие ресурсы, включенные в задание массового импорта) в виде файла NDJSON . Этот Models раздел происходит сразу после Header раздела, что делает его первым разделом данных графа в файле. Вы можете просмотреть пример файла импорта и пример проекта для создания этих файлов в введение в API заданий импорта.

Затем файл необходимо передать в добавочный большой двоичный объект в Хранилище BLOB-объектов Azure. Инструкции по созданию контейнера хранилища Azure см. в статье "Создание контейнера". Затем отправьте файл с помощью предпочтительного метода отправки (некоторые параметры — команда AzCopy, Azure CLI или портал Azure).

После отправки файла NDJSON в контейнер получите ЕГО URL-адрес в контейнере BLOB-объектов . Это значение будет использоваться позже в тексте вызова API массового импорта.

Ниже приведен снимок экрана, показывающий значение URL-адреса файла БОЛЬШОго двоичного объекта в портал Azure:

Затем файл можно использовать в вызове API импорта заданий. Вы предоставите URL-адрес хранилища BLOB-объектов входного файла, а также новый URL-адрес хранилища BLOB-объектов, чтобы указать, где должен храниться выходной журнал при создании службы.

Извлечение моделей

Вы можете перечислить и извлечь модели, хранящиеся в вашем экземпляре Azure Digital Twins.

К вашим параметрам относятся:

• Извлечение одной модели
• Извлечение всех моделей
• Извлечение метаданных и зависимостей для моделей

Вот несколько примеров входных данных.

// 'client' is a valid DigitalTwinsClient object

// Get a single model, metadata and data
Response<DigitalTwinsModelData> md1 = await client.GetModelAsync("<model-Id>");
DigitalTwinsModelData model1 = md1.Value;

// Get a list of the metadata of all available models; print their IDs
AsyncPageable<DigitalTwinsModelData> md2 = client.GetModelsAsync();
await foreach (DigitalTwinsModelData md in md2)
{
    Console.WriteLine($"Type ID: {md.Id}");
}

// Get models and metadata for a model ID, including all dependencies (models that it inherits from, components it references)
AsyncPageable<DigitalTwinsModelData> md3 = client.GetModelsAsync(new GetModelsOptions { IncludeModelDefinition = true });

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

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

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

Обновление моделей

В этом разделе описываются аспекты и стратегии обновления моделей.

Перед обновлением: подумайте в контексте всего решения

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

Ниже приведены некоторые рекомендации по эффективному управлению переходами модели:

• Вместо того, чтобы думать о моделях как отдельных сущностях, рассмотрите возможность развития всего набора моделей, если это необходимо для поддержания моделей и их связей вместе.
• Рассматривайте модели как исходный код и управляйте ими в системе управления версиями. Применяйте те же ограничения к моделям и изменениям моделей и уделяйте им такое же внимание, что и к другому коду в решении.

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

Стратегии обновления моделей

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

Вместо этого, если требуется внести изменения в модель, например, обновить displayName или description, добавить или удалить свойства, необходимо заменить исходную модель.

При замене модели можно выбрать одну из двух стратегий:

• Стратегия 1. Загрузка новой версии модели. Загрузите модель с новым номером версии и обновите двойников для использования этой новой модели. Новая и старая версии модели будут существовать в вашем экземпляре, пока вы не удалите одну.
  • Используйте эту стратегию, если требуется обновить только часть двойников, использующих эту модель, или если требуется обеспечить соответствие двойников моделям и возможность записи во время перехода модели.
• Стратегия 2. Удаление старой модели и повторная загрузка. Удалите исходную модель и загрузите новую модель с тем же именем и идентификатором (значение DTMI). При использовании этой стратегии старая модель полностью заменяется на новую.
  • Используйте эту стратегию, если вы хотите обновить все двойники, использующие эту модель одновременно, помимо всего кода, реагирующего на модели. Если обновление модели содержит критическое изменение в обновлении модели, двойники не будут соответствовать моделям в течение короткого промежутка времени при переходе от старой модели к новой, то есть они не смогут получать обновления до тех пор, пока не будет загружена новая модель и двойники не будут соответствовать ей.

Примечание.

Не рекомендуется вносить критические изменения в модели за пределами разработки.

Чтобы узнать подробнее о каждой стратегии, перейдите к следующим разделам.

Стратегия 1. Загрузка новой версии модели

Этот вариант включает создание новой версии модели и ее загрузку в экземпляр.

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

Для использования этой стратегии выполните приведенные ниже действия.

1. Создайте и загрузите новую версию модели

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

Затем пометьте эту модель как более новую версию модели, обновив поле id модели. Последний раздел идентификатора модели, после ;, представляет номер версии модели. Чтобы указать, что теперь это обновленная версия этой модели, увеличьте число в конце значения id до любого числа, превышающего номер текущей версии.

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

"@id": "dtmi:com:contoso:PatientRoom;1",

Версия 2 этой модели может выглядеть следующим образом:

"@id": "dtmi:com:contoso:PatientRoom;2",

Затем загрузите новую версию модели в экземпляр.

Эта версия модели будет доступна в вашем экземпляре для использования в качестве цифровых двойников. Она не перезаписывает более ранние версии модели, поэтому несколько версий модели теперь сосуществуют в вашем экземпляре.

2. Обновите элементы графа при необходимости

Затем обновите двойников и их связи в экземпляре для использования в новой версии модели вместо старой.

Вы можете следовать инструкциям по обновлению двойников и обновлению связей. Операция установки исправлений для обновления модели двойника будет выглядеть примерно так:

[
  {
    "op": "replace",
    "path": "/$metadata/$model",
    "value": "dtmi:example:foo;1"
  }
]

Внимание

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

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

3. (Необязательно.) Выведите из эксплуатации или удалите старую версию модели

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

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

Разделы выше содержат пример кода и рекомендации по выводу из эксплуатации и удалению моделей.

Стратегия 2. Удаление старой модели и ее повторная загрузка

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

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

Для использования этой стратегии выполните приведенные ниже действия.

1. Удалите старую модель

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

Примечание.

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

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

2. Создайте и загрузите новую модель

Начните с DTDL исходной модели. Обновите, добавьте или удалите поля, которые вы хотите изменить.

Затем загрузите модель в экземпляр как новую модель, загружаемую впервые.

3. Обновите элементы графа при необходимости

Теперь, когда новая модель была загружена вместо старой, двойники в графе автоматически начнут использовать определение новой модели после истечения срока действия кэширования в экземпляре и его сброса. Этот процесс может занять 10–15 минут или более, в зависимости от размера графа. После этого будут доступны новые и измененные свойства модели, а удаленные свойства доступны больше не будут.

Примечание.

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

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

Существует два способа обновления двойников и связей для новой модели, чтобы сделать их доступными для записи:

• При необходимости исправьте двойники и связи, чтобы они соответствовали новой модели. Вы можете следовать инструкциям по обновлению двойников и обновлению связей.
  • При добавлении свойств: не требуется обновлять двойники и связи, чтобы они имели новые значения, так как двойники с отсутствующими новыми значениями остаются действительными. Их можно исправить, если вы хотите добавить значения для новых свойств.
  • При удалении свойств: необходимо исправить двойники, чтобы удалить свойства, которые теперь являются недействительными в новой модели.
  • При обновлении свойств: необходимо исправить двойники, чтобы обновить значения измененных свойств, чтобы они были действительными в новой модели.
• Удалите двойники и связи, которые используют модель, и создайте их заново. Вы можете следовать инструкциям по удалению двойников и повторному созданию двойников, удалению связей и повторному созданию связей.
  • Эту операцию можно выполнить, если вы вносите много изменений в модель и вам будет трудно обновить существующие двойники, чтобы они соответствовали ей. Но повторное создание может оказаться сложным, если имеется много двойников, связанных между собой множеством связей.

Удаление моделей

Модели также можно удалить из службы одним из двух способов:

• Вывод из эксплуатации. После вывода модели из эксплуатации ее нельзя использовать для создания новых цифровых двойников. Существующие цифровые двойники, которые уже используют эту модель, не затрагиваются, поэтому вы по-прежнему можете обновлять их с учетом изменений свойств, а также добавлять или удалять связи.
• Удаление: эта операция полностью удаляет модель из решения. Все двойники, которые использовали эту модель, больше не связаны с какой-либо допустимой моделью, поэтому они обрабатываются так, как будто они вообще не имеют модели. Вы по-прежнему можете читать эти двойники, но не сможете вносить в них обновления, пока они не будут переназначены другой модели.

Это отдельные функции, которые не влияют друг на друга, хотя они могут использоваться совместно для постепенного удаления модели.

Примечание.

Если вы хотите удалить все модели, двойники и связи в экземпляре одновременно, используйте API удаления заданий.

Списание

Для вывода модели из эксплуатации можно использовать метод DecommissionModel в SDK:

// 'client' is a valid DigitalTwinsClient
await client.DecommissionModelAsync(dtmiOfPlanetInterface);
// Write some code that deletes or transitions digital twins
//...

Можно также вывести модель из эксплуатации с помощью вызова REST API DigitalTwinModels Update. Свойство decommissioned — это единственное свойство, которое можно заменить таким вызовом API. Документ с исправлением JSON будет выглядеть примерно так:

[
  {
    "op": "replace",
    "path": "/decommissioned",
    "value": true
  }
]

Состояние списания модели включается в записи ModelData, возвращаемые API-интерфейсами извлечения модели.

Удаление

Можно удалить все модели в экземпляре одновременно или по отдельности.

Пример того, как удалить все модели одновременно, см. в разделе Комплексные примеры для репозитория Azure Digital Twins в GitHub. Файл CommandLoop.cs содержит функцию CommandDeleteAllModels с кодом для удаления всех моделей в экземпляре.

Чтобы удалить отдельную модель, следуйте инструкциям и рекомендациям в оставшейся части этого раздела.

Перед удалением: требования к удалению

Как правило, модели можно удалять в любое время.

Исключением являются модели, от которых зависят другие модели: с помощью связи extends или в качестве компонента. Например, если модель ConferenceRoom расширяет модель Room и имеет модель ACUnit в качестве компонента, то удалить модель Room или ACUnit невозможно до тех пор, пока в ConferenceRoom не будут удалены соответствующие ссылки.

Это можно сделать, обновив зависимые модели, чтобы удалить зависимости или полностью удалить зависимые модели.

Во время удаления: процесс удаления

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

1. Сначала выполните списание модели
2. Подождите несколько минут, чтобы служба обработала все запросы на создание двойника за последние минуты, отправленные до списания
3. Выполните помодельный опрос двойников, чтобы увидеть все двойников, использующих только что списанную модель
4. Удалите двойников, если они больше не нужны, или при необходимости внесите исправления, чтобы они соответствовали новой модели. Можно также оставить их, в этом случае после удаления модели они станут двойниками без модели. Последствия этого состояния см. в следующем разделе.
5. Подождите еще несколько минут, чтобы убедиться в завершении этого перколяционного процесса
6. Удаление модели

Чтобы удалить модель, можно использовать вызов метода DeleteModel из пакета SDK:

// 'client' is a valid DigitalTwinsClient
await client.DeleteModelAsync(IDToDelete);

Можно также удалить модель при помощи вызова REST API DigitalTwinModels Delete.

После удаления: двойники без модели

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

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

Действия, которые можно выполнить.

• Выполнять запросы данных о двойнике
• Читать свойства
• Читать исходящие связи
• Добавление и удаление входящих связей (как и в, другие двойники по-прежнему могут формировать связи с этим двойником).
  • В определении связи target может по-прежнему отражать спецификацию DTMI удаленной модели. Здесь также может работать связь без определенного целевого объекта.
• Удаление отношений
• Удаление двойника

Действия, которые нельзя выполнить.

• Изменить исходящие связи (т.е. связи от этого двойника с другими двойниками)
• Изменить свойства

После удаления: повторная загрузка модели

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

• С точки зрения хранилища решения это то же самое, что и загрузка совершенно новой модели. Служба не помнит, что старая была когда-либо отправлена.
• Если на графе, ссылающемся на удаленную модель, есть оставшиеся двойники, они больше не считаются утратившими связь, так как этот идентификатор модели снова действителен для нового определения. Но если новое определение модели отличается от удаленного определения модели, у этих двойников могут быть свойства и связи, которые соответствуют удаленному определению и не являются действительными для нового.

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

Преобразование моделей версии 2 в версию 3

Azure Digital Twins поддерживает DTDL версии 2 и 3 (сокращено в документации до версии 2 и 3 соответственно). Версия 3 — это рекомендуемый выбор на основе расширенных возможностей. В этом разделе объясняется, как обновить существующую модель DTDL версии 2 до DTDL версии 3.

1. Обновите контекст. Основная функция, идентифицирующая модель как версия 2 или 3, — это @context поле в интерфейсе. Чтобы преобразовать модель из версии 2 в версию 3, измените значение dtmi:dtdl:context;3контекста dtmi:dtdl:context;2 на . Для многих моделей это будет единственное необходимое изменение.
   1. Значение в версии 2: "@context": "dtmi:dtdl:context;2"
   2. Значение в версии 3: "@context": "dtmi:dtdl:context;3".
2. При необходимости обновите семантические типы. В DTDL версии 2 семантические типы поддерживаются в собственном коде. В DTDL версии 3 они включены в расширение функции "Количественные типы". Таким образом, если модель версии 2 использовала семантические типы, необходимо добавить расширение компонента при преобразовании модели в версию 3. Для этого сначала измените @context поле в интерфейсе с одного значения на массив значений, а затем добавьте это значение dtmi:dtdl:extension:quantitativeTypes;1.
   1. Значение в версии 2: "@context": "dtmi:dtdl:context;2"
   2. Значение в версии 3: "@context": ["dtmi:dtdl:context;3", "dtmi:dtdl:extension:quantitativeTypes;1"]
3. При необходимости рассмотрите ограничения размера. Версия 2 и v3 имеют разные ограничения размера, поэтому если интерфейс очень велик, вы можете просмотреть ограничения в различиях между DTDL версии 2 и v3.

После этих изменений бывшая модель DTDL версии 2 была преобразована в модель DTDL версии 3.

Вы также можете рассмотреть новые возможности DTDL версии 3, такие как свойства типа массива, расслабление версий и дополнительные расширения функций, чтобы узнать, будут ли какие-либо из них полезными дополнениями. Полный список различий между DTDL версии 2 и v3 см. в разделе "Изменения из версии 2" в описании языка DTDL версии 3.

Примечание.

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

Модели DTDL версии 3 можно просматривать на панели "Модели", а двойники, созданные с помощью моделей DTDL версии 3, можно просматривать и изменять (включая их с свойствами массива). Однако модели DTDL версии 3 не отображаются на панели "Граф моделей", и их нельзя импортировать с помощью Azure Digital Twins Explorer. Чтобы импортировать модели DTDL версии 3 в экземпляр, используйте другой интерфейс разработчика, например API и пакеты SDK или Azure CLI.

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

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

• Управление цифровыми двойниками