Azure Messaging Webpubsubservice Py

1---
2name: azure-messaging-webpubsubservice-py
3description: |
4  Azure Web PubSub Service SDK for Python. Use for real-time messaging, WebSocket connections, and pub/sub patterns.
5  Triggers: "azure-messaging-webpubsubservice", "WebPubSubServiceClient", "real-time", "WebSocket", "pub/sub".
6package: azure-messaging-webpubsubservice
7---
8 
9# Azure Web PubSub Service SDK for Python
10 
11Real-time messaging with WebSocket connections at scale.
12 
13## Installation
14 
15```bash
16# Service SDK (server-side)
17pip install azure-messaging-webpubsubservice
18 
19# Client SDK (for Python WebSocket clients)
20pip install azure-messaging-webpubsubclient
21```
22 
23## Environment Variables
24 
25```bash
26AZURE_WEBPUBSUB_CONNECTION_STRING=Endpoint=https://<name>.webpubsub.azure.com;AccessKey=...
27AZURE_WEBPUBSUB_HUB=my-hub
28```
29 
30## Service Client (Server-Side)
31 
32### Authentication
33 
34```python
35from azure.messaging.webpubsubservice import WebPubSubServiceClient
36 
37# Connection string
38client = WebPubSubServiceClient.from_connection_string(
39    connection_string=os.environ["AZURE_WEBPUBSUB_CONNECTION_STRING"],
40    hub="my-hub"
41)
42 
43# Entra ID
44from azure.identity import DefaultAzureCredential
45 
46client = WebPubSubServiceClient(
47    endpoint="https://<name>.webpubsub.azure.com",
48    hub="my-hub",
49    credential=DefaultAzureCredential()
50)
51```
52 
53### Generate Client Access Token
54 
55```python
56# Token for anonymous user
57token = client.get_client_access_token()
58print(f"URL: {token['url']}")
59 
60# Token with user ID
61token = client.get_client_access_token(
62    user_id="user123",
63    roles=["webpubsub.sendToGroup", "webpubsub.joinLeaveGroup"]
64)
65 
66# Token with groups
67token = client.get_client_access_token(
68    user_id="user123",
69    groups=["group1", "group2"]
70)
71```
72 
73### Send to All Clients
74 
75```python
76# Send text
77client.send_to_all(message="Hello everyone!", content_type="text/plain")
78 
79# Send JSON
80client.send_to_all(
81    message={"type": "notification", "data": "Hello"},
82    content_type="application/json"
83)
84```
85 
86### Send to User
87 
88```python
89client.send_to_user(
90    user_id="user123",
91    message="Hello user!",
92    content_type="text/plain"
93)
94```
95 
96### Send to Group
97 
98```python
99client.send_to_group(
100    group="my-group",
101    message="Hello group!",
102    content_type="text/plain"
103)
104```
105 
106### Send to Connection
107 
108```python
109client.send_to_connection(
110    connection_id="abc123",
111    message="Hello connection!",
112    content_type="text/plain"
113)
114```
115 
116### Group Management
117 
118```python
119# Add user to group
120client.add_user_to_group(group="my-group", user_id="user123")
121 
122# Remove user from group
123client.remove_user_from_group(group="my-group", user_id="user123")
124 
125# Add connection to group
126client.add_connection_to_group(group="my-group", connection_id="abc123")
127 
128# Remove connection from group
129client.remove_connection_from_group(group="my-group", connection_id="abc123")
130```
131 
132### Connection Management
133 
134```python
135# Check if connection exists
136exists = client.connection_exists(connection_id="abc123")
137 
138# Check if user has connections
139exists = client.user_exists(user_id="user123")
140 
141# Check if group has connections
142exists = client.group_exists(group="my-group")
143 
144# Close connection
145client.close_connection(connection_id="abc123", reason="Session ended")
146 
147# Close all connections for user
148client.close_all_connections(user_id="user123")
149```
150 
151### Grant/Revoke Permissions
152 
153```python
154from azure.messaging.webpubsubservice import WebPubSubServiceClient
155 
156# Grant permission
157client.grant_permission(
158    permission="joinLeaveGroup",
159    connection_id="abc123",
160    target_name="my-group"
161)
162 
163# Revoke permission
164client.revoke_permission(
165    permission="joinLeaveGroup",
166    connection_id="abc123",
167    target_name="my-group"
168)
169 
170# Check permission
171has_permission = client.check_permission(
172    permission="joinLeaveGroup",
173    connection_id="abc123",
174    target_name="my-group"
175)
176```
177 
178## Client SDK (Python WebSocket Client)
179 
180```python
181from azure.messaging.webpubsubclient import WebPubSubClient
182 
183client = WebPubSubClient(credential=token["url"])
184 
185# Event handlers
186@client.on("connected")
187def on_connected(e):
188    print(f"Connected: {e.connection_id}")
189 
190@client.on("server-message")
191def on_message(e):
192    print(f"Message: {e.data}")
193 
194@client.on("group-message")
195def on_group_message(e):
196    print(f"Group {e.group}: {e.data}")
197 
198# Connect and send
199client.open()
200client.send_to_group("my-group", "Hello from Python!")
201```
202 
203## Async Service Client
204 
205```python
206from azure.messaging.webpubsubservice.aio import WebPubSubServiceClient
207from azure.identity.aio import DefaultAzureCredential
208 
209async def broadcast():
210    credential = DefaultAzureCredential()
211    client = WebPubSubServiceClient(
212        endpoint="https://<name>.webpubsub.azure.com",
213        hub="my-hub",
214        credential=credential
215    )
216    
217    await client.send_to_all("Hello async!", content_type="text/plain")
218    
219    await client.close()
220    await credential.close()
221```
222 
223## Client Operations
224 
225| Operation | Description |
226|-----------|-------------|
227| `get_client_access_token` | Generate WebSocket connection URL |
228| `send_to_all` | Broadcast to all connections |
229| `send_to_user` | Send to specific user |
230| `send_to_group` | Send to group members |
231| `send_to_connection` | Send to specific connection |
232| `add_user_to_group` | Add user to group |
233| `remove_user_from_group` | Remove user from group |
234| `close_connection` | Disconnect client |
235| `connection_exists` | Check connection status |
236 
237## Best Practices
238 
2391. **Use roles** to limit client permissions
2402. **Use groups** for targeted messaging
2413. **Generate short-lived tokens** for security
2424. **Use user IDs** to send to users across connections
2435. **Handle reconnection** in client applications
2446. **Use JSON** content type for structured data
2457. **Close connections** gracefully with reasons
246