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

教程：使用 Azure CLI 创建 Azure 数字孪生图

  • 项目

在本教程中，你将使用模型、孪生和关系在 Azure 数字孪生中生成一个图。 本教程使用的工具是适用于 Azure CLI 的 Azure 数字孪生命令集。

可以使用 CLI 命令执行基本的 Azure 数字孪生操作，例如上传模型、创建和修改孪生，以及创建关系。 还可查看 az dt 命令集的参考文档，查看完整的 CLI 命令集。

在本教程中，你将...

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

必备条件

若要完成本教程中的步骤，需要先具备以下先决条件。

如果没有 Azure 订阅，请在开始之前创建一个免费帐户。

下载示例模型

本教程使用两个预先编写的模型，这些模型是适用于 Azure 数字孪生的 C# 端到端示例项目的一部分。 模型文件位于以下位置：

若要将这些文件获取到你的计算机上，请使用上面的导航链接，并将文件正文复制到计算机上同名的本地文件（Room.json 和 Floor.json）中。

为 Azure CLI 准备环境

设置 CLI 会话

若要开始在 CLI 中使用 Azure 数字孪生，首先要做的是登录并将 CLI 上下文设置为此会话的订阅。 在 CLI 窗口中运行以下命令：

az login
az account set --subscription "<your-Azure-subscription-ID>"

提示

在上面的命令中，还可以使用订阅名称而不使用 ID。

如果这是你首次将此订阅与 Azure 数字孪生一起使用，请运行该命令以向 Azure 数字孪生命名空间进行注册。 （如果不确定，可以再次运行该命令，即使过去某个时候操作过也是如此。）

az provider register --namespace 'Microsoft.DigitalTwins'

接下来，添加适用于 Azure CLI 的 Microsoft Azure IoT 扩展以支持用于与 Azure 数字孪生和其他 IoT 服务进行交互的命令。 运行此命令以确保你已安装最新版本的扩展：

az extension add --upgrade --name azure-iot

现在 Azure 数字孪生已可在 Azure CLI 中使用。

若要验证 Azure 数字孪生在 Cloud Shell 中的就绪性，可以随时运行 az dt --help 查看可用的顶层 Azure 数字孪生命令列表。

准备 Azure 数字孪生实例

若要在本文中使用 Azure 数字孪生，首先需要设置一个 Azure 数字孪生实例，还需具备使用它所必需的权限。 如果已有通过以前的工作设置的 Azure 数字孪生实例，则可以使用该实例。

如果没有，请按照设置实例和身份验证中的说明操作。 说明中还包含用于验证是否已成功完成每个步骤并准备好继续使用新实例的步骤。

设置 Azure 数字孪生实例后，请记下以下值，稍后需要这些值来连接到该实例：

  • 实例的主机名
  • 用于创建实例的 Azure 订阅

提示

如果你知道实例的易记名称，则可以使用以下 CLI 命令来获取主机名和订阅值：

az dt show --dt-name <Azure-Digital-Twins-instance-name>

它们在输出中将显示如下：Screenshot of Cloud Shell browser window showing the output of the az dt show command. The hostName field and subscription ID are highlighted.

使用 DTDL 为物理环境建模

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

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

模型类似于面向对象的编程语言中的类；它们为数字孪生提供了日后可遵循并实例化的用户定义的模板。 它们以类似于 JSON 的语言编写，称为 数字孪生定义语言（DTDL），可以定义孪生体的属性、关系和组件。

注意

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

在计算机上导航到在先决条件部分创建的 Room.json 文件。 在代码编辑器中打开该文件，然后通过以下方式对其进行更改：

  1. 更新版本号，以指出正在提供此模型的更新版本。 为此，请将 @id 末尾的 1 更改为 2 。 大于当前版本号的任何数字也有效。

  2. 编辑属性。 将 Humidity 属性的名称更改为 HumidityLevel（或你想要的其他名称。如果使用的名称不是 HumidityLevel，请记住你使用的名称并在整个教程中继续使用该名称，而不是 HumidityLevel）。

  3. 添加属性。 在结束于第 15 行的 HumidityLevel 属性下方，粘贴以下代码以将 RoomName 属性添加到 room 中：

    ,{
  "@type": "Property",
  "name": "RoomName",
  "schema": "string"
}

  4. 添加关系。 在刚刚添加的 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 数字孪生服务实例。 上传模型后，可以创建使用这些模型的孪生实例。

  1. 如果使用的是本地安装的 Azure CLI，则可以跳过此步骤。 如果使用 Cloud Shell 添加模型，需将模型文件上传到 Cloud Shell 的存储，以便在运行使用这些文件的 Cloud Shell 命令时，这些文件可供使用。 为此，请选择“上传/下载文件”图标，然后选择“上传”。

    Screenshot of Cloud Shell browser window showing selection of the Upload icon.

    在计算机上导航到“Room.json”文件并选择“打开”。然后，对“Floor.json”重复此步骤。

  2. 接下来，按如下所示使用 az dt model create 命令将更新的 Room 模型上传到 Azure 数字孪生实例。 第二个命令上传另一个模型 Floor，在下一部分，还要使用该模型创建不同类型的孪生。 实例的主机名有一个占位符（也可以使用实例的易记名称，但性能略有下降），每个模型文件的路径都有一个占位符。 如果使用的是 Cloud Shell，Room.json 和 Floor.json 位于主存储目录中，因此可以在下面需要路径的命令中直接使用文件名。

    az dt model create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --models <path-to-Room.json>
az dt model create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --models <path-to-Floor.json>

    每个命令的输出将显示有关已成功上传的模型的信息。

    提示

    还可以使用 model create 命令的 --from-directory 选项，同时上传一个目录中的所有模型。 有关详细信息，请查看 az dt model create 的可选参数。

  3. 按如下所示使用 az dt model list 命令验证是否已创建模型。 这样做将输出已上传到 Azure 数字孪生实例的所有模型的列表及其完整信息。 实例的主机名有一个占位符（也可以使用实例的易记名称，但性能会略有下降）。

    az dt model list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --definition

    在结果中寻找经过编辑的 Room 模型：

    Screenshot of Cloud Shell showing result of the model list command, which includes the updated Room model.

错误

CLI 还会处理服务中发生的错误。

重新运行 az dt model create 命令，尝试再次重新上传已上传的其中一个相同模型：

az dt model create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --models Room.json

由于无法覆盖模型，因此在同一模型上运行此命令现在将返回错误代码 ModelIdAlreadyExists。

创建数字孪生

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

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

  1. 在 CLI 中运行此代码，以基于前面更新的 Room 模型以及另一个 Floor 模型创建多个孪生体。 回想一下，Room 具有三个属性，因此可以为这些属性提供具有初始值的参数。 （初始化属性值在一般情况下是可选操作，但本教程需要此操作。）实例的主机名有一个占位符（也可以使用实例的易记名称，但性能会略有下降）。

    az dt twin create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --dtmi "dtmi:example:Room;2" --twin-id room0 --properties '{"RoomName":"Room0", "Temperature":70, "HumidityLevel":30}'
az dt twin create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --dtmi "dtmi:example:Room;2" --twin-id room1 --properties '{"RoomName":"Room1", "Temperature":80, "HumidityLevel":60}'
az dt twin create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --dtmi "dtmi:example:Floor;1" --twin-id floor0
az dt twin create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --dtmi "dtmi:example:Floor;1" --twin-id floor1

    注意

    如果你在 Bash 环境中使用 Cloud Shell 以外的任何内容，则可能需要转义内联 JSON 中的某些字符，以便对其进行正确解析。

    有关详细信息，请参阅在不同的 shell 中使用特殊字符。

    每个命令的输出将显示有关已成功创建的孪生的信息（包括随房间孪生一起初始化的房间孪生属性）。

  2. 可按如下所示使用 az dt twin query 命令验证是否已创建孪生。 所示的查询将查找 Azure 数字孪生实例中的所有数字孪生。 实例的主机名有一个占位符（也可以使用实例的易记名称，但性能会略有下降）。

    az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT * FROM DIGITALTWINS"

    在结果中查找 room0、room1、floor0 和 floor1 孪生。 下面是显示此查询结果的一部分的摘录。

    Screenshot of Cloud Shell showing partial result of twin query, including room0 and room1.

注意

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

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

修改数字孪生

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

  1. 运行以下 az dt twin update 命令，将 room0 的 RoomName 从 Room0 更改为 PresidentialSuite。 实例的主机名有一个占位符（也可以使用实例的易记名称，但性能会略有下降）。

    az dt twin update --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id room0 --json-patch '{"op":"add", "path":"/RoomName", "value": "PresidentialSuite"}'

    注意

    本教程建议在 Bash 环境中使用 CLI。 如果使用的是 PowerShell 环境，可能需要将引号字符转义才能正确分析 --json-patch JSON 值。

    此命令的输出将显示孪生的当前信息，结果中应会显示 RoomName 的新值。

    Screenshot of Cloud Shell showing result of the update command, which includes a RoomName of PresidentialSuite.

  2. 可以通过运行 az dt twin show 命令查看 room0 的信息，来验证更新是否成功。 实例的主机名有一个占位符（也可以使用实例的易记名称，但性能会略有下降）。

    az dt twin show --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id room0

    输出应反映更新后的名称。

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

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

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

若要添加关系，请使用 az dt twin relationship create 命令。 指定该关系的来源孪生、关系类型，以及该关系要连接到的孪生。 最后，为该关系指定唯一的 ID。 如果一个关系已定义为具有属性，则还可以在此命令中初始化关系属性。

  1. 运行以下代码，将来自前面创建的每个 Floor 孪生的 contains 类型的关系添加到相应的 Room 孪生。 关系的名称分别为 relationship0 和 relationship1。 实例的主机名有一个占位符（也可以使用实例的易记名称，但性能会略有下降）。

    az dt twin relationship create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --relationship-id relationship0 --relationship contains --twin-id floor0 --target room0
az dt twin relationship create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --relationship-id relationship1 --relationship contains --twin-id floor1 --target room1

    提示

    在 Floor 模型中定义的 contains 关系也有两个属性：ownershipUser 和 ownershipDepartment，因此，在创建关系时，也可以为参数提供这些属性的初始值。 若要在这些属性已初始化的情况下创建关系，请将 --properties 选项添加到上述任一命令，如下所示：

    ... --properties '{"ownershipUser":"MyUser", "ownershipDepartment":"MyDepartment"}'

    每个命令的输出将显示有关已成功创建的关系的信息。

  2. 可以使用以下任一命令来验证关系，这些命令将输出 Azure 数字孪生实例中的关系。 每个命令都有一个用于实例主机名的占位符（也可以使用实例的易记名称，但性能会略有下降）。

    • 若要查看源自每个楼层的所有关系（从一端查看关系）：
      az dt twin relationship list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id floor0
az dt twin relationship list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id floor1
    • 若要查看到达每个房间的所有关系（从“另一”端查看关系）：
      az dt twin relationship list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id room0 --incoming
az dt twin relationship list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id room1 --incoming
    • 若要按 ID 单独查找这些关系：
      az dt twin relationship show --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id floor0 --relationship-id relationship0
az dt twin relationship show --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id floor1 --relationship-id relationship1

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

A diagram showing a conceptual graph. floor0 is connected via relationship0 to room0, and floor1 is connected via relationship1 to room1.

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

Azure 数字孪生的主要功能是能够轻松有效地查询孪生图，以解答有关环境的问题。 在 Azure CLI 中，查询是使用 az dt twin query 命令来实现的。

注意

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

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

在 CLI 中运行以下查询可以回答有关示例环境的一些问题。 每个命令都有一个用于实例主机名的占位符（也可以使用实例的易记名称，但性能会略有下降）。

  1. 在我的环境中，用 Azure 数字孪生表示的所有实体都有哪些？ （查询所有）

    az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT * FROM DIGITALTWINS"

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

    Screenshot of Cloud Shell showing partial result of twin query, including room0 and room1.

    提示

    你可能会认出，这是在前面的创建数字孪生部分中用来查找实例中的所有 Azure 数字孪生的同一命令。

  2. 我的环境中的所有房间都有哪些？ （按模型查询）

    az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT * FROM DIGITALTWINS T WHERE IS_OF_MODEL(T, 'dtmi:example:Room;2')"

    可以将查询限制为某种类型的孪生，以获取有关所表示内容的更多具体信息。 此查询的结果显示 room0 和 room1，但不显示 floor0 或 floor1（因为它们是楼层，而不是房间）。

    Screenshot of Cloud Shell showing result of model query, which includes only room0 and room1.

  3. floor0 上的所有房间都有哪些？ （按关系查询）

    az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.\$dtId = 'floor0'"

    可以根据图形中的关系进行查询，以获取有关如何连接孪生或如何将查询限制在特定区域的信息。 此查询还说明了使用元数据字段 $dtId 查询了孪生体的 ID（类似于上述查询中的 floor0）。 floor0 上只有 room0，因此它是该查询结果中唯一的房间。

    Screenshot of Cloud Shell showing result of relationship query, which includes room0.

    注意

    使用 Cloud Shell 针对类似于这样的以 $ 开头的元数据字段运行查询时，应使用反斜杠将 $ 转义，让 Cloud Shell 知道它不是变量，应将其作为查询文本中的文本来使用。 以上屏幕截图反映了这种转义方式。

  4. 环境中温度高于 75 的所有孪生都有哪些？ （按属性查询）

    az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT * FROM DigitalTwins T WHERE T.Temperature > 75"

    可根据属性查询图形，以回答各种问题，包括在环境中查找可能需要注意的离群值。 还支持其他比较运算符（<、>、= 或 !=）。 room1 出现在此处的结果中，因为它的温度为 80。

    Screenshot of Cloud Shell showing result of property query, which includes only room1.

  5. floor0 上温度高于 75 的所有房间都有哪些？ （复合查询）

    az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "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 的房间。在本例中，这些房间均不满足条件。 结果集为空。

    Screenshot of Cloud Shell showing result of compound query, which doesn't include any items.

清理资源

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

  • 如果你打算继续学习下一篇教程，在此之前可以保留本教程中设置的资源而不要清除任何内容，并重复使用 Azure 数字孪生实例。

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

    重要

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

    打开 Azure Cloud Shell 或本地 CLI 窗口并运行以下命令，以删除资源组及其包含的所有内容。

    az group delete --name <your-resource-group>

你还可能想要删除在本地计算机上创建的模型文件。

后续步骤

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

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

连接端到端解决方案