你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 Python 的 Azure IoT 模型存储库客户端库 - 版本 1.0.0a20220330001

项目
04/05/2023

适用于 Python 的 Azure IoT 模型存储库库提供使用 Azure IoT 模型存储库的功能

入门

安装包

使用 pip 安装适用于 Python 的 Azure IoT 模型存储库库：

pip install azure-iot-modelsrepository

先决条件

遵循 Azure IoT 约定的模型存储库
- 模型存储库可以托管在本地文件系统上，也可以托管在 Web 服务器上
- Azure IoT 托管全局 Azure IoT 模型存储库，如果未提供自定义位置，客户端将使用该存储库

发布模型

按照指南将模型发布到全球 Azure IoT 模型存储库。

如果使用自定义本地或远程存储库，只需将模型文件添加到存储库位置中的目录结构，例如 dtmi/com/example/thermostat-1.json

身份验证

目前不支持身份验证机制。全局终结点不绑定到 Azure 订阅，并且不支持身份验证。发布的所有模型都供匿名公共使用。

关键概念

Azure IoT 模型存储库使构建者能够管理和共享数字孪生模型。这些模型是使用数字孪生定义语言 (DTDL) 定义的 JSON-LD 文档。

存储库定义一种模式，以基于数字孪生模型标识符 (DTMI) 将 DTDL 接口存储在目录结构中。通过将 DTMI 转换为相对路径，可以在存储库中找到接口。例如，DTMI dtmi:com:example:Thermostat;1 转换为 /dtmi/com/example/thermostat-1.json。

示例

以下部分提供了几个代码片段，涵盖了常见的模型存储库任务：

初始化 ModelsRepositoryClient
获取模型
DTMI 约定

初始化 ModelsRepositoryClient

存储库位置

如果实例化期间未提供存储库位置，则使用 Azure IoT 模型存储库全局终结点 (https://devicemodels.azure.com/)

client = ModelsRepositoryClient()

或者，可以通过可选 repository_location 关键字为存储库所在的位置提供自定义位置。客户端接受以下位置格式：

Web 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 IoT 模型存储库。

调用 .get_models() 将在提供的 DTMI 处提取模型，并可能根据依赖项解析模式) (其依赖项。它将返回将 dict DTIS 映射到模型定义的。

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

如果向方法提供多个 DCI，则可以 (检索多个模型，并可能同时) 其依赖项

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模块，导入时，该模块提供一系列用于处理 DTIS 的实用工具操作

# 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 规范

提供反馈

如果遇到 bug 或有建议，请创建问题。

后续步骤

示例

示例存储库中提供了其他示例。

贡献

本项目欢迎贡献和建议。大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。有关详细信息，请访问 https://cla.microsoft.com 。

提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。直接按机器人提供的说明操作。只需使用 CLA 对所有存储库执行一次这样的操作。

此项目采用了 Microsoft 开放源代码行为准则。有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与联系。

通过