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

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

• Вы можете использовать средство тестирования HTTP REST, например Postman, чтобы выполнять прямые вызовы к API Azure Digital Twins. Дополнительные сведения об этом процессе см. в статье "Вызов API Azure Digital Twins" с помощью Postman.
• 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 с помощью Postman:

• Вызов API Azure Digital Twins с помощью Postman

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

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