Azure Digital Twins 數據歷程記錄 （使用 Azure 數據總管）
數據歷程記錄 是 Azure Digital Twins 的整合功能。 它可讓您將 Azure Digital Twins 實例連線至 Azure 數據 總管叢集，以便自動將圖表更新歷程記錄至 Azure 數據總管。 這些歷程記錄更新包括對應項屬性更新、對應項生命週期事件，以及關聯性生命週期事件。
一旦圖表更新歷程記錄至 Azure 數據總管，您就可以使用 Azure 數據總管的 Azure Digital Twins 外掛程式來執行聯合查詢，以跨數位對應項、其關聯性和時間序列數據進行推理。 這可以用來回頭查看圖表過去的狀態，或取得模型化環境行為的深入解析。 您也可以使用這些查詢來為操作儀表板注入動力、擴充 2D 和 3D Web 應用程式，以及驅動沉浸式的擴充/混合實境體驗，以傳達在 Azure Digital Twins 中建立了模型的資產、流程和人員目前和歷史狀態。
如需數據歷程記錄的簡介，包括快速示範，請觀看下列IoT顯示影片：
數據歷程記錄發出的訊息會根據 訊息定價維度來計量。
必要條件：資源和許可權
資料歷程記錄需要下列資源：
- 已啟用系統指派受控識別的 Azure Digital Twins 實例。
- 包含事件中樞的事件中 樞命名空間。
- 包含資料庫的 Azure 數據總管 叢集。 叢集必須啟用公用網路存取。
這些資源會連線到下列流程：
數字對應項圖形更新時，資訊會透過事件中樞傳遞至目標 Azure 數據總管叢集，其中 Azure 數據總管會將資料儲存為對應數據表中的時間戳記錄。
使用數據歷程記錄時，建議使用 2023-01-31 版或更新版本的 API。 使用 2022-05-31 版本時，只能將對應項屬性（而非對應項生命週期或關聯性生命週期事件）進行歷程記錄。 使用舊版時，無法使用數據歷程記錄。
所需的權限
若要設定數據歷程記錄連線，您的 Azure Digital Twins 實例必須具有下列許可權，才能存取事件中樞和 Azure 數據總管資源。 這些角色可讓 Azure Digital Twins 代表您設定事件中樞和 Azure 數據總管資料庫（例如，在資料庫中建立數據表）。 設定數據歷程記錄之後，可以選擇性地移除這些許可權。
- 事件中樞資源：Azure 事件中樞 數據擁有者
- Azure 資料總管叢集： 參與者 （範圍設定為整個叢集或特定資料庫）
- Azure 資料總管資料庫主體指派：管理員（範圍設定為正在使用的資料庫）
稍後，Azure Digital Twins 實例在使用資料歷程記錄時，必須具有事件中樞資源的下列許可權：Azure 事件中樞 數據傳送者（您也可以選擇將 Azure 事件中樞 數據擁有者從數據歷程記錄設定中保留）。
您可以使用 Azure CLI 或 Azure 入口網站 來指派這些許可權。
如果您想要限制數據歷程記錄所涉及的資源網路存取權（Azure Digital Twins 實例、事件中樞或 Azure 數據總管叢集），您應該在設定數據歷程記錄連線之後設定這些限制。 如需此程式的詳細資訊，請參閱 限制數據歷程記錄資源的網路存取。
建立和管理數據歷程記錄連線
本節包含建立、更新和刪除數據歷程記錄連線的資訊。
建立數據歷程記錄連線
設定所有資源和許可權之後，您可以使用 Azure CLI、Azure 入口網站 或 Azure Digital Twins SDK 來建立它們之間的數據歷程記錄連線。 CLI 命令集是 az dt data-history。
此命令一律會建立一個數據表來作為歷程記錄對應項屬性事件，其可以使用預設名稱或您提供的自定義名稱。 此數據表可以選擇性地包含對應項屬性刪除。 您也可以提供關聯性生命週期事件和對應項生命週期事件的數據表名稱，而 命令會建立具有這些名稱的數據表來記錄這些事件類型。
如需如何設定數據歷程記錄連線的逐步指示，請參閱 建立數據歷程記錄連線。
多個 Azure Digital Twins 實例的歷程記錄
如果您想要的話，您可以有多個 Azure Digital Twins 實例將更新歷程記錄到相同的 Azure 數據總管叢集。
每個 Azure Digital Twins 實例都會有自己的數據歷程記錄連線，以相同的 Azure 數據總管叢集為目標。 在叢集中，實例可以將其對應項數據傳送至其中一個...
- Azure 數據總管叢集中的一組數據表 。
- Azure 數據總管叢集中的相同數據表 集。 若要這樣做，請在建立數據歷程記錄連線時，指定相同的 Azure 數據總管數據表名稱。 在 數據歷程記錄數據表架構中，
ServiceId每個數據表中的數據行都會包含來源 Azure Digital Twins 實例的 URL，因此您可以使用此字段來解析共享數據表中發出每個記錄的 Azure Digital Twins 實例。
更新僅限屬性的數據歷程記錄連線
在 2023 年 2 月之前，數據歷程記錄功能只會更新歷程記錄對應項屬性。 如果您有來自該時間的屬性專用數據歷程記錄連線，您可以將它更新為將所有圖表更新記錄化至 Azure 數據總管（包括對應項屬性、對應項生命週期事件和關聯性生命週期事件）。
這需要在 Azure 數據總管叢集中建立新的數據表，以取得新類型的歷程記錄更新（對應項生命週期事件和關聯性生命週期事件）。 針對對應項屬性事件，您可以決定是否要讓新的連接繼續使用原始數據歷程記錄連線中的相同數據表，以便未來儲存對應項屬性更新，或如果您想要新的連接使用全新的數據表集。 然後，依照下列指示進行您的喜好設定。
如果您想要繼續使用現有的數據表進行對應項屬性更新：請使用建立數據歷程記錄連線中的指示，以使用新功能建立新的數據歷程記錄連線。 數據歷程記錄連接名稱可以和原始名稱相同，或是不同的名稱。 使用參數選項來提供兩個新的事件類型數據表的新名稱，並傳入對應項屬性更新數據表的原始數據表名稱。 新的連接將會覆寫舊的連接，並繼續使用原始數據表進行未來的歷程記錄對應項屬性更新。
如果您想要使用所有新的資料表： 首先， 刪除原始的數據歷程記錄連線。 然後，使用建立數據歷程記錄連線中的指示，建立具有新功能的新數據歷程記錄連線。 數據歷程記錄連接名稱可以和原始名稱相同，或是不同的名稱。 使用參數選項，為所有三個事件類型數據表提供新的名稱。
刪除數據歷程記錄連線
您可以使用 Azure CLI、Azure 入口網站 或 Azure Digital Twins API 和 SDK 來刪除資料歷程記錄連線。 CLI 命令是 az dt data-history connection delete。
刪除連線也可讓您清除與數據歷程記錄連線相關聯的資源（針對 CLI 命令，要新增的選擇性參數為 --clean true）。 如果您使用此選項，此命令將會刪除 Azure 數據總管內用來將叢集連結至事件中樞的資源，包括資料庫的數據連線，以及與數據表相關聯的擷取對應。 [清除資源] 選項不會刪除用於數據歷程記錄連線的實際事件中樞和 Azure 數據總管叢集。
清除是最佳嘗試，而且需要執行命令的帳戶具有這些資源的刪除許可權。
注意
如果您有多個共用相同事件中樞或 Azure 數據總管叢集的數據歷程記錄連線，則刪除其中一個連線時，使用 [清除資源] 選項可能會中斷依賴這些資源的其他數據歷程記錄連線。
數據類型和架構
數據歷程記錄會將三種類型的事件從 Azure Digital Twins 實例轉換成 Azure 數據總管：關聯性生命週期事件、對應項生命週期事件和對應項屬性更新（可以選擇性地包含對應項屬性刪除）。 每個事件類型都會儲存在 Azure 數據總管資料庫內自己的數據表中，這表示數據歷程記錄會保留三個數據表總計。 設定資料歷程記錄連線時，您可以指定資料表的自定義名稱。
本節的其餘部分會詳細說明三個 Azure 數據總管數據表，包括每個數據表的數據架構。
對應項屬性更新
對應項屬性更新的 Azure 數據總管數據表具有 AdtPropertyEvents 的預設名稱。 您可以在建立連接時保留預設名稱，或指定自訂資料表名稱。
對應項目屬性更新的時間序列資料會以下列架構儲存：
| 屬性 | 類型 | 描述 |
|---|---|---|
TimeStamp |
Datetime | Azure Digital Twins 處理屬性更新訊息的日期/時間。 此欄位是由系統設定，用戶無法寫入。 |
SourceTimeStamp |
Datetime | 選擇性的可寫入屬性，表示在真實世界中觀察到屬性更新時的時間戳。 此屬性只能使用 Azure Digital Twins API/SDK 的 2022-05-31 版本撰寫，且此值必須符合 ISO 8601 日期和時間格式。 如需如何更新此屬性的詳細資訊，請參閱 更新屬性的sourceTime。 |
ServiceId |
String | 記錄記錄之 Azure IoT 服務的服務實例識別碼 |
Id |
String | 對應項識別碼 |
ModelId |
String | DTDL 模型識別碼 （DTMI） |
Key |
String | 已更新屬性的名稱 |
Value |
動態 | 已更新屬性的值 |
RelationshipId |
String | 在關聯性上定義的屬性（與對應項或裝置相反）更新時，此字段會填入關聯性的標識符。 更新對應項屬性時，此欄位是空的。 |
RelationshipTarget |
String | 在關聯性上定義的屬性（與對應項或裝置相反）更新時，此字段會填入關聯性目標對應項的對應項標識符。 更新對應項屬性時，此欄位是空的。 |
Action |
String | 只有在您選擇將屬性刪除事件進行歷程記錄時，才會存在此資料行。 如果是，這個資料列會包含對應項屬性事件的類型（更新或刪除） |
以下是儲存至 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 |
String | 對應項識別碼 |
Action |
String | 對應項目生命週期事件的類型（建立或刪除） |
TimeStamp |
Datetime | Azure Digital Twins 處理對應項生命週期事件的日期/時間。 此欄位是由系統設定，用戶無法寫入。 |
ServiceId |
String | 記錄記錄之 Azure IoT 服務的服務實例識別碼 |
ModelId |
String | DTDL 模型識別碼 （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 |
String | 關聯性標識碼。 此欄位是由系統設定，用戶無法寫入。 |
Name |
String | 關聯性的名稱 |
Action |
關聯性生命週期事件的類型（建立或刪除） | |
TimeStamp |
Datetime | Azure Digital Twins 處理關聯性生命週期事件的日期/時間。 此欄位是由系統設定，用戶無法寫入。 |
ServiceId |
記錄記錄之 Azure IoT 服務的服務實例識別碼 | |
Source |
來源對應項標識碼。 這是關聯性來源的對應項標識碼。 | |
Target |
目標對應項識別碼。 這是關聯性到達之對應項的標識碼。 |
以下是儲存至 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 | 奧斯陸Factory | SaltMachine_C0 |
端對端擷取延遲
Azure Digital Twins 數據歷程記錄是以 Azure 數據總管所提供的現有擷取機制為基礎。 Azure Digital Twins 可確保圖表更新事件可在不到兩秒內提供給 Azure 數據總管使用。 Azure 數據總管擷取數據可能會引入額外的延遲。
Azure 數據總管中有兩種方法可擷取數據： 批次擷取 和 串流擷取。 您可以根據需求和特定的數據擷取案例，為個別數據表設定這些擷取方法。
串流擷取具有最低的延遲。 不過，由於處理額外負荷，只有在每小時擷取不到 4 GB 的數據時，才應該使用此模式。 如果預期高擷取數據速率，批次擷取效果最好。 Azure 數據總管預設會使用批次擷取。 下表摘要說明預期的最差案例端對端延遲：
| Azure 數據總管組態 | 預期的端對端延遲 | 建議的數據速率 |
|---|---|---|
| 串流擷取 | <12 秒 （<3 秒典型） | <4 GB / 小時 |
| 批次擷取 | 變化 （12 秒-15 m，視組態而定） | >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 Digital Twins 數據歷程記錄數據表的串流擷取，必須在 [Azure 數據總管] 查詢窗格中發出下列命令：
.alter table <table_name> policy streamingingestion enable
請確定 <table_name> 已將 取代為您設定的數據表名稱。 原則生效可能需要 5-10 分鐘的時間。
可視化歷程記錄屬性
Azure Digital Twins Explorer 是一種 開發人員工具，可用來可視化及與 Azure Digital Twins 數據互動，提供數據歷程記錄 總管功能，可在圖表或數據表中檢視歷史屬性。 此功能也適用於 3D Scenes Studio，這是一個沉浸式 3D 環境，可讓 Azure Digital Twins 提供 3D 資產的視覺內容。
如需使用數據歷程記錄總管的詳細資訊，請參閱 驗證和探索歷程記錄屬性。
注意
如果您在視覺數據歷程記錄總管體驗中選取屬性時遇到問題，這可能表示實例中的某些模型發生錯誤。 例如，在模型屬性中具有非唯一列舉值，將會中斷此視覺效果功能。 如果發生這種情況， 請檢閱您的模型定義 ，並確定所有屬性都有效。
下一步
將對應項數據記錄至 Azure 數據總管之後，您可以使用 Azure 數據總管的 Azure Digital Twins 查詢外掛程式，跨數據執行查詢。 在這裡深入瞭解外掛程式： 使用 Azure 數據總管外掛程式進行查詢。
或者，使用建立指示和範例案例深入了解數據歷程記錄： 建立數據歷程記錄連線。