Azure Azure Digital Twins Core Python客户端库

此软件包包含用于访问Azure Digital Twins服务的Azure Digital Twins API SDK，以提供对管理孪生、模型、关系等的访问。

免责声明

Azure SDK Python包对Python 2.7的支持已于2022年1月1日结束。有关更多信息，请参阅https://github.com/Azure/azure-sdk-for-python/issues/20691

入门

简介

Azure Digital Twins 是一个面向下一代物联网解决方案的开发平台，允许您在云中安全、高效地创建、运行和管理业务环境的数字表示。使用 Azure Digital Twins，创建实时操作状态表示既快又经济，数字表示与来自物联网和其他数据源的实时数据保持同步。如果您是 Azure Digital Twins 新用户并想了解更多关于该平台的信息，请确保查看 Azure Digital Twins 的官方文档页面。

有关如何针对 Azure Digital Twins 服务编程的介绍，请访问编码教程页面以获取简单的分步指南。访问此教程了解如何使用命令行客户端应用程序与 Azure Digital Twin 实例交互。最后，为确保您了解如何构建由环境实时数据驱动的端到端 Azure Digital Twins 解决方案，请查看此实用指南。

上述指南可以帮助您开始使用 Azure Digital Twins 的关键元素，例如创建 Azure Digital Twins 实例、模型、孪生图等。使用下面的示例指南熟悉帮助您针对 Azure Digital Twins 编程的各种 API。

安装方法

使用 pip 安装 [azure-digitaltwins-core][pypi_package_keys] 和 azure-identity

pip install azure-digitaltwins-core azure-identity

azure-identity 用于 Azure Active Directory 认证，如下所示。

使用方法

身份验证，权限

要创建新的数字孪生客户端，您需要一个 Azure Digital Twin 实例的端点以及凭据。对于下面的示例，必须设置 AZURE_URL、AZURE_TENANT_ID、AZURE_CLIENT_ID 和 AZURE_CLIENT_SECRET 环境变量。客户端需要一个 TokenCredential 或 ServiceClientCredentials 实例。在此示例中，我们展示了如何使用一个派生类：DefaultAzureCredentials。

注意：为了访问数字孪生服务的数据平面，必须给实体分配权限。为此，请使用 Azure CLI 命令：az dt rbac assign-role --assignee '<user-email | application-id>' --role owner -n '<your-digital-twins-instance>'

DefaultAzureCredential 支持不同的身份验证机制，并根据其执行的环境确定适当的凭据类型。它会尝试按顺序使用多种凭据类型，直到找到有效的凭据。

示例代码

# DefaultAzureCredential supports different authentication mechanisms and determines the appropriate credential type based of the environment it is executing in.
# It attempts to use multiple credential types in an order until it finds a working credential.

# - AZURE_URL: The URL to the ADT in Azure
url = os.getenv("AZURE_URL")

# DefaultAzureCredential expects the following three environment variables:
# - AZURE_TENANT_ID: The tenant ID in Azure Active Directory
# - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
# - AZURE_CLIENT_SECRET: The client secret for the registered application
credential = DefaultAzureCredential()
service_client = DigitalTwinsClient(url, credential)

关键概念

Azure Digital Twins 是一个 Azure IoT 服务，可以创建物理环境的综合模型。它可以创建空间智能图来模拟人员、空间和设备之间的关系和交互。您可以访问 Azure Digital Twins 文档 了解更多关于 Azure Digital Twins 的信息。

示例

您可以使用示例项目探索数字孪生 API（使用客户端库）。

示例项目演示以下内容

• 实例化客户端
• 创建、获取和退役模型
• 创建、查询和删除数字孪生
• 获取和更新数字孪生的组件
• 创建、获取和删除数字孪生之间的关系
• 创建、获取和删除数字孪生的事件路由
• 向数字孪生和数字孪生组件发布遥测消息

创建、列出、退役和删除模型

创建模型

下面使用代码创建模型。您需要传递一个包含模型列表的数组。

temporary_component = {
    "@id": component_id,
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;2",
    "displayName": "Component1",
    "contents": [
    {
        "@type": "Property",
        "name": "ComponentProp1",
        "schema": "string"
    },
    {
        "@type": "Telemetry",
        "name": "ComponentTelemetry1",
        "schema": "integer"
    }
    ]
}

temporary_model = {
    "@id": model_id,
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;2",
    "displayName": "TempModel",
    "contents": [
    {
        "@type": "Property",
        "name": "Prop1",
        "schema": "string"
    },
    {
        "@type": "Component",
        "name": "Component1",
        "schema": component_id
    },
    {
        "@type": "Telemetry",
        "name": "Telemetry1",
        "schema": "integer"
    }
    ]
}

new_models = [temporary_component, temporary_model]
models = service_client.create_models(new_models)
print('Created Models:')
print(models)

模型列表

使用 list_models 获取所有创建的模型

listed_models = service_client.list_models()
for model in listed_models:
    print(model)

获取模型

使用 get_model 和模型的唯一标识符来获取特定模型。

# Get a model
get_model = service_client.get_model(model_id)
print('Get Model:')
print(get_model)

停用模型

要停用模型，请传递您想要停用的模型的模型 ID。

# Decommission a model
service_client.decommission_model(model_id)

删除模型

要删除模型，请传递您想要删除的模型的模型 ID。

# Delete a model
service_client.delete_model(model_id)

创建和删除数字孪生

创建数字孪生

创建孪生时，您需要提供数字孪生的 ID，例如 my_twin，以及基于之前创建的模型的 application/json 数字孪生。您可以在此处查看示例 application/json。

digital_twin_id = 'digitalTwin-' + str(uuid.uuid4())
temporary_twin = {
    "$metadata": {
        "$model": model_id
    },
    "$dtId": digital_twin_id,
    "Prop1": 42
}

created_twin = service_client.upsert_digital_twin(digital_twin_id, temporary_twin)
print('Created Digital Twin:')
print(created_twin)

获取数字孪生

获取数字孪生非常简单。

get_twin = service_client.get_digital_twin(digital_twin_id)
print('Get Digital Twin:')
print(get_twin)

查询数字孪生

使用Azure Digital Twins 查询存储语言查询 Azure Digital Twins 实例中的数字孪生。查询调用支持分页。以下是如何查询数字孪生以及如何遍历结果的示例。

请注意，在您的实例中的更改反映在查询中之前可能会有延迟。有关查询限制的更多详细信息，请参阅 (https://docs.microsoft.com/azure/digital-twins/how-to-query-graph#query-limitations)

query_expression = 'SELECT * FROM digitaltwins'
query_result = service_client.query_twins(query_expression)
print('DigitalTwins:')
for twin in query_result:
    print(twin)

删除数字孪生

只需提供数字孪生的 ID 即可简单地删除数字孪生。

service_client.delete_digital_twin(digital_twin_id)

获取和更新数字孪生组件

更新数字孪生组件

要更新组件或换句话说是要替换、删除和/或添加数字孪生中的组件属性或子属性，您需要数字孪生的 ID、组件名称以及在指定的数字孪生组件上要执行的应用/json-patch+json 操作。以下是如何执行此操作的示例代码。

component_name = "Component1"
patch = [
    {
        "op": "replace",
        "path": "/ComponentProp1",
        "value": "value2"
    }
]
service_client.update_component(digital_twin_id, component_name, patch)

获取数字孪生组件

通过提供组件名称和属于该数字孪生的 ID 来获取组件。

get_component = service_client.get_component(digital_twin_id, component_name)
print('Get Component:')
print(get_component)

创建和列出数字孪生关系

创建数字孪生关系

upsert_relationship 在提供数字孪生 ID、关系名称（例如 "contains"）、关系 ID（例如 "FloorContainsRoom"）以及要创建的应用/json 关系的情况下创建数字孪生上的关系。必须包含具有键 "$targetId" 的属性来指定关系的目标。关系的示例有效载荷可以在此处找到。

hospital_relationships = [
    {
        "$relationshipId": "BuildingHasFloor",
        "$sourceId": building_twin_id,
        "$relationshipName": "has",
        "$targetId": floor_twin_id,
        "isAccessRestricted": False
    },
    {
        "$relationshipId": "BuildingIsEquippedWithHVAC",
        "$sourceId": building_twin_id,
        "$relationshipName": "isEquippedWith",
        "$targetId": hvac_twin_id
    },
    {
        "$relationshipId": "HVACCoolsFloor",
        "$sourceId": hvac_twin_id,
        "$relationshipName": "controlsTemperature",
        "$targetId": floor_twin_id
    },
    {
        "$relationshipId": "FloorContainsRoom",
        "$sourceId": floor_twin_id,
        "$relationshipName": "contains",
        "$targetId": room_twin_id
    }
]

for relationship in hospital_relationships:
    service_client.upsert_relationship(
        relationship["$sourceId"],
        relationship["$relationshipId"],
        relationship
    )

列出数字孪生关系

list_relationships 和 list_incoming_relationships 分别列出数字孪生的所有关系和所有传入关系。

relationships = service_client.list_relationships(digital_twint_id)
for relationship in relationships:
    print(relationship)

incoming_relationships = service_client.list_incoming_relationships(digital_twin_id)
for incoming_relationship in incoming_relationships:
    print(incoming_relationship)

创建、列出和删除数字孪生的事件路由

创建事件路由

要创建事件路由，提供事件路由 ID（例如 "myEventRouteId"）以及包含端点和可选过滤器的事件路由数据，如下例所示。

event_route_id = 'eventRoute-' + str(uuid.uuid4())
event_filter = "$eventType = 'DigitalTwinTelemetryMessages' or $eventType = 'DigitalTwinLifecycleNotification'"
route = DigitalTwinsEventRoute(
    endpoint_name=event_hub_endpoint_name,
    filter=event_filter
)
service_client.upsert_event_route(event_route_id, route)

有关事件路由过滤语言的信息，请参阅“如何管理路由”文档。

列出事件路由

使用 list_event_routes 通过事件路由 ID 列出特定事件路由或设置选项以列出所有事件路由。

event_routes = service_client.list_event_routes()
for event_route in event_routes:
    print(event_route)

删除事件路由

通过事件路由 ID 删除事件路由。

service_client.delete_event_route(event_route_id)

为数字孪生发布遥测消息

要为数字孪生发布遥测消息，您需要提供数字孪生 ID，以及需要更新的遥测的负载。

digita_twin_id = "<DIGITAL TWIN ID>"
telemetry_payload = '{"Telemetry1": 5}'
service_client.publish_telemetry(
    digita_twin_id,
    telemetry_payload
)

您还可以为数字孪生中的特定组件发布遥测消息。除了数字孪生ID和数据负载外，您还需要指定目标组件ID。

digita_twin_id = "<DIGITAL TWIN ID>"
component_name = "<COMPONENT_NAME>"
telemetry_payload = '{"Telemetry1": 5}'
service_client.publish_component_telemetry(
    digita_twin_id,
    component_name,
    telemetry_payload
)

故障排除

日志记录

该库使用标准日志库进行日志记录。HTTP会话（URL、头信息等）的基本信息以INFO级别进行记录。

启用详细DEBUG级别日志记录，包括请求/响应体和未编辑的头信息，可以在客户端通过logging_enable关键字参数实现

客户端级别日志记录

import sys
import logging

# Create logger
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# Create service client and enable logging for all operations
service_client = DigitalTwinsClient(url, credential, logging_enable=True)

按操作级别日志记录

import sys
import logging

# Create logger
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# Get model with logging enabled
model = service_client.get_model(model_id, logging_enable=True)

可选配置

可以在客户端和按操作级别传递可选关键字参数。azure-core 参考文档 描述了重试、日志记录、传输协议等可用配置。

下一步操作

提供反馈

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

贡献

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

提交拉取请求时，CLA机器人将自动确定您是否需要提供CLA并相应地装饰PR（例如，标签、注释）。只需遵循机器人提供的说明即可。您只需在整个使用我们的CLA的存储库中这样做一次。

本项目已采用微软开源行为准则。有关更多信息，请参阅行为准则常见问题解答或通过opencode@microsoft.com联系以获取任何额外的问题或评论。

发行历史

1.2.0 (2022-05-31)

• GA发行版

1.2.0b1 (2022-03-31)

已修复的错误

• 更新azure-core依赖项，以避免安装不一致的依赖项。

其他更改

• 不再支持Python 2.7和3.6。请使用Python 3.7或更高版本。

1.1.0 (2020-11-24)

• 以下GA发行版包含以下更改

API更新

• 将etag和match_condition参数添加到upsert_digital_twin和upsert_relationship API中，以支持条件操作。
• 将EventRoute模型重命名为DigitalTwinsEventRoute。
• 移除了未使用的azure.digitaltwins.core.QueryResult对象。
• 将component_path重命名为component_name
• 将payload参数重命名为telemetry，并将message_id改为关键字参数。

错误修复

• 在DigitalTwinsClient.upsert_relationship中的relationship参数是必需的，并已相应修改。
• 在DigitalTwinsClient.update_relationship中的json_patch参数是必需的，并已相应修改。
• 在DigitalTwinsClient.create_models中将models参数重命名为dtdl_models，现在是必需的。
• 在DigitalTwinsClient.list_models中的dependencies_for参数是可选的，并已相应修改。
• 修复了匹配条件参数。如果提供无效的匹配条件，将引发ValueError。
• 修复了异步列表操作的重复await。

文档

• 根据指南更新了用户代理值。
• 更新了JSON补丁参数类型提示为List[Dict[str, object]]。
• 更新了构造函数凭据类型提示为azure.core.credentials.TokenCredential。
• 更新了示例和文档。

1.0.0b1 (2020-10-31)

• 初始发布