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

为 Azure 数字孪生创建数据历史记录连接

项目
01/23/2024

数据历史记录是一项 Azure 数字孪生功能，用于自动将图形更新历史化为 Azure 数据资源管理器。可以使用适用于 Azure 数据资源管理器的 Azure 数字孪生查询插件查询此数据，以便获取一段时间内有关你的环境的见解。

本文介绍如何在 Azure 数字孪生和 Azure 数据资源管理器之间设置有效的数据历史记录连接。它使用 Azure CLI 和 Azure 门户来设置和连接所需的数据历史资源，包括：

Azure 数字孪生实例
包含一个事件中心的事件中心命名空间
包含一个数据库的 Azure 数据资源管理器群集

它还包含一个示例孪生图，可用于在 Azure 数据资源管理器中查看历史记录化图形更新。

提示

虽然本文使用 Azure 门户，但你也可以使用 REST API 的 2022-05-31 版本来处理数据历史记录。

先决条件

为 Azure CLI 准备环境

在 Azure Cloud Shell 中使用 Bash 环境。有关详细信息，请参阅 Azure Cloud Shell 中的 Bash 快速入门。
如需在本地运行 CLI 参考命令，请安装 Azure CLI。如果在 Windows 或 macOS 上运行，请考虑在 Docker 容器中运行 Azure CLI。有关详细信息，请参阅如何在 Docker 容器中运行 Azure CLI。
- 如果使用的是本地安装，请使用 az login 命令登录到 Azure CLI。若要完成身份验证过程，请遵循终端中显示的步骤。有关其他登录选项，请参阅使用 Azure CLI 登录。
- 出现提示时，请在首次使用时安装 Azure CLI 扩展。有关扩展详细信息，请参阅使用 Azure CLI 的扩展。
- 运行 az version 以查找安装的版本和依赖库。若要升级到最新版本，请运行 az upgrade。

注意

如果愿意，还可以在 PowerShell 环境（而不是 Bash 环境）中使用 Azure Cloud Shell。此页面上的命令是针对 Bash 环境编写的，因此可能需要稍作调整才能在 PowerShell 中运行。

设置 CLI 会话

若要开始在 CLI 中使用 Azure 数字孪生，首先要做的是登录并将 CLI 上下文设置为此会话的订阅。在 CLI 窗口中运行以下命令：

az login
az account set --subscription "<your-Azure-subscription-ID>"

提示

在上面的命令中，还可以使用订阅名称而不使用 ID。

如果这是你首次将此订阅与 Azure 数字孪生一起使用，请运行该命令以向 Azure 数字孪生命名空间进行注册。（如果不确定，可以再次运行该命令，即使过去某个时候操作过也是如此。）

az provider register --namespace 'Microsoft.DigitalTwins'

接下来，添加适用于 Azure CLI 的 Microsoft Azure IoT 扩展以支持用于与 Azure 数字孪生和其他 IoT 服务进行交互的命令。运行此命令以确保你已安装最新版本的扩展：

az extension add --upgrade --name azure-iot

现在 Azure 数字孪生已可在 Azure CLI 中使用。

若要验证 Azure 数字孪生在 Cloud Shell 中的就绪性，可以随时运行 az dt --help 查看可用的顶层 Azure 数字孪生命令列表。

为 CLI 会话设置局部变量

本文提供了可用于创建数据历史记录资源的 CLI 命令。为了便于以后复制和运行这些命令，目前可以在 CLI 会话中设置局部变量，然后在创建资源时在 CLI 命令中再引用这些变量。更新以下命令中的占位符（用 <...> 括号标识），并运行这些命令来创建变量。请确保遵循注释中所述的命名规则。稍后将在创建新资源时使用这些值。

注意

这些命令是为 Bash 环境编写的。如果更愿意使用 PowerShell CLI 环境，可以针对 PowerShell 调整这些命令。

## General Setup
location="<your-resource-region>"
resourcegroup="<your-resource-group-name>"

## Azure Digital Twins Setup
# Instance name can contain letters, numbers, and hyphens. It must start and end with a letter or number, and be between 4 and 62 characters long.
dtname="<name-for-your-digital-twins-instance>"
# Connection name can contain letters, numbers, and hyphens. It must contain at least one letter, and be between 3 and 50 characters long.
connectionname="<name-for-your-data-history-connection>"

## Event Hub Setup
# Namespace can contain letters, numbers, and hyphens. It must start with a letter, end with a letter or number, and be between 6 and 50 characters long.
eventhubnamespace="<name-for-your-event-hub-namespace>"
# Event hub name can contain only letters, numbers, periods, hyphens and underscores. It must start and end with a letter or number.
eventhub="<name-for-your-event-hub>"

## Azure Data Explorer Setup
# Cluster name can contain only lowercase alphanumeric characters. It must start with a letter, and be between 4 and 22 characters long.
clustername="<name-for-your-cluster>"  
# Database name can contain only alphanumeric, spaces, dash and dot characters, and be up to 260 characters in length.
databasename="<name-for-your-database>"

# Enter a name for the table where relationship create and delete events will be stored.
relationshiplifecycletablename="<name-for-your-relationship-lifecycle-events-table>"
# Enter a name for the table where twin create and delete events will be stored.
twinlifecycletablename="<name-for-your-twin-lifecycle-events-table>"
# Optionally, enter a custom name for the table where twin property updates will be stored. If not provided, the table will be named AdtPropertyEvents.
twinpropertytablename="<name-for-your-twin-property-events-table>"

创建带有托管标识的 Azure 数字孪生实例

如果已有 Azure 数字孪生实例，请确保已为其启用了系统分配的托管标识。

如果没有 Azure 数字孪生实例，请按照使用托管标识创建实例中的说明操作，以便首次使用系统分配的托管标识创建 Azure 数字孪生实例。

然后，请确保实例上已有“Azure 数字孪生数据所有者”角色。可以在设置用户访问权限中找到说明。

如果要将实例的名称添加到本地 CLI 变量，以便它会自动插入从本文复制的后续命令中，请将它存储在如下所示的变量 dtname 中：

dtname="<name-of-your-instance>"

创建事件中心命名空间和事件中心

下一步是创建事件中心命名空间和事件中心。此中心将从 Azure 数字孪生实例接收图形生命周期和属性更新通知，然后将消息转发到目标 Azure 数据资源管理器群集。

作为数据历史记录连接设置的一部分，你可以在以后向 Azure 数字孪生实例授予事件中心资源上的“Azure 事件中心数据所有者”角色。

有关事件中心及其功能的详细信息，请参阅事件中心文档。

注意

设置数据历史记录时，必须在 事件中心启用 本地授权。如果最终希望在事件中心上禁用本地授权，请在设置连接后禁用授权。还需要调整一些权限，如本文后面的“限制对数据历史记录资源的网络访问”中所述。

CLI
Portal

使用以下 CLI 命令来创建所需的资源。该命令使用之前在为 CLI 会话设置局部变量中创建的多个局部变量（$location、$resourcegroup、$eventhubnamespace 和 $eventhub）。

创建事件中心命名空间：

az eventhubs namespace create --name $eventhubnamespace --resource-group $resourcegroup --location $location

在事件中心命名空间中创建事件中心：

az eventhubs eventhub create --name $eventhub --resource-group $resourcegroup --namespace-name $eventhubnamespace

创建 Kusto（Azure 数据资源管理器）群集和数据库

接下来，创建 Kusto（Azure 数据资源管理器）群集和数据库以接收来自 Azure 数字孪生的数据。

作为数据历史连接设置的一部分，稍后将为 Azure 数字孪生实例至少授予数据库上的“参与者”角色（它还可以限定到群集），以及授予数据库上的“管理员”角色。

重要

确保群集已启用公用网络访问。如果 Azure 数据资源管理器群集已禁用公共网络访问，Azure 数字孪生将无法配置表和其他所需项目，并且数据历史记录设置将失败。

CLI
Portal

使用以下 CLI 命令来创建所需的资源。该命令使用之前在为 CLI 会话设置局部变量中创建的多个局部变量（$location、$resourcegroup、$clustername 和 $databasename）。

首先将 Kusto 扩展添加到 CLI 会话（如果尚未添加）。

az extension add --name kusto

接下来，创建 Kusto 群集。以下命令需要 5-10 分钟才能执行完毕，并将在开发人员层级中创建 E2a v4 群集。此类群集为引擎和数据管理群集提供单个节点，适用于开发和测试方案。有关 Azure 数据资源管理器中的层级以及如何为生产工作负载选择合适选项的详细信息，请参阅为 Azure 数据资源管理器群集选择正确的计算 SKU 和 Azure 数据资源管理器定价。

az kusto cluster create --cluster-name $clustername --sku name="Dev(No SLA)_Standard_E2a_v4" tier="Basic" --resource-group $resourcegroup --location $location --type SystemAssigned

在新的 Kusto 群集中创建一个数据库（使用上面的群集名称并在同一位置）。此数据库将用于存储上下文化的 Azure 数字孪生数据。下面的命令将创建一个软删除周期为 365 天、热缓存周期为 31 天的数据库。有关可用于此命令的选项的详细信息，请参阅 az kusto database create。

az kusto database create --cluster-name $clustername --database-name $databasename --resource-group $resourcegroup --read-write-database soft-delete-period=P365D hot-cache-period=P31D location=$location

设置数据历史记录连接

创建所需的资源后，请使用本节中的命令在 Azure 数字孪生实例、事件中心和 Azure 数据资源管理器群集之间创建数据历史记录连接。

此命令还将在 Azure 数据资源管理器数据库中创建三个表，分别存储孪生属性更新、孪生生命周期事件和关系生命周期事件。有关这些类型历史记录化数据及其相应的 Azure 数据资源管理器表的详细信息，请参阅数据类型和架构。

CLI
Portal

使用本节中的命令创建数据历史记录连接和 Azure 数据资源管理器中的表。该命令将始终为历史记录化孪生属性事件创建表，并包括用于创建关系生命周期和孪生生命周期事件的表的参数。

注意

默认情况下，此命令假定所有资源都与 Azure 数字孪生实例位于同一资源组中。可以使用此命令的参数选项指定位于不同资源组中的资源。

以下命令使用前面在设置 CLI 会话的局部变量中创建的局部变量，并具有多个参数，包括...

Azure 数据资源管理器中关系生命周期表和孪生生命周期表的名称（如果不想将这些事件类型进行历史记录化，则这些参数是可选的，但如果确实要对这些事件类型进行历史记录化，则是必需的）
一个可选参数，用于指定孪生属性事件表的名称（如果未提供此值，则默认情况下，此表将命名 为 AdtPropertyEvents ）。如果不想指定其他名称，请在运行该参数之前从命令中删除 --adx-property-events-table 该参数。
用于为孪生属性删除启用历史记录化的可选参数 --adx-record-removals （完全删除属性的事件）

az dt data-history connection create adx --dt-name $dtname --cn $connectionname --adx-cluster-name $clustername --adx-database-name $databasename --eventhub $eventhub --eventhub-namespace $eventhubnamespace --adx-property-events-table $twinpropertytablename --adx-twin-events-table $twinlifecycletablename --adx-relationship-events-table $relationshiplifecycletablename --adx-record-removals true

执行上述命令时，可以选择分配代表你设置数据历史连接所需的必要权限（如果已经分配了必要的权限，则可以跳过这些提示）。这些权限被授予 Azure 数字孪生实例的托管标识。所需的最低角色为：

事件中心上的“Azure 事件中心数据所有者”
作用范围至少限定于指定的数据库（也可以限定于群集）的“参与者”
具有“管理员”角色（作用范围限定于指定的数据库）的数据库主体分配（用于表创建/管理）

对于常规数据平面操作，如果需要，可以将这些角色缩减为单个“Azure 事件中心数据发送者”角色。

设置数据历史记录连接后，可以选择删除授予 Azure 数字孪生实例的用于访问事件中心和 Azure 数据资源管理器资源的角色。为了使用数据历史记录，实例需要的唯一角色是事件中心资源上的“Azure 事件中心数据发送者”（或包含这些权限的更高角色，例如“Azure 事件中心数据所有者”）。

注意

设置连接后，Azure 数据资源管理器群集上的默认设置将导致大约不超过 10 分钟的引入延迟。可以通过启用流式引入（小于 10 秒的延迟）或引入批处理策略来减少此延迟。有关 Azure 数据资源管理器引入延迟的信息，请参阅端到端的引入延迟。

限制对数据历史记录资源的网络访问

如果想要限制对数据历史记录中涉及的资源的网络访问（Azure 数字孪生实例、事件中心或 Azure 数据资源管理器群集），则应在设置数据历史记录连接后设置这些限制。这包括禁用资源的本地访问，以及其他减少网络访问的措施。

若要确保数据历史记录资源可以相互通信，还应修改 Azure 数据资源管理器数据库的数据连接，以使用系统分配的托管标识。

按照以下步骤的顺序操作，确保在资源需要减少网络访问时正确设置数据历史记录连接。

确保在数据历史记录资源上启用了本地授权（Azure 数字孪生实例、事件中心和 Azure 数据资源管理器群集）
创建数据历史记录连接
更新 Azure 数据资源管理器数据库的数据连接，以使用系统分配的托管标识。在Azure 门户中，可以通过导航到 Azure 数据资源管理器群集并使用菜单中的数据库导航到数据历史记录数据库来执行此操作。在数据库菜单中，选择“ 数据连接”。在数据历史记录连接的表项中，应会看到“分配托管标识”选项，可在其中选择“系统分配”。
现在，可以通过更改 Azure 数字孪生实例、事件中心或 Azure 数据资源管理器群集上的访问设置来禁用本地授权或设置所需的资源的其他网络限制。

排查连接设置问题

下面是设置数据历史记录连接时可能会遇到的一些常见错误，以及如何解决这些问题。

如果为 Azure 数据资源管理器群集禁用了公用网络访问，则服务无法创建数据历史记录连接时遇到错误，并显示消息“由于内部服务器错误，资源无法 ACT”。如果 Azure 数据资源管理器群集已禁用公用网络访问，则数据历史记录设置将失败，因为 Azure 数字孪生将无法配置表和其他所需项目。
（CLI 用户）如果遇到错误“无法创建 Azure 数字孪生实例连接”。无法在数据库中创建表和映射规则。请检查你对 Azure 数据库资源管理器的权限并运行 az login 以刷新凭据”，请通过在 Azure 数据资源管理器群集的“权限”下将自己添加为 AllDatabasesAdmin 来解决该错误。
（Cloud Shell 用户）如果使用的是 Cloud Shell，并遇到“无法连接到 MSI”错误。请确保 MSI 配置正确”，请尝试改用本地 Azure CLI 安装运行该命令。

使用示例孪生体图进行验证

设置数据历史记录连接后，可以使用数字孪生体的数据进行测试。

如果 Azure 数字孪生实例中已有正在主动接收图形更新的孪生体（包括孪生属性更新或通过创建或删除元素来更改图形结构更新），则可以跳过本部分，并使用自己的资源可视化结果。

否则，请继续本部分，设置将经历孪生和关系生命周期事件并生成孪生属性更新的示例图。

可以使用 Azure 数字孪生数据模拟器为此场景设置示例图。 Azure 数字孪生数据模拟器在 Azure 数字孪生实例中创建孪生体和关系，并持续将属性更新推送到孪生体。

创建示例图

可以使用 Azure 数字孪生数据模拟器来预配示例孪生体图并将属性更新推送到其中。此处创建的孪生体图为一家乳制品公司的巴氏杀菌过程建模。

首先在浏览器中打开 Azure 数字孪生数据模拟器。设置这些字段：

实例 URL：输入 Azure 数字孪生实例的主机名。主机名可以在实例的门户页面中找到，其格式类似于 <Azure-Digital-Twins-instance-name>.api.<region-code>.digitaltwins.azure.net。
模拟类型：从下拉菜单中选择乳品设施。

选择“生成环境”。

Screenshot of the Azure Digital Twins Data simulator.

在环境中创建模型、孪生体和关系时，屏幕上将显示确认消息。这还将生成孪生和关系创建事件，这些事件将分别作为孪生事件和关系生命周期事件进行历史记录化到 Azure 数据资源管理器。

模拟准备就绪后，“开始模拟”按钮将处于已启用状态。向下滚动并选择“开始模拟”，将模拟数据推送到 Azure 数字孪生实例。若要持续更新 Azure 数字孪生实例中的孪生体，请将此浏览器窗口保留在桌面的前景中，并在单独的窗口中完成其他浏览器操作。这将持续生成将历史记录化到 Azure 数据资源管理器的孪生属性更新事件。

在 Azure 数据资源管理器中查看历史记录更新

本部分介绍如何查看模拟器生成并存储在 Azure 数据资源管理器表中的所有三种类型的历史记录化更新。

在 Azure 门户中开始并导航到以前创建的 Azure 数据资源管理器群集。从左侧菜单中选择“数据库”窗格以打开数据库视图。找到你为本文创建的数据库并选中它旁边的复选框，然后选择“查询”。

Screenshot of the Azure portal showing a database in an Azure Data Explorer cluster.

接下来，展开左窗格中的群集和数据库以查看数据历史记录表的名称。应有三个：一个用于关系生命周期事件，一个用于孪生生命周期事件，一个用于孪生属性更新事件。你将使用这些表名称对表运行查询，以验证和查看历史记录化数据。

验证表项

若要验证事件是否正在向数据库进行历史记录化，请首先复制以下命令。它具有关系生命周期事件表名称的占位符，它将表的引入更改为批处理模式，以便每 10 秒从实时模拟引入数据。

.alter table <relationship-lifecycle-events-table-name> policy ingestionbatching @'{"MaximumBatchingTimeSpan":"00:00:10", "MaximumNumberOfItems": 500, "MaximumRawDataSizeMB": 1024}'

将命令粘贴到查询窗口中，将占位符替换为关系事件表的名称。选择 “运行 ”按钮以运行命令。

使用孪生生命周期事件表的名称和属性更新表再次重复该命令，以更新其他表的引入模式。

接下来，将以下命令添加到查询窗口并运行它们。每个命令都包含一个表名称的占位符，这些命令将输出表中的项数。

注意

最多可能需要 5 分钟才能显示第一批引入的数据。

<relationship-lifecycle-events-table-name>
| count

<twin-lifecycle-events-table-name>
| count

<twin-property-updates-table-name>
| count

应在结果中看到，每个表中的项计数大于 0，表示关系生命周期、孪生生命周期和属性更新事件正被历史记录化为其各自的表。

浏览孪生属性更新表

在本部分中，你将对表中的孪生属性更新数据进行更多探索。

首先运行以下命令，查看表中的 100 条记录：

<twin-property-updates-table-name>
| limit 100

接下来，根据孪生体的数据运行查询，以查看已上下文化的时序数据。

使用以下查询绘制奥斯陆乳品厂样本中所有盐机孪生体的外流图。此 Kusto 查询使用 Azure 数字孪生插件选择感兴趣的孪生体，根据 Azure 数据资源管理器中的数据历史记录时序联接这些孪生体，然后绘制结果图表。请确保将 <ADT-instance-host-name> 占位符替换为实例的主机名，并将 <table-name> 占位符替换为孪生属性事件表的名称。

let ADTendpoint = "https://<ADT-instance-host-name>";
let ADTquery = ```SELECT SALT_MACHINE.$dtId as tid
FROM DIGITALTWINS FACTORY 
JOIN SALT_MACHINE RELATED FACTORY.contains 
WHERE FACTORY.$dtId = 'OsloFactory'
AND IS_OF_MODEL(SALT_MACHINE , 'dtmi:assetGen:SaltMachine;1')```;
evaluate azure_digital_twins_query_request(ADTendpoint, ADTquery)
| extend Id = tostring(tid)
| join kind=inner (<table-name>) on Id
| extend val_double = todouble(Value)
| where Key == "OutFlow"
| render timechart with (ycolumns = val_double)

结果应显示输出数字随着时间的推移而更改。

连接疑难解答

如果在 Azure 数据资源管理器中看不到数据，则历史记录化数据流无法正常工作。可以通过在Azure 门户中查看事件中心命名空间来调查此问题，该命名空间显示消息进出命名空间的图表。这样，就可以验证来自 Azure 数字孪生的传入消息流和传出消息流到 Azure 数据资源管理器，以帮助确定流中哪些部分不起作用。

后续步骤

若要继续探索乳制品方案，可以在 GitHub 上查看更多示例查询，这些查询显示如何基于机器类型、工厂、维护技术人员以及这些参数的各种组合来监视乳制品公司运营的绩效。

若要构建用于将乳制品公司运营绩效可视化的 Grafana 仪表板，请阅读使用 Azure 数字孪生、Azure 数据资源管理器和 Grafana 创建仪表板。

有关使用适用于 Azure 数据资源管理器的 Azure 数字孪生查询插件的详细信息，请参阅使用 Azure 数据资源管理器插件进行查询和这篇博客文章。可以在此处详细了解该插件：使用 Azure 数据资源管理器插件进行查询。

通过