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

注

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

クライアント側 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イベントのコールバックを追加する

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

    from azure.messaging.webpubsubclient.models import CallbackType

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

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

    from azure.messaging.webpubsubclient.models import CallbackType

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

  3. 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 リソースを介してライブ メッセージ トラフィックを検査します。

  • Last updated on