快速入门：通过 Azure 数字孪生查找可用房间

  • 项目

重要

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

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

可以通过 Azure 数字孪生服务重新创建物理环境的数字图像。 然后，你可以获得环境中事件的通知并自定义对其的响应。

本快速入门使用一对 .NET 示例将一栋虚构的办公大楼数字化， 并介绍如何查找该大楼中的可用房间。 可以通过数字孪生将多个传感器与环境相关联。 还可以借助二氧化碳模拟传感器来确定可用房间的空气质量是否理想。 其中一个示例应用程序会生成用于可视化此方案的随机传感器数据。

以下视频汇总了快速入门设置：

先决条件

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

  2. 本快速入门中运行的两个控制台应用程序使用 C# 编写。 在开发计算机上安装 .NET Core SDK 2.1.403 或更高版本。 如果已安装 .NET Core SDK，则可在开发计算机上验证 C# 的当前版本。 在命令提示符处运行 dotnet --version。

  3. 下载示例 C# 项目。 解压缩 digital-twins-samples-csharp-master.zip 存档。

创建数字孪生实例

使用此部分的步骤在门户中创建数字孪生的新实例。

  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。

    管理 API 概述

设置应用的权限

此部分将示例应用程序注册到 Azure Active Directory (Azure AD)，使之能够访问数字孪生实例。 如果已经进行了 Azure AD 应用注册，请将其重用于示例。 确保按此部分所述对其进行配置。

注意

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

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

    选择“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 令牌”来启用隐式授权流。

    配置重定向 URI

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

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

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

    Azure Active Directory 应用程序 ID

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

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

      搜索 API 或 Azure 数字孪生

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

      Azure Smart Spaces 的搜索 API

    重要

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

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

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

    添加 API 权限

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

    管理员同意审批

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

生成应用程序

使用以下步骤来生成 occupancy 应用程序。

  1. 打开命令提示符。 转到解压缩 digital-twins-samples-csharp-master.zip 文件的文件夹。

  2. 运行 cd occupancy-quickstart/src。

  3. 运行 dotnet restore。

  4. 编辑 appSettings.json，更新以下变量：

    • ClientId：输入 Azure AD 应用注册的应用程序 ID，此 ID 记录在上一部分。
    • 租户：输入 Azure AD 租户的目录 ID，此 ID 也记录在上一部分。
    • BaseUrl：数字孪生实例的管理 API URL 采用 https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/ 格式。 请将此 URL 中的占位符替换为上一部分的实例的值。

    保存更新的文件。

预配图形

此步骤为数字孪生空间图预配以下项：

  • 多个空间。
  • 一个设备。
  • 两个传感器。
  • 一个自定义函数。
  • 一个角色分配。

空间图使用 provisionSample.yaml 文件进行预配。

  1. 运行 dotnet run ProvisionSample。

    注意

    请使用设备登录 Azure CLI 工具向 Azure AD 进行用户身份验证。 用户必须使用 Microsoft 登录页输入一个给定的用于身份验证的代码。 输入代码以后，请按步骤进行身份验证。 运行工具时，用户必须进行身份验证。

    提示

    运行此步骤时，如果出现以下错误消息，请确保变量已正确复制：EXIT: Unexpected error: The input is not a valid Base-64 string ...

  2. 预配步骤可能需要数分钟。 此外还会在数字孪生实例中预配 IoT 中心， 并且会一直循环下去，直至 IoT 中心的状态为 Running。

    预配示例 - Status=Running

  3. 在执行结束时，请复制设备的 ConnectionString，以便在设备模拟器示例中使用。 仅复制下图所示的字符串。

    复制连接字符串

    提示

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

将控制台窗口保持打开状态，以便以后再次使用。

发送传感器数据

请通过以下步骤生成并运行传感器模拟器设备应用程序。

  1. 打开新的命令提示符窗口。 转到下载在 digital-twins-samples-csharp-master 文件夹中的项目。

  2. 运行 cd device-connectivity。

  3. 运行 dotnet restore。

  4. 编辑 appsettings.json，使用上面的 ConnectionString 更新 DeviceConnectionString。 保存更新的文件。

  5. 运行 dotnet run，开始发送传感器数据。 这些数据将发送到 Azure 数字孪生，如下图所示。

    设备连接

  6. 让此模拟器运行，这样就可以同时查看结果和下一步操作。 此窗口会显示发送到数字孪生的模拟传感器数据， 而下一步则会进行实时查询，以便查找空气清新的可用房间。

    提示

    运行此步骤时，如果出现以下错误消息，请确保 DeviceConnectionString 已正确复制：EXIT: Unexpected error: The input is not a valid Base-64 string ...

查找空气清新的可用空间

传感器示例模拟两个传感器的随机数据值。 这两个传感器是移动传感器和二氧化碳传感器。 在示例中，空气清新的可用空间按定义是指房间没有被占用， 且二氧化碳水平低于 1,000 ppm。 如果不满足条件，则表明空间不可用或者空气质量差。

  1. 打开用于运行早期预配步骤的命令提示符窗口。

  2. 运行 dotnet run GetAvailableAndFreshSpaces。

  3. 并排查看此命令提示符窗口和传感器数据命令提示符窗口。

    传感器数据命令提示符窗口每五秒钟向数字孪生发送一次模拟的移动和二氧化碳数据。 另一命令提示符以实时方式读取图形，根据随机的模拟数据来找出空气清新的可用房间。 它会根据上一次发送的传感器数据以近实时方式显示这其中的一个条件：

    • Room is available and air is fresh

    • Room is not available or air quality is poor

      获取空气清新的可用空间

若要了解本快速入门中的情况以及所调用的 API，请打开 Visual Studio Code，其中的代码工作区项目位于 digital-twins-samples-csharp 中。 请使用以下命令：

<path>\occupancy-quickstart\src>code ..\..\digital-twins-samples.code-workspace

这些教程会详细探讨代码， 并介绍如何修改配置数据以及调用哪些 API。 有关管理 API 的详细信息，请转到数字孪生 Swagger 页：

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger
名称 替换为
YOUR_INSTANCE_NAME 数字孪生实例的名称
YOUR_LOCATION 托管实例的服务器区域

或者，为了方便，请浏览到数字孪生 Swagger。

清理资源

这些教程详细介绍如何执行以下操作：

  • 生成应用程序，以便设施管理员提高住户工作效率。
  • 更有效地运营此大楼。

若要继续学习这些教程，请勿清除本快速入门中创建的资源。 如果不打算继续学习，请删除通过本快速入门创建的所有资源。

  1. 删除下载示例存储库时创建的文件夹。

  2. 在Azure 门户左侧菜单中，选择“所有资源”。 然后，选择数字孪生资源。 在“所有资源”窗格的顶部选择“删除”。

    提示

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

后续步骤

本快速入门通过简单的方案和示例应用程序演示如何使用数字孪生来查找具有良好工作条件的会议室。 若要深入分析此方案，请阅读以下教程：

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