Azure Web PubSub Python客户端库

Azure Web PubSub 是一种云服务，它帮助开发者轻松地在Web应用程序中构建大规模的发布/订阅模式的实时功能。

任何需要服务器和客户端之间或客户端之间按照发布/订阅模式进行实时消息传递的场景都可以从使用Web PubSub中受益。开发者不再需要通过发送重复的HTTP请求在间隔中轮询服务器，这既浪费资源又难以扩展。

如下图所示，您的客户端与您的Web PubSub资源建立WebSocket连接。此客户端库

• 简化了客户端连接的管理
• 简化了客户端之间的消息发送
• 在客户端连接意外中断后自动重试
• 在连接中断恢复后，可靠地按数量和顺序交付消息

此处使用的术语的详细信息请参阅关键概念部分。

此库托管在pypi上。

入门

当前支持的环境

• Python 3.7+

先决条件

• 一个Azure订阅。
• 一个Web PubSub资源。

1. 安装 azure-messaging-webpubsubclient 包

pip install azure-messaging-webpubsubclient

2. 连接到您的 Web PubSub 资源

客户端使用客户端访问 URL 连接并验证服务，其模式为 wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>。客户端有几种方法可以获得客户端访问 URL。在此快速入门中，您可以复制并粘贴以下 Azure 门户中的一个。

如上图所示，客户端有权限向特定组“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. 加入组

请注意，客户端只能接收它已加入的组的消息，您需要添加回调以指定接收消息时的逻辑。

# ...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", WebPubSubDataType.TEXT);

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

示例

为连接、断开连接和停止事件添加回调

1. 当客户端成功连接到您的 Web PubSub 资源时，将触发 connected 事件。

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

2. 当客户端断开连接且无法恢复连接时，将触发 disconnected 事件。

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

3. stopped 事件将在客户端断开连接 且 客户端停止尝试重新连接时触发。这通常发生在调用 client.close() 后，或 auto_reconnect 被禁用，或尝试重新连接的指定限制已达到。如果想要重新启动客户端，可以在停止事件中调用 client.open()。

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

客户端从应用程序服务器或加入的组接收消息

客户端可以添加回调以从您的应用程序服务器或组接收消息。请注意，对于 group-message 事件，客户端 只能 接收它已加入的组消息。

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

# Registers a listener for the "group-message". The callback will be 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 的限制。

• 客户端只能重新加入它最初通过客户端代码而不是服务器端代码加入的组。
• “重新加入组”操作可能因各种原因而失败，例如，客户端没有权限加入组。在这种情况下，您需要添加回调来处理此失败。

# 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() 这样的操作有三个重试次数。您可以通过关键字参数进行配置。如果所有重试都失败，将抛出错误。您可以通过传递与先前重试相同的 ack_id 来继续重试，以便 Web PubSub 服务可以去除重复的操作。

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

指定子协议

您可以更改客户端使用的子协议。默认情况下，客户端使用 json.reliable.webpubsub.azure.v1。您可以选择使用 json.reliable.webpubsub.azure.v1 或 json.webpubsub.azure.v1。

from azure.messaging.webpubsubclient.models import WebPubSubProtocolType
# Change to use json.webpubsub.azure.v1
const client = new WebPubSubClient("<client-access-url>", protocol_type=WebPubSubProtocolType.JSON);

from azure.messaging.webpubsubclient.models import WebPubSubProtocolType
# Change to use json.reliable.webpubsub.azure.v1
const client = new WebPubSubClient("<client-access-url>", protocol_type=WebPubSubProtocolType.JSON_RELIABLE);

关键概念

连接

连接，也称为客户端或客户端连接，表示连接到 Web PubSub 的单个 WebSocket 连接。当成功连接时，Web PubSub 会为该连接分配一个唯一的连接 ID。每个 WebPubSubClient 都会创建其自己的专用连接。

恢复

如果一个使用可靠协议的客户端断开连接，则新的 WebSocket 将尝试使用丢失连接的连接 ID 建立连接。如果新的 WebSocket 连接成功建立，则连接已恢复。在整个客户端断开连接期间，服务保留客户端的上下文以及客户端已订阅的所有消息，当客户端恢复时，服务将发送这些消息到客户端。如果服务返回 WebSocket 错误代码 1008 或恢复尝试持续超过 30 秒，则恢复失败。

重新连接

重新连接发生在客户端连接断开且无法恢复的情况下。重新连接将启动一个新的连接，并且新的连接具有一个新的连接ID。与恢复不同，服务将重新连接的客户端视为新的客户端连接。客户端连接需要重新加入群组。默认情况下，客户端库会在重新连接后重新加入群组。

中心

中心是一个用于一组客户端连接的逻辑概念。通常，您会为单一目的使用一个中心，例如聊天中心或通知中心。当创建客户端连接时，它会连接到一个中心，并在其生命周期内属于该中心。不同的应用程序可以通过使用不同的中心名称来共享一个Web PubSub。

组

组是连接到中心的子集。您可以在任何需要时将客户端连接添加到组中，或从组中删除客户端连接。例如，当客户端加入聊天室或离开聊天室时，这个聊天室可以被视为一个组。客户端可以加入多个组，一个组也可以包含多个客户端。

用户

Web PubSub的连接可以属于一个用户。一个用户可能有多个连接，例如当单个用户通过多个设备或多个浏览器标签连接时。

客户端生命周期

Web PubSub的每个客户端都可以安全地缓存并在应用程序的生命周期内用作单例。已注册的事件回调与客户端具有相同的生命周期。这意味着您可以在任何时间添加或删除回调，并且在重新连接或客户端停止后，注册状态不会改变。

故障排除

此库使用标准的日志记录库进行日志记录。如果您需要详细的DEBUG级别日志，包括请求数据包，可以在客户端或每个操作中设置logging_enable=True。

下一步

您还可以在这里找到更多示例。

其他资源

• 了解有关客户端权限的更多信息，请参阅权限。

• 产品文档

贡献

如果您想为此库做出贡献，请阅读贡献指南以了解有关如何构建和测试代码的更多信息。