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

文章
05/12/2024

本文說明適用於 Azure 資料總管的 Azure Digital Twin 查詢外掛程式、如何透過 Azure Digital Twins 使用 Azure 資料總管 IoT 資料、如何跨 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
```

重要

因為以使用者的 Microsoft Entra 權杖來驗證，外掛程式的使用者必須獲授與 Azure Digital Twins 資料讀者角色或 Azure Digital Twins 資料擁有者角色。您可以在 Azure Digital Twins 解決方案的安全性中找到如何指派此角色的相關資訊。

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

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

將 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 儲存為動態資料類型。

結構描述也支援根據 relationshipTarget 和 relationshipID 欄位，儲存關聯性的屬性。索引鍵/值結構描述讓您不需要為每個對應項屬性建立資料行。

使用多個欄位來代表屬性

您可能想要在結構描述中使用多個欄位來儲存屬性。結構描述中將 JSON 物件儲存為 value 以代表這些屬性。

例如，如果要使用 roll、pitch 和 yaw 這三個欄位來代表屬性，則值物件如下：{"roll": 20, "pitch": 15, "yaw": 45}。

下一步

檢視 Azure 資料總管中的 Kusto 查詢語言相關的外掛程式文件：azure_digital_twins_query_request 外掛程式
檢視使用外掛程式的範例查詢，包括在範例案例中執行查詢的逐步解說：適用於 Azure 資料總管的 Azure Digital Twins 查詢外掛程式：範例查詢和逐步解說

分享方式：