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


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 напрямую.

Ниже приведены дополнительные сведения о проверке подлинности для запросов 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.

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

  • Все вызовы 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:

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