实时消息传递_azure-messaging-webpubsubservice-py

以下为本文档的中文说明

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-webpubsubclient

Environment Variables

AZURE_WEBPUBSUB_CONNECTION_STRING=Endpoint=https://<name>.webpubsub.azure.com;AccessKey=...AZURE_WEBPUBSUB_HUB=my-hub

Service 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

Best Practices

1. Use rolesto limit client permissions
2. Use groupsfor targeted messaging
3. Generate short-lived tokensfor security
4. Use user IDsto send to users across connections
5. Handle reconnectionin client applications
6. Use JSONcontent type for structured data
7. 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.