Azure Digital Twins 資料歷程記錄 (使用 Azure Data Explorer)
資料歷程記錄是 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 | 選用的可寫入屬性，代表實際觀察到屬性更新時的時間戳記。 此屬性只能使用 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 物件來表示。
例如，如果您要使用三個欄位代表一個屬性，以進行變換、傾斜和偏轉，則資料歷程記錄會將下列 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 | OsloFactory | SaltMachine_C0 |
端對端擷取延遲
Azure Digital Twins 資料歷程記錄是以 Azure 資料總管所提供的現有擷取機制為基礎所建置。 Azure Digital Twins 可確保圖表更新事件可在低於兩秒內提供給 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 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 Digital Twins 查詢外掛程式，讓 Azure 資料總管跨資料執行查詢。 在這裡深入了解外掛程式：使用 Azure 資料總管外掛程式進行查詢。
或者，透過建立指示和範例案例深入了解資料歷程記錄：建立資料歷程記錄連線。