你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
数据历史记录 是 Azure 数字孪生的集成功能。 它允许将 Azure 数字孪生实例连接到 Azure 数据资源管理器 群集，以便自动将图形更新历史记录化到 Azure 数据资源管理器。 这些历史记录更新包括孪生属性更新、孪生生命周期事件和关系生命周期事件。
将图形更新历史记录化到 Azure 数据资源管理器后，可以使用 Azure 数据资源管理器的 Azure 数字孪生插件 运行联合查询，以便跨数字孪生、关系和时序数据进行推理。 这可用于及时查看图形的状态，或深入了解建模环境的行为。 还可以使用这些查询为作仪表板提供支持、丰富 2D 和 3D Web 应用程序，以及推动沉浸式增强/混合现实体验，以传达 Azure 数字孪生中建模的资产、流程和人员的当前和历史状态。
有关数据历史记录（包括快速演示）的详细信息，请观看以下 IoT 演示视频：
数据历史记录发出的消息是在消息定价维度下计量的。
先决条件：资源和权限
数据历史记录需要以下资源：
- 启用了系统分配的托管标识的 Azure 数字孪生实例。
- 事件中心命名空间，包含一个事件中心。
- 包含数据库的 Azure 数据资源管理器群集。 群集必须启用公用网络访问。
这些资源已连接到以下流：
更新数字孪生图后，信息会通过事件中心传递到目标 Azure 数据资源管理器群集，其中 Azure 数据资源管理器将数据作为时间戳记录存储在相应的表中。
使用数据历史记录时，建议使用 2023-01-31 或更高版本的 API。 使用 2022-05-31 版本，只能对孪生属性（而不是孪生生命周期或关系生命周期事件）进行历史记录化。 对于早期版本，历史数据不可用。
所需的权限
若要设置数据历史记录连接，Azure 数字孪生实例必须具有以下权限才能访问事件中心和 Azure 数据资源管理器资源。 这些角色使 Azure 数字孪生能够代表你配置事件中心和 Azure 数据资源管理器数据库（例如，在数据库中创建表）。 设置数据历史记录后，可以选择删除这些权限。
- 事件中心资源： Azure 事件中心数据所有者
- Azure 数据资源管理器群集： 参与者 （范围限定为整个群集或特定数据库）
- Azure 数据资源管理器数据库主体分配：管理员（作用范围限定为要使用的数据库）
之后，当使用数据历史记录时，您的 Azure 数字孪生实例必须对 Event Hubs 资源拥有以下权限：Azure Event Hubs 数据发送方（您也可以选择保留在数据历史记录设置中的 Azure Event Hubs 数据所有者 ）。
可以使用 Azure CLI 或 Azure 门户分配这些权限。
如果想要限制对数据历史记录中涉及的资源的网络访问（Azure 数字孪生实例、事件中心或 Azure 数据资源管理器群集），则应在设置数据历史记录连接 后 设置这些限制。 有关此过程的详细信息，请参阅 限制对数据历史记录资源的网络访问。
创建和管理数据历史记录连接
本部分包含用于创建、更新和删除数据历史记录连接的信息。
创建历史数据连接
设置所有资源和权限后，可以使用 Azure CLI、Azure 门户或 Azure 数字孪生 SDK 在它们之间创建数据历史记录连接。 CLI 命令集是 az dt data-history。
该命令将始终为历史记录化孪生属性事件创建一个表，该事件可以使用默认名称或提供的自定义名称。 可选择性地在此表中包括孪生属性删除。 还可以为关系生命周期事件和孪生生命周期事件提供表名称，该命令将创建具有这些名称的表来记录这些事件类型。
有关如何设置数据历史记录连接的分步说明，请参阅 “创建数据历史记录连接”。
多个 Azure 数字孪生实例的历史记录
如果需要，可以有多个 Azure 数字孪生实例将更新历史记录化到同一 Azure 数据资源管理器群集。
每个 Azure 数字孪生实例都有自己的数据历史记录连接，以相同的 Azure 数据资源管理器群集为目标。 在群集中，实例可以将孪生数据发送到其中一个...
- Azure 数据资源管理器群集中的一组单独的表。
- Azure 数据资源管理器群集中的同一组表。 为此，请在 创建数据历史记录连接时指定相同的 Azure 数据资源管理器表名称。 在 数据历史记录表架构中，
ServiceId每个表中的列将包含源 Azure 数字孪生实例的 URL，因此可以使用此字段解析共享表中发出每个记录的 Azure 数字孪生实例。
更新仅限属性的数据历史记录连接
在 2023 年 2 月之前，数据历史记录功能仅记录孪生属性的更新。 如果具有从该时间开始的仅限属性的数据历史记录连接，则可以将其更新为将所有图形更新记录到 Azure 数据资源管理器（包括孪生属性、孪生生命周期事件和关系生命周期事件）。
这需要在 Azure 数据资源管理器群集中为新类型的历史记录更新（孪生生命周期事件和关系生命周期事件）创建新表。 对于孪生属性事件，可以决定希望新连接继续使用原始数据历史记录连接中的同一个表来存储孪生属性更新，还是希望新连接使用全新的表集。 然后，按照下面的说明根据您的喜好进行操作。
如果要继续使用现有表进行孪生属性更新， 使用 “创建数据历史记录连接 ”中的说明，使用新功能创建新的数据历史记录连接。 数据历史记录连接名称可以与原始连接名称相同，也可以是不同的名称。 使用参数选项为两个新事件类型表提供新名称，并传入孪生属性更新表的原始表名称。 新连接将替代旧连接，并继续使用原始表进行将来的历史记录化孪生属性更新。
如果要使用所有新表： 首先， 删除原始数据历史记录连接。 然后，使用 “创建数据历史记录连接 ”中的说明创建新的数据历史记录连接和新功能。 数据历史记录连接名称可以与原始连接名称相同，也可以是不同的名称。 使用参数选项为所有三个事件类型表提供新名称。
删除数据历史记录连接
可以使用 Azure CLI、 Azure 门户或 Azure 数字孪生 API 和 SDK 删除数据历史记录连接。 CLI 命令为 az dt data-history connection delete。
删除连接还可以选择清理与数据历史记录连接关联的资源（对于 CLI 命令，可以添加的可选参数是 --clean true）。 如果使用此选项，该命令将删除 Azure 数据资源管理器中用于将群集链接到事件中心的资源，包括数据库的数据连接以及与表关联的引入映射。 “清理资源”选项 不会 删除用于数据历史记录连接的实际事件中心和 Azure 数据资源管理器群集。
清理是尽力而为的尝试，并且运行命令的帐户需要对这些资源具有删除权限。
注释
如果有多个共享同一事件中心或 Azure 数据资源管理器群集的数据历史记录连接，则在删除其中一个连接时使用“清理资源”选项可能会中断依赖于这些资源的其他数据历史记录连接。
数据类型和架构
数据历史记录将 Azure 数字孪生实例中的三种类型的事件记录到 Azure 数据资源管理器：关系生命周期事件、孪生生命周期事件和孪生属性更新（可以选择包括孪生属性删除）。 其中每个事件类型都存储在 Azure 数据资源管理器数据库中自己的表中，这意味着数据历史记录总共保留三个表。 设置数据历史记录连接时，可以为表指定自定义名称。
本部分的其余部分详细介绍了三个 Azure 数据资源管理器表，包括每个表的数据架构。
孪生属性更新
用于孪生属性更新的 Azure 数据资源管理器表的默认名称为 AdtPropertyEvents。 创建连接时，可以保留默认名称，也可以指定自定义表名称。
孪生属性更新的时序数据使用以下架构存储：
| 特征 | 类型 | DESCRIPTION |
|---|---|---|
TimeStamp |
DateTime | Azure 数字孪生处理属性更新消息的日期/时间。 此字段由系统设置，用户不可写。 |
SourceTimeStamp |
DateTime | 一个可选的可写属性，表示在现实世界中观察到属性更新时的时间戳。 此属性只能使用 2022-05-31 版本的 Azure 数字孪生 API/SDK 写入，并且值必须符合 ISO 8601 日期和时间格式。 若要详细了解如何更新此属性，请参阅更新属性的 sourceTime。 |
ServiceId |
字符串 | 记录日志的 Azure IoT 服务实例 ID |
Id |
字符串 | 孪生 ID |
ModelId |
字符串 | DTDL 模型 ID (DTMI) |
Key |
字符串 | 更新的属性的名称 |
Value |
动态 | 已更新的属性的值 |
RelationshipId |
字符串 | 当在关系（与孪生或设备相对）上定义的属性被更新时，此字段将被赋值为关系 ID。 更新 孪生 属性时，此字段为空。 |
RelationshipTarget |
字符串 | 更新在关系（而不是孪生体或设备）上定义的属性时，将使用关系针对的孪生体的孪生体 ID 填充此字段。 更新 孪生 属性时，此字段为空。 |
Action |
字符串 | 仅当选择将属性删除事件进行历史记录化时，此列才存在。 如果是，则此列包含孪生属性事件的类型（更新或删除） |
下面是存储在 Azure 数据资源管理器中的孪生属性更新的示例表。
TimeStamp |
SourceTimeStamp |
ServiceId |
Id |
ModelId |
Key |
Value |
RelationshipTarget |
RelationshipID |
|---|---|---|---|---|---|---|---|---|
| 2022-12-15 20:23:29.8697482 | 2022-12-15 20:22:14.3854859 | dairyadtinstance.api.wcus.digitaltwins.azure.net | 巴氏杀菌机_A01 | dtmi:assetGen:PasteurizationMachine;1 |
输出 | 130 | ||
| 2022-12-15 20:23:39.3235925 | 2022-12-15 20:22:26.5837559 | dairyadtinstance.api.wcus.digitaltwins.azure.net | 巴氏杀菌机_A01 | dtmi:assetGen:PasteurizationMachine;1 |
输出 | 140 | ||
| 2022-12-15 20:23:47.078367 | 2022-12-15 20:22:34.9375957 | dairyadtinstance.api.wcus.digitaltwins.azure.net | 巴氏杀菌机_A01 | dtmi:assetGen:PasteurizationMachine;1 |
输出 | 130 | ||
| 2022-12-15 20:23:57.3794198 | 2022-12-15 20:22:50.1028562 | dairyadtinstance.api.wcus.digitaltwins.azure.net | 巴氏杀菌机_A01 | dtmi:assetGen:PasteurizationMachine;1 |
输出 | 123 |
表示具有多个字段的属性
可能需要存储具有多个字段的属性。 这些属性用架构属性中的 Value JSON 对象表示。
例如，如果要表示一个包含三个字段（roll、pitch 和 yaw）的属性，则数据历史记录会将以下 JSON 对象存储为 Value: {"roll": 20, "pitch": 15, "yaw": 45}。
孪生生命周期事件
用于孪生生命周期事件的 Azure 数据资源管理器表具有一个自定义名称，可在创建数据历史记录连接时指定该名称。
孪生生命周期事件的时序数据使用以下架构存储：
| 特征 | 类型 | DESCRIPTION |
|---|---|---|
TwinId |
字符串 | 孪生 ID |
Action |
字符串 | 孪生生命周期事件的类型（创建或删除） |
TimeStamp |
DateTime | 孪生生命周期事件的日期/时间由 Azure 数字孪生处理。 此字段由系统设置，用户不可写。 |
ServiceId |
字符串 | 记录此记录的 Azure IoT 服务的服务实例 ID |
ModelId |
字符串 | DTDL 模型 ID (DTMI) |
下面是存储在 Azure 数据资源管理器中的孪生生命周期更新的示例表。
TwinId |
Action |
TimeStamp |
ServiceId |
ModelId |
|---|---|---|---|---|
| 巴氏消毒机_A01 | 创建 | 2022-12-15 07:14:12.4160 | dairyadtinstance.api.wcus.digitaltwins.azure.net | dtmi:assetGen:PasteurizationMachine;1 |
| PasteurizationMachine_A02 | 创建 | 2022-12-15 07:14:12.4210 | dairyadtinstance.api.wcus.digitaltwins.azure.net | dtmi:assetGen:PasteurizationMachine;1 |
| SaltMachine_C0 | 创建 | 2022-12-15 07:14:12.5480 | dairyadtinstance.api.wcus.digitaltwins.azure.net | dtmi:assetGen:SaltMachine;1 |
| 巴氏杀菌机_A02 | 删除 | 2022-12-15 07:15:49.6050 | dairyadtinstance.api.wcus.digitaltwins.azure.net | dtmi:assetGen:PasteurizationMachine;1 |
关系生命周期事件
关系生命周期事件的 Azure 数据资源管理器表具有一个自定义名称，可在创建数据历史记录连接时指定该名称。
关系生命周期事件的时序数据使用以下架构存储：
| 特征 | 类型 | DESCRIPTION |
|---|---|---|
RelationshipId |
字符串 | 关系 ID。 此字段由系统设置，用户不可写。 |
Name |
字符串 | 关系的名称 |
Action |
关系生命周期事件的类型（创建或删除） | |
TimeStamp |
DateTime | 关系生命周期事件的日期/时间由 Azure 数字孪生处理。 此字段由系统设置，用户不可写。 |
ServiceId |
记录日志的 Azure IoT 服务的服务实例 ID | |
Source |
源孪生 ID。 这是关系起源的孪生体的 ID。 | |
Target |
目标孪生 ID。 这是关系到达的孪生体的 ID。 |
下面是存储到 Azure 数据资源管理器的关系生命周期更新示例表。
RelationshipId |
Name |
Action |
TimeStamp |
ServiceId |
Source |
Target |
|---|---|---|---|---|---|---|
| PasteurizationMachine_A01_feeds_Relationship0 | 饲料 | 创建 | 2022-12-15 07:16:12.7120 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A01 | SaltMachine_C0 |
| PasteurizationMachine_A02_feeds_Relationship0 | 饲料 | 创建 | 2022-12-15 07:16:12.7160 | dairyadtinstance.api.wcus.digitaltwins.azure.net | 巴氏杀菌机器_A02 | SaltMachine_C0 |
| PasteurizationMachine_A03_feeds_Relationship0 | 饲料 | 创建 | 2022-12-15 07:16:12.7250 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A03 | SaltMachine_C1 |
| OsloFactory_contains_Relationship0 | 包含 | 删除 | 2022-12-15 07:16:13.1780 | dairyadtinstance.api.wcus.digitaltwins.azure.net | 奥斯陆工厂 | SaltMachine_C0 |
端到端的引入延迟
Azure 数字孪生数据历史记录基于 Azure 数据资源管理器提供的现有引入机制。 Azure 数字孪生将确保在不到两秒内向 Azure 数据资源管理器提供图形更新事件。 引入数据时，Azure 数据资源管理器可能会引入额外的延迟。
Azure 数据资源管理器中有两种方法用于引入数据： 批处理引入 和 流式引入。 可以根据需求和特定的数据引入方案为各个表配置这些引入方法。
流式引入的延迟最低。 但是，由于处理开销，仅当每小时引入的数据少于 4 GB 时，才应使用此模式。 如果预期高引入数据速率，批处理引入效果最佳。 Azure 数据资源管理器默认使用批处理引入。 下表总结了预期的最差情况端到端延迟：
| Azure 数据资源管理器配置 | 预期的端到端延迟 | 建议的数据速率 |
|---|---|---|
| 流式引入 | <12 秒 （<典型值 3 秒） | <4 GB/小时 |
| 批量摄取 | 因配置而异（12 秒-15 米） | >4 GB/小时 |
本部分的余下内容包含有关启用每种类型的引入的详细信息。
批量数据导入（默认）
如果没有另行配置，Azure 数据资源管理器将使用 批量引入。 默认设置可能会导致在执行数字孪生体更新后，仅有 5-10 分钟的数据可供查询。 可以更改引入策略，使批处理最多每 10 秒（至少为 15 分钟）进行一次。 若要更改引入策略，必须在 Azure 数据资源管理器查询视图中发出以下命令：
.alter table <table_name> policy ingestionbatching @'{"MaximumBatchingTimeSpan":"00:00:10", "MaximumNumberOfItems": 500, "MaximumRawDataSizeMB": 1024}'
请确保将<table_name>替换为为您设置的表格名称。 MaximumBatchingTimeSpan 应设置为首选批处理间隔。 策略生效可能需要 5-10 分钟。 可以在以下链接中阅读有关引入批处理的详细信息： Kusto IngestionBatching 策略管理命令。
流式引入
启用 流式引入 是一个 2 步过程：
- 为群集启用流式引入。 此操作只需要执行一次。 （警告：这样做将对可用于热缓存的存储量产生影响，并可能带来额外的限制）。 有关说明，请参阅 在 Azure 数据资源管理器群集上配置流式引入。
- 为所需表添加流式引入策略。 可以在 Azure 数据资源管理器文档中阅读有关为群集启用流式引入的详细信息： Kusto IngestionBatching 策略管理命令。
若要为 Azure 数字孪生数据历史记录表启用流式引入，必须在 Azure 数据资源管理器查询窗格中发出以下命令：
.alter table <table_name> policy streamingingestion enable
确保将 <table_name> 替换为为您设置的具体表名称。 策略生效可能需要 5-10 分钟。
可视化具有历史记录的属性
用于可视化和与 Azure 数字孪生数据交互的开发人员工具 Azure 数字孪生资源管理器 提供了数据历史资源管理器功能，用于在图表或表格中随时间查看历史数据属性。 此功能也可以在 3D Scenes Studio 中使用，这是一个沉浸式 3D 环境，用于为 Azure 数字孪生提供 3D 资产的视觉上下文。
有关使用数据历史记录浏览器的更多详细信息，请参阅验证和浏览历史属性。
注释
如果在视觉数据历史记录资源管理器体验中选择属性时遇到问题，这可能意味着实例中的某些模型中存在错误。 例如，在模型属性中具有非唯一枚举值会破坏此可视化功能。 如果发生这种情况，请查看模型定义并确保所有属性都有效。
后续步骤
将孪生数据历史记录化到 Azure 数据资源管理器后，可以使用 Azure 数据资源管理器的 Azure 数字孪生查询插件跨数据运行查询。 在此处阅读有关插件的详细信息： 使用 Azure 数据资源管理器插件进行查询。
或者，通过创建指引和一个示例场景，深入探索数据历史：创建数据历史连接。