API и пакеты SDK для Azure Digital Twins

2025-01-27

В этой статье представлен обзор доступных API-интерфейсов Azure Digital Twins и методов взаимодействия с ними. REST API можно использовать напрямую с соответствующими спецификациями Swagger или через SDK.

Azure Digital Twins оснащен API плоскости управления, API плоскости данных и пакетами SDK для управления экземпляром и его элементами.

API уровня управления — это API Azure Resource Manager (ARM). Они распространяются на операции управления ресурсами, такие как создание и удаление экземпляра.
API плоскости данных — это интерфейсы API Azure Digital Twins, которые используются для операций управления данными, таких как управление моделями, двойниками и графами.
Пакеты SDK используют существующие API, чтобы упростить разработку пользовательских приложений, использующих Azure Digital Twins.

Общие сведения о плоскости управления

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

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

Ниже приведены пакеты SDK, доступные в настоящее время для API плоскости управления Azure Digital Twins.

Язык пакета SDK	Ссылка на пакет	Справочная документация	Исходный код
.NET (C#)	Azure.ResourceManager.DigitalTwins в NuGet	Справочник по SDK Azure DigitalTwins для .NET	Клиентская библиотека управления Microsoft Azure Digital Twins для .NET на GitHub
Ява	azure-resourcemanager-digitaltwins в Maven	Справочник по управлению ресурсами — Digital Twins	Клиентская библиотека Azure Resource Manager AzureDigitalTwins для Java на GitHub
JavaScript	Клиентская библиотека AzureDigitalTwinsManagement для JavaScript в npm		Клиентская библиотека AzureDigitalTwinsManagement для JavaScript на GitHub
Питон	azure-mgmt-digitaltwins в PyPI		Пакет SDK Microsoft Azure для Python на GitHub
Иди	azure-sdk-for-go/services/digitaltwins/mgmt		Пакет SDK Azure для Go на GitHub

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

Общие сведения о плоскости данных

API плоскости данных — это API-интерфейсы Azure Digital Twins, используемые для управления элементами в вашем экземпляре Azure Digital Twins. К ним относятся такие операции, как создание маршрутов, отправка моделей, создание связей и управление двойниками. Их можно разделить на следующие категории:

DigitalTwinModels — Категория DigitalTwinModels содержит API для управления моделями в экземпляре Azure Digital Twins. К действиям управления относятся передача, проверка, извлечение и удаление моделей, созданных в DTDL.
DigitalTwins — Категория DigitalTwins содержит API, которые позволяют разработчикам создавать, изменять и удалять цифровые двойники и их связи в экземпляре Azure Digital Twins.
Query— Категория "Запрос" позволяет разработчикам находить наборы цифровых двойников в графе двойников по связям.
Event Routes — Категория "Маршруты событий" содержит API-интерфейсы для маршрутизации данных через систему и подчиненные службы.
Import Jobs — API импорта заданий позволяет управлять длительным асинхронным действием для импорта моделей, двойников и связей в массовом режиме.
Delete Jobs — API по удалению заданий позволяет управлять длительным асинхронным процессом, направленным на удаление всех моделей, двойников и связей в экземпляре.

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

Ниже приведены пакеты SDK, доступные в настоящее время для API плоскости данных Azure Digital Twins.

Язык пакета SDK	Ссылка на пакет	Справочная документация	Исходный код
.NET (C#)	Azure.DigitalTwins.Core в NuGet	Справочник по клиентской библиотеке Azure IoT Digital Twins для .NET	Клиентская библиотека Azure IoT Digital Twins для .NET на GitHub
Ява	com.azure:azure-digitaltwins-core в Maven	Справочник по пакету SDK для Azure Digital Twins для Java	Клиентская библиотека Azure IoT Digital Twins для Java на GitHub
JavaScript	Клиентская библиотека Azure Digital Twins Core для JavaScript в npm	Reference for @azure/digital-twins-core	Клиентская библиотека Azure Digital Twins Core для JavaScript на GitHub
Питон	Клиентская библиотека Azure Digital Twins Core для Python в PyPI	Справочник по azure-digitaltwins-core	Клиентская библиотека Azure Digital Twins Core для Python на GitHub

Вы также можете работать с API плоскости данных посредством взаимодействия с Azure Digital Twins с помощью CLI (интерфейс командной строки).

Массовый импорт с помощью API импорта заданий

API импорта заданий — это API плоскости данных, который позволяет импортировать набор моделей, двойников и (или) связей в одном вызове API. Операции API импорта заданий также включаются в команды CLI и SDK плоскости данных. Использование API заданий импорта требует использования Хранилища BLOB-объектов Azure.

Проверка разрешений

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

Сначала необходимо назначаемое системой управляемое удостоверение для экземпляра Azure Digital Twins. Для получения инструкций по настройке управляемого системой удостоверения для экземпляра см. раздел «Включение и отключение управляемого системой удостоверения для экземпляра».

У вас должны быть права на запись в экземпляре Azure Digital Twins для следующих категорий действий данных:

Microsoft.DigitalTwins/jobs/*
Все элементы графа, которые необходимо включить в вызов заданий. Это может включать Microsoft.DigitalTwins/models/*, Microsoft.DigitalTwins/digitaltwins/*и /или Microsoft.DigitalTwins/digitaltwins/relationships/*.

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

Примечание.

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

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

Читатель данных BLOB-объектов в хранилище для входного контейнера BLOB-объектов службы хранения Azure
Соавтор данных BLOB-объектов хранилища для выходного контейнера BLOB-объектов службы хранилища Azure

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

Форматирование данных

API принимает входные данные графа из файла NDJSON, который необходимо загрузить в контейнер BLOB-объектов хранилища Azure. Файл начинается разделом Header, после которого следуют необязательные разделы Models, Twins, и Relationships. Вам не нужно включать в файл все три типа данных графа, но все разделы, которые присутствуют, должны соответствовать этому порядку. Двойники и связи, созданные с помощью этого API, могут дополнительно включать инициализацию их свойств.

Ниже приведен пример входного файла данных для API импорта:

{"Section": "Header"}
{"fileVersion": "1.0.0", "author": "foobar", "organization": "contoso"}
{"Section": "Models"}
{"@id":"dtmi:com:microsoft:azure:iot:model0;1","@type":"Interface","contents":[{"@type":"Property","name":"property00","schema":"integer"},{"@type":"Property","name":"property01","schema":{"@type":"Map","mapKey":{"name":"subPropertyName","schema":"string"},"mapValue":{"name":"subPropertyValue","schema":"string"}}},{"@type":"Relationship","name":"has","target":"dtmi:com:microsoft:azure:iot:model1;1","properties":[{"@type":"Property","name":"relationshipproperty1","schema":"string"},{"@type":"Property","name":"relationshipproperty2","schema":"integer"}]}],"description":{"en":"This is the description of model"},"displayName":{"en":"This is the display name"},"@context":"dtmi:dtdl:context;2"}
{"@id":"dtmi:com:microsoft:azure:iot:model1;1","@type":"Interface","contents":[{"@type":"Property","name":"property10","schema":"string"},{"@type":"Property","name":"property11","schema":{"@type":"Map","mapKey":{"name":"subPropertyName","schema":"string"},"mapValue":{"name":"subPropertyValue","schema":"string"}}}],"description":{"en":"This is the description of model"},"displayName":{"en":"This is the display name"},"@context":"dtmi:dtdl:context;2"}
{"Section": "Twins"}
{"$dtId":"twin0","$metadata":{"$model":"dtmi:com:microsoft:azure:iot:model0;1"},"property00":10,"property01":{"subProperty1":"subProperty1Value","subProperty2":"subProperty2Value"}}
{"$dtId":"twin1","$metadata":{"$model":"dtmi:com:microsoft:azure:iot:model1;1"},"property10":"propertyValue1","property11":{"subProperty1":"subProperty1Value","subProperty2":"subProperty2Value"}}
{"Section": "Relationships"}
{"$dtId":"twin0","$relationshipId":"relationship","$targetId":"twin1","$relationshipName":"has","relationshipProperty1":"propertyValue1","relationshipProperty2":10}

Совет

Пример проекта, который преобразует модели, двойники и связи в формат NDJSON, поддерживаемый API импорта, см. в статье Azure Digital Twins Bulk Import NDJSON Generator. Пример проекта написан для .NET и может быть скачан или адаптирован для создания собственных файлов импорта.

После создания файла загрузите его в блочный BLOB в Хранилище BLOB-объектов Azure, используя предпочтительный метод загрузки (некоторые варианты включают команду AzCopy, Azure CLI или портал Azure). Вы используете URL файла NDJSON из хранилища BLOB в теле вызова API импорта заданий.

Запуск задания импорта

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

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

Внимание

Убедитесь, что управляемое удостоверение, назначаемое системой экземпляра Azure Digital Twins, имеет разрешения RBAC хранилища BLOB-объектов, описанные в разделе "Проверка разрешений".

По мере того, как выполняется задание импорта, служба создает структурированный журнал выходных данных и сохраняет его как новый добавочный BLOB-объект в вашем BLOB-контейнере по указанному в запросе URL-адресу для выходного BLOB-объекта. Ниже приведен пример журнала выходных данных для успешного импорта моделей, двойников и связей заданий:

{"timestamp":"2022-12-30T19:50:34.5540455Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"status":"Started"}}
{"timestamp":"2022-12-30T19:50:37.2406748Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Models","status":"Started"}}
{"timestamp":"2022-12-30T19:50:38.1445612Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Models","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:38.5475921Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Twins","status":"Started"}}
{"timestamp":"2022-12-30T19:50:39.2744802Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Twins","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:39.7494663Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Relationships","status":"Started"}}
{"timestamp":"2022-12-30T19:50:40.4480645Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Relationships","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:41.3043264Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"status":"Succeeded"}}

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

Также можно отменить выполняющееся задание импорта, используя метод Cancel из API по управлению заданиями импорта. После отмены задания и его завершения, когда оно больше не выполняется, вы можете его удалить.

Ограничения и рекомендации

При работе с API заданий импорта следует учитывать следующие аспекты.

Задания импорта не являются атомарными операциями. Нет отката в случае сбоя, частичного завершения задания или использования операции Отмены.
В экземпляре Azure Digital Twins одновременно поддерживается только одно массовое задание. Вы можете просмотреть эту информацию и другие числовые ограничения API Jobs в ограничениях Azure Digital Twins.

Массовое удаление с помощью API удаления заданий

API удаления заданий — это API плоскости данных, который позволяет удалять все модели, двойники и связи в экземпляре с одним вызовом API. Операции API удаления заданий также доступны в виде команд CLI. Проверьте документацию по API, чтобы узнать детали запроса для создания задачи на удаление и проверки её состояния.

Чтобы убедиться, что все элементы удалены, следуйте этим рекомендациям при использовании API удаления заданий:

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

В зависимости от размера удаленного графа задание удаления может занять от нескольких минут до нескольких часов.

Время ожидания по умолчанию для задания удаления — 12 часов, которое можно настроить на любое значение в диапазоне от 15 минут до 24 часов с помощью параметра запроса в API. Это время выполнения задания удаления до истечения времени ожидания, в течение которого служба пытается остановить задание, если оно еще не завершено.

Ограничения и другие рекомендации

При работе с API удаления заданий следует учитывать следующие рекомендации.

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

Заметки об использовании и проверке подлинности

В этом разделе содержатся более подробные сведения об использовании API и пакетов SDK.

Заметки API

Ниже приведены общие сведения о вызове API Azure Digital Twins напрямую.

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

Ниже приведены дополнительные сведения о проверке подлинности для запросов API.

Одним из способов создания токена носителя для запросов API Azure Digital Twins является команда az account get-access-token CLI. Для получения подробных инструкций см. Добавление токена уровня доступа.
Для запросов к API Azure Digital Twins требуется пользователь или служебный принципал, который входит в тот же тенант Microsoft Entra ID, где развернут экземпляр Azure Digital Twins. Чтобы предотвратить вредоносное сканирование конечных точек Azure Digital Twins, запросы с маркерами доступа за пределами исходного клиента возвращают сообщение об ошибке "404 Поддомен не найден". Эта ошибка возвращается, даже если пользователю или субъекту-службе предоставлена роль владельца данных Azure Digital Twins или средства чтения данных Azure Digital Twins через совместную работу Microsoft Entra B2B . Сведения о том, как обеспечить доступ для нескольких арендаторов, см. в статье Написание кода проверки подлинности приложения.

Заметки пакета SDK

Базовый пакет SDK для Azure Digital Twins — это Azure.Core. См. документацию по пространству имен Azure для получения справки по инфраструктуре и типам пакетов SDK.

Ниже приведены дополнительные сведения о проверке подлинности с помощью пакетов SDK.

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

Ниже приведены дополнительные сведения о функциях и возвращенных данных.

Все обращения к API служб представлены в виде функций-членов класса DigitalTwinsClient.
Все функции службы существуют в синхронных и асинхронных версиях.
Все функции службы вызывают исключение для любого кода возврата 400 и выше. Убедитесь, что вызовы обернуты в раздел try, и перехватывайте по крайней мере RequestFailedExceptions. Дополнительные сведения об этом типе исключения см. в справочной документации.
Большинство методов службы возвращают Response<T> (или Task<Response<T>> для асинхронных вызовов), где T — это класс возвращаемого объекта для вызова службы. Класс Response инкапсулирует возвращаемые службой результаты и представляет возвращаемые значения в поле Value.
Методы службы, возвращающие результаты с разбивкой на страницы, возвращают Pageable<T> либо AsyncPageable<T> в качестве результатов. Дополнительные сведения о классе Pageable<T> см. в справочной документации. Дополнительные сведения о AsyncPageable<T> см. в справочной документации.
Можно выполнять итерацию по результатам с разбивкой на страницы с помощью цикла await foreach. Дополнительные сведения об этом процессе см. в разделе "Итерирование с помощью асинхронных перечислений" в C# 8.
Методы службы возвращают строго типизированные объекты везде, где это возможно. Но так как служба Azure Digital Twins основана на моделях, настраиваемых пользователем во время выполнения (через модели DTDL, загруженные в службу), многие API службы принимают и возвращают данные двойника в формате JSON.

Вспомогательные средства сериализации в пакете SDK для .NET (C#)

Вспомогательные функции сериализации — это вспомогательные функции, доступные в пакете SDK для .NET (C#) для быстрого создания или десериализации данных двойника для доступа к базовым сведениям. Поскольку основные методы пакета SDK возвращают данные двойника в формате JSON по умолчанию, можно использовать эти вспомогательные классы для дальнейшего разбиения данных двойника.

Доступны следующие вспомогательные классы:

BasicDigitalTwin: представляет основные данные цифрового двойника.
BasicDigitalTwinComponent: в общих чертах представляет компонент в свойствах ContentsBasicDigitalTwin.
BasicRelationship: в общем виде представляет основополагающие данные отношения.
DigitalTwinsJsonPropertyName: содержит строковые константы для использования в сериализации и десериализации JSON для пользовательских типов цифровых двойников.

Мониторинг метрик API

Метрики API, такие как запросы, задержка и частота сбоев, можно просмотреть на портале Azure.

Сведения о просмотре метрик Azure Digital Twins и управлении ими см. в статье "Мониторинг экземпляра". Полный список метрик API, доступных для Azure Digital Twins, см. в разделе метрики запросов API Azure Digital Twins.

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

Узнайте, как выполнять прямые запросы к API Azure Digital Twins:

Вызов API Azure Digital Twins

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

Код клиентского приложения