您现在访问的是微软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 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. 在左窗格中,选择“创建资源”。From the left pane, select Create a resource. 搜索“数字孪生”,选择“数字孪生(预览版)”。Search for digital twins, and select Digital Twins (preview). 选择“创建”,启动部署过程。Select Create to start the deployment process.

    用于创建新数字孪生实例的选项

  3. 在“数字孪生”窗格中,输入以下信息: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.

      包含输入信息的“数字孪生”窗格

  4. 查看数字孪生信息,然后选择“创建”。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.

  5. 打开数字孪生实例的“概览”窗格。Open the Overview pane of your Digital Twins instance. 记下“管理 API”下的链接。Note the link under Management API.

    管理 API URL 的格式为:https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swaggerThe 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 修改成此格式:https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/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

设置应用的权限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.

  1. Azure 门户中,从左窗格打开 Azure Active Directory,然后打开“属性”窗格。In the Azure portal, open Azure Active Directory from the left pane, and then open the Properties pane. 将“目录 ID”复制到一个临时文件。Copy the Directory ID to a temporary file. 将在下一部分使用此值来配置示例应用程序。You'll use this value to configure a sample application in the next section.

    Azure Active Directory 目录 ID

  2. 打开“应用注册”窗格,然后选择“新建应用程序注册”按钮。Open the App registrations pane, and then select the New application registration button.

    “应用注册”窗格

  3. 在“名称”框中,为此应用注册提供一个友好名称。Give a friendly name for this app registration in the Name box. 选择“本机”作为“应用程序类型”,然后选择 https://microsoft.com 作为“重定向 URI”。Choose Application type as Native, and Redirect URI as https://microsoft.com. 选择“创建”。Select Create.

    “创建”窗格

  4. 打开注册的应用,将“应用程序 ID”字段的值复制到一个临时文件中。Open the registered app, and copy the value of the Application ID field to a temporary file. 该值用于标识 Azure Active Directory 应用。This value identifies your Azure Active Directory app. 将在下一部分使用此应用程序 ID 来配置示例应用程序。You'll use the application ID to configure your sample application in the following sections.

    Azure Active Directory 应用程序 ID

  5. 打开应用注册窗格。Open your app registration pane. 选择“设置” > “所需权限”,然后执行以下操作:Select Settings > Required permissions, and then:

    a.在“解决方案资源管理器”中,右键单击项目文件夹下的“引用”文件夹,并单击“添加引用”。a. 在左上角选择“添加”,打开“添加 API 访问权限”窗格。Select Add on the upper left to open the Add API access pane.

    b.b. 选择“选择 API”,搜索“Azure 数字孪生”。Select Select an API and search for Azure Digital Twins. 如果搜索没有找到该 API,请改为搜索“Azure 智能空间”。If your search doesn't locate the API, search for Azure Smart Spaces instead.

    c.c. 选择“Azure 数字孪生(Azure 智能空间服务)”选项,然后选择“选择”。Select the Azure Digital Twins (Azure Smart Spaces Service) option and choose Select.

    d.d. 选择“选择权限”。Choose Select permissions. 选中“读/写访问权限”委托权限复选框,然后选择“选择”。Select the Read/Write Access delegated permissions check box, and choose Select.

    e.e. 在“添加 API 访问权限”窗格中,选择“完成”。Select Done in the Add API access pane.

    f.f. 在“所需的权限”窗格中选择“授予权限”按钮,接受显示的确认。In the Required permissions pane, select the Grant permissions button, and accept the acknowledgement that 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.

预配图形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 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.

    预配示例

  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.

    预配示例

    提示

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

发送传感器数据Send sensor data

请通过以下步骤生成并运行传感器模拟器应用程序。Build and run the sensor simulator 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.

  5. 运行 dotnet run,开始发送传感器数据。Run dotnet run to start sending sensor data. 可以看到数据会被发送到数字孪生,如下图所示。You see it sent to Digital Twins as shown in the following image.

    设备连接性

  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 previous provisioning step.

  2. 运行 dotnet run GetAvailableAndFreshSpacesRun dotnet run GetAvailableAndFreshSpaces.

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

    一个命令提示符窗口每五秒钟向数字孪生发送一次模拟的移动和二氧化碳数据。One command prompt sends simulated motion and carbon dioxide data to Digital Twins every five seconds. 另一命令以实时方式读取图形,根据随机的模拟数据来找出空气清新的可用房间。The other command 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:

    • 房间可用且空气清新。Available rooms with fresh air.

    • 房间已占用或空气质量差。Occupied or poor air quality of the room.

      获取空气清新的可用空间

若要了解本快速入门中的情况以及所调用的 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
NameName 替换为Replace with
YOUR_INSTANCE_NAMEYOUR_INSTANCE_NAME 数字孪生实例的名称The name of your Digital Twins instance
YOUR_LOCATIONYOUR_LOCATION 托管实例的服务器区域Which server region your instance is hosted on

或者,为了方便,请浏览到数字孪生 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 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 to show how to find rooms with good working conditions. 若要深入分析此方案,请参阅以下教程:For in-depth analysis of this scenario, see this tutorial: