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

發行項
05/12/2024

資料歷程記錄是 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 中的 Bash 快速入門。
若要在本地執行 CLI 參考命令，請安裝 Azure CLI。若您在 Windows 或 macOS 上執行，請考慮在 Docker 容器中執行 Azure CLI。如需詳細資訊，請參閱〈如何在 Docker 容器中執行 Azure CLI〉。
- 如果您使用的是本機安裝，請使用 az login 命令，透過 Azure CLI 來登入。請遵循您終端機上顯示的步驟，完成驗證程序。如需其他登入選項，請參閱使用 Azure CLI 登入。
- 出現提示時，請在第一次使用時安裝 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 的 Microsoft Azure IoT 擴充功能以啟用可與 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 環境，則可以針對 PowerShell 進行調整。

## 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 will be stored.
relationshiplifecycletablename="<name-for-your-relationship-lifecycle-events-table>"
# Enter a name for the table where twin create and delete events will be stored.
twinlifecycletablename="<name-for-your-twin-lifecycle-events-table>"
# Optionally, enter a custom name for the table where twin property updates will be stored. If not provided, the table will be 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 事件中樞資料擁有者角色授與 Azure Digital Twins 執行個體。

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

注意

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

CLI
入口網站

使用下列 CLI 命令來建立必要的資源。命令會使用先前在設定 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
入口網站

使用下列 CLI 命令來建立必要的資源。命令會使用先前在設定 CLI 工作階段的區域變數中建立的數個區域變數 ($location、$resourcegroup、$clustername 和 $databasename)。

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

az extension add --name kusto

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

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 資料總管資料表的詳細資訊，請參閱資料類型和結構描述。

CLI
入口網站

使用本節中的命令，在 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 資料總管叢集上的預設設定會導致擷取延遲大約 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。
模擬類型：從下拉式功能表中選取 [乳製品設備]。

選取 [產生環境]。

Screenshot of the Azure Digital Twins Data simulator.

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

當模擬準備就緒時，將會啟用 [開始模擬] 按鈕。向下捲動並選取 [開始模擬] 以將模擬資料推送至 Azure Digital Twins 執行個體。若要持續更新 Azure Digital Twins 執行個體中的對應項，請將此瀏覽器視窗保留在桌面的前景，並在個別視窗中完成其他瀏覽器動作。這將會持續產生對應項屬性更新事件，這些事件會記錄至 Azure 資料總管。

在 Azure 資料總管中檢視記錄的更新

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

從 Azure 入口網站開始，並瀏覽至您稍早建立的 Azure 資料總管叢集。從左側功能表中選擇 [資料庫] 窗格，以開啟資料庫檢視。尋找您為此文章建立的資料庫，選取其旁邊的核取方塊，然後選取 [查詢]。

Screenshot of the Azure portal showing a database in an Azure Data Explorer cluster.

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

確認資料表項目

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

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

將命令貼到查詢視窗中，以您關聯性事件資料表的名稱取代預留位置。選取 [執行] 按鈕以執行命令。

使用對應項生命週期事件資料表的名稱重複命令兩次，然後使用屬性更新資料表一併更新其他資料表的擷取模式。

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

注意

最多可能需要 5 分鐘的時間，才會顯示第一批擷取的資料。

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

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

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

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

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

在本節中，您將使用資料表中的對應項屬性更新資料，進行更多探索。

首先，執行下列命令來檢視資料表中的 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 資料總管外掛程式進行查詢。

共用方式為