Azure IoT Models Repository客户端库，用于Python

Python版本的Azure IoT Models Repository库提供与Azure IoT Models Repository一起工作的功能

入门

安装包

使用pip安装Azure IoT Models Repository库

pip install azure-iot-modelsrepository

先决条件

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

发布模型

按照指南将模型发布到全局Azure IoT Models Repository。

如果使用自定义本地或远程存储库，您只需将模型文件添加到存储库位置的目录结构中即可，例如 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及其依赖项（取决于依赖项解析模式）。它将返回一个将DTMI映射到模型定义的字典。

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

如果您向该方法提供多个DTMI，您可以一次性检索多个模型（及其依赖项）

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)))

默认情况下，客户端将使用它在实例化时配置的任何dependency_resolution模式来检索模型。但是，可以通过将有效选项之一作为可选关键字参数传递给.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的模块，导入时提供一系列用于处理DTMI的实用操作

# 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"

故障排除

记录

本库使用标准的 logging 库进行日志记录。HTTP会话（URL、头部信息等）将在 DEBUG 级别进行记录。

异常

模型仓库API可能会引发定义在 azure-core 中的异常。

此外，它们可能会引发定义在 azure-iot-modelsrepository 中的异常。

• ModelError - 表示在尝试解析/解析模型定义时发生错误。这通常意味着存在一个不符合 模型DTDL规范 的无效模型。

提供反馈

如果您遇到错误或有所建议，请 提交问题。

下一步

示例

更多示例可以在 示例仓库 中找到。

贡献

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

当您提交拉取请求时，CLA机器人将自动确定您是否需要提供CLA，并适当地装饰PR（例如，标签、注释）。只需按照机器人提供的说明操作即可。您只需要在所有使用我们的CLA的仓库中这样做一次。

本项目已采用 Microsoft开源行为准则。有关更多信息，请参阅 行为准则常见问题解答 或联系 opencode@microsoft.com 询问任何额外的问题或意见。