Python 用 Azure Web PubSub クライアントライブラリ

2025-04-03

注

ここで使われている用語の詳細は、主な概念の記事を参照してください。

クライアント側 SDK は、開発者のワークフローを高速化することを目的としています。具体的には、次のとおりです。

クライアント接続の管理を簡素化
クライアント間でのメッセージの送信が簡素化されます
クライアント接続の意図しないドロップ後に自動的に再試行する
接続の切断からの復旧後に、数と順序を確実にしてメッセージを配信します

図に示すように、クライアントは Web PubSub リソースとの WebSocket 接続を確立します。

Web PubSub リソースとの WebSocket 接続を確立しているクライアントを示すスクリーンショット

作業の開始

前提条件

python=3.8.10
Azure サブスクリプション
Web PubSub リソース

1. `azure-messaging-webpubsubclient` パッケージをインストールする

pip install azure-messaging-webpubsubclient

2. Web PubSub リソースに接続する

クライアントは、 Client Access URL を使用してサービスに接続して認証します。これは、 wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>のパターンに従います。クライアントには、 Client Access URLを取得するいくつかの方法があります。このクイックスタートでは、表示されている Azure portal からコピーして貼り付けることができます。

Azure portal でクライアントアクセス URL を取得する方法を示すスクリーンショット

図に示すように、クライアントには、group1 という名前の特定のグループにメッセージを送信して参加するためのアクセス許可があります。

from azure.messaging.webpubsubclient import WebPubSubClient

client = WebPubSubClient("<client-access-url>")
with client:
    # The client can join/leave groups, send/receive messages to and from those groups all in real-time
    ...

3. グループに参加する

クライアントは、参加しているグループからのみメッセージを受信でき、メッセージを受信するときにロジックを指定するコールバックを追加する必要があります。

from azure.messaging.webpubsubclient.models import CallbackType

# ...continues the code snippet from above

# Registers a listener for the event 'group-message' early before joining a group to not miss messages
group_name = "group1";
client.subscribe(CallbackType.GROUP_MESSAGE, lambda e: print(f"Received message: {e.data}"));

# A client needs to join the group it wishes to receive messages from
client.join_group(groupName);

4. グループにメッセージを送信する

# ...continues the code snippet from above

# Send a message to a joined group
client.send_to_group(group_name, "hello world", "text");

# In the Console tab of your developer tools found in your browser, you should see the message printed there.

例示

`connected`、`disconnected`、および`stopped`イベントのコールバックを追加する

クライアントが Web PubSub リソースに正常に接続されると、connected イベントがトリガーされます。

from azure.messaging.webpubsubclient.models import CallbackType

client.subscribe(CallbackType.CONNECTED, lambda e: print(f"Connection {e.connection_id} is connected"))

クライアントが切断され、接続の回復に失敗すると、disconnected イベントがトリガーされます。

from azure.messaging.webpubsubclient.models import CallbackType

client.subscribe(CallbackType.DISCONNECTED, lambda e: print(f"Connection disconnected: {e.message}"))

stopped イベントは、クライアントが切断、およびクライアントが再接続の試行を停止するときにトリガーされます。これは通常、client.stop() が呼び出された後、または auto_reconnect が無効になっているか、再接続を試行するための指定された制限に達した後に発生します。クライアントを再起動する場合は、停止したイベントで client.start() を呼び出すことができます。
```
from azure.messaging.webpubsubclient.models import CallbackType

client.subscribe(CallbackType.STOPPED, lambda : print("Client has stopped"))
```

クライアントがアプリケーションサーバーまたは参加済みグループからのメッセージを使用する

クライアントは、コールバックを追加して、アプリケーションサーバーまたはグループからのメッセージを使用できます。 group-messageイベントの場合、クライアントは参加したグループメッセージのみを受信できることに注意してください。

from azure.messaging.webpubsubclient.models import CallbackType

# Registers a listener for the "server-message". The callback is invoked when your application server sends message to the connectionID, to or broadcast to all connections.
client.subscribe(CallbackType.CONNECTED, lambda e: print(f"Received message {e.data}"))

# Registers a listener for the "group-message". The callback is invoked when the client receives a message from the groups it has joined.
client.subscribe(CallbackType.GROUP_MESSAGE, lambda e: print(f"Received message from {e.group}: {e.data}"))

再結合エラーの処理

クライアントが切断され、復旧に失敗すると、すべてのグループコンテキストが Web PubSub リソースでクリーンアップされます。つまり、クライアントが再接続するときに、グループに再び参加する必要があります。既定では、クライアントで auto_rejoin_groups オプションが有効になっています。

ただし、auto_rejoin_groupsの制限事項に注意する必要があります。

クライアントは、 サーバー側のコード ではなく 、クライアントコードによって最初に結合されたグループのみを再結合できます。
"グループの再参加" 操作は、さまざまな理由により失敗する可能性があります。たとえば、クライアントにグループに参加するアクセス許可がありません。このような場合は、このエラーを処理するためのコールバックを追加する必要があります。

from azure.messaging.webpubsubclient.models import CallbackType

# By default auto_rejoin_groups=True. You can disable it by setting to False.
client = WebPubSubClient("<client-access-url>", auto_rejoin_groups=True);

# Registers a listener to handle "rejoin-group-failed" event
client.subscribe(CallbackType.REJOIN_GROUP_FAILED, lambda e: print(f"Rejoin group {e.group} failed: {e.error}"))

操作と再試行

既定では、client.join_group()、client.leave_group()、client.send_to_group()、client.send_event() などの操作には 3 回の再試行があります。キーワード引数を使用して構成できます。すべての再試行が失敗した場合、エラーがスローされます。 Web PubSub サービスが操作を重複除去できるように、前の再試行と同じ ack_id を渡すことで再試行を続けることができます。

try:
    client.join_group(group_name)
except SendMessageError as e:
    client.join_group(group_name, ack_id=e.ack_id)

トラブルシューティング

ログを有効にする

このライブラリを使用する場合は、次の環境変数を設定してデバッグログを取得できます。

export AZURE_LOG_LEVEL=verbose

ログを有効にする方法の詳細な手順については、@azure/logger パッケージのドキュメントを参照してください。

ライブトレース

Azure portal からライブトレースツールを使用して、Web PubSub リソースを介してライブメッセージトラフィックを検査します。

次の方法で共有

Python 用 Azure Web PubSub クライアント ライブラリ