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

2024-09-03

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

このチュートリアルでは、次の作業を行う方法について説明します。

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

前提条件

Azure サブスクリプション。無料アカウントを作成します。
Bash コマンドシェル。ローカルシェルを使用するか、Azure Cloud Shell で Bash 環境を使用します。
ローカルコンピューターで実行している場合、Azure CLI をインストールします。

このチュートリアルのコマンドは、Bash シェルの代わりに Windows cmd.exe コマンドシェルを使用して実行できます。

ローカルコンピューターでプロジェクトを作成する場合は、以下のように使用している言語の依存関係をインストールする必要があります。

.NET Core

重要

この記事に示す生の接続文字列は、デモンストレーションのみを目的としています。

接続文字列には、アプリケーションが Azure Web PubSub サービスにアクセスするために必要な認可情報が含まれています。接続文字列内のアクセスキーは、サービスのルートパスワードに似ています。運用環境では、常にアクセスキーを保護してください。 Azure Key Vault を使ってキーの管理とローテーションを安全に行い、WebPubSubServiceClient を使って接続をセキュリティ保護します。

アクセスキーを他のユーザーに配布したり、ハードコーディングしたり、他のユーザーがアクセスできるプレーンテキストで保存したりしないでください。キーが侵害された可能性があると思われる場合は、キーをローテーションしてください。

ローカル開発のための Azure CLI のセットアップ

次の手順に従って、Azure CLI とプロジェクト環境をセットアップします。

コマンドシェルを開きます。
Azure CLI の最新バージョンにアップグレードします。
```
az upgrade
```
Web PubSub 用の Azure CLI 拡張機能をインストールします。
```
az extension add --name webpubsub
```
Azure CLI にサインインします。プロンプトに従って、Azure 資格情報を入力します。
```
az login
```

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

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

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 CLI の az webpubsub key コマンドを使用して、サービスの ConnectionString を取得します。プレースホルダー <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 Token (JWT) 認証を使用して、標準の WebSocket プロトコルにより Azure Web PubSub サービスに接続します。サービス SDK には、トークンを生成するヘルパーメソッドがあります。このチュートリアルでは、サブスクライバーによって ConnectionString からトークンが直接生成されます。実際のアプリケーションでは、認証や認可のワークフローは通常、サーバー側のアプリケーションによって処理されます。ワークフローについての理解を深めるには、チュートリアル「チャットアプリを構築する」を参照してください。

この記事に示す生の接続文字列は、デモンストレーションのみを目的としています。運用環境では、常にアクセスキーを保護してください。 Azure Key Vault を使って安全にキーの管理およびローテーションして、WebPubSubServiceClient を使って接続をセキュリティ保護します。

まず、このプロジェクト用に 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
```

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();
            }
        }
    }
}

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

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

接続が確立されると、クライアントは WebSocket 接続を介してメッセージを受信します。クライアントでは client.MessageReceived.Subscribe(msg => ...)); を使用して受信メッセージをリッスンします。

サブスクライバーを開始するには、<Web-PubSub-connection-string> を前にコピーした接続文字列に置き換えて、次のコマンドを実行します。
```
dotnet run <Web-PubSub-connection-string> "myHub1"
```

まず、subscriber という名前のプロジェクトディレクトリを作成し、必要な依存関係をインストールします。
```
mkdir subscriber
cd subscriber
npm init -y
npm install --save ws
npm install --save @azure/web-pubsub
```
WebSocket API を使用して Web PubSub サービスに接続します。次のコードを使用して、subscribe.js ファイルを作成します。
```
const WebSocket = require('ws');
const { WebPubSubServiceClient } = require('@azure/web-pubsub');

async function main() {
  const hub = "pubsub";
  let service = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, hub);
  let token = await service.getClientAccessToken();
  let ws = new WebSocket(token.url);
  ws.on('open', () => console.log('connected'));
  ws.on('message', data => console.log('Message received: %s', data));
}

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

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

接続が確立されると、クライアントは WebSocket 接続を介してメッセージを受信します。クライアントでは client.MessageReceived.Subscribe(msg => ...)); を使用して受信メッセージをリッスンします。
<Web-PubSub-connection-string> を前にコピーした接続文字列に置き換えて、次のコマンドを実行します。 Windows コマンドシェルを使用している場合は、export の代わりに set を使用できます。
```
export WebPubSubConnectionString=<Web-PubSub-connection-string>
node subscribe.js
```

まず、subscriber という名前のプロジェクトディレクトリを作成し、必要な依存関係をインストールします。

mkdir subscriber
cd subscriber
# Create venv
python -m venv env
# Activate venv
source ./env/bin/activate

pip install azure-messaging-webpubsubservice
pip install websockets

WebSocket API を使用して Web PubSub サービスに接続します。次のコードを使用して、subscribe.py ファイルを作成します。
```
import asyncio
import sys
import websockets

from azure.messaging.webpubsubservice import WebPubSubServiceClient


async def connect(url):
    async with websockets.connect(url) as ws:
        print('connected')
        while True:
            print('Received message: ' + await ws.recv())

if __name__ == '__main__':

    if len(sys.argv) != 3:
        print('Usage: python subscribe.py <connection-string> <hub-name>')
        exit(1)

    connection_string = sys.argv[1]
    hub_name = sys.argv[2]

    service = WebPubSubServiceClient.from_connection_string(connection_string, hub=hub_name)
    token = service.get_client_access_token()

    try:
        asyncio.get_event_loop().run_until_complete(connect(token['url']))
    except KeyboardInterrupt:
        pass
```
このコードでは、Web PubSub のハブに接続される WebSocket 接続を作成します。ハブは Web PubSub の論理ユニットです。ここで、クライアントのグループにメッセージを発行できます。主要な概念に関するページには、Web PubSub で使用される用語に関する詳細な説明があります。

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

接続が確立されると、クライアントは WebSocket 接続を介してメッセージを受信します。 await ws.recv() を使用して受信メッセージをリッスンします。
<Web-PubSub-connection-string> を前にコピーした接続文字列に置き換えて、次のコマンドを実行します。
```
python subscribe.py <Web-PubSub-connection-string> "myHub1"
```

まず、このチュートリアル用に pubsub という名前のプロジェクトディレクトリを作成します。
```
mkdir pubsub
cd pubsub
```

pubsub ディレクトリ内で、Maven を使用して webpubsub-quickstart-subscriber という名前の新しいコンソールアプリを作成し、webpubsub-quickstart-subscriber ディレクトリに移動します。

mvn archetype:generate --define interactiveMode=n --define groupId=com.webpubsub.quickstart --define artifactId=webpubsub-quickstart-subscriber --define archetypeArtifactId=maven-archetype-quickstart --define archetypeVersion=1.4
cd webpubsub-quickstart-subscriber

pom.xml の dependencies ノードに WebSocket と Azure Web PubSub SDK を追加します。
- azure-messaging-webpubsub: Java 用 Web PubSub サービス SDK
- Java-WebSocket: Java 用 WebSocket クライアント SDK
```
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-webpubsub</artifactId>
    <version>1.0.0</version>
</dependency>

<dependency>
    <groupId>org.java-websocket</groupId>
    <artifactId>Java-WebSocket</artifactId>
    <version>1.5.1</version>
</dependency>
```
Web PubSub では、サービスに接続し、WebSocket 接続を介してメッセージにサブスクライブできます。 WebSocket は全二重通信チャネルなので、サービスはリアルタイムでクライアントにメッセージをプッシュできます。 WebSocket をサポートする任意の API またはライブラリを使用できます。このサンプルでは、パッケージ Java-WebSocket を使用します。
/src/main/java/com/webpubsub/quickstart ディレクトリに移動します。

App.java ファイルの内容を編集し、次のコードに置き換えます。

package com.webpubsub.quickstart;

import com.azure.messaging.webpubsub.*;
import com.azure.messaging.webpubsub.models.*;

import org.java_websocket.client.WebSocketClient;
import org.java_websocket.handshake.ServerHandshake;

import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;

/**
* Connect to Azure Web PubSub service using WebSocket protocol
*/
public class App 
{
    public static void main( String[] args ) throws IOException, URISyntaxException
    {
        if (args.length != 2) {
            System.out.println("Expecting 2 arguments: <connection-string> <hub-name>");
            return;
        }

        WebPubSubServiceClient service = new WebPubSubServiceClientBuilder()
            .connectionString(args[0])
            .hub(args[1])
            .buildClient();

        WebPubSubClientAccessToken token = service.getClientAccessToken(new GetClientAccessTokenOptions());

        WebSocketClient webSocketClient = new WebSocketClient(new URI(token.getUrl())) {
            @Override
            public void onMessage(String message) {
                System.out.println(String.format("Message received: %s", message));
            }

            @Override
            public void onClose(int arg0, String arg1, boolean arg2) {
                // TODO Auto-generated method stub
            }

            @Override
            public void onError(Exception arg0) {
                // TODO Auto-generated method stub
            }

            @Override
            public void onOpen(ServerHandshake arg0) {
                // TODO Auto-generated method stub
            }

        };

        webSocketClient.connect();
        System.in.read();
    }
}

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

接続が確立されると、クライアントは WebSocket 接続を介してメッセージを受信します。 onMessage(String message) を使用して受信メッセージをリッスンします。

サブスクライバーアプリを起動するには、webpubsub-quickstart-subscriber ディレクトリに移動し、次のコマンドを実行します。 <Web-PubSub-connection-string> を先ほどコピーした接続文字列で置き換えます。
```
mvn compile & mvn package & mvn exec:java -Dexec.mainClass="com.webpubsub.quickstart.App" -Dexec.cleanupDaemonThreads=false -Dexec.args="<Web-PubSub-connection-string> 'myHub1'"
```

2. サービス SDK を使用してメッセージを発行する

Azure Web PubSub SDK を使用してパブリッシャーを作成し、接続されているクライアントにメッセージを発行します。このプロジェクトでは、別のコマンドシェルを開く必要があります。

まず、publisher という名前のプロジェクトディレクトリを作成し、必要な依存関係をインストールします。
```
mkdir publisher
cd publisher
dotnet new console
dotnet add package Azure.Messaging.WebPubSub
```

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() の呼び出しでは、単純にハブ内の接続されているすべてのクライアントにメッセージが送信されます。

次のコマンドを実行して、メッセージを送信します。 <Web-PubSub-connection-string> を先ほどコピーした接続文字列で置き換えます。
```
dotnet run <Web-PubSub-connection-string> "myHub1" "Hello World"
```
サブスクライバーのコマンドシェルがメッセージを受信することを確認します。
```
Message received: Hello World
```

まず、publisher という名前のプロジェクトディレクトリを作成し、必要な依存関係をインストールします。
```
mkdir publisher
cd publisher
npm init -y
npm install --save @azure/web-pubsub
```

Azure Web PubSub SDK を使用して、サービスにメッセージを発行します。次のコードを使用して、publish.js ファイルを作成します。

const { WebPubSubServiceClient } = require('@azure/web-pubsub');

const hub = "pubsub";
let service = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, hub);

// by default it uses `application/json`, specify contentType as `text/plain` if you want plain-text
service.sendToAll(process.argv[2], { contentType: "text/plain" });

service.sendToAll() の呼び出しでは、単純にハブ内の接続されているすべてのクライアントにメッセージが送信されます。

メッセージを送信するには、<Web-PubSub-connection-string> を前にコピーした接続文字列に置き換えて、次のコマンドを実行します。 Windows コマンドシェルを使用している場合は、export の代わりに set を使用できます。
```
export WebPubSubConnectionString=<Web-PubSub-connection-string>
node publish "Hello World"
```
サブスクライバーが次のメッセージを受信したことを確認できます。
```
Message received: Hello World
```

まず、publisher という名前のプロジェクトディレクトリを作成し、必要な依存関係をインストールします。

mkdir publisher
cd publisher
# Create venv
python -m venv env
# Active venv
source ./env/bin/activate

pip install azure-messaging-webpubsubservice

Azure Web PubSub SDK を使用して、サービスにメッセージを発行します。次のコードを使用して、publish.py ファイルを作成します。

import sys
from azure.messaging.webpubsubservice import WebPubSubServiceClient

if __name__ == '__main__':

    if len(sys.argv) != 4:
        print('Usage: python publish.py <connection-string> <hub-name> <message>')
        exit(1)

    connection_string = sys.argv[1]
    hub_name = sys.argv[2]
    message = sys.argv[3]

    service = WebPubSubServiceClient.from_connection_string(connection_string, hub=hub_name)
    res = service.send_to_all(message, content_type='text/plain')
    print(res)

send_to_all() では、ハブ内の全ての接続済みクライアントにメッセージが送信されます。

メッセージを送信するには、<Web-PubSub-connection-string> を前にコピーした接続文字列に置き換えて、次のコマンドを実行します。
```
python publish.py <Web-PubSub-connection-string> "myHub1" "Hello World"
```
前のコマンドシェルを調べて、サブスクライバーがメッセージを受信したことを確認します。
```
Received message: Hello World
```

pubsub ディレクトリに移動します。 Maven を使用してパブリッシャーコンソールアプリ webpubsub-quickstart-publisher を作成し、webpubsub-quickstart-publisher ディレクトリに移動します。

mvn archetype:generate --define interactiveMode=n --define groupId=com.webpubsub.quickstart --define artifactId=webpubsub-quickstart-publisher --define archetypeArtifactId=maven-archetype-quickstart --define archetypeVersion=1.4
cd webpubsub-quickstart-publisher

Azure Web PubSub SDK の依存関係を pom.xml の dependencies ノードに追加します。

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-webpubsub</artifactId>
    <version>1.0.0</version>
</dependency>

Azure Web PubSub SDK を使用して、サービスにメッセージを発行します。 /src/main/java/com/webpubsub/quickstart ディレクトリに移動し、App.java ファイルをエディターで開いて、その内容を次のコードに置き換えます。


package com.webpubsub.quickstart;

import com.azure.messaging.webpubsub.*;
import com.azure.messaging.webpubsub.models.*;

/**
* Publish messages using Azure Web PubSub service SDK
*
*/
public class App 
{
    public static void main( String[] args )
    {
        if (args.length != 3) {
            System.out.println("Expecting 3 arguments: <connection-string> <hub-name> <message>");
            return;
        }

        WebPubSubServiceClient service = new WebPubSubServiceClientBuilder()
            .connectionString(args[0])
            .hub(args[1])
            .buildClient();
        service.sendToAll(args[2], WebPubSubContentType.TEXT_PLAIN);
    }
}

sendToAll() の呼び出しでは、ハブ内の接続されているすべてのクライアントにメッセージが送信されます。

メッセージを送信するには、webpubsub-quickstart-publisher ディレクトリに移動し、次のコマンドを使用してプロジェクトを実行します。 <Web-PubSub-connection-string> を先ほどコピーした接続文字列で置き換えます。
```
mvn compile & mvn package & mvn exec:java -Dexec.mainClass="com.webpubsub.quickstart.App" -Dexec.cleanupDaemonThreads=false -Dexec.args="<Web-PubSub-connection-string> 'myHub1' 'Hello World'"
```
サブスクライバーが次のメッセージを受信したことを確認できます。
```
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 のサンプルをさらに確認する

次の方法で共有

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