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

将 Azure 数字孪生与 Azure 时序见解相集成

  • 项目

本文介绍如何将 Azure 数字孪生与 Azure 时序见解 (TSI) 相集成。

本文中所述的解决方案使用时序见解收集和分析有关你的 IoT 解决方案的历史数据。 Azure 数字孪生适合用于将数据馈送到时序见解中，因为它支持关联多个数据流，并可在将信息发送到时序见解之前将信息标准化。

提示

分析一段时间内的历史孪生数据的最简单方法是使用数据历史记录功能将 Azure 数字孪生实例连接到 Azure 数据资源管理器 群集，以便图形更新自动历史记录化到 Azure 数据资源管理器。 然后，你可以使用 Azure 数据资源管理器的 Azure 数字孪生查询插件在 Azure 数据资源管理器中查询此数据。 如果你不需要专门使用时序见解，则可以考虑使用此替代方法来简化集成体验。

先决条件

需要设置以下资源，才能设置与时序见解的关系：

提示

在本文中，为简单起见，手动更新在时序见解中查看的不断更改的数字孪生体值。 但是，如果要使用实时模拟数据完成本文，可以设置一个 Azure 函数，用于根据来自模拟设备的 IoT 遥测事件更新数字孪生体。 有关说明，请遵循引入 IoT 中心数据操作，包括运行设备模拟器并验证数据流是否正常工作的最终步骤。

稍后，查找另一个提示以显示开始运行设备模拟器的位置，并让 Azure Functions 自动更新孪生体，而不是发送手动数字孪生体更新命令。

解决方案体系结构

你将通过以下路径将时序见解附加到 Azure 数字孪生。

端到端方案中的 Azure 服务图，其中突出显示了“时序见解”。

创建事件中心命名空间

创建事件中心之前，请先创建一个可从 Azure 数字孪生实例接收事件的事件中心命名空间。 可以参考以下 Azure CLI 说明，也可以按照使用 Azure 门户创建事件中心使用 Azure 门户。 若要查看哪些区域支持事件中心，请访问可用的 Azure 产品（按区域）。

az eventhubs namespace create --name <name-for-your-Event-Hubs-namespace> --resource-group <your-resource-group> --location <region>

提示

如果收到错误消息，其中声明 BadRequest: The specified service namespace is invalid.，请确保为命名空间选择的名称满足此参考文档中所述的命名要求：创建命名空间。

你会使用此事件中心命名空间来容纳本文所需的两个事件中心：

  1. 孪生体中心 - 用于接收孪生体更改事件的事件中心
  2. 时序中心 - 用于将事件流式传输到时序见解的事件中心

后续各部分会指导你在事件中心命名空间中创建和配置这些中心。

创建孪生体中心

你在本文中创建的第一个事件中心是孪生体中心。 此事件中心会从 Azure 数字孪生接收孪生体更改事件。 若要设置孪生体中心，请完成本部分中的以下步骤：

  1. 创建孪生体中心
  2. 创建一个授权规则以控制对中心的权限
  3. 在 Azure 数字孪生中创建一个终结点，它使用授权规则访问中心
  4. 在 Azure 数字孪生中创建一个路由，它将孪生体更新事件发送到终结点和所连接的孪生体中心
  5. 获取孪生体中心连接字符串

使用以下 CLI 命令创建孪生体中心。 为孪生体中心指定名称。

az eventhubs eventhub create --name <name-for-your-twins-hub> --resource-group <your-resource-group> --namespace-name <your-Event-Hubs-namespace-from-earlier>

创建孪生体中心授权规则

创建具有发送和接收权限的授权规则。 指定规则的名称。

az eventhubs eventhub authorization-rule create --rights Listen Send --name <name-for-your-twins-hub-auth-rule> --resource-group <your-resource-group> --namespace-name <your-Event-Hubs-namespace-from-earlier> --eventhub-name <your-twins-hub-from-earlier>

创建孪生体中心终结点

创建一个 Azure 数字孪生终结点，用于将事件中心链接到 Azure 数字孪生实例。 为孪生体中心终结点指定名称。

az dt endpoint create eventhub --dt-name <your-Azure-Digital-Twins-instance-name> --eventhub-resource-group <your-resource-group> --eventhub-namespace <your-Event-Hubs-namespace-from-earlier> --eventhub <your-twins-hub-name-from-earlier> --eventhub-policy <your-twins-hub-auth-rule-from-earlier> --endpoint-name <name-for-your-twins-hub-endpoint>

创建孪生体中心事件路由

每当孪生的状态更新后，Azure 数字孪生实例都可以发出孪生更新事件。 在本部分，你将创建一个 Azure 数字孪生事件路由，它会将这些更新事件定向到孪生体中心以供进一步处理。

在 Azure 数字孪生中创建路由，将孪生体更新事件发送到前面的终结点。 此路由中的筛选器只允许将孪生更新消息传递到你的终结点。 为孪生体中心事件路由指定名称。 对于此命令中的 Azure 数字孪生实例名称占位符，可以使用易记名称或主机名来提高性能。

az dt route create --dt-name <your-Azure-Digital-Twins-instance-hostname-or-name> --endpoint-name <your-twins-hub-endpoint-from-earlier> --route-name <name-for-your-twins-hub-event-route> --filter "type = 'Microsoft.DigitalTwins.Twin.Update'"

获取孪生体中心连接字符串

使用前面为孪生体中心创建的授权规则获取孪生体事件中心连接字符串。

az eventhubs eventhub authorization-rule keys list --resource-group <your-resource-group> --namespace-name <your-Event-Hubs-namespace-from-earlier> --eventhub-name <your-twins-hub-from-earlier> --name <your-twins-hub-auth-rule-from-earlier>

记下结果中的 primaryConnectionString 值，以在本文后面配置孪生体中心应用设置。

创建时序中心

你在本文中创建的第二个事件中心是时序中心。 此事件中心会将 Azure 数字孪生事件流式传输到时序见解。 若要设置时序中心，请完成以下步骤：

  1. 创建时序中心
  2. 创建一个授权规则以控制对中心的权限
  3. 获取时序中心连接字符串

以后，当你创建时序见解实例时，会将此时序中心作为时序见解实例的事件源进行连接。

使用以下命令创建时序中心。 为时序中心指定名称。

 az eventhubs eventhub create --name <name-for-your-time-series-hub> --resource-group <your-resource-group> --namespace-name <your-Event-Hub-namespace-from-earlier>

创建时序中心授权规则

创建具有发送和接收权限的授权规则。 为时序中心授权规则指定名称。

az eventhubs eventhub authorization-rule create --rights Listen Send --name <name-for-your-time-series-hub-auth-rule> --resource-group <your-resource-group> --namespace-name <your-Event-Hub-namespace-from-earlier> --eventhub-name <your-time-series-hub-name-from-earlier>

获取时序中心连接字符串

使用前面为时序见解中心创建的授权规则获取时序中心连接字符串：

az eventhubs eventhub authorization-rule keys list --resource-group <your-resource-group> --namespace-name <your-Event-Hub-namespace-from-earlier> --eventhub-name <your-time-series-hub-name-from-earlier> --name <your-time-series-hub-auth-rule-from-earlier>

记下结果中的 primaryConnectionString 值，以在本文后面配置时序中心应用设置。

另外请记下以下值，以便以后使用它们创建时序见解实例。

  • 事件中心命名空间
  • 时序中心名称
  • 时序中心授权规则

创建函数

在本部分，你会创建一个 Azure 函数，它会将孪生体更新事件从其原始的 JSON 补丁文档形式转换为 JSON 对象，其中仅包含来自孪生体的已更新值和添加的值。

  1. 首先，创建新的函数应用项目。

    可以使用 Visual Studio（相关说明，请参阅使用 Visual Studio 开发 Azure Functions），Visual Studio Code（相关说明，请参阅在 Azure 中使用 Visual Studio Code 创建 C# 函数）或 Azure CLI（相关说明，请参阅在 Azure 中从命令行创建 C# 函数）来执行此操作。

  2. 创建名为 ProcessDTUpdatetoTSI.cs 的新 Azure 函数，以将设备遥测事件更新到时序见解。 函数类型是“事件中心触发器”。

    创建类型为事件中心触发器的新 Azure 函数的 Visual Studio 的屏幕截图。

  3. 将以下包添加到项目（可以使用 Visual Studio NuGet 包管理器，或者使用命令行工具中的 dotnet add package 命令）。

  4. 将 ProcessDTUpdatetoTSI.cs 文件中的代码替换为以下代码：

    using System.Collections.Generic;
using System.Threading.Tasks;
using System.Text;
using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using Azure.Messaging.EventHubs;

namespace UpdateTSI
{
    public static class ProcessDTUpdatetoTSI
    { 
        [FunctionName("ProcessDTUpdatetoTSI")]
        public static async Task Run(
            [EventHubTrigger("twins-event-hub", Connection = "EventHubAppSetting-Twins")]EventData myEventHubMessage,
            [EventHub("tsi-event-hub", Connection = "EventHubAppSetting-TSI")]IAsyncCollector<string> outputEvents,
            ILogger log)
        {
            JObject message = (JObject)JsonConvert.DeserializeObject(Encoding.UTF8.GetString(myEventHubMessage.Body));
            log.LogInformation($"Reading event: {message}");

            // Read values that are replaced or added
            var tsiUpdate = new Dictionary<string, object>();
            foreach (var operation in message["patch"])
            {
                if (operation["op"].ToString() == "replace" || operation["op"].ToString() == "add")
                {
                    //Convert from JSON patch path to a flattened property for TSI
                    //Example input: /Front/Temperature
                    //        output: Front.Temperature
                    string path = operation["path"].ToString().Substring(1);
                    path = path.Replace("/", ".");
                    tsiUpdate.Add(path, operation["value"]);
                }
            }
            // Send an update if updates exist
            if (tsiUpdate.Count > 0)
            {
                tsiUpdate.Add("$dtId", myEventHubMessage.Properties["cloudEvents:subject"]);
                await outputEvents.AddAsync(JsonConvert.SerializeObject(tsiUpdate));
            }
        }
    }
}

    保存函数代码。

  5. 将包含 ProcessDTUpdatetoTSI.cs 函数的项目发布到 Azure 中的函数应用。

    若要了解如何使用 Visual Studio 发布函数，请参阅使用 Visual Studio 开发 Azure Functions。 若要了解如何使用 Visual Studio Code 发布函数，请参阅使用 Visual Studio Code 在 Azure 中创建 C# 函数。 若要了解如何使用 Azure CLI 发布函数，请参阅在 Azure 中从命令行创建 C# 函数。

保存函数应用名称，以便以后用于为两个事件中心配置应用设置。

配置函数应用

接下来，为函数分配访问角色并配置应用程序设置，使之能够访问你的资源 。

在 Azure Cloud Shell 或本地 Azure CLI 中运行以下命令。

注意

此部分必须由有权管理用户对 Azure 资源的用户访问权限（包括授予和委派权限）的 Azure 用户完成。 满足此要求的常见角色包括“所有者”、“帐户管理员”或“用户访问管理员”和“参与者”的组合。 有关 Azure 数字孪生角色的权限要求的详细信息，请参阅设置实例和身份验证。

分配访问角色

Azure 函数需要将持有者令牌传递给它。 为确保传递了持有者令牌，请为函数应用授予 Azure 数字孪生实例的“Azure 数字孪生数据所有者”角色，这将授予函数应用在实例上执行数据平面活动的权限。

  1. 使用以下命令为函数创建系统托管标识（如果该函数已有一个，此命令将输出其详细信息）。 记下输出中的 principalId 字段。 你将使用此 ID 来引用函数，以便可以在下一步中授予其权限。

    az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>

  2. 使用以下命令中的 principalId 值为函数赋予 Azure 数字孪生实例的“Azure 数字孪生数据所有者”角色。

    az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"

配置应用程序设置

接下来，通过为函数设置环境变量使其可以访问 Azure 数字孪生实例的 URL。

提示

通过将 https:// 添加到实例主机名的开头，创建 Azure 数字孪生实例的 URL。 若要查看主机名以及实例的所有属性，请运行 az dt show --dt-name <your-Azure-Digital-Twins-instance>。

以下命令为实例的 URL 设置环境变量，函数在需要访问实例时将使用该环境变量。

az functionapp config appsettings set --resource-group <your-resource-group> --name <your-function-app-name> --settings "ADT_SERVICE_URL=https://<your-Azure-Digital-Twins-instance-host-name>"

接下来在函数应用的设置中添加环境变量，使它可以访问孪生体中心和时序中心 。

使用先前保存的孪生体中心 primaryConnectionString 值在函数应用中创建包含孪生体中心连接字符串的应用设置：

az functionapp config appsettings set --settings "EventHubAppSetting-Twins=<your-twins-hub-primaryConnectionString>" --resource-group <your-resource-group> --name <your-function-app-name>

使用先前保存的时序中心 primaryConnectionString 值在函数应用中创建包含时序中心连接字符串的应用设置：

az functionapp config appsettings set --settings "EventHubAppSetting-TSI=<your-time-series-hub-primaryConnectionString>" --resource-group <your-resource-group> --name <your-function-app-name>

创建和连接时序见解实例

在本部分中，你会设置时序见解实例以从时序中心接收数据。 有关此过程的详细信息，请参阅设置 Azure 时序见解 Gen2 PAYG 环境。 按照以下步骤创建时序见解环境。

  1. 在 Azure 门户中，搜索“时序见解环境”，然后选择“创建”按钮。 选择以下选项以创建时序环境。

    • 订阅 - 选择订阅。
      • 资源组 - 选择资源组。
    • 环境名称 - 为时序环境指定名称。
    • 位置 - 选择位置。
    • 层 - 选择“Gen2(L1)”定价层。
    • 属性名称 - 输入“$dtId”（在选择时序 ID 的最佳做法中详细了解如何选择 ID 值）。
    • 存储帐户名称 - 指定存储帐户名称。
    • 启用热存储 - 将此字段设置为“是”。

    可以在此页面上保留其他属性的默认值。 选择“下一步: 事件源 >”按钮。

    Azure 门户的屏幕截图，显示了如何创建时序见解环境（第 1/3 部分）。

    Azure 门户的屏幕截图，显示了如何创建时序见解环境（第 2/3 部分）。

  2. 在“事件源”选项卡上，选择以下字段：

    • 创建事件源? - 选择“是”。
    • 源类型 - 选择“事件中心”。
    • 名称 - 为事件源指定名称。
    • 订阅 - 选择自己的 Azure 订阅。
    • 事件中心命名空间 - 选择在本文前面部分创建的命名空间。
    • 事件中心名称 - 选择在本文前面部分创建的时序中心名称。
    • 事件中心访问策略名称 - 选择在本文前面部分创建的时序中心授权规则。
    • 事件中心使用者组 - 选择“新建”，并为事件中心使用者组指定名称。 然后选择“添加”。
    • 属性名称将此字段留空。

    选择“查看 + 创建”按钮以查看所有详细信息。 然后，再次选择“查看 + 创建”按钮以创建时序环境。

    Azure 门户的屏幕截图，显示了如何创建时序见解环境（第 3/3 部分）。

将 IoT 数据发送到 Azure 数字孪生

若要开始将数据发送到时序见解，需要开始更新 Azure 数字孪生中的数字孪生体属性并更改数据值。

使用 az dt twin update CLI 命令更新在先决条件部分中添加的孪生体的属性。 如果使用了从 IoT 中心引入遥测数据的孪生体创建说明，则可以在本地 CLI 或 Cloud Shell bash 终端中使用以下命令更新 thermostat67 孪生体上的温度属性。 Azure 数字孪生 实例的主机名有一个占位符（也可以使用实例的易记名称，但性能会略有下降）。

az dt twin update --dt-name <your-Azure-Digital-Twins-instance-hostname-or-name> --twin-id thermostat67 --json-patch '{"op":"replace", "path":"/Temperature", "value": 20.5}'

使用不同属性值再重复该命令至少 4 次，以创建稍后可在时序见解环境中观察到的多个数据点。

提示

如果要使用实时模拟数据完成本文，而不是手动更新数字孪生体值，请先确保已完成先决条件部分中的提示，设置从模拟设备更新孪生体的 Azure 函数。 在此之后，可以立即运行设备，以开始发送模拟数据并通过该数据流更新数字孪生体。

在时序见解中可视化数据

数据现在应流向时序见解实例并且可供分析。 按照以下步骤浏览传入的数据。

  1. 在 Azure 门户中，搜索先前创建的时序环境名称。 在左侧菜单选项中，选择“概述”以查看“时序见解资源管理器 URL” 。 选择 URL 以查看在时序见解环境中反映的温度变化。

    Azure 门户的屏幕截图，其中在时序见解环境的概述选项卡中显示时序见解资源管理器 URL。

  2. 在资源管理器的左侧，你会看到显示了 Azure 数字孪生实例中的孪生体。 选择已为其编辑属性的孪生体，选择已更改的属性，然后选择“添加”。

    时序见解资源管理器的屏幕截图，突出显示了选择 thermostat67、选择属性 temperature 和选择“添加”的步骤。

  3. 现在你应该看到所做的属性更改反映在图形中，如下所示。

    带有初始温度数据的时序见解资源管理器的屏幕截图，显示了一系列介于 68 到 85 之间的随机值。

如果运行模拟很长一段时间，则可视化效果将如下所示：

时序见解资源管理器的屏幕截图，其中以三条不同颜色的平行线绘制每个孪生体的温度数据。

后续步骤

建立数据管道以将时序数据从 Azure 数字孪生发送到时序见解后，可能需要考虑如何将专为 Azure 数字孪生设计的资产模型转换为时序见解的资产模型。 有关集成过程中下一步的教程，请参阅 Azure 数字孪生与时序见解 Gen2 之间的模型同步。