您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

Azure 数字孪生 API 和 SDK

Azure 数字孪生配备有“控制平面 API”和“数据平面 API”,用于管理实例及其元素 。

  • 控制平面 API 是 Azure 资源管理器 (ARM) API,涵盖创建实例和删除实例等资源管理操作。
  • 数据平面 API 是 Azure 数字孪生 API,用于管理模型、孪生体和图形等数据管理操作。

本文将概述可用的 API 以及与它们进行交互的方法。 可通过 Postman 等工具或通过 SDK 直接将 REST API 与其关联的 Swagger 配合使用。

概述:控制平面 API

控制平面 API 是用于将 Azure 数字孪生实例作为一个整体进行管理的 ARM API,因此它们涵盖了创建实例或删除实例等操作。 你还将使用这些 API 来创建和删除终结点。

最新的控制平面 API 版本为 2020-12-01。

若要使用控制平面 API:

还可通过 Azure 门户CLI 与 Azure 数字孪生交互,运用控制平面 API。

概述:数据平面 API

数据平面 API 是用于管理 Azure 数字孪生实例中的元素的 Azure 数字孪生 API。 这包括创建路由、上传模型、创建关系和管理孪生等操作,并且可大体上可以划分为以下类别:

  • DigitalTwinModels - DigitalTwinModels 类别包含用于管理 Azure 数字孪生实例中的 模型的 API。 管理活动包括上传、验证、检索和删除在 DTDL 中创作的模型。
  • DigitalTwins - DigitalTwins 类别包含让开发人员能够在 Azure 数字孪生实例中创建、修改和删除 数字孪生体及其关系的 API。
  • 查询 - 查询类别让开发人员能够跨关系 查找孪生图中的数字孪生体集
  • 事件路由 - 事件路由类别包含通过系统向下游服务 路由数据的 API。

最新的数据平面 API 版本为 2020-10-31。

若要使用数据平面 API:

还可通过 CLI 与 Azure 数字孪生交互,运用数据平面 API。

.NET (C#) SDK(数据平面)

Azure 数字孪生 .NET (C#) SDK 是用于 .NET 的 Azure SDK 的一部分。 它是开源 SDK,基于 Azure 数字孪生数据平面 API。

备注

有关 SDK 设计的详细信息,请参阅常规的 Azure SDK 设计原则和具体的 .NET 设计准则

若要使用 SDK,请在项目中包括 NuGet 包 Azure.DigitalTwins.Core。 还需要最新版本的 Azure.Identity 包。 在 Visual Studio 中,可使用 NuGet 包管理器添加这些包(通过“工具”>“NuGet 管理器”>“管理解决方案的 NuGet 包”进行访问)。 可在 .NET 命令行工具中使用下方 NuGet 包链接中找到的命令,将这些包添加到项目中:

有关如何在实践中使用 API 的详细演练步骤,请参阅便可客户端应用程序代码

序列化帮助程序

序列化帮助程序是可在 SDK 内使用的帮助程序函数,用于快速创建或反序列化孪生数据以访问基本信息。 由于核心 SDK 方法默认以 JSON 形式返回孪生数据,因此,使用这些帮助程序类有助于进一步细分孪生数据。

可用的帮助程序类包括:

  • BasicDigitalTwin:一般表示数字孪生体的核心数据
  • BasicDigitalTwinComponent:一般表示 BasicDigitalTwinContents 属性中的一个组件
  • BasicRelationship:一般表示关系的核心数据
  • DigitalTwinsJsonPropertyName:包含在自定义数字孪生类型的 JSON 序列化和反序列化中使用的字符串常数

常规 API/SDK 使用说明

备注

请注意,Azure 数字孪生目前不支持跨域资源共享 (CORS)。 有关影响和解决策略的详细信息,请参阅《概念:Azure 数字孪生解决方案的安全性》一文的 跨源资源共享 (CORS)部分。

以下列表提供了有关使用 API 和 SDK 的更多详细信息和一般准则。

  • 可使用 HTTP REST 测试工具(如 Postman)直接对 Azure 数字孪生 API 进行调用。 有关此过程的详细信息,请参阅通过 Postman 发出 API 请求
  • 若要使用 SDK,请实例化 DigitalTwinsClient 类。 构造函数需要凭据,可使用不同类型的身份验证方法在 Azure.Identity 包中获得。 有关 Azure.Identity 的详细信息,请参阅其命名空间文档
  • 你可能会发现 InteractiveBrowserCredential 在入门时非常有用,但还有其他几个选项,包括托管标识的凭据,你可使用此类凭据针对 Azure 数字孪生对使用 MSI 设置的 Azure 函数进行身份验证。 有关 InteractiveBrowserCredential 的详细信息,请参阅其类文档
  • 请求 Azure 数字孪生 API 的用户或者服务主体需要属于 Azure 数字孪生实例所在的相同 Azure Active Directory (Azure AD) 租户。 为了防止对 Azure 数字孪生终结点进行恶意扫描,将针对使用发起租户外部的访问令牌进行的请求返回“404 找不到子域”错误消息。 即使已通过 Azure AD B2B 协作向用户或服务主体授予 Azure 数字孪生数据所有者或 Azure 数字孪生数据读取者角色,也会返回此错误。 有关如何在多个租户之间实现访问的信息,请参阅编写应用身份验证代码
  • 所有服务 API 调用都公开为 DigitalTwinsClient 类的成员函数。
  • 所有服务函数都存在于同步和异步版本中。
  • 如果返回状态为 400 或更高,所有服务函数均会引发异常。 请确保将调用包装到 try 部分,并至少捕获 RequestFailedExceptions。 有关此类异常的详细信息,请参阅其参考文档
  • 大多数服务方法会返回 Response<T>Task<Response<T>>(针对异步调用),其中 T 是服务调用的返回对象的类。 Response 类封装服务返回并在其 Value 字段中显示返回值。
  • 包含分页结果的服务方法返回 Pageable<T>AsyncPageable<T> 作为结果。 有关 Pageable<T> 类的详细信息,请参阅其参考文档;有关 AsyncPageable<T> 的详细信息,请参阅其参考文档
  • 可使用 await foreach 循环来循环访问分页结果。 有关此过程的详细信息,请参阅相关文档
  • 基础 SDK 为 Azure.Core。 请参阅 Azure 命名空间文档,了解 SDK 基础结构和类型。

服务方法尽可能返回强类型对象。 但由于 Azure 数字孪生是基于用户在运行时自定义配置的模型(通过上传到服务的 DTDL 模型),所以许多服务 API 采用并返回 JSON 格式的孪生数据。

监视 API 指标

可在 Azure 门户中查看请求、延迟和失败率等 API 指标。

在门户主页上,搜索 Azure 数字孪生实例以获取其详细信息。 在 Azure 数字孪生实例的菜单中选择“指标”选项以打开指标”页。

此屏幕截图显示了 Azure 数字孪生的“指标”页。

在此处,你可查看实例的指标并创建自定义视图。

后续步骤

请参阅如何使用 Postman 直接请求 API:

或使用本教程创建客户端应用,练习使用 .NET SDK: