教學課程：部署 Azure Digital Twins 預覽並設定空間圖表

發行項
01/10/2020

重要

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

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

您可以使用 Azure Digital Twins 預覽版在一致的空間系統中將人員、地點及裝置結合在一起。這系列的教學課程會示範如何使用 Azure Digital Twins 來偵測溫度和空氣品質狀況最佳的會議室使用情况。

這些教學課程會逐步引導您使用 .NET 主控台應用程式來建置辦公大樓的案例。這棟大樓有多個樓層，每個樓層各有許多會議室。會議室內含一些裝置，附加可偵測移動、周圍溫度和空氣品質的感應器。

您將了解如何使用 Azure Digital Twins 服務，複寫建築物中的實體區域和實體作為數位物件。您會使用另一個主控台應用程式來模擬裝置事件。然後，您將了解如何以近乎即時的方式監視來自這些實體區域和實體的事件。

辦公室管理員可以使用此資訊，協助在此建築物內工作的員工預約狀況最佳的會議室。辦公室設備管理員可以使用您的設定來取得會議室的使用量趨勢，以及監視運作狀況以便進行維護。

在本系列的第一個教學課程中，您將了解如何：

部署 Digital Twins。
將權限授與應用程式。
修改 Digital Twins 範例應用程式。
佈建您的建築物。

這些教學課程會使用並修改尋找可用會議室快速入門所用的相同範例，以涵蓋更詳細且深入的概念。

必要條件

Azure 訂用帳戶。如果您沒有 Azure 帳戶，請建立一個免費帳戶。
.NET Core SDK。這些教學課程中使用的 Azure Digital Twins 範例都是以 C# 撰寫。請務必在開發電腦上安裝 .NET Core SDK 2.1.403 版或更新版本，以建置及執行範例。在命令視窗中執行 dotnet --version，以確認電腦上安裝的版本是否正確。
Visual Studio Code 以探索範例程式碼。

部署 Digital Twins

使用這一節中的步驟，建立 Azure Digital Twins 服務的新執行個體。每個訂用帳戶只能建立一個執行個體。如果您已經有執行個體在執行，請跳至下一節。

登入 Azure 入口網站。
選取首頁側邊的導覽列，然後選取 [+ 建立資源]。
搜尋 Digital Twins，然後選取 [Digital Twins]。

或者，選取 [物聯網]，然後選取 [Digital Twins (預覽)]。
選取 [建立] 以啟動部署程序。
在 [Digital Twins] 窗格中，輸入下列資訊：
- 資源名稱：為 Digital Twins 執行個體建立獨一無二的名稱。
- 訂用帳戶：選擇您要用來建立此 Digital Twins 執行個體的訂用帳戶。
- 資源群組：選取或建立 Digital Twins 執行個體的資源群組。
- 位置：選取最接近您裝置的位置。
檢閱 Digital Twins 資訊，然後選取 [建立]。 Digital Twins 執行個體可能需要幾分鐘的時間才會建立好。您可以在 [通知] 窗格中監視進度。
開啟 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。

將權限授與應用程式

Digital Twins 會使用 Azure Active Directory (Azure AD) 來控制服務的讀取/寫入權限。任何需要與 Digital Twins 執行個體連線的應用程式，都必須向 Azure AD 註冊。本節中的步驟示範如何註冊範例應用程式。

如果您已經有一個應用程式註冊，您可以將它重複使用於您的範例。不過，請瀏覽本節內容，以確定您的應用程式註冊設定正確。

注意

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

在 Azure 入口網站中，從可展開的左側功能表開啟 Azure Active Directory，然後開啟 [應用程式註冊] 窗格。
選取 [+ 新增註冊] 按鈕。
在 [名稱] 方塊中為此應用程式註冊提供易記的名稱。
1. 在 [重新導向 URI (選擇性)] 區段底下的文字方塊中，輸入 https://microsoft.com。
2. 確認 Azure Active Directory 應用程式支援哪些帳戶和租用戶。
3. 選取 [註冊]。
[驗證] 刀鋒視窗會指定重要的驗證組態設定。
1. 選取 [+ 新增平台]，以新增 [重新導向 URI] 並設定 [存取權杖]。
2. 選取 [是]，將應用程式指定為公用用戶端。
3. 確認 Azure Active Directory 應用程式支援哪些帳戶和租用戶。
選取適當的平台後，在使用者介面右側的側邊面板中，設定您的 [重新導向 URI] 和 [存取權杖]。
1. [重新導向 URI] 必須符合驗證要求所提供的位址：
  - 對於裝載在本機開發環境中的應用程式，請選取 [公用用戶端 (行動和傳統型)]。請務必將 [公用用戶端] 設定為 [是]。
  - 對於裝載在 Azure App Service 上的單頁應用程式，請選取 [Web]。
2. 判斷 [登出 URL] 是否適當。
3. 勾選 [存取權杖] 或 [識別碼權杖]，以啟用隱含授與流程。
按一下 [設定]，然後按 [儲存]。
開啟已註冊應用程式的 [概觀] 窗格，並將下列實體的值複製到暫存檔。您會使用這些值來設定後續章節的應用程式範例。
- 應用程式 (用戶端) 識別碼
- 目錄 (租用戶) 識別碼
開啟應用程式註冊的 [API 權限] 窗格。選取 [+ 新增權限] 按鈕。在 [要求 API 權限] 窗格中選取 [我的組織使用的 API] 索引標籤，然後搜尋下列其中一個項目：
1. Azure Digital Twins. 選取 Azure Digital Twins API。
2. 或者，搜尋 Azure Smart Spaces Service。選取 [Azure 智慧空間服務] API。
重要

所顯示的 Azure AD API 名稱和識別碼取決於您的租用戶：
- 測試租用戶和客戶帳戶應搜尋 Azure Digital Twins。
- 其他 Microsoft 帳戶應搜尋 Azure Smart Spaces Service。
任一 API 經選取後，將會在相同的 [要求 API 權限] 窗格中顯示為 Azure Digital Twins。選取 [讀取 ] 下拉式選項，然後選取 [Read.Write] 核取方塊。選取 [新增權限] 按鈕。
根據您組織的設定，您可能需要執行其他步驟，授與對此 API 的系統管理員存取權。請連絡系統管理員以取得詳細資訊。管理員存取權一經核准，[API 權限] 窗格中的 [需要管理員同意] 資料行就會顯示您的權限。

確認顯示 Azure Digital Twins。

設定 Digital Twins 範例

本節將逐步引導您設定透過 Digital Twins REST API 通訊的 Azure Digital Twins 應用程式。

下載範例

如果您已經針對尋找可用會議室快速入門下載範例，您可以略過這些步驟。

下載 Digital Twins .NET 範例。
將電腦上 zip 資料夾的內容解壓縮。

探索範例

在擷取的範例資料夾中，開啟 Visual Studio Code 中的檔案 digital-twins-samples-csharp\digital-twins-samples.code-workspace。此檔案包含兩個專案：

您可以使用佈建範例 occupancy-quickstart 來設定和佈建空間智慧圖形。此圖形是實體空間與其所含資源的數位化影像。它會使用物件模型來定義智慧型建築物的物件。如需 Digital Twin 和 REST API 的完整清單，請瀏覽此 REST API 文件，或針對您的執行個體所建立的管理 API URL。

若要探索範例以了解如何與 Digital Twins 執行個體通訊，您可以從 src\actions 資料夾著手。此資料夾中的檔案會實作您將在這些教學課程中使用的命令：
- provisionSample.cs 檔案示範如何佈建空間圖形。
- getSpaces.cs 檔案可取得已佈建空間的相關資訊。
- getAvailableAndFreshSpaces.cs 檔案可取得自訂函式 (稱為使用者定義的函式) 的結果。
- createEndpoints.cs 檔案可建立端點來與其他服務互動。
模擬範例 device-connectivity 可模擬感應器資料，並將資料傳送到針對您的 Digital Twins 執行個體所佈建的 IoT 中樞。您會在佈建空間圖形之後，在下一個教學課程中使用此範例。用來設定此範例的感應器和裝置識別碼，應該與您要用來佈建圖形的感應器和裝置識別碼相同。

設定佈建範例

開啟命令視窗，然後移至所下載的範例。執行以下命令：
```
cd occupancy-quickstart/src
```
執行此命令，將相依性還原至範例專案：
```
dotnet restore
```
在 Visual Studio Code 中，開啟 occupancy-quickstart 專案中的 appSettings.json 檔案。更新下列值：
- ClientId：輸入 Azure AD 應用程式註冊的應用程式識別碼。您在設定應用程式權限的章節中記下了這個識別碼。
- Tenant：輸入 Azure AD 租用戶的目錄識別碼。您也在設定應用程式權限的章節中記下了這個識別碼。
- BaseUrl：輸入您的 Digital Twins 執行個體 URL。若要取得此 URL，以您執行個體的值取代此 URL 中的預留位置：https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/。您也可以從部署區段修改「管理 API URL」，藉此來取得此 URL。將 swagger/ 取代為 api/v1.0/。
檢閱您可以使用此範例來探索的 Digital Twins 功能清單。執行以下命令：
```
dotnet run
```

了解佈建程序

本節說明範例如何佈建建築物的空間圖表。

在 Visual Studio Code 中，瀏覽至 occupancy-quickstart\src\actions 資料夾並開啟 provisionSample.cs 檔案。請注意下列函式：

public static async Task<IEnumerable<ProvisionResults.Space>> ProvisionSample(HttpClient httpClient, ILogger logger)
{
    IEnumerable<SpaceDescription> spaceCreateDescriptions;
    using (var r = new StreamReader("actions/provisionSample.yaml"))
    {
        spaceCreateDescriptions = await GetProvisionSampleTopology(r);
    }

    var results = await CreateSpaces(httpClient, logger, spaceCreateDescriptions, Guid.Empty);

    Console.WriteLine($"Completed Provisioning: {JsonConvert.SerializeObject(results, Formatting.Indented)}");

    return results;
}

此函式會使用相同資料夾中的 provisionSample.yaml。開啟此檔案，並記下辦公大樓的階層：Venue、Floor、Area 和 Rooms。上述任何實體空間均可包含「裝置」和「感應器」。每個專案都有預先定義的 type，例如 Floor、Room。

範例 yaml 檔案會顯示使用 Default Digital Twins 物件模型的空間圖形。此模型可提供適用於大部分類型的泛型名稱。對於大樓來說，使用泛型名稱就已足夠。例如，對 SensorDataType 使用 Temperature，對 SpaceBlobType 使用 Map。範例空間類型是子類型為 FocusRoom、ConferenceRoom 等等的 Room。

如果您必須針對不同類型的場地 (例如工廠) 建立空間圖形，您可能需要不同的物件模型。您可以在命令列上針對佈建範例執行 dotnet run GetOntologies 命令，以找出可供使用的模型。

如需空間圖形和物件模型的詳細資訊，請參閱了解 Digital Twins 物件模型和空間智慧圖形。

修改範例空間圖形

provisionSample.yaml 檔案包含下列節點：

resources：resources 節點會建立 Azure IoT 中樞資源來與您設定中的裝置進行通訊。位於您圖形根節點的 IoT 中樞，可以與您圖形中的所有裝置和感應器通訊。
spaces：在 Digital Twins 物件模型中，spaces 表示實際位置。每個空間都有一個 Type，例如 Region、Venue 或 Customer，以及一個易記 Name的。空間可以屬於建立階層式結構的其他空間。 provisionSample.yaml 檔案有虛構建築物的空間圖形。請注意，Venue 內的 Floor 類型、樓層中的 Area，以及區域中 Room 節點的空間邏輯巢狀。
devices：空間可以包含 devices，這是可管理許多感應器的實體或虛擬實體。例如，裝置可能是用戶的電話、Raspberry Pi 感測器 Pod 或閘道。在您範例的虛構建築物中，請注意名為「聚焦會議室」(Focus Room) 且包含 Raspberry Pi 3 A1 裝置的會議室。每個裝置節點都是以唯一的 hardwareId 識別，這已在範例中硬式編碼。若要針對實際生產環境設定這個範例，請以您設定中的值取代這些值。
sensors：裝置可以包含多個 sensors。其可偵測並記錄實體變更，例如溫度、移動和電力。每個感應器節點都是以 hardwareId 唯一識別 (已在此硬式編碼)。對於實際應用程式，請使用設定中感應器的唯一識別碼來取代這些值。 provisionSample.yaml 檔案有兩個感應器可記錄 Motion 和 CarbonDioxide。在 CarbonDioxide 感應器的程式碼行下面新增下列幾行，以新增另一個感應器來記錄 Temperature。在 provisionSample.yaml 中，這幾行已註解化。您可以藉由移除每一行前面的 # 字元來將該行取消註解。
```
        - dataType: Temperature
          hardwareId: SAMPLE_SENSOR_TEMPERATURE
```
注意

請確定 dataType 和 hardwareId 索引鍵與此程式碼片段上方的陳述式相符。此外確定您的編輯器不會以空格取代標籤。

儲存並關閉 provisionSample.yaml 檔案。在下一個教學課程中，您會在此檔案中新增更多資訊，然後佈建 Azure Digital Twins 範例建築物。

提示

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

清除資源

至此，如果您不想要再探索 Azure Digital Twins，請放心地刪除在本教學課程中建立的資源：

從 Azure 入口網站的左側功能表中，選取 [所有資源]，選取您的 Digital Twins 資源群組，然後選取 [刪除]。

提示

如果您在刪除 Digital Twins 執行個體時遇到問題，已推出的服務更新中具有修正程式。請重試刪除執行個體。
如有必要，請刪除工作電腦上的應用程式範例。

下一步

若要了解如何實作自訂邏輯來監視範例建築物的狀況，請繼續進行本系列的下一個教學課程：

教學課程：佈建建築物及監視運作狀況