Azure Web PubSub 服务 Python 客户端库

Azure Web PubSub 服务 是一个由 Azure 管理的服务，它帮助开发者轻松构建具有实时功能和发布/订阅模式的 Web 应用程序。任何需要服务器和客户端之间或客户端之间进行实时发布/订阅消息传递的场景都可以使用 Azure Web PubSub 服务。传统实时功能，通常需要从服务器轮询或提交 HTTP 请求，也可以使用 Azure Web PubSub 服务。

您可以在应用程序服务器端使用此库来管理 WebSocket 客户端连接，如下面的图所示

使用此库

• 向中心群组和组发送消息。
• 向特定用户和连接发送消息。
• 将用户和连接组织成组。
• 关闭连接
• 为现有连接授权、撤销和检查权限

源代码 | 包（Pypi） | 包（Conda） | API参考文档 | 产品文档

免责声明

Azure SDK Python包对Python 2.7的支持已于2022年1月1日结束。有关更多信息及疑问，请参阅https://github.com/Azure/azure-sdk-for-python/issues/20691

入门指南

先决条件

• 使用此包需要Python 3.6或更高版本。
• 您需要一个Azure订阅，以及一个Azure WebPubSub服务实例。
• 现有的Azure Web PubSub服务实例。

1. 安装包

python -m pip install azure-messaging-webpubsubservice

2. 创建并验证WebPubSubServiceClient

您可以使用连接字符串来验证WebPubSubServiceClient

>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient

>>> service = WebPubSubServiceClient.from_connection_string(connection_string='<connection_string>', hub='hub')

或使用服务端点和访问密钥

>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient
>>> from azure.core.credentials import AzureKeyCredential

>>> service = WebPubSubServiceClient(endpoint='<endpoint>', hub='hub', credential=AzureKeyCredential("<access_key>"))

或使用Azure Active Directory

1. pip install azure-identity

2. 按照文档在你的Webpubsub资源上启用AAD身份验证

3. 更新代码以使用DefaultAzureCredential

   >>> from azure.messaging.webpubsubservice import WebPubSubServiceClient
   >>> from azure.identity import DefaultAzureCredential
   >>> service = WebPubSubServiceClient(endpoint='<endpoint>', hub='hub', credential=DefaultAzureCredential())
   

关键概念

连接

连接，也称为客户端或客户端连接，代表连接到Web PubSub服务的单个WebSocket连接。当连接成功时，Web PubSub服务将分配一个唯一的连接ID给此连接。

中心

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

组

组是中心连接的子集。您可以在任何时候将客户端连接添加到组，或从组中删除客户端连接。例如，当客户端加入聊天室或退出聊天室时，这个聊天室可以被认为是组。客户端可以加入多个组，组可以包含多个客户端。

用户

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

消息

当客户端连接时，它可以通过WebSocket连接向上游应用程序发送消息或接收来自上游应用程序的消息。

示例

以JSON格式广播消息

>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient

>>> service = WebPubSubServiceClient.from_connection_string('<connection_string>', hub='hub1')
>>> service.send_to_all(message = {
        'from': 'user1',
        'data': 'Hello world'
    })

WebSocket客户端将接收到JSON序列化的文本：{"from": "user1", "data": "Hello world"}。

以纯文本格式广播消息

>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient
>>> service = WebPubSubServiceClient.from_connection_string('<connection_string>', hub='hub1')
>>> service.send_to_all(message = 'Hello world', content_type='text/plain')

WebSocket客户端将接收到文本：Hello world。

以二进制格式广播消息

>>> import io
>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient
>>> service = WebPubSubServiceClient.from_connection_string('<connection_string>', hub='hub')
>>> service.send_to_all(message=io.StringIO('Hello World'), content_type='application/octet-stream')

WebSocket客户端将接收到二进制文本：b'Hello world'。

故障排除

日志记录

此SDK使用Python标准日志库。您可以将日志配置为将调试信息打印到stdout或任何您想要的地方。

import sys
import logging
from azure.identity import DefaultAzureCredential
>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

endpoint = "<endpoint>"
credential = DefaultAzureCredential()

# This WebPubSubServiceClient will log detailed information about its HTTP sessions, at DEBUG level
service = WebPubSubServiceClient(endpoint=endpoint, hub='hub', credential=credential, logging_enable=True)

同样，logging_enable可以启用单个调用的详细日志，即使它没有为WebPubSubServiceClient启用

result = service.send_to_all(..., logging_enable=True)

使用此日志配置，将打印stdout中的HTTP请求和响应详细信息。

下一步

请查看更多示例。

贡献

本项目欢迎贡献和建议。大多数贡献需要您同意贡献者许可协议（CLA），声明您有权并且确实授予我们使用您贡献的权利。有关详细信息，请访问 https://cla.microsoft.com。

当您提交拉取请求时，CLA机器人会自动确定您是否需要提供CLA，并适当装饰PR（例如，标签、注释）。只需遵循机器人提供的说明即可。您在整个使用我们的CLA的仓库中只需这样做一次。

本项目已采用微软开源行为准则。有关更多信息，请参阅行为准则FAQ或通过opencode@microsoft.com联系，有任何额外问题或评论。