適用于 Azure 資料總管的 Azure Digital Twins 查詢外掛程式

發行項
10/27/2023

本文說明適用于 Azure 資料總管的 Azure Digital Twin 查詢外掛程式、如何使用 Azure 資料總管 IoT 資料搭配 Azure Digital Twins、如何跨 Azure 資料總管和 Azure Digital Twins 對應資料等等。

適用于 Azure 資料總管的 Azure Digital Twins 外掛程式可讓您執行 Azure 資料總管查詢，以跨 Azure Digital Twins 圖形和 Azure 資料總管時間序列資料庫存取和合併資料。使用外掛程式，藉由推理數位對應項及其關聯性，以將不同的時間序列資料內容化，以深入瞭解模型化環境的行為。

例如，使用此外掛程式，您可以撰寫 Kusto 查詢，以：

透過 Azure Digital Twins 查詢外掛程式選取感興趣的數位對應項，
在 Azure 資料總管中針對個別時間序列聯結這些對應項，然後
對這些對應項執行進階時間序列分析。

在 Azure Digital Twins 中結合對應項圖形中的資料與 Azure 資料總管中的時間序列資料，可協助您瞭解解決方案各個部分的操作行為。

使用外掛程式

您可以使用下列命令，在 Kusto 查詢中叫用外掛程式。有兩個預留位置和 <Azure-Digital-Twins-endpoint><Azure-Digital-Twins-query> ，分別代表 Azure Digital Twins 實例端點和 Azure Digital Twins 查詢的字串。

evaluate azure_digital_twins_query_request(<Azure-Digital-Twins-endpoint>, <Azure-Digital-Twins-query>)

外掛程式的運作方式是呼叫 Azure Digital Twins 查詢 API ，而查詢語言結構與使用 API 時相同，但有兩個例外：

*不支援子句中的 SELECT 萬用字元。相反地，使用外掛程式執行的 Azure Digital Twin 查詢應該使用子句中的 SELECT 別名。

例如，請考慮使用 API 執行的下列 Azure Digital Twins 查詢：
```
SELECT * FROM DIGITALTWINS
```
若要在使用外掛程式時執行該查詢，應該重寫如下：
```
SELECT T FROM DIGITALTWINS T
```
外掛程式傳回的資料行名稱可能不是以 $ 開頭。在子句中使用 SELECT 別名也有助於避免此案例。

例如，請考慮使用 API 執行的下列 Azure Digital Twins 查詢：
```
SELECT T.$dtId, T.Temperature FROM DIGITALTWINS T
```
若要在使用外掛程式時執行該查詢，應該重寫如下：
```
SELECT T.$dtId as tid, T.Temperature FROM DIGITALTWINS T
```

重要

外掛程式的使用者必須獲得 Azure Digital Twins 資料讀取者 角色或 Azure Digital Twins 資料擁有者 角色，因為使用者的 Microsoft Entra 權杖是用來驗證。如需如何指派此角色的資訊，請參閱 Azure Digital Twins 解決方案的安全性。

如需使用外掛程式的詳細資訊，請參閱 azure_digital_twins_query_request 外掛程式的 Kusto 檔。

若要查看範例查詢，並完成範例資料的逐步解說，請參閱適用于 Azure 資料總管的 Azure Digital Twins 查詢外掛程式：GitHub 中的範例查詢和逐步解說。

將 Azure Digital Twins 資料內嵌至 Azure 資料總管

使用外掛程式進行查詢之前，您必須將 Azure Digital Twins 資料內嵌至 Azure 資料總管。有兩個主要方式可以這麼做：透過 資料歷程記錄 功能，或透過直接擷取。下列各節會更詳細地說明這些選項。

擷取資料歷程記錄

將 IoT 資料從 Azure Digital Twins 擷取至 Azure 資料總管最簡單的方式，就是使用 資料歷程記錄 功能。這項功能可讓您設定 Azure Digital Twins 實例與 Azure 資料總管叢集之間的連線，以及圖表更新（包括對應項屬性更新、對應項生命週期事件和關聯性生命週期事件）會自動向叢集記錄。如果您使用裝置遙測資料將數位對應項帶入生活，這是不錯的選擇。如需此功能的詳細資訊，請參閱資料歷程記錄（使用 Azure 資料總管）。

直接擷取

您也可以選擇從 IoT 中樞或其他來源直接將 IoT 資料內嵌到 Azure 資料總管叢集中。然後，Azure Digital Twins 圖表將用來使用聯合 Azure Digital Twins/Azure 資料總管查詢，將時間序列資料內容化。此選項是直接擷取工作負載的絕佳選擇，不過，您無法利用 Azure Digital Twins 的事件架構來更新其他對應項、觸發下游服務，或在對應項變更狀態時發出通知。如需此程式的詳細資訊，請繼續進行本節的其餘部分。

跨 Azure 資料總管和 Azure Digital Twins 對應資料

如果您要將時間序列資料直接擷取至 Azure 資料總管，您可能需要將此原始時間序列資料轉換成適合聯合 Azure Digital Twins/Azure 資料總管查詢的架構。

Azure 資料總管中的更新原則可讓您在每當新資料插入來源資料表時，自動轉換和附加資料至目標資料表。

如果您的裝置遙測資料中的感應器識別碼與 Azure Digital Twins 中的對應項識別碼不同，您可以使用更新原則，以對應項識別碼豐富原始時間序列資料，並將其保存至目標資料表。使用對應項識別碼，即可將目標資料表與 Azure Digital Twins 外掛程式所選取的數位對應項聯結。

例如，假設您已建立下表，以保存流入 Azure 資料總管實例的原始時間序列資料。

.create-merge table rawData (Timestamp:datetime, someId:string, Value:string, ValueType:string)

您可以建立對應資料表，以將時間序列識別碼與對應項識別碼和其他選擇性欄位產生關聯。

.create-merge table mappingTable (someId:string, twinId:string, otherMetadata:string)

然後，建立目標資料表來保存擴充的時間序列資料。

.create-merge table timeseriesSilver (twinId:string, Timestamp:datetime, someId:string, otherMetadata:string, ValueNumeric:real, ValueString:string)

接下來，建立函式 Update_rawData ，藉由將原始資料與對應資料表聯結來擴充原始資料。這麼做會將對應項識別碼新增至產生的目標資料表。

.create-or-alter function with (folder = "Update", skipvalidation = "true") Update_rawData() { 
rawData 
| join kind=leftouter mappingTable on someId 
| project 
    Timestamp, ValueNumeric = toreal(Value), ValueString = Value, ... 
}

最後，建立更新原則來呼叫函式並更新目標資料表。

.alter table timeseriesSilver policy update 
@'[{"IsEnabled": true, "Source": "rawData", "Query": "Update_rawData()", "IsTransactional": false, "PropagateIngestionProperties": false}]'

建立目標資料表之後，您可以使用 Azure Digital Twins 外掛程式來選取感興趣的對應項，然後將它們與目標資料表中的時間序列資料聯結。

範例架構

以下是可用來表示共用資料的架構範例。此範例會遵循對應項屬性更新的 Azure 資料總管資料歷程記錄架構。

`TimeStamp`	`SourceTimeStamp`	`TwinId`	`ModelId`	`Name`	`Value`	`RelationshipTarget`	`RelationshipID`
2021-02-01 17:24	2021-02-01 17:11	ConfRoomTempSensor	`dtmi:com:example:TemperatureSensor;1`	溫度	301.0

數位對應項屬性會儲存為索引鍵/值組（ name, value ）。 name 和 value 會儲存為動態資料類型。

架構也支援根據和 relationshipID 欄位儲存關聯性 relationshipTarget 的屬性。索引鍵/值架構可避免為每個對應項屬性建立資料行的需求。

代表具有多個欄位的屬性

您可能想要將屬性儲存在具有多個欄位的架構中。這些屬性是以將 JSON 物件儲存為 value 架構來表示。

例如，如果您想要代表具有三個欄位的屬性，適用于 roll、pitch 和 yaw，值物件看起來會像這樣： {"roll": 20, "pitch": 15, "yaw": 45} 。

下一步

在 Azure 資料總管中檢視Kusto 查詢語言的外掛程式檔： azure_digital_twins_query_request外掛程式
使用外掛程式檢視範例查詢，包括範例案例中執行查詢的逐步解說：適用于 Azure 資料總管的 Azure Digital Twins 查詢外掛程式：範例查詢和逐步解說
閱讀另一個分析 Azure Digital Twins 中歷程記錄資料的策略：與Azure 時間序列深入解析整合