适用于 Python 的 Azure Web PubSub 服务客户端库

项目
09/08/2023

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

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

The overflow diagram shows the overflow of using the service client library.

可以使用此库来执行以下操作：

将消息发送到中心和组。
将消息发送到特定用户和连接。
将用户和连接组织到组中。
关闭连接。
授予、撤销、检查现有连接的权限。

先决条件

使用此包需要 Python 3.6 或更高版本。
需要 Azure 试用版订阅和 Azure WebPubSub 服务实例才能使用此包。
一个现有的 Azure Web PubSub 服务实例。

重要

适用于 Python 2.7 的 Azure SDK Python 包支持在 2022 年 1 月 1 日结束。有关详细信息，请参阅 Azure SDK Python 包支持。

安装包

使用此命令安装包：

python -m pip install azure-messaging-webpubsubservice

创建 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>"))

或使用 Microsoft Entra ID：

pip install azure-identity。
在 Webpubsub 资源上启用 Microsoft Entra 授权。

更新代码以使用 DefaultAzureCredential。

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

示例

以 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。

后续步骤

有关更多示例，请参阅适用于 Python 示例的 Azure Web PubSub 服务客户端库。

贡献

本项目欢迎贡献和建议。大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。有关详细信息，请参阅参与者许可协议。

提交拉取请求时，CLA 机器人会自动确定你是否需要提供 CLA，并相应地修饰 PR（例如“标签”、“注释”）。按照机器人提供的说明操作。只需使用 CLA 对所有存储库执行一次这样的操作。

此项目采用了 Azure 开放源代码行为准则。有关详细信息，请参阅行为准则常见问题解答，如有任何疑问或意见，请联系开源管理团队。

通过