以下为本文档的中文说明
azure-messaging-webpubsubservice-py 是 Azure Web PubSub 服务的 Python SDK 技能，专注于实时消息传递和 WebSocket 连接管理。Azure Web PubSub 是微软 Azure 提供的一项托管服务，支持大规模 WebSocket 连接和发布/订阅消息模式。该技能指导开发者如何正确使用这个 SDK 构建实时应用。核心内容包括：服务端 SDK（azure-messaging-webpubsubservice）用于服务端操作，客户端 SDK（azure-messaging-webpubsubclient）用于 Python WebSocket 客户端。环境配置方面需要设置连接字符串或 Entra ID 认证。服务端功能涵盖：客户端认证与授权——通过 WebPubSubServiceClient 生成客户端访问令牌或获取客户端证书；消息收发——向指定用户、组或所有客户端广播消息；连接管理——管理 WebSocket 连接的生命周期。使用场景包括：实时聊天应用、协作编辑工具、实时数据仪表板、在线游戏、直播互动、物联网设备实时通信等需要低延迟双向通信的应用。核心原则是“托管服务简化实时通信”，通过 Azure 的托管基础设施，开发者无需自己搭建和维护 WebSocket 服务器即可实现大规模实时消息推送。
Azure Web PubSub Service SDK for Python
Real-time messaging with WebSocket connections at scale.
Installation
# Service SDK (server-side)pipinstallazure-messaging-webpubsubservice# Client SDK (for Python WebSocket clients)pipinstallazure-messaging-webpubsubclientEnvironment Variables
AZURE_WEBPUBSUB_CONNECTION_STRING=Endpoint=https://<name>.webpubsub.azure.com;AccessKey=...AZURE_WEBPUBSUB_HUB=my-hubService Client (Server-Side)
Authentication
fromazure.messaging.webpubsubserviceimportWebPubSubServiceClient# Connection stringclient=WebPubSubServiceClient.from_connection_string(connection_string=os.environ["AZURE_WEBPUBSUB_CONNECTION_STRING"],hub="my-hub")# Entra IDfromazure.identityimportDefaultAzureCredential client=WebPubSubServiceClient(endpoint="https://<name>.webpubsub.azure.com",hub="my-hub",credential=DefaultAzureCredential())Generate Client Access Token
# Token for anonymous usertoken=client.get_client_access_token()print(f"URL:{token['url']}")# Token with user IDtoken=client.get_client_access_token(user_id="user123",roles=["webpubsub.sendToGroup","webpubsub.joinLeaveGroup"])# Token with groupstoken=client.get_client_access_token(user_id="user123",groups=["group1","group2"])Send to All Clients
# Send textclient.send_to_all(message="Hello everyone!",content_type="text/plain")# Send JSONclient.send_to_all(message={"type":"notification","data":"Hello"},content_type="application/json")Send to User
client.send_to_user(user_id="user123",message="Hello user!",content_type="text/plain")Send to Group
client.send_to_group(group="my-group",message="Hello group!",content_type="text/plain")Send to Connection
client.send_to_connection(connection_id="abc123",message="Hello connection!",content_type="text/plain")Group Management
# Add user to groupclient.add_user_to_group(group="my-group",user_id="user123")# Remove user from groupclient.remove_user_from_group(group="my-group",user_id="user123")# Add connection to groupclient.add_connection_to_group(group="my-group",connection_id="abc123")# Remove connection from groupclient.remove_connection_from_group(group="my-group",connection_id="abc123")Connection Management
# Check if connection existsexists=client.connection_exists(connection_id="abc123")# Check if user has connectionsexists=client.user_exists(user_id="user123")# Check if group has connectionsexists=client.group_exists(group="my-group")# Close connectionclient.close_connection(connection_id="abc123",reason="Session ended")# Close all connections for userclient.close_all_connections(user_id="user123")Grant/Revoke Permissions
fromazure.messaging.webpubsubserviceimportWebPubSubServiceClient# Grant permissionclient.grant_permission(permission="joinLeaveGroup",connection_id="abc123",target_name="my-group")# Revoke permissionclient.revoke_permission(permission="joinLeaveGroup",connection_id="abc123",target_name="my-group")# Check permissionhas_permission=client.check_permission(permission="joinLeaveGroup",connection_id="abc123",target_name="my-group")Client SDK (Python WebSocket Client)
fromazure.messaging.webpubsubclientimportWebPubSubClient client=WebPubSubClient(credential=token["url\ ioimportWebPubSubServiceClientfromazure.identity.aioimportDefaultAzureCredentialasyncdefbroadcast():credential=DefaultAzureCredential()client=WebPubSubServiceClient(endpoint="https://<name>.webpubsub.azure.com",hub="my-hub",credential=credential)awaitclient.send_to_all("Hello async!",content_type="text/plain")awaitclient.close()awaitcredential.close()Client Operations
| Operation | Description |
|---|---|
get_client_access_token | Generate WebSocket connection URL |
send_to_all | Broadcast to all connections |
send_to_user | Send to specific user |
send_to_group | Send to group members |
send_to_connection | Send to specific connection |
add_user_to_group | Add user to group |
remove_user_from_group | Remove user from group |
close_connection | Disconnect client |
connection_exists | Check connection status |
Best Practices
- Use rolesto limit client permissions
- Use groupsfor targeted messaging
- Generate short-lived tokensfor security
- Use user IDsto send to users across connections
- Handle reconnectionin client applications
- Use JSONcontent type for structured data
- Close connectionsgracefully with reasons
When to Use
This skill is applicable to execute the workflow or actions described in the overview.
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
