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

Azure 数字孪生 API 和 SDK

  • 项目

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

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

  • 控制平面 API 是 Azure 资源管理器 (ARM) API，涵盖创建实例和删除实例等资源管理操作。
  • 数据平面 API 是 Azure 数字孪生 API，用于管理模型、孪生体和图形等数据管理操作。
  • SDK 利用了现有 API，以便于轻松开发使用 Azure 数字孪生的自定义应用程序。

控制平面 API

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

要直接调用 API，可引用控制平面 Swagger 存储库中最新的 Swagger 文件夹。 此文件夹还包括一个示例文件夹，其中显示了用法。

下面是当前可用于 Azure 数字孪生控制平面 API 的 SDK。

SDK 语言 包链接 参考文档 源代码
.NET (C#) NuGet 上的 Azure.ResourceManager.DigitalTwins 适用于 .NET 的 Azure DigitalTwins SDK 参考 GitHub 上适用于 .NET 的 Microsoft Azure 数字孪生管理客户端库
Java Maven 上的 azure-resourcemanager-digitaltwins 资源管理参考 - 数字孪生 GitHub 上适用于 Java 的 Azure 资源管理器 AzureDigitalTwins 客户端库
JavaScript npm 上适用于 JavaScript 的 AzureDigitalTwinsManagement 客户端库 GitHub 上适用于 JavaScript 的 AzureDigitalTwinsManagement 客户端库
Python PyPI 上的 azure-mgmt-digitaltwins GitHub 上适用于 Python 的 Microsoft Azure SDK
Go azure-sdk-for-go/services/digitaltwins/mgmt GitHub 上适用于 Go 的 Azure SDK

还可以通过 Azure 门户 和 CLI 与 Azure 数字孪生交互来练习控制平面 API。

数据平面 API

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

  • DigitalTwinModels - DigitalTwinModels 类别包含用于管理 Azure 数字孪生实例中的模型的 API。 管理活动包括上传、验证、检索和删除在 DTDL 中创作的模型。
  • DigitalTwins - DigitalTwins 类别包含让开发人员能够在 Azure 数字孪生实例中创建、修改和删除数字孪生体及其关系的 API。
  • Query - 查询类别让开发人员能够跨关系查找孪生图中的数字孪生体集。
  • Event Routes - 事件路由类别包含通过系统向下游服务路由数据的 API。
  • Import Jobs - 通过导入作业 API，可以管理长时间运行的异步操作，以 批量导入模型、孪生体和关系。
  • Delete Jobs - 删除作业 API 允许管理长时间运行的异步操作，以 删除实例中的所有模型、孪生体和关系。

要直接调用 API，可引用数据平面 Swagger 存储库中最新的 Swagger 文件夹。 此文件夹还包括一个示例文件夹，其中显示了用法。 还可以查看数据平面 API 参考文档。

下面是当前可用于 Azure 数字孪生数据平面 API 的 SDK。

SDK 语言 包链接 参考文档 源代码
.NET (C#) NuGet 上的 Azure.DigitalTwins.Core 适用于 .NET 的 Azure IoT 数字孪生客户端库参考 GitHub 上适用于 .NET 的 Azure IoT 数字孪生客户端库
Java Maven 上的 com.azure:azure-digitaltwins-core 适用于 Java 的 Azure 数字孪生 SDK 参考 GitHub 上适用于 Java 的 Azure IoT 数字孪生客户端库
JavaScript npm 上适用于 JavaScript 的 Azure 数字孪生核心客户端库 Reference for @azure/digital-twins-core GitHub 上适用于 JavaScript 的 Azure 数字孪生核心客户端库
Python PyPI 上适用于 Python 的 Azure 数字孪生核心客户端库 azure-digitaltwins-core 参考 GitHub 上适用于 Python 的 Azure 数字孪生核心客户端库

还可以通过 CLI 与 Azure 数字孪生交互来练习数据平面 API。

使用情况和身份验证说明

本部分包含有关使用 API 和 SDK 的更多详细信息。

API 说明

下面是用于直接调用 Azure 数字孪生 API 的一些常规信息。

下面是有关 API 请求身份验证的一些详细信息。

  • 为 Azure 数字孪生 API 请求生成持有者令牌的一种方法是使用 az account get-access-token CLI 命令。 有关详细说明，请参阅 获取持有者令牌。
  • 向 Azure 数字孪生 API 发出的请求需要用户或服务主体，该主体是 Azure 数字孪生实例所在的同 一 Microsoft Entra ID 租户的一部分。 为防止恶意扫描 Azure 数字孪生终结点，对于来自源租户外部的具有访问令牌的请求，会返回“404 子域未找到”错误消息。 即使用户或服务主体通过 Microsoft Entra B2B 协作获得了 Azure 数字孪生数据所有者或 Azure 数字孪生数据读取者角色，也会返回此错误。 有关如何在多个租户之间实现访问的信息，请参阅编写应用身份验证代码。

SDK 说明

Azure 数字孪生的基础 SDK 是 Azure.Core。 请参阅 Azure 命名空间文档，了解 SDK 基础结构和类型。

下面是有关使用 SDK 进行身份验证的一些详细信息。

  • 首先实例化 DigitalTwinsClient 类。 构造函数需要凭据，可使用不同类型的身份验证方法在 Azure.Identity 包中获得。 有关 Azure.Identity 的详细信息，请参阅其命名空间文档。
  • 你可能会发现 InteractiveBrowserCredential 在入门时非常有用，但还有其他几个选项，包括托管标识的凭据，你可使用此类凭据针对 Azure 数字孪生对使用 MSI 设置的 Azure 函数进行身份验证。 有关 InteractiveBrowserCredential 的详细信息，请参阅其类文档。

下面是有关函数和返回数据的一些详细信息。

  • 所有服务 API 调用都公开为 DigitalTwinsClient 类的成员函数。
  • 所有服务函数都存在于同步和异步版本中。
  • 如果返回状态为 400 或更高，所有服务函数均会引发异常。 请确保将调用包装到 try 部分，并至少捕获 RequestFailedExceptions。 有关此类异常的详细信息，请参阅其参考文档。
  • 大多数服务方法会返回 Response<T> 或 Task<Response<T>>（针对异步调用），其中 T 是服务调用的返回对象的类。 Response 类封装服务返回并在其 Value 字段中显示返回值。
  • 包含分页结果的服务方法返回 Pageable<T> 或 AsyncPageable<T> 作为结果。 有关 Pageable<T> 类的详细信息，请参阅其参考文档；有关 AsyncPageable<T> 的详细信息，请参阅其参考文档。
  • 可使用 await foreach 循环来循环访问分页结果。 有关此过程的详细信息，请参阅在 C# 8 中利用异步枚举进行循环访问。
  • 服务方法尽可能返回强类型对象。 但由于 Azure 数字孪生是基于用户在运行时自定义配置的模型（通过上传到服务的 DTDL 模型），所以许多服务 API 采用并返回 JSON 格式的孪生数据。

.NET (C#) SDK 中的序列化帮助程序

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

可用的帮助程序类包括：

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

使用导入作业 API 批量导入

导入作业 API 是一个数据平面 API，可用于在单个 API 调用中导入一组模型、孪生体和/或关系。 CLI 命令和数据平面 SDK 中还包括导入作业 API 操作。 使用导入作业 API 需要使用Azure Blob 存储。

检查权限

若要使用导入作业 API，需要启用本节中所述的权限设置。

首先，需要为 Azure 数字孪生实例提供 系统分配的托管标识 。 有关为实例设置系统托管标识的说明，请参阅 实例的“启用/禁用托管标识”。

对于以下数据操作类别，需要在 Azure 数字孪生实例中具有 写入权限 ：

  • Microsoft.DigitalTwins/jobs/*
  • 要在“作业”调用中包含的任何图形元素。 这可能包括 Microsoft.DigitalTwins/models/*、 Microsoft.DigitalTwins/digitaltwins/*和/或 Microsoft.DigitalTwins/digitaltwins/relationships/*。

提供所有这些权限的内置角色是 Azure 数字孪生数据所有者。 还可以使用自定义角色仅授予对所需数据类型的精细访问权限。 有关 Azure 数字孪生中的角色的详细信息，请参阅 Azure 数字孪生解决方案的安全性。

注意

如果尝试导入作业 API 调用，并且缺少尝试导入的某个图形元素类型的写入权限，作业将跳过该类型并导入其他元素类型。 例如，如果对模型和孪生具有写入访问权限，但不能访问关系，则尝试批量导入所有三种类型的元素只会成功导入模型和孪生体。 作业状态将反映失败，消息将指示缺少哪些权限。

还需要向 Azure 数字孪生实例的系统分配的托管标识授予以下 RBAC 权限，以便它可以访问Azure Blob 存储容器中的输入和输出文件：

最后，生成可在对作业 API 的请求中使用的持有者令牌。 有关说明，请参阅 获取持有者令牌。

设置数据格式

API 接受来自 NDJSON 文件的图形信息输入，该文件必须上传到 Azure Blob 存储 容器。 该文件以节 Header 开头，后跟可选节 Models， Twins以及 Relationships。 无需在文件中包括所有三种类型的图形数据，但存在的任何部分都必须遵循该顺序。 使用此 API 创建的孪生体和关系可以选择包括其属性的初始化。

下面是导入 API 的示例输入数据文件：

{"Section": "Header"}
{"fileVersion": "1.0.0", "author": "foobar", "organization": "contoso"}
{"Section": "Models"}
{"@id":"dtmi:com:microsoft:azure:iot:model0;1","@type":"Interface","contents":[{"@type":"Property","name":"property00","schema":"integer"},{"@type":"Property","name":"property01","schema":{"@type":"Map","mapKey":{"name":"subPropertyName","schema":"string"},"mapValue":{"name":"subPropertyValue","schema":"string"}}},{"@type":"Relationship","name":"has","target":"dtmi:com:microsoft:azure:iot:model1;1","properties":[{"@type":"Property","name":"relationshipproperty1","schema":"string"},{"@type":"Property","name":"relationshipproperty2","schema":"integer"}]}],"description":{"en":"This is the description of model"},"displayName":{"en":"This is the display name"},"@context":"dtmi:dtdl:context;2"}
{"@id":"dtmi:com:microsoft:azure:iot:model1;1","@type":"Interface","contents":[{"@type":"Property","name":"property10","schema":"string"},{"@type":"Property","name":"property11","schema":{"@type":"Map","mapKey":{"name":"subPropertyName","schema":"string"},"mapValue":{"name":"subPropertyValue","schema":"string"}}}],"description":{"en":"This is the description of model"},"displayName":{"en":"This is the display name"},"@context":"dtmi:dtdl:context;2"}
{"Section": "Twins"}
{"$dtId":"twin0","$metadata":{"$model":"dtmi:com:microsoft:azure:iot:model0;1"},"property00":10,"property01":{"subProperty1":"subProperty1Value","subProperty2":"subProperty2Value"}}
{"$dtId":"twin1","$metadata":{"$model":"dtmi:com:microsoft:azure:iot:model1;1"},"property10":"propertyValue1","property11":{"subProperty1":"subProperty1Value","subProperty2":"subProperty2Value"}}
{"Section": "Relationships"}
{"$dtId":"twin0","$relationshipId":"relationship","$targetId":"twin1","$relationshipName":"has","relationshipProperty1":"propertyValue1","relationshipProperty2":10}

提示

有关将模型、孪生体和关系转换为导入 API 支持的 NDJSON 的示例项目，请参阅 Azure 数字孪生批量导入 NDJSON 生成器。 示例项目是针对 .NET 编写的，可以下载或改编，以帮助你创建自己的导入文件。

创建文件后，使用首选上传方法将其上传到Azure Blob 存储中的块 blob（某些选项是 AzCopy 命令、Azure CLI 或 Azure 门户）。 你将在导入作业 API 调用的正文中使用 NDJSON 文件的 Blob 存储 URL。

运行导入作业

现在，可以继续调用 导入作业 API。 有关在一个 API 调用中导入完整图形的详细说明，请参阅 使用导入作业 API 批量上传模型、孪生体和关系。 还可以使用导入作业 API 独立导入每个资源类型。 有关将导入作业 API 与单个资源类型配合使用的详细信息，请参阅模型、孪生体和关系的导入作业 API 说明。

在 API 调用的正文中，将提供 NDJSON 输入文件的 Blob 存储 URL。 你还将提供一个新的 Blob 存储 URL，用于指示在服务创建输出日志后要存储的输出日志的位置。

重要

确保 Azure 数字孪生实例的系统分配托管标识具有“检查权限”部分中所述的存储 Blob RBAC 权限。

执行导入作业时，服务会生成结构化输出日志，并将其存储为 Blob 容器中的新追加 Blob，该 URL 位置是在请求中为输出 Blob 指定的 URL 位置。 下面是成功导入模型、孪生和关系的作业的示例输出日志：

{"timestamp":"2022-12-30T19:50:34.5540455Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"status":"Started"}}
{"timestamp":"2022-12-30T19:50:37.2406748Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Models","status":"Started"}}
{"timestamp":"2022-12-30T19:50:38.1445612Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Models","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:38.5475921Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Twins","status":"Started"}}
{"timestamp":"2022-12-30T19:50:39.2744802Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Twins","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:39.7494663Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Relationships","status":"Started"}}
{"timestamp":"2022-12-30T19:50:40.4480645Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Relationships","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:41.3043264Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"status":"Succeeded"}}

作业完成后，可以使用 BulkOperationEntityCount 指标查看引入的实体总数。

还可以使用 “导入作业 API”中的“取消”操作 取消正在运行的导入作业。 作业取消且不再运行后，可以将其删除。

限制和注意事项

使用导入作业 API 时，请记住以下注意事项：

使用删除作业 API 批量删除

删除作业 API 是一个数据平面 API，可用于使用单个 API 调用删除实例中的所有模型、孪生体和关系。 删除作业 API 操作也可用作 CLI 命令。 请访问 API 文档，查看创建删除作业的请求详细信息，并检查其状态。

若要确保删除所有元素，请在使用“删除作业 API”时遵循这些建议：

  • 有关如何生成持有者令牌以对 API 请求进行身份验证的说明，请参阅 获取持有者令牌。
  • 如果最近将大量实体导入到图形中，请等待一段时间，并验证图形中的所有元素是否已同步，然后再开始删除作业。
  • 停止实例上的所有操作，尤其是上传操作，直到删除作业完成。

根据要删除的图形的大小，删除作业可能需要几分钟到多个小时。

删除作业的默认超时期限为 12 小时，可以使用 API 上的查询参数调整为 15 分钟到 24 小时之间的任意值。 这是删除作业在超时之前运行的时间量，此时，如果尚未完成，服务将尝试停止作业。

限制和其他注意事项

使用删除作业 API 时，请记住以下注意事项：

  • 删除作业不是原子操作。 如果作业失败、部分作业完成或超时，则不会回滚。
  • Azure 数字孪生实例中一次仅支持一个批量作业。 可以在 Azure 数字孪生限制中 查看作业 API 的此信息和其他数字限制。

监视 API 指标

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

有关查看和管理 Azure 数字孪生指标的信息，请参阅 “监视实例”。 有关可用于 Azure 数字孪生的 API 指标的完整列表，请参阅 Azure 数字孪生 API 请求指标。

后续步骤

了解如何使用 Postman 向 Azure 数字孪生 API 发出直接请求：

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