你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
Azure 数字孪生数据历史记录（与 Azure 数据资源管理器配合使用）
数据历史记录是 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 数字孪生实例必须对事件中心资源具有以下权限：Azure 事件中心数据发送者（也可以选择保留数据历史设置中的“Azure 事件中心数据所有者”）。
可以使用 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。 创建连接时，可以保留默认名称，也可以指定自定义表名称。
孪生属性更新的时序数据使用以下架构存储：
| 属性 | 类型 | 说明 |
|---|---|---|
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 | PasteurizationMachine_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 | PasteurizationMachine_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 | PasteurizationMachine_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 | PasteurizationMachine_A01 | dtmi:assetGen:PasteurizationMachine;1 |
输出 | 123 |
表示具有多个字段的属性
可能需要存储具有多个字段的属性。 这些属性在架构的 Value 特性中使用 JSON 对象表示。
例如，如果要表示一个包含三个字段（roll、pitch 和 yaw）的属性，则数据历史记录会将以下 JSON 对象存储为 Value: {"roll": 20, "pitch": 15, "yaw": 45}。
孪生生命周期事件
用于孪生生命周期事件的 Azure 数据资源管理器 表具有在创建数据历史记录连接时将指定的自定义名称。
孪生生命周期事件的时序数据使用以下架构存储：
| 属性 | 类型 | 说明 |
|---|---|---|
TwinId |
字符串 | 孪生体 ID |
Action |
字符串 | 孪生生命周期事件的类型（创建或删除） |
TimeStamp |
DateTime | 孪生生命周期事件的日期/时间由 Azure 数字孪生处理。 此字段由系统设置，是用户不可写的。 |
ServiceId |
字符串 | 记录此记录的 Azure IoT 服务的服务实例 ID |
ModelId |
字符串 | DTDL 模型 ID (DTMI) |
下面是存储在 Azure 数据资源管理器 的孪生生命周期更新的示例表。
TwinId |
Action |
TimeStamp |
ServiceId |
ModelId |
|---|---|---|---|---|
| PasteurizationMachine_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 |
| PasteurizationMachine_A02 | 删除 | 2022-12-15 07:15:49.6050 | dairyadtinstance.api.wcus.digitaltwins.azure.net | dtmi:assetGen:PasteurizationMachine;1 |
关系生命周期事件
关系生命周期事件的 Azure 数据资源管理器表具有在创建数据历史记录连接时将指定的自定义名称。
关系生命周期事件的时序数据使用以下架构存储：
| 属性 | 类型 | 说明 |
|---|---|---|
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 | feeds | 创建 | 2022-12-15 07:16:12.7120 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A01 | SaltMachine_C0 |
| PasteurizationMachine_A02_feeds_Relationship0 | feeds | 创建 | 2022-12-15 07:16:12.7160 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A02 | SaltMachine_C0 |
| PasteurizationMachine_A03_feeds_Relationship0 | feeds | 创建 | 2022-12-15 07:16:12.7250 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A03 | SaltMachine_C1 |
| OsloFactory_contains_Relationship0 | contains | 删除 | 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 数据资源管理器插件进行查询。
或者，通过创建说明和示例方案深入了解数据历史记录： 创建数据历史记录连接。