你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
适用于 Python 的 Azure Web PubSub 服务客户端库 - 版本 1.0.1
Azure Web PubSub 服务是一项 Azure 托管服务,可帮助开发者轻松构建具有实时功能和发布-订阅模式的 Web 应用程序。 任何需要在服务器和客户端或客户端之间进行实时发布-订阅消息传送的方案都可以使用 Azure Web PubSub 服务。 通常需要从服务器轮询或提交 HTTP 请求的传统实时功能也可以使用 Azure Web PubSub 服务。
可以在应用服务器端使用此库来管理 WebSocket 客户端连接,如下图所示:
可以使用此库来执行以下操作:
- 将消息发送到中心和组。
- 将消息发送到特定用户和连接。
- 将用户和连接组织到组中。
- 关闭连接
- 授予、撤销、检查现有连接的权限
源代码 | 包 (Pypi) | API 参考文档 | 产品文档
免责声明
对 Python 2.7 的 Azure SDK Python 包支持已于 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>"))
pip install
azure-identity
按照文档中所述在 Webpubsub 资源上启用 AAD 身份验证
更新代码以使用 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 的连接可以属于一个用户。 用户可能具有多个连接,例如当单个用户跨多个设备或多个浏览器选项卡进行连接时。
Message
客户端连接后,可以通过 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)
同样,即使没有为 WebPubSubServiceClient 启用详细日志记录,logging_enable
也可以为单个调用启用详细日志记录:
result = service.send_to_all(..., logging_enable=True)
Http 请求和响应详细信息通过此日志记录配置打印到 stdout。
后续步骤
可以在此处找到更多示例。
贡献
本项目欢迎贡献和建议。 大多数贡献要求你同意贡献者许可协议 (CLA),并声明你有权(并且确实有权)授予我们使用你的贡献的权利。 有关详细信息,请访问 https://cla.microsoft.com 。
提交拉取请求时,CLA 机器人将自动确定你是否需要提供 CLA,并相应地修饰 PR(例如标签、注释)。 直接按机器人提供的说明操作。 只需使用 CLA 对所有存储库执行一次这样的操作。
本项目采用 Microsoft 开源行为准则。 有关详细信息,请参阅“行为准则常见问题解答”,如有其他任何问题或意见,请联系 opencode@microsoft.com。