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

Статья
11/20/2023

В этой статье представлен обзор доступных API-интерфейсов Azure Digital Twins и методов взаимодействия с ними. Интерфейсы REST API можно использовать непосредственно с связанными Swaggers или с помощью пакета 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 уровня управления — это интерфейсы API ARM, используемые для управления экземпляром Azure Digital Twins в целом, поэтому они охватывают такие операции, как создание или удаление всего экземпляра. Они также используются для создания и удаления конечных точек.

Чтобы вызвать 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
Java	azure-resourcemanager-digitaltwins в Maven	Справочник по управлению ресурсами — Digital Twins	Клиентская библиотека Azure Resource Manager AzureDigitalTwins для Java на GitHub
JavaScript	Клиентская библиотека AzureDigitalTwinsManagement для JavaScript в npm		Клиентская библиотека AzureDigitalTwinsManagement для JavaScript на GitHub
Python	azure-mgmt-digitaltwins в PyPI		Пакет SDK Microsoft Azure для Python на GitHub
Go	azure-sdk-for-go/services/digitaltwins/mgmt		Пакет SDK Azure для Go на GitHub

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

API плоскости данных

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
Java	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
Python	Клиентская библиотека Azure Digital Twins Core для Python в PyPI	Справочник по azure-digitaltwins-core	Клиентская библиотека Azure Digital Twins Core для Python на GitHub

Вы также можете выполнять api плоскости данных, взаимодействуя с 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, где существует экземпляр 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: представляет компонент в свойствах Contents двойника BasicDigitalTwin.
BasicRelationship: представляет основные данные связи.
DigitalTwinsJsonPropertyName: содержит строковые константы для использования в сериализации и десериализации JSON для пользовательских типов цифровых двойников.

Массовый импорт с помощью 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-объектов Azure с помощью предпочтительного метода отправки (некоторые параметры — команда AzCopy, Azure CLI или портал Azure). Вы будете использовать URL-адрес хранилища BLOB-объектов файла NDJSON в теле вызова API импорта заданий.

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

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

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

Внимание

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

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

{"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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Вызов API Azure Digital Twins

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

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

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