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

教程：使用示例客户端应用创建 Azure 数字孪生图

项目
01/03/2024

在本教程中，你将使用模型、孪生和关系在 Azure 数字孪生中生成一个图。本教程的工具是用于与 Azure 数字孪生实例交互的示例命令行客户端应用程序。该客户端应用类似于为客户端应用编写代码中编写的应用。

可以使用此示例执行基本的 Azure 数字孪生操作，例如上传模型、创建和修改孪生以及创建关系。还可查看示例的代码来了解 Azure 数字孪生 API，并按你想要的方式修改示例项目来练习实现你自己的命令。

在本教程中，你将...

为环境建模
创建数字孪生
添加关系以构成图
查询该图以回答问题

必备条件

开始本教程之前，请先满足以下先决条件：

如果没有 Azure 订阅，请在开始之前创建一个免费帐户。
本教程使用 .NET。可以从下载 .NET 下载适用于多个平台的最新版 .NET SDK。

然后继续完成本部分其余内容，设置剩余的先决条件。

获取示例资源

本教程是在使用 C# 编写的 Azure 数字孪生端到端示例项目推动下编写的。导航到示例链接，然后选择标题下方的“浏览代码”按钮，在你的计算机上获取示例项目。

此时会转到这些示例的 GitHub 存储库，你可以通过选择“代码”按钮然后再选择“下载 ZIP”将其下载为 .zip。

这会将 .zip 文件夹以 digital-twins-samples-main.zip 形式下载到计算机上。解压缩文件夹并提取文件。

准备 Azure 数字孪生实例

若要在本文中使用 Azure 数字孪生，你需要有一个 Azure 数字孪生实例，还需具备使用它所必需的权限。如果你已设置了一个 Azure 数字孪生实例，则可以使用该实例并跳到下一部分。如果没有，请按照设置实例和身份验证中的说明操作。该说明中包含可帮助你验证是否已成功完成每个步骤的信息。

设置实例后，记下实例的主机名。可以在 Azure 门户中找到该主机名。

配置示例项目

接下来，设置将与 Azure 数字孪生实例交互的示例客户端应用程序。

在计算机上，导航到先前从 Azure 数字孪生端到端示例下载的文件夹（如果尚未解压缩，则将其解压缩）。

在该文件夹中，导航到“digital-twins-samples-main\AdtSampleApp\SampleClientApp”并打开“appsettings.json”文件。此 JSON 文件包含运行项目所需的配置变量。

在文件正文中，将 instanceUrl 更改为 Azure 数字孪生实例主机名 URL（通过在主机名前面添加 https://，如下所示）。

{
  "instanceUrl": "https://<your-Azure-Digital-Twins-instance-host-name>"
}

保存并关闭该文件。

设置本地 Azure 凭据

当你在本地计算机上运行示例时，此示例使用 DefaultAzureCredential（属于 Azure.Identity 库的一部分）对用户进行 Azure 数字孪生实例验证。若要详细了解客户端应用可向 Azure 数字孪生进行身份验证的不同方法，请参阅编写应用身份验证代码。

使用 DefaultAzureCredential，此示例将在本地环境中搜索凭据，如本地 DefaultAzureCredential 或 Visual Studio/Visual Studio Code 中的 Azure 登录。因此，应该通过这些机制在本地登录 Azure，以便设置示例的凭据。

如果使用 Visual Studio 或 Visual Studio Code 运行代码示例，请确保使用要用于访问 Azure 数字孪生实例的相同 Azure 凭据登录到该编辑器。如果使用本地 CLI 窗口，请运行 az login 命令来登录到你的 Azure 帐户。此后，当你运行代码示例时，应当会自动对你进行身份验证。

运行示例项目

设置应用和身份验证后，打开用于运行项目的本地控制台窗口。在控制台中导航到“digital-twins-samples-main\AdtSampleApp\SampleClientApp”文件夹，并使用以下 dotnet 命令运行项目：

dotnet run

项目将开始运行，执行身份验证，然后等待命令。

下面是项目控制台外观的屏幕截图：

提示

有关在此项目中可以使用的所有可能命令的列表，请在项目控制台中输入 help，然后按回车键。

确认应用成功运行后，可以停止运行项目。稍后你将在本教程中再次运行它。

使用 DTDL 为物理环境建模

设置 Azure 数字孪生实例和示例应用后，接下来可以开始生成方案图。

创建 Azure 数字孪生解决方案的第一步是为环境定义孪生模型。

模型类似于面向对象的编程语言中的类；它们是用户定义的模板，可将其实例化以创建数字孪生。 Azure 数字孪生的模型采用类似于 JSON 的语言（称为 数字孪生定义语言（DTDL）编写，它们根据孪生体的属性、关系和组件定义一种类型的孪生体。

注意

DTDL 还允许在数字孪生上定义命令。但是，Azure 数字孪生服务当前不支持命令。

在先前下载的示例项目文件夹中，导航到“digital-twins-samples-main\AdtSampleApp\SampleClientApp\Models”文件夹。此文件夹包含示例模型。

打开“Room.json”进行编辑，并对代码进行以下更改：

更新版本号，以指出正在提供此模型的更新版本。为此，请将 @id 末尾的 1 更改为 2 。大于当前版本号的任何数字也有效。
编辑属性。将 Humidity 属性的名称更改为 HumidityLevel（或你想要的其他名称。如果使用的名称不是 HumidityLevel，请记住你使用的名称并在整个教程中继续使用该名称，而不是 HumidityLevel）。
添加属性。在结束于第 15 行的 HumidityLevel 属性下方，粘贴以下代码以将 RoomName 属性添加到 room 中：
```
,{
  "@type": "Property",
  "name": "RoomName",
  "schema": "string"
}
```
添加关系。在刚刚添加的 RoomName 属性下方，粘贴以下代码，使此类孪生体能够与其他孪生体形成 contains 关系：
```
,{
  "@type": "Relationship",
  "name": "contains"
}
```

完成后，更新后的模型应如下所示：

{
    "@id": "dtmi:example:Room;2",
    "@type": "Interface",
    "displayName": "Room",
    "contents": [
      {
        "@type": "Property",
        "name": "Temperature",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "HumidityLevel",
        "schema": "double"
      }
      ,{
        "@type": "Property",
        "name": "RoomName",
        "schema": "string"
      }
      ,{
        "@type": "Relationship",
        "name": "contains"
      }
    ],
    "@context": "dtmi:dtdl:context;3"
  }

在继续操作之前，请务必保存该文件。

将模型上传到 Azure 数字孪生

设计模型后，需要将其上传到 Azure 数字孪生实例。这将使用你自己的自定义领域词汇来配置 Azure 数字孪生服务实例。上传模型后，可以创建使用这些模型的孪生实例。

返回到打开了“digital-twins-samples-main\AdtSampleApp\SampleClientApp”文件夹的控制台窗口，然后使用 dotnet run 再次运行控制台应用。
在项目控制台窗口中，运行以下命令以上传更新后的 Room 模型和 Floor 模型，你将在下一节中使用这些模型创建不同类型的孪生。
```
CreateModels Room Floor
```
输出应指示模型已成功创建。
通过运行命令 GetModels true 来验证模型是否已创建。此命令将输出已上传到 Azure 数字孪生实例的所有模型的完整信息。在结果中寻找经过编辑的 Room 模型：

将控制台应用保持运行状态以便完成后续步骤。

错误

该示例应用程序还处理服务中的错误。

若要对此进行测试，请重新运行 CreateModels 命令，以尝试重新上传已经上传的 Room 模型：

CreateModels Room

由于无法改写模型，此命令现在将返回服务错误，指示你尝试创建的某些模型 ID 已经存在。

有关如何删除现有模型的详细信息，请参阅管理 DTDL 模型。

创建数字孪生

现在，一些模型已上传到 Azure 数字孪生实例，你可以根据模型定义创建数字孪生。数字孪生表示业务环境中的实体，这类似于农场中的传感器、大楼中的房间或汽车上的灯。

要创建数字孪生，请使用 CreateDigitalTwin 命令。必须引用孪生所基于的模型，并且可以选择定义模型中任何属性的初始值。在此阶段，无需传递任何关系信息。

在先前更新的 Room 模型和另一个 Floor 模型的基础上，在正在运行的项目控制台中运行此代码，以创建多个孪生模型。回想一下，Room 具有三个属性，因此可以为这些属性提供具有初始值的参数。（初始化属性值在一般情况下是可选操作，但本教程需要此操作。）
```
CreateDigitalTwin dtmi:example:Room;2 room0 RoomName string Room0 Temperature double 70 HumidityLevel double 30
CreateDigitalTwin dtmi:example:Room;2 room1 RoomName string Room1 Temperature double 80 HumidityLevel double 60
CreateDigitalTwin dtmi:example:Floor;1 floor0
CreateDigitalTwin dtmi:example:Floor;1 floor1
```
这些命令的输出应指示孪生已成功创建。
可以运行 Query 命令来验证是否已创建孪生。此命令在 Azure 数字孪生实例中查询其包含的所有数字孪生。在结果中查找 room0、room1、floor0 和 floor1 孪生。

注意

对图表中的数据进行更改后，可能会有长达 10 秒的延迟才会在查询中反映更改。

DigitalTwins API 会立即反映更改，因此如果需要即时响应，请使用 API 请求 (DigitalTwins GetById) 或 SDK 调用 (GetDigitalTwin) 获取孪生数据，而不是查询。

修改数字孪生

你可以修改已创建的孪生的属性。

注意

底层 REST API 使用 JSON 补丁格式定义对孪生的更新。该命令行应用也使用此格式，以便用户更真实地体验底层 API 所需的内容。

运行以下命令，将 room0 的 RoomName 从“Room0”更改为“PresidentialSuite”：
```
UpdateDigitalTwin room0 add /RoomName string PresidentialSuite
```
输出应指示模型已成功更新。
可通过运行以下命令查看 room0 的信息，来验证更新是否成功：
```
GetDigitalTwin room0
```
输出应反映更新后的名称。

通过添加关系来创建关系图

接下来，你可以在这些孪生体之间建立一些关系，将它们连接到孪生图。孪生图用于表示整个环境。

可由你在两个不同孪生之间创建的关系的类型，是在前面上传的模型中定义的。 Floor 的模型定义指定了楼层可以有一个名为 contains 的关系类型，因此可以创建从每个 Floor 孪生体到它所包含的相应房间的 contains 类型的关系。

要添加关系，请使用 CreateRelationship 命令。指定该关系的来源孪生、关系类型，以及该关系要连接到的孪生。最后，为该关系指定唯一的 ID。

运行以下命令，将来自之前创建的每个 Floor 孪生的 contains 关系添加到对应的 Room 孪生。关系的名称分别为 relationship0 和 relationship1。
```
CreateRelationship floor0 contains room0 relationship0
CreateRelationship floor1 contains room1 relationship1
```
提示

在 Floor 模型中定义的 contains 关系也有两个字符串属性：ownershipUser 和 ownershipDepartment，因此，在创建关系时，也可以为参数提供这些属性的初始值。下面是上述命令的另一个版本，该版本将创建 relationship0，其中也会指定这些属性的初始值：
```
CreateRelationship floor0 contains room0 relationship0 ownershipUser string MyUser ownershipDepartment string myDepartment
```
这些命令的输出确认关系已成功创建：
可以使用以下任一命令来验证关系，这些命令将输出 Azure 数字孪生实例中的关系。
- 若要查看源自每个楼层的所有关系（从一端查看关系）：
```
GetRelationships floor0
GetRelationships floor1
```
- 若要查看到达每个房间的所有关系（从“另一”端查看关系）：
```
GetIncomingRelationships room0
GetIncomingRelationships room1
```
- 若要按 ID 单独查找这些关系：
```
GetRelationship floor0 relationship0
GetRelationship floor1 relationship1
```

本教程中设置的孪生和关系形成以下概念图：

查询孪生图以回答环境问题

Azure 数字孪生的主要功能是能够轻松有效地查询孪生图，以解答有关环境的问题。

注意

对图表中的数据进行更改后，可能会有长达 10 秒的延迟才会在查询中反映更改。

DigitalTwins API 会立即反映更改，因此如果需要即时响应，请使用 API 请求 (DigitalTwins GetById) 或 SDK 调用 (GetDigitalTwin) 获取孪生数据，而不是查询。

在正在运行的项目控制台中运行以下命令，回答有关示例环境的一些问题。

在我的环境中，用 Azure 数字孪生表示的所有实体都有哪些？（查询所有）
```
Query
```
使用此命令可以一目了然地评估环境，确保在 Azure 数字孪生中以你希望的方式表示所有内容。此命令的输出结果包含每个数字孪生及其详细信息。下面是结果摘录：

提示

在示例项目中，不带任何附加参数的命令 Query 相当于 Query SELECT * FROM DIGITALTWINS。若要使用查询 API 或 CLI 命令查询实例中的所有孪生体，请使用较长的（完整）查询。
我的环境中的所有房间都有哪些？（按模型查询）
```
Query SELECT * FROM DIGITALTWINS T WHERE IS_OF_MODEL(T, 'dtmi:example:Room;2')
```
可以将查询限制为某种类型的孪生，以获取有关所表示内容的更多具体信息。此查询的结果显示 room0 和 room1，但不显示 floor0 或 floor1（因为它们是楼层，而不是房间）。
floor0 上的所有房间都有哪些？（按关系查询）
```
Query SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.$dtId = 'floor0'
```
可以根据图形中的关系进行查询，以获取有关如何连接孪生或如何将查询限制在特定区域的信息。 floor0 上只有 room0，因此它是结果中唯一的房间。
环境中温度高于 75 的所有孪生都有哪些？（按属性查询）
```
Query SELECT * FROM DigitalTwins T WHERE T.Temperature > 75
```
可以根据属性查询图形，以回答各种问题，包括在环境中查找可能需要注意的离群值。还支持其他比较运算符（<、>、= 或 !=）。 room1 出现在此处的结果中，因为它的温度为 80。
floor0 上温度高于 75 的所有房间都有哪些？（复合查询）
```
Query SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.$dtId = 'floor0' AND IS_OF_MODEL(room, 'dtmi:example:Room;2') AND room.Temperature > 75
```
还可以像在 SQL 一样使用组合运算符（例如 AND、OR 和 NOT）合并之前的查询。此查询使用 AND 使先前有关孪生温度的查询更具体。现在，结果仅包括 floor0 上温度高于 75 的房间。在本例中，这些房间均不满足条件。结果集为空。

现已针对设置的方案运行多个查询，本教程到此完成。停止运行项目并关闭控制台窗口。

清理资源

完成本教程后，可以选择要删除的资源，具体取决于接下来要执行的操作。

如果打算继续学习下一个教程，可保留在此处设置的资源，以便继续在下一个教程中使用此 Azure 数字孪生实例和已配置的示例应用
若要继续使用 Azure 数字孪生实例，但想要清除其所有模型、孪生体和关系，可使用示例应用的 DeleteAllTwins 和 DeleteAllModels 命令分别清除实例中的孪生体和模型。

如果不再需要在本教程中创建的任何资源，可使用 az group delete CLI 命令删除本文中的 Azure 数字孪生实例及其他所有资源。这会删除资源组中的所有 Azure 资源及资源组本身。

重要

删除资源组的操作不可逆。资源组以及包含在其中的所有资源将被永久删除。请确保不要意外删除错误的资源组或资源。

打开 Azure Cloud Shell 或本地 CLI 窗口并运行以下命令，以删除资源组及其包含的所有内容。
```
az group delete --name <your-resource-group>
```

你可能还需要从本地计算机中删除下载的项目文件夹。

后续步骤

在本教程中，你已通过示例客户端应用程序在实例中生成一个图，开始使用了 Azure 数字孪生。你创建了模型、数字孪生和关系以构成图。你还对该图运行了一些查询，以大致了解 Azure 数字孪生可以解答的与环境有关的问题。

请继续学习下一篇教程，将 Azure 数字孪生与其他 Azure 服务结合使用来实现数据驱动的端到端方案：

连接端到端解决方案