教程：部署 Azure 数字孪生预览版并配置空间图

重要

Azure 数字孪生服务的新版本已发布。 鉴于新服务的扩展功能，本文档集 (中所述的原始 Azure 数字孪生服务) 已停用。

若要查看新服务的文档，请访问活动的 Azure 数字孪生文档。

可以使用 Azure 数字孪生预览服务将人员、地点和设备规整到一个一致的空间系统中。 本系列教程演示如何使用 Azure 数字孪生来检测温度和空气质量达到理想化条件时的房间占用情况。

这些教程演示如何通过 .NET 控制台应用程序生成一个涉及一栋办公大楼的方案， 该楼有多个楼层，每个楼层有多个房间。 房间包含设备，通过附加的传感器来检测移动、环境温度和空气质量。

本系列教程会介绍如何通过 Azure 数字孪生服务将大楼中的物理区域和实体复制为数字对象。 可以使用另一控制台应用程序模拟设备事件。 然后，教程会介绍如何以近实时的方式监视来自这些物理区域和实体的事件。

办公室主任可以根据此信息帮助在此大楼工作的员工预订理想化条件的会议室。 办公设备管理员可以根据你的设置了解房间的使用趋势，并监视进行维护所需的工作条件。

本系列的第一个教程介绍如何执行以下操作：

• 部署数字孪生。
• 向应用授权。
• 修改数字孪生示例应用。
• 预配大楼。

这些教程使用和修改介绍如何查找可用房间的快速入门所使用的示例，目的是更详细且更深入地探讨相关概念。

先决条件

• Azure 订阅。 如果没有 Azure 帐户，请创建一个免费帐户。

• .NET Core SDK。 在这些教程中使用的 Azure 数字孪生示例以 C# 编写。 请确保在用于生成和运行示例的开发计算机上安装 .NET Core SDK 2.1.403 或更高版本。 在命令窗口中运行 dotnet --version 即可检查计算机上是否已安装正确的版本。

• Visual Studio Code，用于探索示例代码。

部署数字孪生

请使用此部分的步骤创建 Azure 数字孪生服务的新实例。 每个订阅只能创建一个实例。 如果已经有一个实例在运行，请跳至下一部分。

1. 登录 Azure 门户。

2. 依次选择主侧栏和“+ 创建资源”。

   

3. 搜索“数字孪生”，然后选择“数字孪生”。

   

   或者，选择“物联网”，然后选择“数字孪生（预览版）”。

4. 选择“创建”，启动部署过程。

   

5. 在“数字孪生”窗格中，输入以下信息：

   • 资源名称：为数字孪生实例创建一个唯一名称。

   • 订阅：选择需要将其用于创建此数字孪生实例的订阅。

   • 资源组：为数字孪生实例选择或创建资源组。

   • 位置：选择离设备最近的位置。

     

6. 查看数字孪生信息，然后选择“创建”。 创建数字孪生实例可能需要数分钟。 可在“通知”窗格中监视进度。

7. 打开数字孪生实例的“概览”窗格。 记下“管理 API”下的链接。 管理 API URL 的格式为：

   https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swagger
   

   此 URL 将引导你到适用于实例的 Azure 数字孪生 REST API 文档。 阅读如何使用 Azure 数字孪生 Swagger，了解如何阅读和使用此 API 文档。 复制管理 API URL 并将其修改成此格式：

   https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/
   

   应用程序将使用此修改过的 URL 作为基 URL 来访问实例。 将此修改过的 URL 复制到一个临时文件。 下一部分将需要此 URL。

   

向应用授权

数字孪生使用 Azure Active Directory (Azure AD) 来控制对服务的读/写访问权限。 任何需要与数字孪生实例连接的应用程序都必须注册到 Azure AD。 本部分的步骤介绍如何注册示例应用。

如果已经进行了应用注册，可以将其重用于示例。 但是，请浏览本部分，确保应用注册已正确配置。

注意

本部分提供有关 Azure AD 应用注册的说明。

1. 在 Azure 门户中，从可展开的左菜单打开“Azure Active Directory”，然后打开“应用注册”窗格。

   

2. 选择“+ 新建注册”按钮。

   

3. 在“名称”框中，为此应用注册提供一个友好名称。

   1. 在“重定向 URI (可选)”部分下的文本框中输入 https://microsoft.com。

   2. 验证 Azure Active Directory 应用支持哪些帐户和租户。

   3. 选择“注册”。

   

4. “身份验证”边栏选项卡可指定重要的身份验证配置设置。

   1. 通过选择“+ 添加平台”，添加“重定向 URI”并配置“访问令牌”。

   2. 选择“是”以指定该应用为“公共客户端”。

   3. 验证 Azure Active Directory 应用支持哪些帐户和租户。

   

5. 选择适当的平台后，在用户界面右侧的侧面板中配置“重定向 URI”和“访问令牌”。

   1. “重定向 URI”必须与身份验证请求所提供的地址相匹配：

      • 对于本地开发环境中托管的应用，请选择“公共客户端(移动和桌面)”。 确保将“公共客户端”设为“是”。
      • 对于 Azure 应用服务上托管的单页应用，请选择“Web”。

   2. 确定“注销 URL”是否合适。

   3. 通过选中“访问令牌”或“ID 令牌”来启用隐式授权流。

   

   单击“配置”，然后单击“保存”。

6. 打开已注册的应用的“概述”窗格，然后将以下实体的值复制到临时文件。 在以下部分中，将使用这些值配置示例应用程序。

   • 应用程序(客户端) ID
   • 目录（租户）ID

   

7. 打开用于应用注册的“API 权限”窗格。 选择“+ 添加权限”按钮。 在“请求 API 权限”窗格中，选择“我的组织使用的 API”选项卡，然后搜索以下任意一项：

   1. Azure Digital Twins. 选择 Azure 数字孪生 API。

      

   2. 或者，搜索 Azure Smart Spaces Service。 选择“Azure 智能空间服务”API。

      

   重要

   将显示的 Azure AD API 名称和 ID 取决于租户：

   • 测试租户和客户帐户应搜索 Azure Digital Twins。
   • 其他 Microsoft 帐户应搜索 Azure Smart Spaces Service。

8. 选择后，任一 API 会在同一个“请求 API 权限”窗格中显示为“Azure 数字孪生”。 选择“读取”下拉选项，然后选中“Read.Write”复选框。 选择“添加权限”按钮。

   

9. 根据组织的设置，可能需要执行其他步骤才能授予对此 API 的管理员访问权限。 请联系管理员以了解详细信息。 在该管理员访问权限得到批准后，“API 权限”窗格中的“需要管理员同意”列将显示你的权限。

   

   验证是否显示“Azure 数字孪生”。

配置数字孪生示例

本部分详细介绍一个可以与数字孪生 REST API 通信的 Azure 数字孪生应用程序。

下载示例

如果已下载适用于介绍如何查找可用房间的快速入门的示例，可以跳过这些步骤。

1. 下载数字孪生 .NET 示例。
2. 解压缩计算机上的 zip 文件夹的内容。

探索示例

在解压缩后的示例文件夹中，通过 Visual Studio Code 打开 digital-twins-samples-csharp\digital-twins-samples.code-workspace 文件。 该文件包含两个项目：

• 可以通过预配示例 occupancy-quickstart 配置和预配空间智能图。 该图是你的物理空间以及其中的资源的数字化图像。 它使用对象模型来定义智能大楼的对象。 如需数字孪生对象和 REST API 的完整列表，请访问此 REST API 文档或者为你的实例创建的管理 API URL。

  若要通过浏览示例以了解它与数字孪生实例的通信方式，可以从 src\actions 文件夹开始。 该文件夹中的文件实现的命令是将要在这些教程中使用的命令：

  • provisionSample.cs 文件说明如何预配空间图。
  • getSpaces.cs 文件获取已预配空间的相关信息。
  • getAvailableAndFreshSpaces.cs 文件获取名为“用户定义函数”的自定义函数的结果。
  • createEndpoints.cs 文件创建与其他服务交互的终结点。

• 模拟示例 device-connectivity 模拟传感器数据并将其发送到为数字孪生实例预配的 IoT 中心。 将在预配空间图后的下一教程中使用此示例。 用于配置此示例的传感器和设备标识符应该与用于预配图形的相同。

配置预配示例

1. 打开一个命令窗口，转到已下载的示例。 运行以下命令：

   cd occupancy-quickstart/src
   

2. 通过运行以下命令将依赖项还原到示例项目：

   dotnet restore
   

3. 在 Visual Studio Code 中打开 occupancy-quickstart 项目中的 appSettings.json 文件。 请更新以下值：

   • ClientId：输入 Azure AD 应用注册的应用程序 ID。 已在设置应用权限的部分记下此 ID。
   • 租户：输入 Azure AD 租户的目录 ID。 也已在设置应用权限的部分记下此 ID。
   • BaseUrl：输入数字孪生实例的 URL。 若要获取此 URL，请将其中的占位符替换为适用于你的实例的值：https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/。 也可通过修改部署部分的管理 API URL 来获取此 URL。 将 swagger/ 替换为 api/v1.0/。

4. 查看可通过示例探索的数字孪生功能列表。 运行以下命令：

   dotnet run
   

了解预配过程

此部分介绍示例如何预配大楼的空间图。

在 Visual Studio Code 中浏览到 occupancy-quickstart\src\actions 文件夹，打开 provisionSample.cs 文件。 注意以下函数：

public static async Task<IEnumerable<ProvisionResults.Space>> ProvisionSample(HttpClient httpClient, ILogger logger)
{
    IEnumerable<SpaceDescription> spaceCreateDescriptions;
    using (var r = new StreamReader("actions/provisionSample.yaml"))
    {
        spaceCreateDescriptions = await GetProvisionSampleTopology(r);
    }

    var results = await CreateSpaces(httpClient, logger, spaceCreateDescriptions, Guid.Empty);

    Console.WriteLine($"Completed Provisioning: {JsonConvert.SerializeObject(results, Formatting.Indented)}");

    return results;
}

此函数使用同一文件夹中的 provisionSample.yaml。 打开此文件，注意办公大楼的层次结构：地点、楼层、区域和房间。 任何一个这样的物理空间都可能包含设备和传感器。 每个条目都有一个预定义 type的 ，例如 Floor、Room。

示例 yaml 文件显示一个使用 Default 数字孪生对象模型的空间图。 该模型提供适用于大多数类型的通用名称。 通用名称对于大楼来说已足够。 例如，使用“温度”作为 SensorDataType，使用“地图”作为 SpaceBlobType。 例如，子类型为 FocusRoom、ConferenceRoom 等的房间为空间类型。

如果必须为另一类型的地点（例如工厂）创建空间图，则可能需要另一对象模型。 若要找出可供使用的具体模型，可在适用于预配示例的命令行中运行 dotnet run GetOntologies 命令。

若要详细了解空间图和对象模型，请阅读了解数字孪生对象模型和空间智能图。

修改示例空间图

provisionSample.yaml 文件包含以下节点：

• resources：resources 节点创建一个 Azure IoT 中心资源，用于与设置中的设备通信。 在图形根节点处的 IoT 中心可以与图形中的所有设备和传感器通信。

• spaces：在数字孪生对象模型中，spaces 表示物理位置。 每个空间都有一个 Type（例如，区域、地点或客户） 和一个友好的 Name。 一些空间可能属于另一些空间，形成一个层次结构。 provisionSample.yaml 文件有一个虚构大楼的空间图。 注意 Venue 中有 Floor 类型，楼层中有 Area，区域中有 Room 节点，这样就形成了空间的逻辑嵌套。

• devices：空间可能包含 devices，这是物理或虚拟实体，用于管理大量传感器。 例如，设备可能是用户的电话、Raspberry Pi 传感器 Pod 或网关。 在示例的虚构大楼中，注意名为“专注室”的房间包含一个 Raspberry Pi 3 A1 设备。 每个设备节点均由已硬编码到示例中的唯一 hardwareId 进行标识。 若要针对实际生产来配置此示例，请将这些项替换为你设置中的值。

• sensors：一个设备可能包含多个 sensors， 用于检测和记录物理变化，例如温度、移动和电池剩余电量的变化。 每个传感器节点都通过此处硬编码的 hardwareId 进行唯一标识。 对于实际的应用程序，请将这些项替换为设置中传感器的唯一标识符。 provisionSample.yaml 文件有两个传感器，用于记录移动和二氧化碳情况。 请添加另一传感器来记录温度，方法是将以下行添加到二氧化碳传感器对应的行下面。 这些行作为注释行在 provisionSample.yaml 中提供。 可以取消注释这些行，方法是删除每一行前面的 # 字符。

          - dataType: Temperature
            hardwareId: SAMPLE_SENSOR_TEMPERATURE
  

  注意

  请确保 dataType 和 hardwareId 键与此代码片段上面的语句对齐。 另请确保编辑器不将空格替换为制表符。

保存并关闭 provisionSample.yaml 文件。 在下一教程中，将向此文件添加更多的信息，然后预配 Azure 数字孪生示例大楼。

提示

可以使用 Azure 数字孪生图形查看器查看和修改空间图。

清理资源

如果不希望继续探索 Azure 数字孪生，可以删除本教程中创建的资源：

1. 在 Azure 门户的左菜单中依次选择“所有资源”、数字孪生资源组、“删除”。

   提示

   如果在删除数字孪生实例时遇到麻烦，请使用已推出的包含修补程序的服务更新。 请重新尝试删除实例。

2. 可以根据需要删除工作计算机上的示例应用程序。

后续步骤

若要了解如何实现一个用于监视示例大楼中条件的自定义逻辑，请继续学习此系列中的下一教程：

教程：预配大楼并监视工作条件