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

Клиентская библиотека репозитория моделей Интернета вещей Azure для Python — версия 1.0.0a20220330001

  • Статья

Библиотека репозитория моделей Интернета вещей Azure для Python предоставляет функциональные возможности для работы с репозиторием моделей Интернета вещей Azure.

Начало работы

Установка пакета

Установите библиотеку репозитория моделей Интернета вещей Azure для Python с помощью pip:

pip install azure-iot-modelsrepository

Предварительные требования

  • Репозиторий моделей в соответствии с соглашениями Azure IoT
    • Репозиторий моделей можно разместить в локальной файловой системе или на веб-сервере.
    • В Azure IoT размещается глобальный репозиторий моделей Интернета вещей Azure , который клиент будет использовать, если пользовательское расположение не указано.

Опубликование моделей

Следуйте руководству по публикации моделей в глобальном репозитории моделей Интернета вещей Azure.

При использовании пользовательского локального или удаленного репозитория можно просто добавить файлы модели в структуру каталогов в расположении репозитория, например. dtmi/com/example/thermostat-1.json

Аутентификация

В настоящее время механизмы проверки подлинности не поддерживаются. Глобальная конечная точка не привязана к подписке Azure и не поддерживает проверку подлинности. Все опубликованные модели предназначены для анонимного общедоступного использования.

Основные понятия

Репозиторий моделей Интернета вещей Azure позволяет разработчикам управлять моделями цифровых двойников и совместно использовать их. Модели представляют собой документы JSON-LD , определенные с помощью языка определения Цифровых двойников (DTDL).

Репозиторий определяет шаблон для хранения интерфейсов DTDL в структуре каталогов на основе идентификатора модели цифрового двойника (DTMI). Интерфейс можно найти в репозитории, преобразовав DTMI в относительный путь. Например, DTMI dtmi:com:example:Thermostat;1 преобразуется в /dtmi/com/example/thermostat-1.json.

Примеры

В следующих разделах представлено несколько фрагментов, охватывающих общие задачи репозитория моделей:

Инициализация ModelsRepositoryClient

Расположение репозитория

Если во время создания экземпляра расположение репозитория не указано, используется глобальная конечная точка репозитория моделей Интернета вещей Azure (https://devicemodels.azure.com/).

client = ModelsRepositoryClient()

Кроме того, можно указать пользовательское расположение репозитория с помощью необязательного repository_location ключевого слова . Клиент принимает следующие форматы расположения:

  • URL-адрес веб-сайта — например, "https://contoso.com/models/"
  • URI локальной файловой системы — например, "file:///path/to/repository/"
  • Путь к файлу POSIX — например, "/path/to/repository/"
  • Путь к файлу буквы диска — например, "C:/path/to/repository/"
client = ModelsRepositoryClient(repository_location="https://contoso.com/models/")

Режим разрешения зависимостей

Клиент может быть настроен с дополнительным dependency_resolution режимом при создании экземпляра, используя одно из следующих значений:

  • 'disabled' — Клиент не будет разрешать зависимости модели.
  • 'enabled' — Клиент разрешает все зависимости модели.
  • 'tryFromExpanded' — Клиент попытается разрешить модели с помощью расширенного определения модели (если это невозможно, то вернитесь в 'enabled' режим).
client = ModelsRepositoryClient(dependency_resolution="enabled")

dependency_resolution Если режим не указан:

  • Клиенты, настроенные для глобальной конечной точки репозитория моделей Azure IoT, по умолчанию будут использовать 'tryFromExpanded'
  • Клиенты, настроенные для пользовательского расположения (удаленного или локального), будут по умолчанию использовать 'enabled'

Дополнительные параметры

Если необходимо переопределить поведение конвейера по умолчанию из библиотеки azure-core, можно указать различные аргументы ключевых слов во время создания экземпляра.

Очистка клиента

Завершив работу с клиентом, обязательно вызовите .close() , чтобы освободить ресурсы

client = ModelsRepositoryClient()
# Do things
client.close()

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

with ModelsRepositoryClient() as client:
    # Do things

ModelsRepositoryClient — получение моделей

Обратите внимание, что перед их получением модели необходимо сначала опубликовать модели в репозитории . В следующих примерах предполагается, что вы используете глобальный репозиторий моделей Интернета вещей Azure.

Вызов .get_models() приведет к выбору модели по предоставленному DTMI и, возможно, ее зависимостям (в зависимости от режима разрешения зависимостей). Он возвращает объект dict , который сопоставляет DTMIs с определениями модели.

dtmi = "dtmi:com:example:TemperatureController;1"
with ModelsRepositoryClient() as client:
    models = get_models(dtmi)
print("{} resolved in {} interfaces".format(dtmi, len(models)))

Если вы предоставляете методу несколько DTMIs, можно получить несколько моделей (и потенциально их зависимостей) одновременно.

dtmis = ["dtmi:com:example:TemperatureController;1", "dtmi:com:example:azuresphere:sampledevice;1"]
with ModelsRepositoryClient() as client:
    models = get_models(dtmis)
print("{} resolved in {} interfaces".format(dtmi, len(models)))

По умолчанию клиент будет использовать режим разрешения зависимостей в зависимостей, с помощью которого он был настроен при получении моделей. Однако это поведение можно переопределить, передав любой из допустимых параметров в в качестве необязательного аргумента ключевого слова в .get_models()

dtmi = "dtmi:com:example:TemperatureController;1"
with ModelsRepositoryClient(dependency_resolution="disabled") as client:
    models = get_models(dtmi, dependency_resolution="enabled")

Соглашения DTMI

Пакет содержит модуль с именем dtmi_conventions, который при импорте предоставляет ряд служебных операций для работы с DTMIs.

# Returns True - this is a valid DTMI
dtmi_conventions.is_valid_dtmi("dtmi:com:example:Thermostat;1")

# Returns False - this is NOT a valid DTMI
dtmi_conventions.is_valid_dtmi("dtmi:com:example:Thermostat")

dtmi = "dtmi:com:example:Thermostat;1"

# Local repository example
repo_uri = "file:///path/to/repository"
print(dtmi_conventions.get_model_uri(dtmi, repo_uri))
# Prints: "file:///path/to/repository/dtmi/com/example/thermostat-1.json"
print(dtmi_conventions.get_model_uri(dtmi, repo_uri, expanded=True))
# Prints: "file:///path/to/repository/dtmi/com/example/thermostat-1.expanded.json"

# Remote repository example
repo_uri = "https://contoso.com/models/"
print(dtmi_conventions.get_model_uri(dtmi, repo_uri))
# Prints: "https://contoso/com/models/dtmi/com/example/thermostat-1.json"
print(dtmi_conventions.get_model_uri(dtmi, repo_uri, expanded=True))
# Prints: "https://contoso/com/models/dtmi/com/example/thermostat-1.expanded.json"

Устранение неполадок

Ведение журнала

Эта библиотека использует стандартную библиотеку ведения журнала для ведения журнала. Сведения о сеансах HTTP (URL-адреса, заголовки и т. д.) регистрируются на DEBUG уровне.

Исключения

API репозитория моделей могут вызывать исключения, определенные в azure-core.

Кроме того, они могут вызывать исключения, определенные в azure-iot-modelsrepository:

  • ModelError — указывает на ошибку при попытке синтаксического анализа или разрешения определения модели. Как правило, это означает, что существует неправильно сформированная модель, которая не соответствует спецификации модели DTDL.

Отзывы

Если у вас возникли ошибки или есть предложения, откройте проблему.

Дальнейшие действия

Примеры

Дополнительные примеры доступны в репозитории примеров.

Участие

На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Для получения подробных сведений посетите веб-страницу https://cla.microsoft.com.

При отправке запроса на включение внесенных изменений CLA-бот автоматически определит необходимость предоставления соглашения CLA и соответствующего оформления запроса на включение внесенных изменений (например, добавление метки, комментария). Просто следуйте инструкциям бота. Будет достаточно выполнить их один раз для всех репозиториев, поддерживающих соглашение CLA.

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения см. в разделе часто задаваемых вопросов о правилах поведения или обратитесь к opencode@microsoft.com с любыми дополнительными вопросами или комментариями.