チュートリアル: WebSocket API と Azure Web PubSub サービス SDK を使用してメッセージの発行とサブスクライブを行う

Azure Web PubSub サービスは、WebSocket とパブリッシュ-サブスクライブ パターンを使用して、リアルタイム メッセージング Web アプリケーションを作成するのに役立ちます。 このチュートリアルでは、WebSocket API を使用してサービスにサブスクライブし、サービス SDK を使用してメッセージを発行する方法について説明します。

このチュートリアルでは、以下の内容を学習します。

  • Azure Web PubSub サービス インスタンスを作成する
  • 完全な URL を生成して WebSocket 接続を確立する
  • 標準の WebSocket プロトコルを使用してメッセージをサブスクライブする
  • サービス SDK を使用してメッセージを発行する

Azure サブスクリプションをお持ちでない場合は、開始する前に Azure 無料アカウントを作成してください。

前提条件

  • Azure Cloud Shell で Bash 環境を使用します。 詳細については、Azure Cloud Shell の Bash のクイックスタートに関するページを参照してください。 新しいウィンドウで Cloud Shell を起動する

  • CLI リファレンス コマンドをローカルで実行する場合、Azure CLI をインストールします。 Windows または macOS で実行している場合は、Docker コンテナーで Azure CLI を実行することを検討してください。 詳細については、「Docker コンテナーで Azure CLI を実行する方法」を参照してください。

    • ローカル インストールを使用する場合は、az login コマンドを使用して Azure CLI にサインインします。 認証プロセスを完了するには、ターミナルに表示される手順に従います。 その他のサインイン オプションについては、Azure CLI でのサインインに関するページを参照してください。

    • 初回使用時にインストールを求められたら、Azure CLI 拡張機能をインストールします。 拡張機能の詳細については、Azure CLI で拡張機能を使用する方法に関するページを参照してください。

    • az version を実行し、インストールされているバージョンおよび依存ライブラリを検索します。 最新バージョンにアップグレードするには、az upgrade を実行します。

  • このセットアップには、Azure CLI のバージョン 2.22.0 以降が必要です。 Azure Cloud Shell を使用している場合は、最新バージョンが既にインストールされています。

Azure Web PubSub インスタンスを作成する

リソース グループを作成する

リソース グループとは、Azure リソースのデプロイと管理に使用する論理コンテナーです。 az group create コマンドを使用して、myResourceGroup という名前のリソース グループを eastus に作成します。

az group create --name "myResourceGroup" -l "EastUS"

Web PubSub インスタンスを作成する

az extension add を実行して、webpubsub 拡張機能をインストールするか、最新バージョンにアップグレードします。

az extension add --upgrade --name webpubsub

Azure CLI の az webpubsub create コマンドを使用して、作成したリソース グループに Web PubSub を作成します。 次のコマンドは、EastUS のリソース グループ myResourceGroup の下に "無料の" Web PubSub リソースを作成します。

重要

Web PubSub リソースには、それぞれ一意の名前を付ける必要があります。 次の例では、<your-unique-resource-name> をお使いの Web PubSub の名前に置き換えてください。

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

このコマンドの出力では、新しく作成したリソースのプロパティが表示されます。 次の 2 つのプロパティをメモしておきます。

  • Resource Name: 上記の --name パラメーターに指定した名前です。
  • hostName: この例では、ホスト名は <your-unique-resource-name>.webpubsub.azure.com/ です。

この時点で、お使いの Azure アカウントのみが、この新しいリソースで任意の操作を実行することを許可されています。

将来使用するために ConnectionString を取得する

重要

接続文字列には、アプリケーションが Azure Web PubSub サービスにアクセスするために必要な認可情報が含まれています。 接続文字列内のアクセス キーは、サービスのルート パスワードに似ています。 アクセス キーは常に慎重に保護してください。 キーを安全に管理およびローテーションするには、Azure Key Vault を使用します。 アクセス キーを他のユーザーに配布したり、ハードコーディングしたり、他のユーザーがアクセスできるプレーンテキストで保存したりしないでください。 キーが侵害された可能性があると思われる場合は、キーをローテーションしてください。

Azure CLI の az webpubsub key コマンドを使用して、サービスの ConnectionString を取得します。

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

フェッチされた ConnectionString をコピーします。これは、このチュートリアルの後半で <connection_string> の値として使用します。

プロジェクトのセットアップ

前提条件

サブスクライバーをセットアップする

クライアントは、JSON Web Token (JWT) 認証を使用して、標準の WebSocket プロトコルにより Azure Web PubSub サービスに接続します。 サービス SDK には、トークンを生成するヘルパー メソッドがあります。 このチュートリアルでは、サブスクライバーによって 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();
                }
            }
        }
    }
    
    

    上記のコードでは、Azure Web PubSub のハブに接続するための WebSocket 接続を作成します。 ハブは Azure Web PubSub の論理ユニットです。ここで、クライアントのグループにメッセージを発行できます。 主要な概念に関するページには、Azure Web PubSub で使用される用語に関する詳細な説明があります。

    Azure Web PubSub サービスでは JSON Web Token (JWT) 認証が使用されます。そのため、コード サンプルでは、Web PubSub SDK で WebPubSubServiceClient.GetClientAccessUri() を使用して、有効なアクセス トークンを持つ完全な URL を含むサービスへの URL を生成します。

    接続が確立されると、WebSocket 接続を介してメッセージを受信します。 そのため、受信メッセージをリッスンするために client.MessageReceived.Subscribe(msg => ...)); を使用します。

  3. 前の手順でフェッチされた ConnectionString<connection_string> を置き換えて、下のコマンドを実行します。

    dotnet run "<connection_string>" "myHub1"
    

サービス 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. 前の手順でフェッチされた ConnectionString<connection_string> を置き換えて、下のコマンドを実行します。

    dotnet run "<connection_string>" "myHub1" "Hello World"
    
  4. 前のサブスクライバーが下のメッセージを受信したのを確認できます。

    Message received: Hello World
    

次のステップ

このチュートリアルでは、Web PubSub サービスに接続する方法と、接続されているクライアントにメッセージを発行する方法の基本的な考え方について説明しています。

サービスの使用方法の詳細については、他のチュートリアルを参照してください。