教學課程：使用 WebSocket API 和 Azure Web PubSub 服務 SDK 發佈和訂閱訊息

  • 發行項

Azure Web PubSub 服務可協助您輕鬆地建置即時 Web 傳訊應用程式。 在本教學課程中，您將瞭解如何使用 WebSocket API 訂閱服務，並使用 Web PubSub 服務 SDK 發佈訊息。

在本教學課程中，您會了解如何：

  • 建立 Web PubSub 服務實例
  • 產生建立 WebSocket 連線的完整 URL
  • 建立 Web PubSub 訂閱者用戶端，以使用標準 WebSocket 通訊協定接收訊息
  • 使用 Web PubSub 服務 SDK 建立 Web PubSub 發行者用戶端來發布訊息

必要條件

您可以使用 Windows cmd.exe 命令殼層，而不是 Bash 殼層來執行本教學課程中的命令。

如果在本機電腦上建立專案，您必須安裝所使用語言的相依性：

準備您的環境

適用於本機開發的 Azure CLI 設定

請遵循下列步驟來設定 Azure CLI 和您的項目環境。

  1. 開啟命令殼層。

  2. 升級至最新版的 Azure CLI。

    az upgrade

  3. 安裝適用於 Web PubSub 的 Azure CLI 擴充功能。

    az extension add --name webpubsub

  4. 登入 Azure CLI。 在提示之後，輸入您的 Azure 認證。

    az login

建立資源群組

資源群組是在其中部署與管理 Azure 資源的邏輯容器。 使用 az group create 命令，在位置中eastus建立名為 myResourceGroup 的資源群組。

az group create --name myResourceGroup --location EastUS

1.建立 Azure Web PubSub 實例

建立 Web PubSub 執行個體

使用 Azure CLI az webpubsub create 命令，在您所建立的資源群組中建立 Web PubSub。 下列命令會在 中的EastUS資源群組myResourceGroup下建立免費的 Web PubSub 資源：

每個 Web PubSub 資源都必須有唯一的名稱。 使用下列命令中的 Web PubSub 實例名稱取代 <your-unique-resource-name> 。

az webpubsub create --resource-group myResourceGroup --name <your-unique-resource-name> --location EastUS --sku Free_F1

此命令的輸出會顯示新建立之資源的屬性。 記下下列兩個屬性：

  • name：您在上述參數中 --name 提供的 Web PubSub 名稱。
  • hostName：在此範例中，主機名為 <your-unique-resource-name>.webpubsub.azure.com/。

此時，您的 Azure 帳戶是唯一有權在此新資源上執行任何作業的帳戶。

取得連接字串

重要

連接字串 包含應用程式存取 Azure Web PubSub 服務所需的授權資訊。 連接字串內的存取金鑰類似於您服務的根密碼。 在生產環境中，請務必小心保護您的存取密鑰。 使用 Azure 金鑰保存庫 安全地管理和輪替密鑰。 請避免將存取金鑰散發給其他使用者、進行硬式編碼，或將密鑰儲存到其他使用者可存取的純文本中的任何位置。 如果您認為金鑰可能遭到入侵，請輪替您的金鑰。

使用 Azure CLI az webpubsub key 命令來取得服務的 連線 ionString。 將 <your-unique-resource-name> 佔位元取代為您的 Azure Web PubSub 實例名稱。

az webpubsub key show --resource-group myResourceGroup --name <your-unique-resource-name> --query primaryConnectionString --output tsv

複製 連接字串 以供稍後使用。

建立訂閱者用戶端

用戶端會使用 JSON Web 令牌 （JWT） 驗證，透過標準 WebSocket 通訊協定連線到 Azure Web PubSub 服務。 服務 SDK 提供協助程式方法來產生令牌。 在本教學課程中，訂閱者會直接從 連線 ionString 產生令牌。 在實際的應用程式中，伺服器端應用程式通常會處理驗證/授權工作流程。 若要進一步瞭解工作流程，請參閱建置聊天應用程式教學課程。

  1. 首先，為此專案建立名為 subscriber 的項目目錄，並安裝必要的相依性：

    • 套件 Websocket.Client 是支援 WebSocket 連線的第三方套件。 您可以使用任何支援 WebSocket 的 API/連結庫。
    • SDK 套件 Azure.Messaging.WebPubSub 有助於產生 JWT 令牌。
    mkdir subscriber
cd subscriber
dotnet new console
dotnet add package Websocket.Client --version 4.3.30
dotnet add package Azure.Messaging.WebPubSub --version 1.0.0

  2. 將中的 Program.cs 程式代碼取代為將連線至服務的下列程式代碼：

    using System;
using System.Threading.Tasks;

using Azure.Messaging.WebPubSub;

using Websocket.Client;

namespace subscriber
{
    class Program
    {
        static async Task Main(string[] args)
        {
            if (args.Length != 2)
            {
                Console.WriteLine("Usage: subscriber <connectionString> <hub>");
                return;
            }
            var connectionString = args[0];
            var hub = args[1];

            // Either generate the URL or fetch it from server or fetch a temp one from the portal
            var serviceClient = new WebPubSubServiceClient(connectionString, hub);
            var url = serviceClient.GetClientAccessUri();

            using (var client = new WebsocketClient(url))
            {
                // Disable the auto disconnect and reconnect because the sample would like the client to stay online even no data comes in
                client.ReconnectTimeout = null;
                client.MessageReceived.Subscribe(msg => Console.WriteLine($"Message received: {msg}"));
                await client.Start();
                Console.WriteLine("Connected.");
                Console.Read();
            }
        }
    }
}

    此程式代碼會建立 WebSocket 連線，連線到 Web PubSub 中的中樞。 中樞是 Web PubSub 中的邏輯單元，您可以在其中將訊息發佈至用戶端群組。 重要概念 包含 Web PubSub 中所用詞彙的詳細說明。

    Web PubSub 服務會使用 JSON Web 令牌 （JWT） 驗證。 範例程式代碼會在 WebPubSubServiceClient.GetClientAccessUri() Web PubSub SDK 中使用 ，以產生包含具有有效存取令牌之完整 URL 的服務 URL。

    建立連線之後，您的用戶端會透過 WebSocket 連線接收訊息。 用戶端會使用 client.MessageReceived.Subscribe(msg => ...)); 來接聽傳入訊息。

  3. 若要啟動訂閱者，請執行下列命令，將 <Web-PubSub-connection-string> 取代為您稍早複製的 連接字串：

    dotnet run <Web-PubSub-connection-string> "myHub1"

2.使用服務 SDK 發佈訊息

使用 Azure Web PubSub SDK 建立發行者，將訊息發佈至連線的用戶端。 針對此專案，您必須開啟另一個命令殼層。

  1. 首先，建立名為 publisher 的項目目錄，並安裝必要的相依性：

    mkdir publisher
cd publisher
dotnet new console
dotnet add package Azure.Messaging.WebPubSub

  2. Program.cs更新 檔案以使用 WebPubSubServiceClient 類別，並將訊息傳送至用戶端。

    using System;
using System.Threading.Tasks;
using Azure.Messaging.WebPubSub;

namespace publisher
{
    class Program
    {
        static async Task Main(string[] args)
        {
            if (args.Length != 3) {
                Console.WriteLine("Usage: publisher <connectionString> <hub> <message>");
                return;
            }
            var connectionString = args[0];
            var hub = args[1];
            var message = args[2];

            // Either generate the token or fetch it from server or fetch a temp one from the portal
            var serviceClient = new WebPubSubServiceClient(connectionString, hub);
            await serviceClient.SendToAllAsync(message);
        }
    }
}

    呼叫 SendToAllAsync() 只會將訊息傳送至中樞中的所有已連線用戶端。

  3. 執行下列命令來傳送訊息。 將取代<Web-PubSub-connection-string>為您稍早複製的 連接字串。

    dotnet run <Web-PubSub-connection-string> "myHub1" "Hello World"

  4. 檢查訂閱者的命令殼層，以查看它是否收到訊息：

    Message received: Hello World

清理

您可以刪除包含這些資源的資源群組，以刪除在本快速入門中建立的資源。

az group delete --name myResourceGroup --yes

如果您不打算繼續使用 Azure Cloud Shell，您可以刪除包含相關聯記憶體帳戶的資源群組，以避免累積成本。 資源群組的名稱為 cloud-shell-storage-<your-region>。 執行下列命令，將 取代 <CloudShellResourceGroup> 為 Cloud Shell 組名。

az group delete --name <CloudShellResourceGroup> --yes

警告

刪除資源群組將會刪除所有資源，包括在本教學課程範圍之外建立的資源。

下一步

本教學課程提供如何連線至 Web PubSub 服務，並將訊息發佈至連線用戶端的基本概念。

請參閱其他教學課程，進一步探討如何使用服務。

教學課程：使用 Azure Web PubSub 建立聊天室

探索更多 Azure Web PubSub 範例