共用方式為

快速入門：使用 Azure Digital Twins 尋找空閒會議室

  • 發行項

重要

已發行新版本的 Azure Digital Twins 服務。 在新的服務擴充功能中，本檔集) 中所述的原始 Azure Digital Twins 服務 (已淘汰。

若要檢視新服務的檔，請流覽使用中的 Azure Digital Twins 檔。

Azure Digital Twins 服務可讓您重新建立實體環境的數位影像。 然後，您可以收到環境事件通知，並自訂關於通知的回應。

本快速入門會使用一組 .NET 範例將虛構辦公大樓數位化。 文中會示範如何尋找該大樓內的空閒會議室。 使用 Digital Twins，便可將許多感應器關聯至環境。 您還可以借助於模擬的二氧化碳感應器，來了解空閒會議室的空氣品質是否理想。 其中一個應用程式範例會產生隨機的感應器資料，以協助您將此案例視覺化。

下列影片將摘要說明快速入門的設定：

必要條件

  1. 如果您沒有 Azure 帳戶，請在您開始之前先建立 免費帳戶。

  2. 您在此快速入門中執行的兩個主控台應用程式是使用 C# 所撰寫的。 在開發電腦上安裝 .NET Core SDK 2.1.403 版或更新版本。 如果您已安裝 .NET Core SDK，請確認開發電腦上目前的 C# 版本。 在命令提示字元中執行 dotnet --version。

  3. 下載範例 C# 專案。 將 digital-twins-samples-csharp-master.zip 封存檔解壓縮。

建立 Digital Twins 執行個體

遵循這一節中的步驟，在入口網站中建立新的 Digital Twins 執行個體。

  1. 登入 Azure 入口網站。

  2. 選取首頁側邊的導覽列，然後選取 [+ 建立資源]。

    展開首頁側邊列，然後選取 [+ 建立資源]

  3. 搜尋 Digital Twins，然後選取 [Digital Twins]。

    用於建立新 Digital Twins 實例的選項

    或者，選取 [物聯網]，然後選取 [Digital Twins (預覽)]。

  4. 選取 [建立] 以啟動部署程序。

    建立並確認資源的部署

  5. 在 [Digital Twins] 窗格中，輸入下列資訊：

    • 資源名稱：為 Digital Twins 執行個體建立獨一無二的名稱。

    • 訂用帳戶：選擇您要用來建立此 Digital Twins 執行個體的訂用帳戶。

    • 資源群組：選取或建立 Digital Twins 執行個體的資源群組。

    • 位置：選取最接近您裝置的位置。

      具有輸入資訊的數字對應項窗格

  6. 檢閱 Digital Twins 資訊，然後選取 [建立]。 Digital Twins 執行個體可能需要幾分鐘的時間才會建立好。 您可以在 [通知] 窗格中監視進度。

  7. 開啟 Digital Twins 執行個體的 [概觀] 窗格。 請記下 [管理 API] 底下的連結。 管理 API URL 的格式為：

    https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swagger

    此 URL 會帶您前往您的執行個體所適用的 Azure Digital Twins REST API 文件。 請閱讀如何使用 Azure Digital Twins Swagger，以了解如何閱讀及使用此 API 文件。 複製管理 API URL 並修改為此格式：

    https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/

    應用程式會使用修改後的 URL 作為基底 URL 來存取執行個體。 將這個修改後的 URL 複製到暫存檔。 您在下一節中將會用到此 URL。

    管理 API 概觀

設定應用程式的權限

本節會向 Azure Active Directory (Azure AD) 註冊應用程式範例，讓此範例可以存取 Digital Twins 執行個體。 如果您已經有一個 Azure AD 應用程式註冊，請將它重複使用於您的範例。 請確定其設定和本節所述相同。

注意

本節提供 Azure AD 應用程式註冊的指示。

  1. 在 Azure 入口網站中，從可展開的左側功能表開啟 Azure Active Directory，然後開啟 [應用程式註冊] 窗格。

    選取 [Azure Active Directory] 窗格

  2. 選取 [+ 新增註冊] 按鈕。

    選取 [新增註冊] 按鈕

  3. 在 [名稱] 方塊中為此應用程式註冊提供易記的名稱。

    1. 在 [重新導向 URI (選擇性)] 區段底下的文字方塊中，輸入 https://microsoft.com。

    2. 確認 Azure Active Directory 應用程式支援哪些帳戶和租用戶。

    3. 選取 [註冊]。

    建立窗格

  4. [驗證] 刀鋒視窗會指定重要的驗證組態設定。

    1. 選取 [+ 新增平台]，以新增 [重新導向 URI] 並設定 [存取權杖]。

    2. 選取 [是]，將應用程式指定為公用用戶端。

    3. 確認 Azure Active Directory 應用程式支援哪些帳戶和租用戶。

    公用用戶端組態設定

  5. 選取適當的平台後，在使用者介面右側的側邊面板中，設定您的 [重新導向 URI] 和 [存取權杖]。

    1. [重新導向 URI] 必須符合驗證要求所提供的位址：

      • 對於裝載在本機開發環境中的應用程式，請選取 [公用用戶端 (行動和傳統型)]。 請務必將 [公用用戶端] 設定為 [是]。
      • 對於裝載在 Azure App Service 上的單頁應用程式，請選取 [Web]。

    2. 判斷 [登出 URL] 是否適當。

    3. 勾選 [存取權杖] 或 [識別碼權杖]，以啟用隱含授與流程。

    設定重新導向 URI

    按一下 [設定]，然後按 [儲存]。

  6. 開啟已註冊應用程式的 [概觀] 窗格，並將下列實體的值複製到暫存檔。 您會使用這些值來設定後續章節的應用程式範例。

    • 應用程式 (用戶端) 識別碼
    • 目錄 (租用戶) 識別碼

    Azure Active Directory 應用程式識別碼

  7. 開啟應用程式註冊的 [API 權限] 窗格。 選取 [+ 新增權限] 按鈕。 在 [要求 API 權限] 窗格中選取 [我的組織使用的 API] 索引標籤，然後搜尋下列其中一個項目：

    1. Azure Digital Twins. 選取 Azure Digital Twins API。

      搜尋 API 或 Azure Digital Twins

    2. 或者，搜尋 Azure Smart Spaces Service。 選取 [Azure 智慧空間服務] API。

      Azure Smart Spaces 的搜尋 API

    重要

    所顯示的 Azure AD API 名稱和識別碼取決於您的租用戶：

    • 測試租用戶和客戶帳戶應搜尋 Azure Digital Twins。
    • 其他 Microsoft 帳戶應搜尋 Azure Smart Spaces Service。

  8. 任一 API 經選取後，將會在相同的 [要求 API 權限] 窗格中顯示為 Azure Digital Twins。 選取 [讀取 ] 下拉式選項，然後選取 [Read.Write] 核取方塊。 選取 [新增權限] 按鈕。

    新增 API 權限

  9. 根據您組織的設定，您可能需要執行其他步驟，授與對此 API 的系統管理員存取權。 請連絡系統管理員以取得詳細資訊。 管理員存取權一經核准，[API 權限] 窗格中的 [需要管理員同意] 資料行就會顯示您的權限。

    管理員 同意核准

    確認顯示 Azure Digital Twins。

建置應用程式

遵循下列步驟來建置會議室使用情形應用程式。

  1. 開啟命令提示字元。 移至 digital-twins-samples-csharp-master.zip 檔案解壓縮到的資料夾。

  2. 執行 cd occupancy-quickstart/src。

  3. 執行 dotnet restore。

  4. 編輯 appSettings.json 以更新下列變數：

    • ClientId：輸入 Azure AD 應用程式註冊的應用程式識別碼，其記載於上一節。
    • Tenant：輸入 Azure AD 租用戶的目錄識別碼，其同樣記載於上一節。
    • BaseUrl：Digital Twins 執行個體的管理 API URL 所用的格式為 https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/。 將此 URL 中的預留位置替換為執行個體在上一節的值。

    儲存更新的檔案。

佈建圖形

此步驟會佈建含有下列項目的 Digital Twins 空間圖形：

  • 數個空間。
  • 一個裝置。
  • 兩個感應器。
  • 一個自訂函式。
  • 一個角色指派。

此空間圖形會使用 provisionSample.yaml 檔案來加以佈建。

  1. 執行 dotnet run ProvisionSample。

    注意

    裝置登入 Azure CLI 工具可用來對 Azure AD 驗證使用者。 使用者必須輸入指定代碼，才能使用 Microsoft 登入頁面來進行驗證。 輸入代碼後，請遵循相關步驟來進行驗證。 當工具執行時，使用者必須進行驗證。

    提示

    如果您在執行此步驟時出現下列錯誤訊息，請確定所複製的變數是否正確：EXIT: Unexpected error: The input is not a valid Base-64 string ...

  2. 佈建步驟可能需要進行幾分鐘的時間。 它也會在 Digital Twins 執行個體內佈建 IoT 中樞。 這個過程會一直循環進行，直到 IoT 中樞顯示狀態為 Running。

    布建範例 - Status=Running

  3. 執行結束時，請複製裝置的 ConnectionString 以便用於裝置模擬器範例。 您只需要複製下圖所述的字串。

    複製 連接字串

    提示

    您可以使用 Azure Digital Twins Graph Viewer 檢視和修改空間圖形。

保持主控台視窗開啟以供稍後使用。

傳送感應器資料

遵循下列步驟來建置及執行感應器模擬器裝置應用程式。

  1. 開啟新的命令提示字元。 移至您在 digital-twins-samples-csharp-master 資料夾中下載的專案。

  2. 執行 cd device-connectivity。

  3. 執行 dotnet restore。

  4. 編輯 appsettings.json 以使用先前的 ConnectionString 來更新 DeviceConnectionString。 儲存更新的檔案。

  5. 執行 dotnet run 來開始傳送感應器資料。 資料會傳送至 Digital Twins，如下圖所示。

    裝置連線能力

  6. 讓此模擬器執行，以便您可以使用下一個步驟的動作來並排檢視結果。 此視窗會顯示傳送到 Digital Twins 的模擬感應器資料。 下一個步驟會進行即時查詢，以尋找有新鮮空氣的空閒會議室。

    提示

    如果您在執行此步驟時出現下列錯誤訊息，請確定所複製的 DeviceConnectionString 是否正確：EXIT: Unexpected error: The input is not a valid Base-64 string ...

尋找有新鮮空氣的空閒空間

感應器範例會模擬兩個感應器的隨機資料值。 它們分別是動作和二氧化碳。 在範例中，有新鮮空氣的空閒會議室定義是會議室內沒有人。 其另外的定義是二氧化碳濃度低於 1,000 ppm。 如果情況不符，就表示沒有空閒會議室，要不然就是空氣品質不良。

  1. 開啟稍早用來執行佈建步驟的命令提示字元。

  2. 執行 dotnet run GetAvailableAndFreshSpaces。

  3. 查看這個命令提示字元和並排顯示的感應器資料命令提示字元。

    感應器資料命令提示字元會每隔五秒將模擬的動作和二氧化碳資料傳送至 Digital Twins。 另一個命令提示字元會即時讀取圖形，以根據隨機的模擬資料來找出有新鮮空氣的空閒會議室。 它會根據最後一次傳送的感應器資料，近乎即時地顯示下列其中一個情況：

    • Room is available and air is fresh

    • Room is not available or air quality is poor

      取得有新鮮空氣的空閒空間

若要了解本快速入門所發生的情況以及已呼叫的 API，請使用 digital-twins-samples-csharp 中找到的程式碼工作區專案來開啟 Visual Studio Code。 使用下列命令：

<path>\occupancy-quickstart\src>code ..\..\digital-twins-samples.code-workspace

教學課程會深入探索此程式碼。 其會告訴您如何修改組態資料，以及呼叫了哪些 API。 如需管理 API 的詳細資訊，請移至 Digital Twins Swagger 頁面：

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger
名稱 更換為
YOUR_INSTANCE_NAME Digital Twins 執行個體的名稱
YOUR_LOCATION 您的執行個體裝載所在的伺服器區域

或者，為求方便，瀏覽至 Digital Twins Swagger。

清除資源

教學課程會詳細說明如何：

  • 建置應用程式讓設施管理員提高設施是否有人使用的辨別能力。
  • 更有效率地管理大樓。

若要繼續進行教學課程，請勿清除在此快速入門中建立的資源。 如果您不打算繼續，請刪除本快速入門建立的所有資源。

  1. 刪除下載存放庫範例時所建立的資料夾。

  2. 從 Azure 入口網站 左側功能表中，選取 [所有資源]。 然後，選取 Digital Twins 資源。 在 [所有資源] 窗格的頂端，選取 [刪除]。

    提示

    如果您先前在刪除 Digital Twins 執行個體時遇到問題，已推出的服務更新中具有修正程式。 請重試刪除執行個體。

下一步

本快速入門使用簡單的案例和範例應用程式，示範如何使用 Digital Twins 來尋找有良好工作條件的會議室。 若要深入分析此案例，請閱讀本教學課程：

教學課程：部署 Azure Digital Twins 及設定空間圖形