整合 Azure Digital Twins 與 Azure SignalR 服務

發行項
01/04/2024

在本文中，您將瞭解如何整合 Azure Digital Twins 與 Azure SignalR 服務。

本文所述的解決方案可讓您將數位對應項遙測資料推送至連線的用戶端，例如單一網頁或行動應用程式。因此，用戶端會使用來自 IoT 裝置的即時計量和狀態進行更新，而不需要輪詢伺服器或提交新的 HTTP 要求以進行更新。

必要條件

以下是在繼續之前，您應該完成的必要條件：

在本文中將解決方案與 Azure SignalR Service 整合之前，您應該先完成 Azure Digital Twins 連線端對端解決方案，因為此操作說明文章會建置在此解決方案之上。本教學課程會逐步引導您設定與虛擬 IoT 裝置搭配運作的 Azure Digital Twins 實例，以觸發數位對應項更新。本操作說明文章會使用 Azure SignalR Service 將這些更新連線到範例 Web 應用程式。
您將需要本教學課程中的下列值：
- 事件方格主題
- 資源群組
- App Service/函式應用程式名稱
您需要在電腦上安裝 Node.js 。

請務必使用 Azure 帳戶登入 Azure 入口網站，因為您必須在本指南中使用。

解決方案架構

您將透過下列路徑將 Azure SignalR 服務連結至 Azure Digital Twins。圖表中的 A、B 和 C 區段取自端對端教學課程必要條件的架構圖表。在本操作說明文章中，您將建置現有架構上的第 D 節，其中包含兩個新的 Azure 函式，可與 SignalR 和用戶端應用程式通訊。

下載範例應用程式

首先，下載必要的範例應用程式。您將需要下列兩個範例：

Azure Digital Twins 端對端範例：此範例包含一個 AdtSampleApp ，其中包含兩個 用來在 Azure Digital Twins 實例周圍移動資料的 Azure 函式（您可以在連線端對端解決方案中更詳細地瞭解此案例）。它也包含 DeviceSimulator 範例應用程式，可模擬 IoT 裝置，每秒產生新的溫度值。
- 如果您尚未將範例下載為必要條件教學課程的一部分，請流覽至範例，然後選取 標題下方的 [流覽程式碼 ] 按鈕。這麼做會帶您前往範例的 GitHub 存放庫，您可以選取 [程式碼 ] 按鈕和 [下載 ZIP]，以下載為 .zip 。
此按鈕會在您的電腦中下載範例存放庫的複本，作為 digital-twins-samples-main.zip 。將資料夾解壓縮。
SignalR 整合 Web 應用程式範例：此範例 React Web 應用程式會從 Azure SignalR 服務取用 Azure Digital Twins 遙測資料。
- 流覽至範例連結，並使用相同的下載程式將範例複本下載到您的電腦，作為 digitaltwins-signalr-webapp-sample-main.zip 。將資料夾解壓縮。

在本節中，您會建立要用於應用程式的基本 Azure SignalR 實例。下列步驟會使用Azure 入口網站來建立新的實例，但您也可以使用 Azure CLI。如需詳細資訊，請參閱 Azure SignalR Service CLI 參考 中的 az signalr create 命令。

登入 Azure 入口網站。
在頁面左上角，選取 [+ 建立資源 ]。
在 [ 建立資源 ] 頁面上的 [搜尋服務和市 集] 文字方塊中， 輸入 signalr ，然後從清單中選取 SignalR 服務 。
在 [ SignalR 服務] 頁面上，選取 [ 建立 ]。
在 [ 基本] 索引 標籤上，輸入新 SignalR Service 實例的基本資訊。輸入下列值：

欄位	建議的值	描述
訂用帳戶	選擇您的訂用帳戶	選取您想要用來建立新 SignalR Service 實例的訂用帳戶。
資源群組	建立名為 SignalRTestResources 的資源群組	選取或建立 SignalR 資源的資源群組。為本教學課程建立新的資源群組，而不是使用現有的資源群組會很有用。若要在完成本教學課程之後釋放資源，請刪除資源群組。刪除資源群組也會刪除屬於群組的所有資源。此動作無法復原。刪除資源群組之前，請確定它不包含您想要保留的資源。如需詳細資訊，請參閱使用資源群組來管理您的 Azure 資源。
資源名稱	testsignalr	輸入要用於 SignalR 資源的唯一資源名稱。如果您的區域中已經採用 testignalr ，請新增數位或字元，直到名稱是唯一的。名稱必須是 1 到 63 個字元的字串，且只包含數位、字母和連字號（ `-` ）字元。名稱不能以連字號字元開頭或結尾，且連續連字號字元無效。
區域	選擇您的區域	為新的 SignalR 服務實例選取適當的區域。 Azure SignalR Service 目前無法在所有區域中使用。如需詳細資訊，請參閱 Azure SignalR 服務區域可用性
定價層	選取 [變更 ]，然後選擇 [ 免費]（僅限開發/測試）。選擇 [ 選取 ] 以確認您選擇的定價層。	Azure SignalR Service 有三個定價層：免費、標準和進階版。除非必要條件另有說明，否則教學課程會使用免費層。如需階層與定價之間功能差異的詳細資訊，請參閱 Azure SignalR 服務定價
服務模式	選擇適當的服務模式	當您在 Web 應用程式中裝載 SignalR 中樞邏輯，並使用 SignalR 服務作為 Proxy 時，請使用預設值。當您使用無伺服器技術，例如 Azure Functions 來裝載 SignalR 中樞邏輯時，請使用無伺服器。傳統模式僅供回溯相容性使用，不建議使用。如需詳細資訊，請參閱 Azure SignalR Service 中的服務模式。

您不需要變更 SignalR 教學課程之 [網路 和標籤 ] 索引標籤上的設定。

選取 [基本] 索引 標籤底部的 [ 檢閱 + 建立] 按鈕。
在 [ 檢閱 + 建立] 索引標籤上，檢閱值，然後選取 [ 建立 ]。部署需要一些時間才能完成。
部署完成時，選取 [移至資源 ] 按鈕。
在 [SignalR 資源] 頁面上，從左側的功能表中， 選取 [設定 ]。
複製主鍵的連線字串 。在本教學課程稍後，您需要此連接字串來設定您的應用程式。

讓瀏覽器視窗保持開啟至Azure 入口網站，因為您將在下一節中再次使用它。

發佈及設定 Azure Functions 應用程式

在本節中，您將設定兩個 Azure 函式：

negotiate - HTTP 觸發程式函式。它會使用 SignalR連線ionInfo 輸入系結來產生並傳回有效的連線資訊。
broadcast - 事件方格觸發程式函式。它會透過事件方格接收 Azure Digital Twins 遙測資料，並使用您在上一個步驟中建立的 SignalR 實例輸出系結，將訊息廣播至所有連線的用戶端應用程式。

啟動 Visual Studio 或您選擇的另一個程式碼編輯器，然後在 digital-twins-samples-main\ADTSampleApp 資料夾中開啟程式碼方案 。然後執行下列步驟來建立函式：

在 SampleFunctionsApp 專案中，建立名為 SignalRFunctions.cs 的新 C# 類別。

以下列程式碼取代類別檔案的內容：

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Azure.WebJobs.Extensions.SignalRService;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using Azure.Messaging.EventGrid;

namespace SignalRFunction
{
    public static class SignalRFunctions
    {
        public static double temperature;

        [FunctionName("negotiate")]
        public static SignalRConnectionInfo GetSignalRInfo(
            [HttpTrigger(AuthorizationLevel.Anonymous, "post")] HttpRequest req,
            [SignalRConnectionInfo(HubName = "dttelemetry")] SignalRConnectionInfo connectionInfo)
        {
            return connectionInfo;
        }

        [FunctionName("broadcast")]
        public static Task SendMessage(
            [EventGridTrigger] EventGridEvent eventGridEvent,
            [SignalR(HubName = "dttelemetry")] IAsyncCollector<SignalRMessage> signalRMessages,
            ILogger log)
        {
            JObject eventGridData = (JObject)JsonConvert.DeserializeObject(eventGridEvent.Data.ToString());

            log.LogInformation($"Event grid message: {eventGridData}");

            var patch = (JObject)eventGridData["data"]["patch"][0];
            if (patch["path"].ToString().Contains("/Temperature"))
            {
                temperature = Math.Round(patch["value"].ToObject<double>(), 2);
            }

            var message = new Dictionary<object, object>
            {
                { "temperatureInFahrenheit", temperature},
            };

            return signalRMessages.AddAsync(
                new SignalRMessage
                {
                    Target = "newMessage",
                    Arguments = new[] { message }
                });
        }
    }
}

在 Visual Studio 的 [封裝管理員主控台 ] 視窗中，或您電腦上的任何命令視窗，流覽至 digital-twins-samples-main\AdtSampleApp\SampleFunctionsApp 資料夾 ，然後執行下列命令以將 NuGet 套件安裝 SignalRService 至專案：
```
dotnet add package Microsoft.Azure.WebJobs.Extensions.SignalRService --version 1.2.0
```
執行此命令應該解決類別中的任何相依性問題。
使用您慣用的方法，將函式發佈至 Azure。

如需如何使用 Visual Studio 發佈函 式的指示，請參閱使用 Visual Studio 開發 Azure Functions。如需如何使用 Visual Studio Code 發佈函 式的指示，請參閱使用 Visual Studio Code 在 Azure 中建立 C# 函式。如需如何使用 Azure CLI 發佈函式的指示，請參閱從命令列在 Azure 中建立 C# 函式。

設定函式

接下來，設定函式以與您的 Azure SignalR 實例通訊。您一開始會收集 SignalR 實例的連接字串，然後將它新增至函式應用程式的設定。

移至Azure 入口網站，然後在入口網站頂端的搜尋列中搜尋 SignalR 實例的名稱。選取實例以開啟它。
從實例功能表中選取 [金鑰 ]，以檢視 SignalR 服務實例的連接字串。
選取複製圖示以複製 主要連接字串 。
最後，使用下列 Azure CLI 命令，將 Azure SignalR 連接字串新增至函式的應用程式設定。此外，請從教學課程必要條件中，將預留位置取代為您的資源群組和 App Service/函式應用程式名稱。如果您已在電腦上安裝 Azure CLI，您可以在 Azure Cloud Shell 中或本機執行命令：
```
az functionapp config appsettings set --resource-group <your-resource-group> --name <your-function-app-name> --settings "AzureSignalRConnectionString=<your-Azure-SignalR-ConnectionString>"
```
此命令的輸出會列印為 Azure 函式設定的所有應用程式設定。查看 AzureSignalRConnectionString 清單底部以確認已新增。

將函式連線至事件方格

接下來，將廣播 Azure 函式訂閱 您在教學課程必要條件期間建立的事件方格主題。此動作可讓遙測資料從控溫器67 對應項流經事件方格主題和函式。在此，函式可以將資料廣播至所有用戶端。

若要廣播資料，您將從事件方格主題建立事件訂用帳戶，以 作為端點的廣播 Azure 函式。

在 Azure 入口網站中，藉由搜尋頂端搜尋列中的名稱來流覽至您的事件方格主題。選取 [+ 事件訂閱 ]。

Screenshot of how to create an event subscription in the Azure portal.

在 [ 建立事件訂閱 ] 頁面上，填入欄位，如下所示（預設不會提及填滿的欄位）：

事件訂用帳戶詳細 > 資料名稱 ：為您的事件訂用帳戶命名。
端點詳細資料 > 端點類型 ：從功能表選項中選取 [Azure 函式]。
端點詳細資料 > 端點：選取 [選取端點 ] 連結，這會開啟 [ 選取 Azure 函式 ] 視窗：
- 填入您的 訂用帳戶 、 資源群組 、 函式應用程式和 函式（廣播）。選取訂用帳戶之後，其中某些欄位可能會自動填入。
- 選取 [ 確認選取專案 ]。

Screenshot of the form for creating an event subscription in the Azure portal.

回到 [ 建立事件訂閱 ] 頁面上，選取 [ 建立 ]。

此時，您應該會在 [事件方格主題 ] 頁面中看到兩個事件訂閱。

設定和執行 Web 應用程式

在本節中，您會看到結果運作情形。首先，設定範例用戶端應用程式以連線到您已設定的 Azure SignalR 流程。接下來，您將啟動模擬裝置範例應用程式，以透過 Azure Digital Twins 實例傳送裝置遙測資料。之後，您將檢視範例 Web 應用程式，以查看模擬裝置資料即時更新範例 Web 應用程式。

設定範例用戶端應用程式

接下來，您將設定範例用戶端應用程式。首先，收集交涉 函式的 HTTP 端點 URL，然後使用它在電腦上設定應用程式程式碼。

移至Azure 入口網站的 [函式應用程式 ] 頁面，然後從清單中選取您的函式應用程式。在應用程式功能表中，選取 [函式 ]，然後選擇交涉函式。
選取 [取得函式 URL ]，然後透過 /api 複製值（不包含最後一個 /negotiate？ ）。您將在下一個步驟中使用此值。
使用 Visual Studio 或任何您選擇的程式碼編輯器，開啟您在下載範例應用程式一節中下載的 unzipped digitaltwins-signalr-webapp-sample-main 資料夾。
開啟 src/App.js 檔案，並將中的 HubConnectionBuilder 函式 URL 取代為您在上一個步驟中儲存之交涉函式的 HTTP 端點 URL：
```
    const hubConnection = new HubConnectionBuilder()
        .withUrl('<Function-URL>')
        .build();
```
在 Visual Studio 的 開發人員命令提示字元 或您電腦上的任何命令視窗中，流覽至 digitaltwins-signalr-webapp-sample-main\src 資料夾。執行下列命令以安裝相依節點套件：
```
npm install
```

接下來，在Azure 入口網站中設定函式應用程式中的許可權：

在Azure 入口網站的 [函式應用程式 ] 頁面中，選取您的函式應用程式實例。
向下捲動實例功能表中，然後選取 [CORS ]。在 [CORS] 頁面上，將它輸入空白方塊來新增 http://localhost:3000 為允許的來源。核取 [啟用存取控制-允許認證 ] 的 方塊，然後選取 [ 儲存 ]。

執行裝置模擬器

在端對端教學課程必要條件期間，您已將裝置模擬器設定為透過IoT 中樞和 Azure Digital Twins 實例傳送資料。

現在，啟動位於 digital-twins-samples-main\DeviceSimulator\DeviceSimulator.sln 的模擬器專案。如果您使用 Visual Studio，您可以開啟專案，然後在工具列中使用此按鈕執行它：

主控台視窗將會開啟並顯示模擬裝置溫度遙測訊息。這些訊息會透過您的 Azure Digital Twins 實例傳送，然後由 Azure 函式和 SignalR 挑選。

您不需要在此主控台中執行任何其他動作，但在完成下一個步驟時讓它保持執行狀態。

查看結果

若要查看作用中的結果，請啟動 SignalR 整合 Web 應用程式範例。您可以執行下列命令，從 digitaltwins-signalr-webapp-sample-main\src 位置的任何主控台視窗 執行此動作：

npm start

執行此命令將會開啟執行範例應用程式的瀏覽器視窗，以顯示視覺溫度計。應用程式執行之後，您應該會開始看到來自裝置模擬器的溫度遙測值，這些值會即時透過 Web 應用程式反映的 Azure Digital Twins 傳播。

Screenshot of the sample client web app, showing a visual temperature gauge. The temperature reflected is 67.52.

清除資源

如果您不再需要本文中建立的資源，請遵循下列步驟加以刪除。

使用 Azure Cloud Shell 或本機 Azure CLI，您可以使用 az group delete 命令來刪除資源群組中的所有 Azure 資源。移除資源群組也會移除：

Azure Digital Twins 實例（從端對端教學課程）
IoT 中樞和中樞裝置註冊（從端對端教學課程）
事件方格主題和相關聯的訂用帳戶
Azure Functions 應用程式，包括所有三個函式和相關聯的資源，例如儲存體
Azure SignalR 實例

重要

刪除資源群組是無法復原的。資源群組及其中包含的所有資源都會永久刪除。請確定您不會不小心刪除錯誤的資源群組或資源。

az group delete --name <your-resource-group>

最後，刪除您下載到本機電腦的專案範例資料夾（ digital-twins-samples-main.zip 、 digitaltwins-signalr-webapp-sample-main.zip ，以及其解壓縮的對應專案）。

下一步

在本文中，您會使用 SignalR 設定 Azure 函式，以將 Azure Digital Twins 遙測事件廣播至範例用戶端應用程式。

接下來，深入瞭解 Azure SignalR 服務：

什麼是 Azure SignalR 服務？

或深入瞭解 Azure Functions 的 Azure SignalR 服務驗證：

Azure SignalR 服務驗證