共用方式為

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

  • 發行項

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

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

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

必要條件

  • Azure 訂用帳戶，建立免費帳戶。
  • Bash 命令殼層。 在 Azure Cloud Shell 中使用本機殼層或 Bash 環境。
  • 如果執行於本機電腦上，請安裝 Azure CLI。

您可以使用 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 執行個體

若要在您已建立的資源群組中建立 Web PubSub 執行個體，請使用 Azure CLI az webpubsub create 命令。 下列命令會在 EastUS 中資源群組 myResourceGroup 下建立免費 Web PubSub 資源：

每個 Web PubSub 資源都必須有唯一的名稱。 在下列命令中，將 <your-unique-resource-name> 取代為您的 Web PubSub 執行個體名稱。

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 Key Vault，以安全的方式管理及輪替金鑰。 避免將存取金鑰散發給其他使用者、寫入程式碼，或將其以純文字儲存在他人可以存取的位置。 如果您認為金鑰可能已遭盜用，請輪替金鑰。

使用 Azure CLI az webpubsub key 命令取得服務的 ConnectionString。 使用您的 Azure Web PubSub 執行個體名稱取代 <your-unique-resource-name> 預留位置。

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

複製連接字串以備後續使用。

建立訂閱者用戶端

用戶端會使用 JSON Web 權杖 (JWT) 驗證，透過標準 WebSocket 通訊協定連線至 Azure Web PubSub 服務。 服務 SDK 提供可產生權杖的 Helper 方法。 在此教學課程中，訂閱者會直接從 ConnectionString 產生權杖。 在實際的應用程式中，伺服器端應用程式通常會處理驗證/授權工作流程。 若要進一步了解此工作流程，請參閱建置聊天應用程式教學課程。

  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) 驗證。 範例程式碼會使用 Web PubSub SDK 中的 WebPubSubServiceClient.GetClientAccessUri() 產生服務的 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 範例