您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

快速入门:通过 Azure 数字孪生查找可用房间Quickstart: Find available rooms by using Azure Digital Twins

可以通过 Azure 数字孪生服务重新创建物理环境的数字图像。The Azure Digital Twins service allows you to re-create a digital image of your physical environment. 然后,你可以获得环境中事件的通知并自定义对其的响应。You can then get notified by events in your environment and customize your responses to them.

本快速入门使用一对 .NET 示例将一栋虚构的办公大楼数字化,This quickstart uses a pair of .NET samples to digitize an imaginary office building. 并介绍如何查找该大楼中的可用房间。It shows you how to find available rooms in that building. 可以通过数字孪生将多个传感器与环境相关联。With Digital Twins, you can associate many sensors with your environment. 还可以借助二氧化碳模拟传感器来确定可用房间的空气质量是否理想。You also can find out if the air quality of your available room is optimal with the help of a simulated sensor for carbon dioxide. 其中一个示例应用程序会生成用于可视化此方案的随机传感器数据。One of the sample applications generates random sensor data to help you visualize this scenario.

以下视频汇总了快速入门设置:The following video summarizes the quickstart setup:

必备条件Prerequisites

  1. 如果没有 Azure 帐户,请在开始前创建一个免费帐户If you don't have an Azure account, create a free account before you begin.

  2. 本快速入门中运行的两个控制台应用程序使用 C# 编写。The two console applications you run in this quickstart are written by using C#. 在开发计算机上安装 .NET Core SDK 2.1.403 或更高版本Install the .NET Core SDK version 2.1.403 or above on your development machine. 如果已安装 .NET Core SDK,则可在开发计算机上验证 C# 的当前版本。If you have the .NET Core SDK installed, verify the current version of C# on your development machine. 在命令提示符处运行 dotnet --versionRun dotnet --version in a command prompt.

  3. 下载示例 C# 项目Download the sample C# project. 解压缩 digital-twins-samples-csharp-master.zip 存档。Extract the digital-twins-samples-csharp-master.zip archive.

创建数字孪生实例Create a Digital Twins instance

使用此部分的步骤在门户中创建数字孪生的新实例。Create a new instance of Digital Twins in the portal by following the steps in this section.

  1. 登录 Azure 门户Sign in to the Azure portal.

  2. 依次选择主侧栏和“+ 创建资源” 。Select the home side-bar, then + Create a resource.

    展开主侧栏,然后选择“+ 创建资源”Expand the home side-bar, then select + Create a resource

  3. 搜索“数字孪生” ,然后选择“数字孪生” 。Search for Digital Twins, and select Digital Twins.

    用于创建新数字孪生实例的选项Selections for creating a new Digital Twins instance

    或者,选择“物联网” ,然后选择“数字孪生(预览版)” 。Alternatively, select Internet of Things, and select Digital Twins (preview).

  4. 选择“创建”,启动部署过程。 Select Create to start the deployment process.

    创建并确认资源的部署Create and confirm the deployment of the resource

  5. 在“数字孪生”窗格中,输入以下信息: In the Digital Twins pane, enter the following information:

    • 资源名称:为数字孪生实例创建一个唯一名称。Resource Name: Create a unique name for your Digital Twins instance.

    • 订阅:选择需要将其用于创建此数字孪生实例的订阅。Subscription: Choose the subscription that you want to use to create this Digital Twins instance.

    • 资源组:为数字孪生实例选择或创建资源组Resource group: Select or create a resource group for the Digital Twins instance.

    • 位置:选择离你的设备最近的位置。Location: Select the closest location to your devices.

      包含输入信息的“数字孪生”窗格Digital Twins pane with entered information

  6. 查看数字孪生信息,然后选择“创建” 。Review your Digital Twins information, and then select Create. 创建数字孪生实例可能需要数分钟。Your Digital Twins instance might take a few minutes to be created. 可在“通知”窗格中监视进度。 You can monitor the progress in the Notifications pane.

  7. 打开数字孪生实例的“概览”窗格。 Open the Overview pane of your Digital Twins instance. 记下“管理 API”下的链接。 Note the link under Management API. 管理 API URL 的格式为: The Management API URL is formatted as:

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

    此 URL 将引导你到适用于实例的 Azure 数字孪生 REST API 文档。This URL takes you to the Azure Digital Twins REST API documentation that applies to your instance. 阅读如何使用 Azure 数字孪生 Swagger,了解如何阅读和使用此 API 文档。Read How to use Azure Digital Twins Swagger to learn how to read and use this API documentation. 复制管理 API URL 并将其修改成此格式: Copy and modify the Management API URL to this format:

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

    应用程序将使用此修改过的 URL 作为基 URL 来访问实例。Your application will use the modified URL as the base URL to access your instance. 将此修改过的 URL 复制到一个临时文件。Copy this modified URL to a temporary file. 下一部分将需要此 URL。You'll need this in the next section.

    管理 API 概述Management API overview

设置应用的权限Set permissions for your app

此部分将示例应用程序注册到 Azure Active Directory (Azure AD),使之能够访问数字孪生实例。This section registers your sample application to Azure Active Directory (Azure AD) so that it can access your Digital Twins instance. 如果已经进行了 Azure AD 应用注册,请将其重用于示例。If you already have an Azure AD app registration, reuse it for your sample. 确保按此部分所述对其进行配置。Make sure that it's configured as described in this section.

备注

本部分提供有关 Azure AD 应用注册的说明。This section provides instructions for Azure AD app registration.

  1. Azure 门户中,从可展开的左菜单打开“Azure Active Directory” ,然后打开“应用注册”窗格 。In the Azure portal, open Azure Active Directory from the expandable left menu, and then open the App registrations pane.

    选择“Azure Active Directory”窗格Select the Azure Active Directory pane

  2. 选择“+ 新建注册” 按钮。Select the + New registration button.

    选择“新建注册”按钮Select the New registration button

  3. 在“名称” 框中,为此应用注册提供一个友好名称。Give a friendly name for this app registration in the Name box.

    1. 在“重定向 URI (可选)” 部分下的文本框中输入 https://microsoft.comUnder Redirect URI (optional) section, enter https://microsoft.com in the textbox.

    2. 验证 Azure Active Directory 应用支持哪些帐户和租户。Verify which accounts and tenants are supported by your Azure Active Directory app.

    3. 选择“注册” 。Select Register.

    “创建”窗格Create pane

  4. “身份验证” 边栏选项卡可指定重要的身份验证配置设置。The Authentication blade specifies important authentication configuration settings.

    1. 通过选择“+ 添加平台” ,添加“重定向 URI” 并配置“访问令牌” 。Add Redirect URIs and configure Access Tokens by selecting + Add a platform.

    2. 选择“是” 以指定该应用为“公共客户端” 。Select Yes to specify that the app is a public client.

    3. 验证 Azure Active Directory 应用支持哪些帐户和租户。Verify which accounts and tenants are supported by your Azure Active Directory app.

    公共客户端配置设置Public client configuration setting

  5. 选择适当的平台后,在用户界面右侧的侧面板中配置“重定向 URI” 和“访问令牌” 。After selecting the appropriate platform, configure your Redirect URIs and Access Tokens in the side panel to the right of the user interface.

    1. “重定向 URI” 必须与身份验证请求所提供的地址相匹配:Redirect URIs must match the address supplied by the authentication request:

      • 对于本地开发环境中托管的应用,请选择“公共客户端(移动和桌面)” 。For apps hosted in a local development environment, select Public client (mobile & desktop). 确保将“公共客户端” 设为“是” 。Make sure to set public client to Yes.
      • 对于 Azure 应用服务上托管的单页应用,请选择“Web” 。For Single-Page Apps hosted on Azure App Service, select Web.
    2. 确定“注销 URL” 是否合适。Determine whether a Logout URL is appropriate.

    3. 通过选中“访问令牌” 或“ID 令牌” 来启用隐式授权流。Enable the implicit grant flow by checking Access tokens or ID tokens.

    配置重定向 URIConfigure Redirect URIs

    单击“配置” ,然后单击“保存” 。Click Configure, then Save.

  6. 打开已注册的应用的“概述” 窗格,然后将以下实体的值复制到临时文件。Open the Overview pane of your registered app, and copy the values of the following entities to a temporary file. 在以下部分中,将使用这些值配置示例应用程序。You'll use these values to configure your sample application in the following sections.

    • 应用程序(客户端) IDApplication (client) ID
    • 目录(租户) IDDirectory (tenant) ID

    Azure Active Directory 应用程序 IDAzure Active Directory application ID

  7. 打开用于应用注册的“API 权限”窗格 。Open the API permissions pane for your app registration. 选择“+ 添加权限”按钮 。Select + Add a permission button. 在“请求 API 权限” 窗格中,选择“我的组织使用的 API” 选项卡,然后搜索以下任意一项:In the Request API permissions pane, select the APIs my organization uses tab, and then search for one of the following:

    1. Azure Digital Twins 列中的一个值匹配。Azure Digital Twins. 选择 Azure 数字孪生 API。Select the Azure Digital Twins API.

      搜索“API”或“Azure 数字孪生”Search API or Azure Digital Twins

    2. 或者,搜索 Azure Smart Spaces ServiceAlternatively, search for Azure Smart Spaces Service. 选择“Azure 智能空间服务” API。Select the Azure Smart Spaces Service API.

      搜索 Azure 智能空间的 APISearch API for Azure Smart Spaces

    重要

    将显示的 Azure AD API 名称和 ID 取决于租户:The Azure AD API name and ID that will appear depends on your tenant:

    • 测试租户和客户帐户应搜索 Azure Digital TwinsTest tenant and customer accounts should search for Azure Digital Twins.
    • 其他 Microsoft 帐户应搜索 Azure Smart Spaces ServiceOther Microsoft accounts should search for Azure Smart Spaces Service.
  8. 选择后,任一 API 会在同一个“请求 API 权限”窗格中显示为“Azure 数字孪生” 。Either API will appear as Azure Digital Twins in the same Request API permissions pane once selected. 选择“读取”下拉选项 ,然后选中“Read.Write”复选框 。Select the Read drop-down option, and then select the Read.Write checkbox. 选择“添加权限”按钮 。Select the Add permissions button.

    添加 API 权限Add API permissions

  9. 根据组织的设置,可能需要执行其他步骤才能授予对此 API 的管理员访问权限。Depending on your organization's settings, you might need to take additional steps to grant admin access to this API. 请联系管理员以了解详细信息。Contact your administrator for more information. 在该管理员访问权限得到批准后,“API 权限”窗格中的“需要管理员同意”列将显示你的权限 。Once the admin access is approved, the Admin Consent Required column in the API permissions pane will display your permissions.

    管理员同意审批Admin consent approval

    验证是否显示“Azure 数字孪生” 。Verify that Azure Digital Twins appears.

生成应用程序Build application

使用以下步骤来生成 occupancy 应用程序。Build the occupancy application by following these steps.

  1. 打开命令提示符。Open a command prompt. 转到解压缩 digital-twins-samples-csharp-master.zip 文件的文件夹。Go to the folder where your digital-twins-samples-csharp-master.zip files were extracted.

  2. 运行 cd occupancy-quickstart/srcRun cd occupancy-quickstart/src.

  3. 运行 dotnet restoreRun dotnet restore.

  4. 编辑 appSettings.json,更新以下变量:Edit appSettings.json to update the following variables:

    • ClientId:输入 Azure AD 应用注册的应用程序 ID,此 ID 记录在上一部分。ClientId: Enter the Application ID of your Azure AD app registration, noted in the preceding section.
    • 租户:输入 Azure AD 租户的目录 ID,此 ID 也记录在上一部分。Tenant: Enter the Directory ID of your Azure AD tenant, also noted in the previous section.
    • BaseUrl:数字孪生实例的管理 API URL 采用 https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/ 格式。BaseUrl: The Management API URL of your Digital Twins instance is in the format https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/. 请将此 URL 中的占位符替换为上一部分的实例的值。Replace the placeholders in this URL with values for your instance from the previous section.

    保存更新的文件。Save the updated file.

预配图形Provision graph

此步骤为数字孪生空间图预配以下项:This step provisions your Digital Twins spatial graph with:

  • 多个空间。Several spaces.
  • 一个设备。One device.
  • 两个传感器。Two sensors.
  • 一个自定义函数。A custom function.
  • 一个角色分配。One role assignment.

空间图使用 provisionSample.yaml 文件进行预配。The spatial graph is provisioned by using the provisionSample.yaml file.

  1. 运行 dotnet run ProvisionSampleRun dotnet run ProvisionSample.

    备注

    请使用设备登录 Azure CLI 工具向 Azure AD 进行用户身份验证。The Device Login Azure CLI tool is used to authenticate the user to Azure AD. 用户必须使用 Microsoft 登录页输入一个给定的用于身份验证的代码。The user must enter a given code to authenticate by using the Microsoft login page. 输入代码以后,请按步骤进行身份验证。After the code is entered, follow the steps to authenticate. 运行工具时,用户必须进行身份验证。The user must authenticate when the tool is running.

    提示

    运行此步骤时,如果出现以下错误消息,请确保变量已正确复制:EXIT: Unexpected error: The input is not a valid Base-64 string ...When you run this step, make sure your variables were copied properly if the following error message appears: EXIT: Unexpected error: The input is not a valid Base-64 string ...

  2. 预配步骤可能需要数分钟。The provisioning step might take a few minutes. 此外还会在数字孪生实例中预配 IoT 中心,It also provisions an IoT Hub within your Digital Twins instance. 并且会一直循环下去,直至 IoT 中心的状态为 RunningIt loops through until the IoT Hub shows Status=Running.

    预配示例 - Status=RunningProvision the sample - Status=Running

  3. 在执行结束时,请复制设备的 ConnectionString,以便在设备模拟器示例中使用。At the end of the execution, copy the ConnectionString of the device for use in the device simulator sample. 仅复制下图所示的字符串。Copy only the string outlined in this image.

    复制连接字符串Copy the connection string

    提示

    可以使用 Azure 数字孪生图形查看器查看和修改空间图。You can view and modify your spatial graph using the Azure Digital Twins Graph Viewer.

将控制台窗口保持打开状态,以便以后再次使用。Keep the console window open for use again later.

发送传感器数据Send sensor data

请通过以下步骤生成并运行传感器模拟器设备应用程序。Build and run the sensor simulator device application by following these steps.

  1. 打开新的命令提示符窗口。Open a new command prompt. 转到下载在 digital-twins-samples-csharp-master 文件夹中的项目。Go to the project you downloaded in the digital-twins-samples-csharp-master folder.

  2. 运行 cd device-connectivityRun cd device-connectivity.

  3. 运行 dotnet restoreRun dotnet restore.

  4. 编辑 appsettings.json,使用上面的 ConnectionString 更新 DeviceConnectionStringEdit appsettings.json to update DeviceConnectionString with the previous ConnectionString. 保存更新的文件。Save the updated file.

  5. 运行 dotnet run,开始发送传感器数据。Run dotnet run to start sending sensor data. 这些数据将发送到 Azure 数字孪生,如下图所示。It will be sent to Azure Digital Twins as shown in the following image.

    设备连接性Device Connectivity

  6. 让此模拟器运行,这样就可以同时查看结果和下一步操作。Let this simulator run so that you can view results side by side with the next step action. 此窗口会显示发送到数字孪生的模拟传感器数据,This window shows you the simulated sensor data sent to Digital Twins. 而下一步则会进行实时查询,以便查找空气清新的可用房间。The next step queries in real time to find available rooms with fresh air.

    提示

    运行此步骤时,如果出现以下错误消息,请确保 DeviceConnectionString 已正确复制:EXIT: Unexpected error: The input is not a valid Base-64 string ...When you run this step, make sure DeviceConnectionString was copied properly if the following error message appears: EXIT: Unexpected error: The input is not a valid Base-64 string ...

查找空气清新的可用空间Find available spaces with fresh air

传感器示例模拟两个传感器的随机数据值。The sensor sample simulates random data values for two sensors. 这两个传感器是移动传感器和二氧化碳传感器。They're motion and carbon dioxide. 在示例中,空气清新的可用空间按定义是指房间没有被占用,Available spaces with fresh air are defined in the sample by no presence in the room. 且二氧化碳水平低于 1,000 ppm。They're also defined by a carbon dioxide level under 1,000 ppm. 如果不满足条件,则表明空间不可用或者空气质量差。If the condition isn't fulfilled, the space isn't available or the air quality is poor.

  1. 打开用于运行早期预配步骤的命令提示符窗口。Open the command prompt you used to run the provisioning step earlier.

  2. 运行 dotnet run GetAvailableAndFreshSpacesRun dotnet run GetAvailableAndFreshSpaces.

  3. 并排查看此命令提示符窗口和传感器数据命令提示符窗口。Look at this command prompt and the sensor data command prompt side by side.

    传感器数据命令提示符窗口每五秒钟向数字孪生发送一次模拟的移动和二氧化碳数据。The sensor data command prompt sends simulated motion and carbon dioxide data to Digital Twins every five seconds. 另一命令提示符以实时方式读取图形,根据随机的模拟数据来找出空气清新的可用房间。The other command prompt reads the graph in real time to find out available rooms with fresh air based on random simulated data. 它会根据上一次发送的传感器数据以近实时方式显示这其中的一个条件:It displays one of these conditions in near real time based on the sensor data that was sent last:

    • Room is available and air is fresh

    • Room is not available or air quality is poor

      获取空气清新的可用空间Get available spaces with fresh air

若要了解本快速入门中的情况以及所调用的 API,请打开 Visual Studio Code,其中的代码工作区项目位于 digital-twins-samples-csharp 中。To understand what happened in this quickstart and what APIs were called, open Visual Studio Code with the code workspace project found in digital-twins-samples-csharp. 使用以下命令:Use the following command:

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

这些教程会详细探讨代码,The tutorials go deep into the code. 并介绍如何修改配置数据以及调用哪些 API。They teach you how to modify configuration data and what APIs are called. 有关管理 API 的详细信息,请转到数字孪生 Swagger 页:For more information on Management APIs, go to your Digital Twins Swagger page:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger
名称Name 替换为Replace with
YOUR_INSTANCE_NAMEYOUR_INSTANCE_NAME 数字孪生实例的名称The name of your Digital Twins instance
YOUR_LOCATIONYOUR_LOCATION 托管实例的服务器区域The server region where your instance is hosted

或者,为了方便,请浏览到数字孪生 SwaggerOr for convenience, browse to Digital Twins Swagger.

清理资源Clean up resources

这些教程详细介绍如何执行以下操作:The tutorials go into detail about how to:

  • 生成应用程序,以便设施管理员提高住户工作效率。Build an application for facility managers to increase occupant productivity.
  • 更有效地运营此大楼。Operate the building more efficiently.

若要继续学习这些教程,请勿清除本快速入门中创建的资源。To continue to the tutorials, don't clean up the resources created in this quickstart. 如果不打算继续学习,请删除通过本快速入门创建的所有资源。If you don't plan to continue, delete all the resources created by this quickstart.

  1. 删除下载示例存储库时创建的文件夹。Delete the folder that was created when you downloaded the sample repository.

  2. Azure 门户左侧的菜单中,选择“所有资源”。 From the menu on the left in the Azure portal, select All resources. 然后,选择数字孪生资源。Then select your Digital Twins resource. 在“所有资源”窗格的顶部选择“删除” 。At the top of the All resources pane, select Delete.

    提示

    如果之前在删除数字孪生实例时遇到麻烦,请使用已推出的包含修补程序的服务更新。If you previously experienced trouble deleting your Digital Twins instance, a service update has been rolled out with the fix. 请重新尝试删除实例。Please retry deleting your instance.

后续步骤Next steps

本快速入门通过简单的方案和示例应用程序演示如何使用数字孪生来查找具有良好工作条件的会议室。This quickstart used a simple scenario and sample applications to show how Digital Twins can be used to find rooms with good working conditions. 若要深入分析此方案,请阅读以下教程:For in-depth analysis of this scenario, read this tutorial: