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

• 範例用戶端應用程式
• CLI

在本教學課程中，您將使用模型、對應項和關聯性，在 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 認證

此範例會在本機電腦上執行 Azure Digital Twins 實例時，使用 DefaultAzureCredential （程式庫的 Azure.Identity 一部分）來驗證使用者。 如需用戶端應用程式使用 Azure Digital Twins 進行驗證之不同方式的詳細資訊，請參閱 撰寫應用程式驗證碼 。

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

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

執行範例專案

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

dotnet run

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

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

提示

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

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

使用 DTDL 建立實體環境模型

現在已設定 Azure Digital Twins 實例和範例應用程式，您可以開始建置案例的圖表。

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

模型類似于物件導向程式設計語言中的類別;它們是使用者定義的範本，您可以具現化來建立 數位對應項 。 Azure Digital Twins 的模型是以稱為 Digital Twins 定義語言 （DTDL） 的類似 JSON 語言撰寫，並以其屬性、關聯性和元件來定義對應項的類型。

注意

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

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

開啟 Room.json 進行編輯，並對程式碼進行下列變更：

1. 更新版本號碼，指出您提供此模型的更新版本。 將值結尾的 @id 1 變更 為 2 ，以執行此動作。 任何大於目前版本號碼的數位也會運作。

2. 編輯屬性。 將屬性的名稱 Humidity 變更為 HumidityLevel （或您想要的異動專案）。如果您使用與 HumidityLevel 不同的 專案，請記得您在教學課程中使用和繼續使用該內容，而不是 HumidityLevel ）。

3. 新增屬性。 在 HumidityLevel 結束于第 15 行的屬性底下，貼上下列程式碼，將屬性新增 RoomName 至會議室：

   ,{
     "@type": "Property",
     "name": "RoomName",
     "schema": "string"
   }
   

4. 新增關聯。 在您剛新增的屬性 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 服務實例。 上傳模型之後，您可以建立使用這些模型的對應項實例。

1. 返回開啟至 digital-twins-samples-main\AdtSampleApp\SampleClientApp 資料夾的主控台視窗，並使用 再次 dotnet run 執行主控台應用程式。

2. 在專案主控台視窗中，執行下列命令來上傳更新的會議室模型，以及您將在下一節中用來建立不同類型的對應項的 Floor 模型。

   CreateModels Room Floor
   

   輸出應該表示已成功建立模型。

3. 執行 命令 GetModels true 來確認已建立模型。 此命令會列印已上傳至 Azure Digital Twins 實例之所有模型的完整資訊。 在結果中尋找編輯過的會議室模型：

   

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

錯誤

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

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

CreateModels Room

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

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

建立數位對應項

現在，某些模型已上傳至您的 Azure Digital Twins 實例，您可以根據模型定義建立 數位 對應項。 數位對應項代表您商務環境中的實體，例如農場上的感應器、建築物中的會議室或汽車中的燈光。

若要建立數位對應項，您可以使用 CreateDigitalTwin 命令。 您必須參考對應項所依據的模型，而且可以選擇性地為模型中的任何屬性定義初始值。 您不需要在這個階段傳遞任何關聯性資訊。

1. 在執行中的專案主控台中執行此程式碼，根據您稍早更新的 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
   

   這些命令的輸出應該表示已成功建立對應項。

   

2. 您可以執行 命令來確認已建立對應 Query 項。 此命令會查詢 Azure Digital Twins 實例中所包含的所有數位對應項。 在結果中尋找 room0、room1、floor0 和 floor1 對應項。

注意

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

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

修改數位對應項

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

注意

基礎 REST API 會使用 JSON 修補程式 格式來定義對應項的更新。 命令列應用程式也會使用此格式，以更真實的體驗基礎 API 預期。

1. 執行此命令，將 room0 的 RoomName 從 「Room0」 變更為 「PresidentialSuite」：

   UpdateDigitalTwin room0 add /RoomName string PresidentialSuite
   

   輸出應該表示對應項已成功更新。

2. 您可以執行此命令來確認更新是否成功，以查看 room0 的資訊：

   GetDigitalTwin room0
   

   輸出應該會反映更新的名稱。

藉由新增關聯性來建立圖表

接下來，您可以建立這些對應項之間的一些關聯性，以將它們連線到對應項 圖形 。 對應項圖形可用來代表整個環境。

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

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

1. 執行下列命令，將您稍早建立的每個 Floor 對應項關聯性新增 contains 至對應的 Room 對應項。 關聯性為 relationship0 和 relationship1。

   CreateRelationship floor0 contains room0 relationship0
   CreateRelationship floor1 contains room1 relationship1
   

   提示

   containsFloor 模型中 的 關聯性也以兩個字串屬性定義， ownershipUserownershipDepartment 因此您也可以在建立關聯性時，提供這些屬性的初始值引數。 以下是上述命令的替代版本，可建立關聯性0，同時指定這些屬性的初始值：

   CreateRelationship floor0 contains room0 relationship0 ownershipUser string MyUser ownershipDepartment string myDepartment
   

   這些命令的輸出會確認已成功建立關聯性：

   

2. 您可以使用下列任何命令來驗證關聯性，這會在 Azure Digital Twins 實例中列印關聯性。

   • 若要查看每個樓層的所有關聯性（從一邊檢視關聯性）：

     GetRelationships floor0
     GetRelationships floor1
     

   • 若要查看抵達每個房間的所有關聯性（從「另一方」檢視關聯性）：

     GetIncomingRelationships room0
     GetIncomingRelationships room1
     

   • 若要個別尋找這些關聯性，請依識別碼：

     GetRelationship floor0 relationship0
     GetRelationship floor1 relationship1
     

您在本教學課程中設定的對應項和關聯性會形成下列概念圖表：

查詢對應項圖形以回答環境問題

Azure Digital Twins 的主要功能是 能夠輕鬆且有效率地查詢 對應項圖形，以回答有關您環境的問題。

注意

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

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

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

1. Azure Digital Twins 中代表我環境的所有實體為何？ （全部查詢）

   Query
   

   此命令可讓您一目了然地盤點環境，並確定所有專案都以您想要在 Azure Digital Twins 內呈現。 此命令的結果是輸出，其中包含每個數位對應項及其詳細資料。 以下是摘錄：

   

   提示

   在範例專案中，不含任何其他引數的命令 Query 相當於 Query SELECT * FROM DIGITALTWINS 。 若要使用 查詢 API 或 CLI 命令 查詢實例中的所有對應項，請使用較長的 （完整） 查詢。

2. 我環境中的所有會議室為何？ （依模型查詢）

   Query SELECT * FROM DIGITALTWINS T WHERE IS_OF_MODEL(T, 'dtmi:example:Room;2')
   

   您可以將查詢限制為特定類型的對應項，以取得所代表內容的詳細資訊。 結果顯示 room0 和 room1，但不顯示 floor0 或 floor1（因為它們是樓層，而不是房間）。

   

3. 樓上所有的房間都是什麼？ （依關聯性查詢）

   Query SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.$dtId = 'floor0'
   

   您可以根據圖形中的關聯性進行查詢，以取得對應項連接方式的相關資訊，或將查詢限制在特定區域。 只有 room0 位於 floor0，因此這是結果中唯一的房間。

   

4. 我環境中所有雙胞胎的溫度都高於 75？ （依屬性查詢）

   Query SELECT * FROM DigitalTwins T WHERE T.Temperature > 75
   

   您可以根據屬性來查詢圖表，以回答各種問題，包括在您的環境中找出可能需要注意的極端值。 也支援其他比較運算子 （ < 、 > 、 = 或 ！= ） 。 room1 會顯示在此結果中，因為它的溫度為 80。

   

5. 樓0上的所有房間都溫度高於 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
   

   您也可以使用 、 等組合運算子，結合先前的查詢，就像 ANDORNOT 在 SQL 中一樣。 此查詢會使用 AND ，讓先前有關對應項溫度的查詢更具體。 結果現在只包含樓面 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 服務結合，以完成資料驅動的端對端案例：

連線端對端解決方案