建立 Azure Digital Twins 的資料歷程記錄連線

資料歷史記錄是 Azure Digital Twins 的一項功能，可自動將圖更新歷史儲存至 Azure 資料總管。您可以使用適用於 Azure 數據總管的 Azure Digital Twins 查詢外掛程式查詢此數據，以隨時間推移深入了解您的環境。

本文說明如何設定 Azure Digital Twins 與 Azure 數據總管之間的工作數據歷程記錄連線。它會使用 Azure CLI 和 Azure 入口網站來設定及連線所需的數據歷程記錄資源，包括：

Azure Digital Twins 實例
包含事件中樞的命名空間
包含資料庫的 Azure 數據總管叢集

它也包含範例雙重圖表，可以用來查看 Azure 資料探索者中的歷史圖形更新。

小提示

雖然本文使用 Azure 入口網站，但您也可以使用 2022-05-31 版的其餘 API 來處理數據歷程記錄。

先決條件

備妥環境以使用 Azure CLI

在 Azure Cloud Shell 中使用 Bash 環境。如需詳細資訊，請參閱開始使用 Azure Cloud Shell。
若要在本地執行 CLI 參考命令，請安裝 Azure CLI。如果您正在 Windows 或 macOS 上執行，請考慮在 Docker 容器中執行 Azure CLI。如需詳細資訊，請參閱〈如何在 Docker 容器中執行 Azure CLI〉。
- 如果您使用的是本機安裝，請使用 az login 命令，透過 Azure CLI 來登入。若要完成驗證程式，請遵循終端機中顯示的步驟。如需其他登入選項，請參閱使用 Azure CLI 向 Azure 進行驗證。
- 出現提示時，請在第一次使用時安裝 Azure CLI 延伸模組。如需擴充功能的詳細資訊，請參閱使用和管理 Azure CLI 的擴充功能。
- 執行 az version 以尋找已安裝的版本和相依程式庫。若要升級至最新版本，請執行 az upgrade。

備註

如果您想要的話，您也可以在 PowerShell 環境中使用 Azure Cloud Shell，而不是 Bash 環境。此頁面上的命令是針對Bash環境所撰寫，因此可能需要在PowerShell中執行一些小型調整。

設定 CLI 工作階段

若要開始在 CLI 中使用 Azure Digital Twins，您要做的第一件事就是登入，並針對此工作階段設定訂閱的 CLI 內容。在您的 CLI 視窗中執行下列命令：

az login
az account set --subscription "<your-Azure-subscription-ID>"

小提示

您也可以在上一個命令中使用訂用帳戶名稱，而不是標識符。

如果您是第一次搭配 Azure Digital Twins 使用此訂用帳戶，請執行下列命令向 Azure Digital Twins 命名空間註冊。（如果你不確定，沒關係，即使你過去曾經執行過它，也可以再次執行。）

az provider register --namespace 'Microsoft.DigitalTwins'

接下來，您會新增適用於 Azure CLI 的 Azure IoT 擴充功能Microsoft，以啟用與 Azure Digital Twins 和其他 IoT 服務互動的命令。執行此命令以確定您擁有最新版本的延伸模組：

az extension add --upgrade --name azure-iot

現在您已準備好在 Azure CLI 中使用 Azure Digital Twins。

您可以隨時執行 az dt --help 來確認此狀態，以查看可用的最上層 Azure Digital Twins 命令清單。

設定 CLI 工作階段的局部變數

本文提供 CLI 命令，可讓您用來建立數據歷程記錄資源。為了方便稍後複製並執行這些命令，您現在可以在 CLI 工作階段中設定局部變數，然後在建立資源時稍後在 CLI 命令中參考這些變數。若要建立變數，請在下列命令中更新佔位元元（以 <...> 括號識別），然後執行命令。請務必遵循批注中所述的命名規則。這些值稍後會在建立新資源時使用。

備註

這些命令是針對Bash環境所撰寫。如果您希望在 PowerShell CLI 環境中使用，可以對其進行調整。

## General Setup
location="<your-resource-region>"
resourcegroup="<your-resource-group-name>"

## Azure Digital Twins Setup
# Instance name can contain letters, numbers, and hyphens. It must start and end with a letter or number, and be between 4 and 62 characters long.
dtname="<name-for-your-digital-twins-instance>"
# Connection name can contain letters, numbers, and hyphens. It must contain at least one letter, and be between 3 and 50 characters long.
connectionname="<name-for-your-data-history-connection>"

## Event Hub Setup
# Namespace can contain letters, numbers, and hyphens. It must start with a letter, end with a letter or number, and be between 6 and 50 characters long.
eventhubnamespace="<name-for-your-event-hub-namespace>"
# Event hub name can contain only letters, numbers, periods, hyphens and underscores. It must start and end with a letter or number.
eventhub="<name-for-your-event-hub>"

## Azure Data Explorer Setup
# Cluster name can contain only lowercase alphanumeric characters. It must start with a letter, and be between 4 and 22 characters long.
clustername="<name-for-your-cluster>"  
# Database name can contain only alphanumeric, spaces, dash and dot characters, and be up to 260 characters in length.
databasename="<name-for-your-database>"

# Enter a name for the table where relationship create and delete events are stored.
relationshiplifecycletablename="<name-for-your-relationship-lifecycle-events-table>"
# Enter a name for the table where twin create and delete events are stored.
twinlifecycletablename="<name-for-your-twin-lifecycle-events-table>"
# Optionally, enter a custom name for the table where twin property updates are stored. If not provided, the table is named AdtPropertyEvents.
twinpropertytablename="<name-for-your-twin-property-events-table>"

使用受控識別建立 Azure Digital Twins 實例

如果您已經有 Azure Digital Twins 實例，請確定您已為其啟用系統指派的受控識別。

如果您沒有 Azure Digital Twins 實例，請遵循使用受控識別建立實例中的指示，第一次建立具有系統指派受控識別的 Azure Digital Twins 實例。

然後，請確定您在實例上具有 Azure Digital Twins 數據擁有者 角色。您可以在設定使用者存取權限中找到指示。

如果您想要將實例的名稱新增至本機 CLI 變數，以便自動插入本文複製的後續命令，請將它儲存在如下的變數 dtname 中：

dtname="<name-of-your-instance>"

建立事件中樞命名空間和事件中樞

下一個步驟是建立事件中樞命名空間和事件中樞。此中樞會從 Azure Digital Twins 實例接收圖形生命週期和屬性更新通知，然後將訊息轉送至目標 Azure 數據總管叢集。

稍後，在設定數據歷程記錄連線時，您會將Azure Digital Twins實例授予事件中樞資源的Azure Event Hubs資料擁有者角色。

如需事件中樞及其功能的詳細資訊，請參閱事件中樞檔。

備註

設定數據歷程記錄時，必須在事件中樞上啟用本機授權。如果您最終想要在事件中樞上停用本機授權，請在設定連線之後停用授權。您也需要調整一些許可權，如本文稍後限制數據歷程記錄資源的網路存取中所述。

命令列介面
入口網站

使用下列 CLI 命令來建立必要的資源。這些指令會使用先前在$location中建立的數個局部變數（$resourcegroup、 $eventhubnamespace$eventhub和）。

建立事件中樞命名空間：

az eventhubs namespace create --name $eventhubnamespace --resource-group $resourcegroup --location $location

在您的命名空間中建立事件中樞：

az eventhubs eventhub create --name $eventhub --resource-group $resourcegroup --namespace-name $eventhubnamespace

建立 Kusto （Azure 數據總管）叢集和資料庫

接下來，建立 Kusto （Azure 數據總管）叢集和資料庫，以從 Azure Digital Twins 接收數據。

在後續的數據歷程連線設定中，您需要將 Azure Digital Twins 實例授予至少資料庫的 參與者 角色（也可以擴展至叢集），以及資料庫的 管理員 角色。

這很重要

請確定叢集已啟用公用網路存取。如果 Azure 資料總管叢集已停用公用網路存取，Azure Digital Twins 就無法設定數據表和其他必要成品，且數據歷程記錄設定失敗。

命令列介面
入口網站

使用下列 CLI 命令來建立必要的資源。這些指令會使用先前在$location中建立的數個局部變數（$resourcegroup、 $clustername$databasename和）。

如果您還沒有 Kusto 擴充功能，請從將 Kusto 擴充功能新增至 CLI 工作階段開始。

az extension add --name kusto

接下來，建立 Kusto 叢集。下列命令需要 5-10 分鐘才能執行，並在開發人員層中建立 E2a v4 叢集。這種類型的叢集具有引擎和數據管理叢集的單一節點，而且適用於開發和測試案例。如需 Azure 數據總管中階層以及如何為生產工作負載選取正確選項的詳細資訊，請參閱為 Azure 數據總管叢集和 Azure 數據總管定價選取正確的計算 SKU。

az kusto cluster create --cluster-name $clustername --sku name="Dev(No SLA)_Standard_E2a_v4" tier="Basic" --resource-group $resourcegroup --location $location --type SystemAssigned

在新的 Kusto 叢集中建立資料庫（使用先前指定的叢集名稱和相同位置）。此資料庫可用來儲存內容化 Azure Digital Twins 數據。下列命令會建立具有365天軟刪除期間及31天熱快取期間的資料庫。如需此命令可用選項的詳細資訊，請參閱 az kusto database create。

az kusto database create --cluster-name $clustername --database-name $databasename --resource-group $resourcegroup --read-write-database soft-delete-period=P365D hot-cache-period=P31D location=$location

設定資料歷程記錄連線

既然您已建立必要的資源，請使用本節中的命令，在 Azure Digital Twins 實例、事件中樞和 Azure 數據總管叢集之間建立數據歷程記錄連線。

此命令也會在 Azure 資料探索者資料庫中建立三個資料表，分別儲存數位孿生屬性更新、關係生命週期事件和數位孿生生命週期事件。如需這些型別的歷程記錄數據及其對應 Azure 數據總管數據表的詳細資訊，請參閱數據類型和架構。

命令列介面
入口網站

使用本節中的命令，在 Azure 數據總管中建立數據歷程記錄連線和數據表。命令一律會建立資料表以用於歷程記錄對應項屬性更新，並且包含參數來建立關聯性生命週期和對應項生命週期事件的資料表。

備註

根據預設，此命令假設所有資源都位於與 Azure Digital Twins 實例相同的資源群組中。您可以使用此命令的參數選項，指定位於不同資源群組中的資源。

下列命令會使用稍早在設定 CLI 工作階段的局部變數中建立的局部變數，並具有數個參數，包括...

在 Azure 數據總管中，關係生命週期和雙生命週期的資料表名稱（如果您不想記錄這些事件類型的歷史，這些參數是可選的；但如果您想記錄這些事件類型的歷史，則是必需的參數）
指定對應項屬性事件數據表名稱的選擇性參數（如果未提供此值，則此數據表預設會命名為 AdtPropertyEvents ）。如果您不想指定另一個名稱，請先從命令中移除 --adx-property-events-table 參數，再執行它。
用來開啟記錄對應項目屬性刪除的選擇性參數 --adx-record-removals (完全移除屬性的事件)

az dt data-history connection create adx --dt-name $dtname --cn $connectionname --adx-cluster-name $clustername --adx-database-name $databasename --eventhub $eventhub --eventhub-namespace $eventhubnamespace --adx-property-events-table $twinpropertytablename --adx-twin-events-table $twinlifecycletablename --adx-relationship-events-table $relationshiplifecycletablename --adx-record-removals true

執行上一個命令時，您可以選擇指派代表您設定數據歷程記錄連線所需的必要許可權（如果您已指派必要的許可權，您可以略過這些提示）。這些權限會授與 Azure Digital Twins 執行個體的受控識別。最低必要角色為：

Azure 事件中樞事件中樞上的資料擁有者
參與者範圍至少為指定的資料庫 (也可以限定於叢集)
具有角色管理員的資料庫主體指派 (用於建立/管理資料表) 範圍設定為指定的資料庫

針對一般數據平面作業，如有需要，這些角色可以縮減為單一 Azure 事件中樞數據傳送者角色。

設定數據歷程記錄連線之後，您可以選擇性地移除授與 Azure Digital Twins 實例的角色，以存取事件中樞和 Azure 數據總管資源。為了使用數據歷程記錄，在Azure事件匯流排資源上，實例唯一需要的角色是Azure事件匯流排數據傳送者（或包含這些許可權的更高角色，例如Azure事件匯流排數據擁有者）。

備註

設定連線之後，Azure 數據總管叢集上的預設設定會導致大約 10 分鐘或更短的擷取延遲。您可以啟用串流擷取（延遲少於 10 秒）或擷取批處理原則來降低此延遲。如需 Azure 數據總管擷取延遲的詳細資訊，請參閱端對端擷取延遲。

限制對數據歷程記錄資源的網路存取

如果您想要限制數據歷程記錄所涉及的資源網路存取權（Azure Digital Twins 實例、事件中樞或 Azure 數據總管叢集），您應該在設定數據歷程記錄連線之後設定這些限制。這些限制包括停用資源的本機存取，以及其他減少網路存取的措施。

為了確保數據歷程記錄資源可以彼此通訊，您也應該修改 Azure 數據總管資料庫的數據連線，以使用系統指派的受控識別。

若要確定當您的資源需要減少網路存取時，資料歷程記錄連線已正確設定，請依序執行下列步驟：

請確保在您的資料歷程記錄資源（Azure Digital Twins 實例、事件中樞和 Azure 資料總管叢集）上啟用本機授權。
建立數據歷程記錄連線
更新 Azure 數據總管資料庫的數據連線，以使用系統指派的受控識別。在 Azure 入口網站中，您可以更新數據連線，方法是先流覽至 Azure 資料探索者叢集，然後在功能表中選擇資料庫以進入數據歷程記錄資料庫。在資料庫功能表中，選取 [數據連線]。在資料歷程記錄連線的資料表項目中，您應該會看到 [指派受控識別] 的選項，您可以在其中選擇 [系統指派]。
您現在可以藉由變更 Azure Digital Twins 實例、事件中樞或 Azure 數據總管叢集上的存取設定，來停用本機授權或設定所需資源的其他網路限制。

疑難排解連線設定

以下是設定數據歷程記錄連線時可能會遇到的一些常見錯誤，以及如何加以解決。

如果您已停用 Azure 數據總管叢集的公用網路存取，您遇到服務無法建立資料歷程記錄連線的錯誤，並出現「資源因內部伺服器錯誤而無法 ACT」訊息。如果 Azure 資料總管叢集已停用公用網路存取，數據歷程記錄設定會失敗，因為 Azure Digital Twins 無法設定數據表和其他必要成品。
（CLI 使用者）如果您遇到「無法建立 Azure Digital Twins 實例連線」錯誤。無法在資料庫中建立資料表和對應規則。檢查 Azure 資料庫總管的許可權，然後執行 az login 以重新整理您的認證，“藉由將自己新增為 Azure 數據總管叢集中的許可權下的 AllDatabasesAdmin 來解決錯誤。
（Cloud Shell 使用者）如果您使用 Cloud Shell，並遇到「無法連線到 MSI」錯誤。請確定 MSI 已正確設定，「請嘗試改為使用本機 Azure CLI 安裝來執行命令。

使用範例對應項圖形進行驗證

現在您已設定資料歷程記錄連線，可以使用來自數位對應項的資料進行測試。

如果您的 Azure Digital Twins 實例中已經有雙胞胎體元，且正主動接收圖更新（包括雙胞胎體元屬性更新或透過建立或刪除元素來變更圖結構），您可以略過本節，並透過自己的資源將結果可視化。

否則，請繼續進行本節，以設定將處理對應項和關聯性生命週期事件的範例圖表，並產生對應項屬性更新。

您可以使用 Azure Digital Twins 數據模擬器來設定此案例的範例圖表。 Azure Digital Twins 數據模擬器會在 Azure Digital Twins 實例中建立對應項和關聯性，並持續將屬性更新推送至對應項。

建立範例圖表

您可以使用 Azure Digital Twins 數據模擬器 來布建範例對應項圖形，並將屬性更新推送至其中。這個雙重圖表模擬了一家乳品公司的巴氏殺菌過程。

從在瀏覽器中開啟 Azure Digital Twins 數據模擬器開始。設定下列欄位：

實例 URL：輸入 Azure Digital Twins 實例的主機名。您可以在實例的入口網站頁面中找到主機名，而且具有類似 <Azure-Digital-Twins-instance-name>.api.<region-code>.digitaltwins.azure.net的格式。
模擬類型：從下拉功能表中選取 [乳品設備 ]。

請選擇產生環境。

Azure Digital Twins 數據模擬器的螢幕快照。

您會在畫面上看到確認訊息，因為模型、對應項和關聯性會在您的環境中建立。此程式也會產生對應項和關聯性建立事件，這些事件會分別以對應項和關聯性生命週期事件的形式記錄至 Azure 數據總管。

當模擬準備就緒時，會啟用 [ 開始模擬] 按鈕。向下卷動並選取 [ 開始模擬 ] 以將模擬數據推送至您的 Azure Digital Twins 實例。若要持續更新 Azure Digital Twins 實例中的雙胞胎，請將此瀏覽器視窗保留在桌面上的最前端，並在其他視窗中執行其他瀏覽器操作。此視窗會持續產生對應項屬性更新事件，這些事件會記錄至 Azure 數據總管。

在 Azure 數據總管中檢視歷程記錄的更新

本節說明如何檢視模擬器所產生的所有三種類型的歷程記錄更新，並儲存在 Azure 數據總管數據表中。

從 Azure 入口網站開始，並流覽至您稍早建立的 Azure 數據總管叢集。從左側功能表中，選擇 [數據] 下的 [查詢] 窗格，以開啟查詢視圖。

Azure 入口網站的螢幕快照，其中顯示 Azure 數據總管叢集的查詢窗格。

接下來，展開左窗格中的叢集和資料庫，以查看數據歷程表的名稱。其中應該有三個：一個用於對應項屬性更新事件，一個用於關聯性生命週期事件，另一個用於對應項生命週期事件。您可以使用這些數據表名稱在數據表上執行查詢，以驗證和檢視歷程記錄的數據。

驗證表格條目

若要確認事件已記錄到資料庫，請從複製下列命令開始。它具有 關聯性生命週期事件數據表名稱的佔位元，並將數據表的擷取變更為批次模式，以便每隔 10 秒從即時模擬內嵌數據。

.alter table <relationship-lifecycle-events-table-name> policy ingestionbatching @'{"MaximumBatchingTimeSpan":"00:00:10", "MaximumNumberOfItems": 500, "MaximumRawDataSizeMB": 1024}'

將命令貼到查詢視窗中，以事件關係表的名稱取代佔位符。選取 [ 執行] 按鈕以執行命令。

使用 雙胞胎生命週期事件數據表 的名稱重複命令兩次，然後使用 屬性更新數據表 來更新其他數據表的擷取模式。

接下來，將下列命令新增至查詢視窗並加以執行。每個命令都包含其中一個數據表名稱的佔位元，而命令會輸出資料表中的項目數。

備註

第一批內嵌的數據最多可能需要 5 分鐘的時間才會出現。

<twin-property-updates-table-name>
| count

<relationship-lifecycle-events-table-name>
| count

<twin-lifecycle-events-table-name>
| count

您應該會在結果中看到，每個資料表中的項目計數都大於零，這表示屬性更新、關聯生命週期和對應項目生命週期事件正被記錄到各自的資料表中。

探索對應項屬性更新資料表

在本節中，您會對表格中的雙重屬性更新數據進行更多探索。

首先，執行下列命令來檢視數據表中的 100 筆記錄：

<twin-property-updates-table-name>
| limit 100

接下來，根據雙胞胎的數據執行查詢，以查看具情境化的時間序列數據。

使用下列查詢，以圖表列出範例 Oslo 乳品工廠中的所有供鹽機器對應項。此 Kusto 查詢會使用 Azure Digital Twins 外掛程式來選取感興趣的對應項、將這些對應項聯結至 Azure 數據總管中的數據歷程記錄時間序列，然後繪製結果圖表。請務必以執行個體的主機名稱取代 <ADT-instance-host-name> 預留位置，並以對應項屬性更新資料表的名稱取代 <table-name> 預留位置。

let ADTendpoint = "https://<ADT-instance-host-name>";
let ADTquery = ```SELECT SALT_MACHINE.$dtId as tid
FROM DIGITALTWINS FACTORY 
JOIN SALT_MACHINE RELATED FACTORY.contains 
WHERE FACTORY.$dtId = 'OsloFactory'
AND IS_OF_MODEL(SALT_MACHINE , 'dtmi:assetGen:SaltMachine;1')```;
evaluate azure_digital_twins_query_request(ADTendpoint, ADTquery)
| extend Id = tostring(tid)
| join kind=inner (<table-name>) on Id
| extend val_double = todouble(Value)
| where Key == "OutFlow"
| render timechart with (ycolumns = val_double)

結果應該會顯示隨著時間變化的外流數據。

疑難排解連線

如果您在 Azure 數據總管中看不到數據，則歷程記錄化數據流無法正常運作。您可以在 Azure 入口網站中檢視事件中樞命名空間來調查問題，其會顯示顯示訊息進出命名空間的圖表。此顯示可讓您確認來自 Azure Digital Twins 的傳入訊息流程，以及傳出訊息至 Azure 數據總管，以協助您識別流程的哪個部分無法運作。

後續步驟

若要持續探索乳品案例，您可以在 GitHub 上檢視更多範例查詢，以示範如何根據機器類型、工廠、維護技術人員，以及這些參數的各種組合來監視乳品作業的效能。

若要建置可可視化乳品作業效能的 Grafana 儀錶板，請參閱使用 Azure Digital Twins、Azure 數據總管和 Grafana 建立儀錶板。

如需使用適用於 Azure 數據總管的 Azure Digital Twins 查詢外掛程式的詳細資訊，請參閱使用 Azure 數據總管外掛程式進行查詢和此部落格文章。您也可以在這裡深入瞭解外掛程式：使用 Azure 數據總管外掛程式進行查詢。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-04-21