教學課程：使用 Azure CLI 建立 Azure Digital Twins 圖表

發行項
05/13/2024

在本教學課程中，您將使用模型、對應項和關聯性，在 Azure Digital Twins 中建置圖表。本教學課程的工具是適用於 Azure CLI 的 Azure Digital Twins 命令集。

您可以使用 CLI 命令來執行基本的 Azure Digital Twins 動作，例如上傳模型、建立與修改對應項，以及建立關聯性。您也可以查看 az dt 命令集的參考文件，以查看完整的 CLI 命令集。

在本教學課程中，您將會…

為環境建立模型
建立數位分身
新增關聯性以形成圖表
查詢圖表以回答問題

必要條件

若要完成本教學課程中的步驟，您必須先完成下列必要條件。

如尚未擁有 Azure 訂用帳戶，請在開始之前先建立免費帳戶。

下載範例模型

本教學課程使用兩個預先撰寫的模型，這些模型是適用於 Azure Digital Twins 的 C# 端對端範例專案的一部分。模型檔案在這裡：

若要在您的機器上使用檔案，請使用上述導覽連結，並以相同名稱 (Room.json 和 Floor.json) 將檔案內文複製到您機器上的本機檔案。

備妥環境以使用 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。

設定 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 命令清單，以確認這一點。

準備 Azure Digital Twins 執行個體

若要使用本文中的 Azure Digital Twins，您必須先設定 Azure Digital Twins 執行個體以及使用的必要權限。如果您已經透過先前的工作設定 Azure Digital Twins 執行個體，您可以使用該執行個體。

否則，請依照設定執行個體和驗證中的指示進行。這些指示也包含可驗證您已成功完成每個步驟，並已準備好繼續使用新執行個體的步驟。

設定 Azure Digital Twins 執行個體之後，請記下下列值以供稍後連線到執行個體時使用：

執行個體的主機名稱
您用來建立執行個體的 Azure 訂用帳戶

提示

如果您知道執行個體的自訂名稱，可以使用下列 CLI 命令來取得主機名稱和訂用帳戶的值：

az dt show --dt-name <Azure-Digital-Twins-instance-name>

這些值會出現在輸出中，如下所示： Cloud Shell 瀏覽器視窗的螢幕擷取畫面，其中顯示 az dt show 命令的輸出。hostName 欄位和訂用帳戶識別碼會反白顯示。

使用 DTDL 建立實體環境的模型

現在已設定 CLI 和 Azure Digital Twins 執行個體，您可以開始建置某個案例的圖表。

建立 Azure Digital Twins 解決方案的第一個步驟是定義您環境的對應項模型。

模型類似物件導向程式設計語言中的類別，為數位分身提供日後可遵循並具現化的使用者定義範本。其是以類似 JSON、稱為「Digital Twins 定義語言 (DTDL)」的語言所撰寫，並且可定義對應項的屬性、關聯性及元件。

注意

DTDL 也允許在數位對應項上定義命令。但目前在 Azure Digital Twins 服務上不支援命令。

在您的機器上瀏覽至您在必要條件一節建立的 Room.json 檔案。在程式碼編輯器中開啟，並以下列方式變更：

更新版本號碼，指出您正在提供此模型的更新版本。您可以透過將 @id 值結尾的 1變更為 2 來進行此操作。任何大於目前版本號碼的數字也都能運作。
編輯屬性。將 Humidity 屬性的名稱變更為 HumidityLevel (或任何您想要的名稱。若您使用與 HumidityLevel 不同的名稱，請記住您使用的名稱，並繼續在本教學課程中使用該名稱，而非 HumidityLevel)。
新增屬性。在第 15 行結束的 HumidityLevel 屬性下方，貼上下列程式碼以將 RoomName 屬性新增到 Room：
```
,{
  "@type": "Property",
  "name": "RoomName",
  "schema": "string"
}
```
新增關聯。在您剛新增的 RoomName 屬性下方，貼上下列程式碼讓此類型的對應項能夠與其他對應項產生 contains 關聯性：
```
,{
  "@type": "Relationship",
  "name": "contains"
}
```

當您完成時，更新的模型應該會符合下列內容：

{
    "@id": "dtmi:example:Room;2",
    "@type": "Interface",
    "displayName": "Room",
    "contents": [
      {
        "@type": "Property",
        "name": "Temperature",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "HumidityLevel",
        "schema": "double"
      }
      ,{
        "@type": "Property",
        "name": "RoomName",
        "schema": "string"
      }
      ,{
        "@type": "Relationship",
        "name": "contains"
      }
    ],
    "@context": "dtmi:dtdl:context;3"
  }

請務必儲存檔案再繼續。

將模型上傳到 Azure Digital Twins

設計模型之後，您需要將其上傳到您的 Azure Digital Twins 執行個體。這樣做會使用您自己的自訂網域詞彙來設定 Azure Digital Twins 服務執行個體。在您上傳模型後，就可以建立使用模型的對應項執行個體。

如果您使用 Azure CLI 的本機安裝，您可以略過此步驟。如果您使用 Cloud Shell，您必須將模型檔案上傳至 Cloud Shell 的儲存體，如此一來當您執行使用這些檔案的 Cloud Shell 命令時，就可以使用這些檔案。若要這樣做，請選取 [上傳/下載檔案] 圖示，然後選擇 [上傳]。

瀏覽至機器上的 Room.json 檔案，然後選取 [開啟]。然後，針對 Floor.json 重複此步驟。
接下來，如下所示使用 az dt model create 命令，將更新的 Room 模型上傳至 Azure Digital Twins 執行個體。第二個命令會上傳另一個模型 Floor，您將在下一節使用此模型來建立不同類型的對應項。執行個體主機名稱有預留位置 (您也可以使用執行個體的自訂名稱，但效能會稍微降低)，每個模型檔案的路徑也有預留位置。如果您使用 Cloud Shell，Room.json 和 Floor.json 位於主要儲存體目錄中，因此您可以直接在下列需要路徑的命令中使用檔案名稱。
```
az dt model create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --models <path-to-Room.json>
az dt model create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --models <path-to-Floor.json>
```
每個命令的輸出會顯示成功上傳模型的相關資訊。

提示

您也可以使用 model create 命令的 --from-directory 選項，同時上傳目錄中的所有模型。如需詳細資訊，請參閱 az dt model create 的選擇性參數。
確認已使用 az dt model list 命令建立模型，如下所示。這樣做會列印一份已上傳到 Azure Digital Twins 執行個體的所有模型清單，並包含其完整資訊。執行個體主機名稱有一個預留位置 (您也可以使用執行個體的自訂名稱，但效能會稍微降低)。
```
az dt model list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --definition
```
在結果中尋找編輯過的 Room 模型：

錯誤

CLI 也會處理來自服務的錯誤。

再次執行 az dt model create 命令以嘗試第二次重新上傳您上傳的其中一個相同模型：

az dt model create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --models Room.json

由於無法覆寫模型，因此對同一個模型執行此命令現在會傳回 ModelIdAlreadyExists 的錯誤碼。

建立數位分身

現在您已將一些模型上傳到 Azure Digital Twins 執行個體，您可以依據模型定義來建立數位對應項。數位分身代表您商務環境中的實體，例如伺服陣列上的感應器、建築物中的房間，或汽車的燈。

若要建立數位對應項，請使用 az dt twin create 命令。您必須參考作為分身基礎的模型，並且可以選擇性地定義模型中任何屬性的初始值。您不需要在此階段傳遞任何關聯性資訊。

在 CLI 中執行此程式碼，依據您先前更新的 Room 模型及另外一個 Floor 模型建立數個對應項。回想一下，由於 Room 具備三個屬性，因此您可以提供引數來為這些屬性提供初始值。 (一般而言，初始化屬性值是選擇性的，但本教學課程需要這些值)。執行個體主機名稱有一個預留位置 (您也可以使用執行個體的自訂名稱，但效能會稍微降低)。
```
az dt twin create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --dtmi "dtmi:example:Room;2" --twin-id room0 --properties '{"RoomName":"Room0", "Temperature":70, "HumidityLevel":30}'
az dt twin create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --dtmi "dtmi:example:Room;2" --twin-id room1 --properties '{"RoomName":"Room1", "Temperature":80, "HumidityLevel":60}'
az dt twin create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --dtmi "dtmi:example:Floor;1" --twin-id floor0
az dt twin create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --dtmi "dtmi:example:Floor;1" --twin-id floor1
```
注意

如果您在 Bash 環境中使用 Cloud Shell 以外的任何項目，您可能需要逸出內嵌 JSON 中的特定字元，使系統正確剖析。

如需詳細資訊，請參閱在不同殼層中使用特殊字元 (機器翻譯)。

每個命令的輸出會顯示成功建立對應項的相關資訊 (包括已使用其初始化 room 對應項的屬性)。
您可以使用 az dt twin query 命令確認已建立對應項，如下所示。顯示的查詢會尋找 Azure Digital Twins 執行個體中的所有數位對應項。執行個體主機名稱有一個預留位置 (您也可以使用執行個體的自訂名稱，但效能會稍微降低)。
```
az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT * FROM DIGITALTWINS"
```
在結果中尋找 room0、room1、floor0 和 floor1 對應項。以下是顯示此查詢部分結果的節錄。

注意

變更圖表中的資料之後，最多可能會有 10 秒的延遲，變更才會反映在查詢中。

DigitalTwins API 會立即反映變更，所以如果您需要立即回應，請使用 API 要求 (DigitalTwins GetById) 或 SDK 呼叫 (GetDigitalTwin) 來取得對應項資料，而不是使用查詢。

修改數位分身

您也可以修改已建立的對應項屬性。

執行下列 az dt twin update 命令，將 room0 的 RoomName 從 Room0 變更為 PresidentialSuite。執行個體主機名稱有一個預留位置 (您也可以使用執行個體的自訂名稱，但效能會稍微降低)。
```
az dt twin update --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id room0 --json-patch '{"op":"add", "path":"/RoomName", "value": "PresidentialSuite"}'
```
注意

針對本教學課程，建議您在 Bash 環境中使用 CLI。如果您使用 PowerShell 環境，您可能需要逸出引號字元，才能正確剖析 --json-patch JSON 值。

此命令的輸出會顯示對應項的目前資訊，您應該會在結果中看到 RoomName 的新值。
您可以執行 az dt twin show 命令查看 room0 的資訊，確認更新成功。執行個體主機名稱有一個預留位置 (您也可以使用執行個體的自訂名稱，但效能會稍微降低)。
```
az dt twin show --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id room0
```
輸出應該會反映更新的名稱。

新增關聯性以建立圖表

接下來，您可以在這些對應項之間建立一些關聯性，將這些對應項連接成一個對應項圖表。分身圖表可用於表示整個環境。

您可以從一個對應項建立至另一個對應項的關聯性類型，定義在您稍早上傳的模型中。 Floor 的模型定義指定樓層可以有一個稱為 contains 的關聯性類型。由於模型定義指定此關聯性，因此可以從每個 Floor 對應項建立 contains類型關聯性，到它所包含的對應房間。

若要新增關聯性，請使用 az dt twin relationship create 命令。指定關聯性的來源對應項、關聯性類型，以及關聯性所連接的對應項。最後，為關聯性提供唯一識別碼。如果將關聯性定義為具有屬性，您也可以在此命令中初始化關聯性屬性。

執行下列程式碼，從您先前建立的每個 Floor 對應項到對應的 Room 對應項新增一個 contains 類型關聯性。關聯性名為 relationship0 和 relationship1。執行個體主機名稱有一個預留位置 (您也可以使用執行個體的自訂名稱，但效能會稍微降低)。
```
az dt twin relationship create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --relationship-id relationship0 --relationship contains --twin-id floor0 --target room0
az dt twin relationship create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --relationship-id relationship1 --relationship contains --twin-id floor1 --target room1
```
提示

Floor 模型中的 contains 關聯性也定義了兩個屬性：ownershipUser 和 ownershipDepartment，因此您也可以在建立關聯性時，為這些屬性提供有初始值的引數。若要在已初始化這些屬性的狀況下建立關聯性，請將 --properties 選項新增至上述任一命令，如下所示：
```
... --properties '{"ownershipUser":"MyUser", "ownershipDepartment":"MyDepartment"}'
```
每個命令的輸出會顯示成功建立關聯性的相關資訊。

您可以使用下列任何一個命令來驗證關聯性，這些命令會列印您 Azure Digital Twins 執行個體中的關聯性。每個命令針對執行個體主機名稱都有一個預留位置 (您也可以使用執行個體的自訂名稱，但效能會稍微降低)。

查看來自每一個樓層的所有關聯性 (從一端檢視關聯性)：

az dt twin relationship list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id floor0
az dt twin relationship list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id floor1

查看抵達每個房間的所有關聯性 (從「另一端」檢視關聯性)：

az dt twin relationship list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id room0 --incoming
az dt twin relationship list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id room1 --incoming

依識別碼個別查詢這些關聯性：

az dt twin relationship show --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id floor0 --relationship-id relationship0
az dt twin relationship show --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id floor1 --relationship-id relationship1

您在本教學課程中設定的分身和關聯性會形成以下概念圖表：

查詢分身圖表以回答環境問題

Azure Digital Twins 的主要功能是能夠輕鬆且有效率地查詢分身圖表，以回答有關環境的問題。在 Azure CLI 中，使用 az dt twin query 命令完成查詢。

注意

變更圖表中的資料之後，最多可能會有 10 秒的延遲，變更才會反映在查詢中。

在 CLI 中執行下列查詢，以回答範例環境的一些問題。每個命令針對執行個體主機名稱都有一個預留位置 (您也可以使用執行個體的自訂名稱，但效能會稍微降低)。

我環境中的所有實體在 Azure Digital Twins 中代表什麼？ (查詢全部)
```
az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT * FROM DIGITALTWINS"
```
此查詢讓您一眼就能了解環境，確認所有項目的呈現方式都與您希望在 Azure Digital Twins 中的呈現方式相同。此查詢的結果是包含每個數位對應項及其詳細資料的輸出。以下是節錄：

提示

您也許會發現此命令與您先前在建立數位對應項一節中用來尋找執行個體中所有 Azure Digital Twins 的命令相同。
我的環境中有哪些房間？ (依模型查詢)
```
az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT * FROM DIGITALTWINS T WHERE IS_OF_MODEL(T, 'dtmi:example:Room;2')"
```
您可以將查詢限制在特定類型的分身，以取得其表示項目更具體的資訊。此查詢的結果顯示 room0 與 room1，但不會顯示 floor0 或 floor1 (因為其為樓層，而非房間)。
floor0 上有哪些房間？ (依關聯性查詢)
```
az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.\$dtId = 'floor0'"
```
您可以根據圖表中的關聯性進行查詢，以取得分身連線方式的資訊，或是將您的查詢限制在特定區域。此查詢也說明使用中繼資料欄位 $dtId 查詢對應項的標識碼 (如上述查詢中的 floor0)。由於只有 room0 位於 floor0 上，因此這是此查詢結果中唯一的房間。

注意

使用 Cloud Shell 執行以如 $ 開頭的中繼資料欄位查詢時，請使用倒單引號來逸出 $，讓 Cloud Shell 知道這並不是變數，並應該以查詢文字中的常值來取用。從上述螢幕擷取畫面可以看出。
我的環境中有哪些對應項的溫度高於 75？ (依屬性查詢)
```
az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT * FROM DigitalTwins T WHERE T.Temperature > 75"
```
您可以根據屬性查詢圖表來回答各種問題，包括尋找您環境中需要注意的極端值。也支援其他比較運算子 (<、>、= 或 !=)。 room1 顯示在此處的結果中，因為其溫度為 80。
floor0 上有哪些房間的溫度高於 75？ (複合查詢)
```
az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.\$dtId = 'floor0' AND IS_OF_MODEL(room, 'dtmi:example:Room;2') AND room.Temperature > 75"
```
您也可以合併使用 AND、OR、NOT 等運算子，如在 SQL 中一樣合併先前的查詢。此查詢使用 AND，讓先前有關分身溫度的查詢更為明確。結果現在只會包含位於 floor0 上溫度高於 75 的房間 (在此案例中，沒有任何房間符合此條件)。結果集為空白。

清除資源

完成本教學課程之後，您可以根據接下來要執行的動作，選擇要移除的資源。

若您希望繼續進行下一個教學課程，您可以保留在此處設定的資源，並重複使用 Azure Digital Twins 執行個體而不清除當中的任何項目。

如果您想要繼續使用本文中的 Azure Digital Twins 執行個體，但清除其所有模型、對應項和關聯性，請執行下列 az dt job deletion CLI 命令：
```
az dt job deletion create -n <name-of-Azure-Digital-Twins-instance> -y
```
如果您只想要刪除部分元素，可以使用 az dt twin relationship delete、az dt twin delete 和 az dt model delete 命令，選擇性地只刪除您想要移除的元素。

如果您不需要在本教學課程中建立的任何資源，可以使用 az group delete CLI 命令刪除本文的 Azure Digital Twins 執行個體和其他所有資源。這會刪除資源群組中的所有 Azure 資源，以及資源群組本身。

重要

刪除資源群組是無法回復的動作。資源群組和其中包含的所有資源都將永久刪除。請確定您不會誤刪錯誤的資源群組或資源。

開啟 Azure Cloud Shell 或本機 CLI 視窗，並執行以下命令，以刪除資源群組及其包含的所有內容。
```
az group delete --name <your-resource-group>
```

您也可以刪除您在本機電腦上建立的模型檔案。

下一步

在本教學課程中，您透過使用 Azure CLI 在執行個體中建置了圖形，來開始使用 Azure Digital Twins。您建立了模型、數位對應項和關聯性以形成圖表。您也在圖表上執行了一些查詢，了解 Azure Digital Twins 可以針對環境回答的問題種類。

請繼續進行下一個教學課程，將 Azure Digital Twins 結合其他 Azure 服務，來完成資料驅動的端對端案例：

連線端對端解決方案

共用方式為