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

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

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

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

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

先决条件

为 Azure CLI 准备环境

• 在 Azure Cloud Shell 中使用 Bash 环境。 有关详细信息，请参阅开始使用 Azure Cloud Shell。

  

• 如需在本地运行 CLI 参考命令，请安装 Azure CLI。 如果在 Windows 或 macOS 上运行，请考虑在 Docker 容器中运行 Azure CLI。 有关详细信息，请参阅如何在 Docker 容器中运行 Azure CLI。

  • 如果使用的是本地安装，请使用 az login 命令登录到 Azure CLI。 若要完成身份验证过程，请遵循终端中显示的步骤。 有关其他登录选项，请参阅 使用 Azure CLI 向 Azure 进行身份验证。

  • 出现提示时，请在首次使用时安装 Azure CLI 扩展。 有关扩展详细信息，请参阅使用和管理 Azure CLI 的扩展。

  • 运行az version命令，以查看已安装的版本和依赖库。 若要升级到最新版本，请运行az upgrade。

设置 CLI 会话

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

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

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

az provider register --namespace 'Microsoft.DigitalTwins'

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

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

现在，你已准备好在 Azure CLI 中使用 Azure 数字孪生。

可以通过随时运行 az dt --help 来验证此状态，以查看可用的顶级 Azure 数字孪生命令列表。

为 CLI 会话设置本地变量

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

## 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 are stored.
relationshiplifecycletablename="<name-for-your-relationship-lifecycle-events-table>"
# Enter a name for the table where twin create and delete events are stored.
twinlifecycletablename="<name-for-your-twin-lifecycle-events-table>"
# Optionally, enter a custom name for the table where twin property updates are stored. If not provided, the table is 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 事件中心数据所有者 角色。

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

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 数字孪生实例至少授予数据库上的“参与者”角色（它还可以限定到群集），以及授予数据库上的“管理员”角色。

az extension add --name kusto

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

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 数据资源管理器表的详细信息，请参阅 数据类型和架构。

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 数据资源管理器数据库的数据连接，以使用系统分配的托管标识。

若要确保在资源需要减少网络访问时正确设置数据历史记录连接，请按顺序执行以下步骤：

1. 确保对数据历史记录资源（Azure 数字孪生实例、事件中心和 Azure 数据资源管理器群集）启用了本地授权
2. 创建数据历史记录连接
3. 更新 Azure 数据资源管理器数据库的数据连接，以使用系统分配的托管标识。 在 Azure 门户中，可以通过导航到 Azure 数据资源管理器群集并使用菜单中 的数据库 导航到数据历史记录数据库来更新数据连接。 在数据库菜单中，选择 “数据连接”。 在数据历史记录连接的表项中，应会看到 “分配托管标识”选项，可在其中选择 “系统分配”。
4. 现在，可以通过更改 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。
• 模拟类型：从下拉菜单中选择“乳品设施”。

选择“ 生成环境”。

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

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

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

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

从 Azure 门户 开始，导航到之前创建的 Azure 数据资源管理器群集。 从左侧菜单中选择 “查询 ”窗格，在 “数据”下打开查询视图。

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

验证表格条目

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

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

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

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

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

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

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

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

应该在结果中看到，每个表中的项计数大于零，这表明属性更新、关系生命周期和孪生生命周期事件正被记录到各自的表中。

浏览孪生属性更新表

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

首先运行以下命令，查看表中的 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 数据资源管理器插件进行查询。