教學課程：使用範例用戶端應用程式來建立 Azure Digital Twins 圖表

發行項
05/15/2024

在本教學課程中，您將使用模型、對應項和關聯性，在 Azure Digital Twins 中建置圖表。本教學課程的工具是會與 Azure Digital Twins 執行個體互動的範例命令列用戶端應用程式。此用戶端應用程式類似於撰寫用戶端應用程式程式碼中所撰寫的應用程式。

您可以使用此範例來執行基本的 Azure Digital Twins 動作，例如上傳模型、建立與修改分身，以及建立關聯性。您也可以查看範例的程式碼 (英文) 以了解 Azure Digital Twins API，並依您想要的方式修改範例專案來練習實作命令。

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

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

必要條件

開始本教學課程之前，請先從下列必要條件開始：

如尚未擁有 Azure 訂用帳戶，請在開始之前先建立免費帳戶。
本教學課程使用 .NET。您可以從下載 .NET 下載此適用於多個平台的 .NET SDK 的最新版本。

然後，繼續進行本節的其餘部分，以設定剩餘必要條件。

取得範例資源

本教學課程是由以 C# 撰寫的 Azure Digital Twins 端對端樣本專案 (英文) 所驅動。瀏覽至範例連結，然後選取標題底下的 [瀏覽程式碼] 按鈕，以在電腦上取得樣本專案。

這將會帶您前往樣本的 GitHub 存放庫，您可以選取 [程式碼] 按鈕，以及 [下載 ZIP] 按鈕，以 .zip 形式下載樣本。

這會將 .ZIP 資料夾以 digital-twins-samples-main.zip 的形式下載至您的機器。將資料夾解壓縮並擷取檔案。

準備 Azure Digital Twins 執行個體

若要使用本文中的 Azure Digital Twins，您必須要有 Azure Digital Twins 執行個體，以及必要的使用權限。如果您已經設定好 Azure Digital Twins 執行個體，您可以直接使用該執行個體，並跳至下一節。否則，請依照設定執行個體和驗證中的指示進行。指示中包含的資訊可協助您確認已成功完成每個步驟。

設定執行個體之後，請記下執行個體的主機名稱。您可以在 Azure 入口網站中找到主機名稱。

設定範例專案

接下來，請設定將和您 Azure Digital Twins 執行個體互動的範例用戶端應用程式。

在您的電腦上瀏覽至先前從 Azure Digital Twins 端對端樣本 (英文) 下載的資料夾 (如果尚未解壓縮，請將其解壓縮)。

在資料夾內，瀏覽至 digital-twins-samples-main\AdtSampleApp\SampleClientApp，然後開啟 appsettings.json 檔案。此 JSON 檔案包含執行專案所需的組態變數。

在檔案本文中，將 instanceUrl 變更為您的 Azure Digital Twins 執行個體 URL (透過新增 https:// 至主機名稱前方，如下所示)。

{
  "instanceUrl": "https://<your-Azure-Digital-Twins-instance-host-name>"
}

儲存並關閉檔案。

設定本機 Azure 認證

這個範例會使用 DefaultAzureCredential (屬於 Azure.Identity 程式庫)，在本機電腦上執行時，使用 Azure Digital Twins 執行個體來驗證使用者。如需深入了解用戶端應用程式向 Azure Digital Twins 進行驗證的不同方式，請參閱撰寫應用程式驗證碼。

使用 DefaultAzureCredential，該範例會搜尋本機環境中的認證，例如在本機 Azure CLI 中或在 Visual Studio 或 Visual Studio Code 中的 Azure 登入。因此，您應該透過下列其中一種機制本機登入 Azure，以設定該範例的認證。

如果您使用 Visual Studio 或 Visual Studio Code 來執行程式碼範例，請確定使用要用來存取 Azure Digital Twins 執行個體的相同 Azure 認證來登入該編輯器。如果您使用本機 CLI 視窗，請執行 az login 命令來登入您的 Azure 帳戶。之後，當您執行程式碼範例時，應該會自動驗證。

執行範例專案

現已設定好應用程式和驗證，接下來請開啟您要用來執行專案的本機「主控台視窗」。在主控台中瀏覽至 digital-twins-samples-main\AdtSampleApp\SampleClientApp 資料夾，然後使用這個 dotnet 命令來執行專案：

dotnet run

專案將會開始執行，並進行驗證，然後等候命令。

以下為專案主控台外觀的螢幕擷取畫面：

提示

如需您可以搭配此專案使用的所有可能命令清單，請在專案主控台中輸入 help，然後按返回。

確認應用程式已成功執行之後，便可以停止執行專案。您會在本教學課程稍後再次執行此專案。

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

現已設定好 Azure Digital Twins 執行個體和範例應用程式，接下來可以開始建置某個案例的圖表。

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

模型類似於物件導向程式設計語言中的類別；其為使用者定義的範本，加以具現化即可建立數位對應項。 Azure Digital Twins 的模型會以稱為「數位對應項定義語言 (DTDL)」的類 JSON 語言來撰寫，並以對應項的屬性、關聯性和元件來定義對應項類型。

注意

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

在您稍早下載的範例專案資料夾中，瀏覽至 digital-twins-samples-main\AdtSampleApp\SampleClientApp\Models 資料夾。此資料夾包含範例模型。

開啟 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 服務執行個體。在您上傳模型後，就可以建立使用模型的對應項執行個體。

返回開啟至 digital-twins-samples-main\AdtSampleApp\SampleClientApp 資料夾的主控台視窗，並使用 dotnet run 再次執行主控台應用程式。
在專案主控台視窗中，執行下列命令以上傳您更新的 Room 模型，以及您在下一節中還會使用的 Floor 模型，以建立其他對應項類型。
```
CreateModels Room Floor
```
輸出應該會指出模型已成功建立。
執行 GetModels true 命令以驗證模型已建立。此命令會列印已上傳至 Azure Digital Twins 執行個體之所有模型的完整資訊。在結果中尋找編輯過的 Room 模型：

讓主控台應用程式繼續執行，以進行後續步驟。

錯誤

範例應用程式也會處理來自服務的錯誤。

若要進行測試，請重新執行 CreateModels 命令，嘗試重新上傳您已上傳的 Room 模型：

CreateModels Room

由於無法覆寫模型，此命令現在會傳回服務錯誤，指出您嘗試建立的某些模型識別碼已存在。

如需如何刪除現有模型的詳細資訊，請參閱管理 DTDL 模型。

建立數位分身

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

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

在正在執行專案的主控台中執行此程式碼，依據您先前更新的 Room 模型及另外一個 Floor 模型建立數個對應項。回想一下，由於 Room 具備三個屬性，因此您可以提供引數來為這些屬性提供初始值。 (一般而言，初始化屬性值是選擇性的，但本教學課程需要這些值)。
```
CreateDigitalTwin dtmi:example:Room;2 room0 RoomName string Room0 Temperature double 70 HumidityLevel double 30
CreateDigitalTwin dtmi:example:Room;2 room1 RoomName string Room1 Temperature double 80 HumidityLevel double 60
CreateDigitalTwin dtmi:example:Floor;1 floor0
CreateDigitalTwin dtmi:example:Floor;1 floor1
```
這些命令的輸出應該會指出分身已成功建立。
您可以透過執行 Query 命令來驗證對應項已建立。此命令向 Azure Digital Twins 執行個體查詢其包含的所有數位分身。在結果中尋找 room0、room1、floor0 和 floor1 對應項。

注意

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

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

修改數位分身

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

注意

基礎 REST API 會使用 JSON Patch (英文) 格式來定義對應項的更新。命令列應用程式也會使用此格式，讓您更真實地體驗基礎 API 所預期的內容。

請執行此命令，將 room0 的 RoomName 從「Room0」變更為「PresidentialSuite」：
```
UpdateDigitalTwin room0 add /RoomName string PresidentialSuite
```
輸出應該會指出分身已成功更新。
您可以執行此命令查看 room0 的資訊，以確認更新成功：
```
GetDigitalTwin room0
```
輸出應該會反映更新的名稱。

新增關聯性以建立圖表

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

您可以從一個對應項建立至另一個對應項的關聯性類型，定義在您稍早上傳的模型 (部分機器翻譯) 中。 Floor 的模型定義 (英文) 會指定樓層可以有稱為 contains 的關聯性類型，而可建立每個 Floor 對應項與其所包含對應房間的 contains 類型關聯性。

若要新增關聯性，請使用 CreateRelationship 命令。指定關聯性的來源對應項、關聯性類型，以及關聯性所連接的對應項。最後，為關聯性提供唯一識別碼。

執行下列程式碼，以新增先前所建立的每個 Floor 對應項與對應的 Room 對應項的 contains 關聯性。關聯性名為 relationship0 和 relationship1。
```
CreateRelationship floor0 contains room0 relationship0
CreateRelationship floor1 contains room1 relationship1
```
提示

Floor 模型 (英文) 中的 contains 關聯性也定義了兩個字串屬性：ownershipUser 和 ownershipDepartment，因此您也可以在建立關聯性時，為這些屬性提供有初始值的引數。以下是可建立 relationship0 的上述命令替代版本，其也會指定這些屬性的初始值：
```
CreateRelationship floor0 contains room0 relationship0 ownershipUser string MyUser ownershipDepartment string myDepartment
```
這些命令的輸出會確認已成功建立關聯性：
您可以使用下列任何一個命令來驗證關聯性，這些命令會列印您 Azure Digital Twins 執行個體中的關聯性。
- 查看來自每一個樓層的所有關聯性 (從其中一端檢視關聯性)：
```
GetRelationships floor0
GetRelationships floor1
```
- 查看抵達每個房間的所有關聯性 (從「另一端」檢視關聯性)：
```
GetIncomingRelationships room0
GetIncomingRelationships room1
```
- 依識別碼個別查詢這些關聯性：
```
GetRelationship floor0 relationship0
GetRelationship floor1 relationship1
```

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

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

Azure Digital Twins 的主要功能是能夠輕鬆且有效率地查詢分身圖表，以回答有關環境的問題。

注意

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

在執行中的專案主控台中執行下列命令，以回答範例環境的一些問題。

我環境中的所有實體在 Azure Digital Twins 中代表什麼？ (查詢全部)
```
Query
```
此命令讓您一眼就能了解環境，確認所有項目的呈現方式都與您希望在 Azure Digital Twins 中的呈現方式相同。此命令的結果包含每個數位對應項及其詳細資料的輸出。以下是節錄：

提示

在範例專案中，不包含任何其他引數的 Query 命令等同於 Query SELECT * FROM DIGITALTWINS。若要使用查詢 API 或 CLI 命令來查詢執行個體中的所有對應項，請使用較長 (完整) 的查詢。
我的環境中有哪些房間？ (依模型查詢)
```
Query SELECT * FROM DIGITALTWINS T WHERE IS_OF_MODEL(T, 'dtmi:example:Room;2')
```
您可以將查詢限制在特定類型的分身，以取得其表示項目更具體的資訊。此查詢的結果顯示 room0 與 room1，但不會顯示 floor0 或 floor1 (因為其為樓層，而非房間)。
floor0 上有哪些房間？ (依關聯性查詢)
```
Query SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.$dtId = 'floor0'
```
您可以根據圖表中的關聯性進行查詢，以取得分身連線方式的資訊，或是將您的查詢限制在特定區域。由於只有 room0 位於 floor0 上，因此其為結果中唯一的房間。
我的環境中有哪些對應項的溫度高於 75？ (依屬性查詢)
```
Query SELECT * FROM DigitalTwins T WHERE T.Temperature > 75
```
您可以根據屬性查詢圖表來回答各種問題，包括尋找您環境中需要注意的極端值。也支援其他比較運算子 (<、>、= 或 !=)。 room1 顯示在此處的結果中，因為其溫度為 80。
floor0 上有哪些房間的溫度高於 75？ (複合查詢)
```
Query 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 執行個體，但要清除其所有模型、對應項和關聯性，則可以使用範例應用程式的 DeleteAllTwins 和 DeleteAllModels 命令，分別清除執行個體中的對應項和模型。

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

重要

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

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

您也可能想要從本機電腦刪除所下載的專案資料夾。

下一步

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

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

連線端對端解決方案

共用方式為