Поделиться через


Управление моделями 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 полностью поддерживает модели 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 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> в .NET SDK). Поэтому, чтобы использовать эту модель непосредственно в REST API, заключите ее в скобки.

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

Примечание.

В настоящее время существуют некоторые функции DTDL, которые Azure Digital Twins не поддерживает, включая атрибут для свойств и связей, а writableminMultiplicity также maxMultiplicity для связей. Дополнительные сведения см. в заметках 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 в Хранилище BLOB-объектов Azure. Инструкции по созданию контейнера хранилища Azure см. в статье "Создание контейнера". Затем отправьте файл с помощью предпочтительного метода отправки (некоторые параметры — команда AzCopy, Azure CLI или портал Azure).

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

Вот снимок экрана, показывающий значение URL-адреса BLOB-файла в портале Azure.

Снимок экрана: портал Azure с URL-адресом файла в контейнере хранилища.

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

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

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

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

Вызов 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;2 на dtmi:dtdl:context;3. Для многих моделей это изменение является единственным обязательным.
    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.

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

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