0
# Message Operations
1
2
Comprehensive message handling operations including sending, receiving, updating, peeking, and deletion. These operations form the core functionality for queue-based messaging patterns.
3
4
## Capabilities
5
6
### Message Sending
7
8
Send messages to the queue with optional visibility delays and expiration settings.
9
10
```python { .api }
11
def send_message(
12
self,
13
content: Any,
14
*,
15
visibility_timeout: Optional[int] = None,
16
time_to_live: Optional[int] = None,
17
timeout: Optional[int] = None,
18
**kwargs
19
) -> QueueMessage:
20
"""
21
Send a message to the queue.
22
23
Parameters:
24
- content: Message content (string, bytes, or object for encoding)
25
- visibility_timeout: Seconds before message becomes visible (0-604800, default: 0)
26
- time_to_live: Message expiration in seconds (1-604800, default: 604800)
27
- timeout: Request timeout in seconds
28
29
Returns:
30
QueueMessage with ID, pop_receipt, insertion time, and expiration time
31
32
Raises:
33
RequestTooLargeError: If message exceeds 64KB limit
34
"""
35
```
36
37
### Message Receiving
38
39
Receive messages from the queue with automatic visibility timeout management.
40
41
```python { .api }
42
def receive_message(
43
self,
44
*,
45
visibility_timeout: Optional[int] = None,
46
timeout: Optional[int] = None,
47
**kwargs
48
) -> Optional[QueueMessage]:
49
"""
50
Receive a single message from the queue.
51
52
Parameters:
53
- visibility_timeout: Seconds message stays invisible (1-43200, default: 30)
54
- timeout: Request timeout in seconds
55
56
Returns:
57
QueueMessage if available, None if queue is empty
58
"""
59
60
def receive_messages(
61
self,
62
*,
63
messages_per_page: Optional[int] = None,
64
visibility_timeout: Optional[int] = None,
65
max_messages: Optional[int] = None,
66
timeout: Optional[int] = None,
67
**kwargs
68
) -> ItemPaged[QueueMessage]:
69
"""
70
Receive multiple messages from the queue with pagination.
71
72
Parameters:
73
- messages_per_page: Messages per page (1-32, default: 1)
74
- visibility_timeout: Seconds messages stay invisible (1-43200, default: 30)
75
- max_messages: Maximum total messages to receive
76
- timeout: Request timeout in seconds
77
78
Returns:
79
ItemPaged iterator yielding QueueMessage objects
80
"""
81
```
82
83
### Message Peeking
84
85
Peek at messages without changing their visibility or dequeue count.
86
87
```python { .api }
88
def peek_messages(
89
self,
90
max_messages: Optional[int] = None,
91
*,
92
timeout: Optional[int] = None,
93
**kwargs
94
) -> List[QueueMessage]:
95
"""
96
Peek at messages without dequeuing them.
97
98
Parameters:
99
- max_messages: Maximum messages to peek (1-32, default: 1)
100
- timeout: Request timeout in seconds
101
102
Returns:
103
List of QueueMessage objects (without pop_receipt)
104
105
Note:
106
Peeked messages cannot be deleted or updated
107
"""
108
```
109
110
### Message Updates
111
112
Update message content and visibility timeout for received messages.
113
114
```python { .api }
115
def update_message(
116
self,
117
message: Union[QueueMessage, str],
118
pop_receipt: Optional[str] = None,
119
content: Optional[Any] = None,
120
*,
121
visibility_timeout: Optional[int] = None,
122
timeout: Optional[int] = None,
123
**kwargs
124
) -> QueueMessage:
125
"""
126
Update message content and/or visibility timeout.
127
128
Parameters:
129
- message: QueueMessage object or message ID
130
- pop_receipt: Message pop receipt (required if message is string ID)
131
- content: New message content (None to keep current content)
132
- visibility_timeout: New visibility timeout in seconds (0-43200)
133
- timeout: Request timeout in seconds
134
135
Returns:
136
QueueMessage with updated pop_receipt and next_visible_on time
137
138
Raises:
139
ResourceNotFoundError: If message not found or pop_receipt invalid
140
"""
141
```
142
143
### Message Deletion
144
145
Delete individual messages or clear all messages from the queue.
146
147
```python { .api }
148
def delete_message(
149
self,
150
message: Union[QueueMessage, str],
151
pop_receipt: Optional[str] = None,
152
*,
153
timeout: Optional[int] = None,
154
**kwargs
155
) -> None:
156
"""
157
Delete a message from the queue.
158
159
Parameters:
160
- message: QueueMessage object or message ID
161
- pop_receipt: Message pop receipt (required if message is string ID)
162
- timeout: Request timeout in seconds
163
164
Raises:
165
ResourceNotFoundError: If message not found or pop_receipt invalid
166
"""
167
168
def clear_messages(
169
self,
170
*,
171
timeout: Optional[int] = None,
172
**kwargs
173
) -> None:
174
"""
175
Clear all messages from the queue.
176
177
Parameters:
178
- timeout: Request timeout in seconds
179
180
Note:
181
This operation cannot be undone
182
"""
183
```
184
185
## Usage Examples
186
187
### Basic Message Operations
188
189
```python
190
from azure.storage.queue import QueueClient
191
192
queue_client = QueueClient.from_connection_string(conn_str, "myqueue")
193
194
# Send a message
195
message = queue_client.send_message("Hello, World!")
196
print(f"Message sent with ID: {message.id}")
197
198
# Send message with visibility delay
199
delayed_message = queue_client.send_message(
200
"Delayed message",
201
visibility_timeout=300, # Visible after 5 minutes
202
time_to_live=3600 # Expires after 1 hour
203
)
204
205
# Receive and process messages
206
messages = queue_client.receive_messages(max_messages=5)
207
for message in messages:
208
print(f"Processing: {message.content}")
209
210
# Simulate processing time
211
import time
212
time.sleep(2)
213
214
# Delete message after processing
215
queue_client.delete_message(message)
216
```
217
218
### Message Visibility Management
219
220
```python
221
# Receive message with custom visibility timeout
222
message = queue_client.receive_message(visibility_timeout=120) # 2 minutes
223
224
if message:
225
try:
226
# Process message
227
result = process_message(message.content)
228
229
# If processing successful, delete message
230
queue_client.delete_message(message)
231
232
except Exception as e:
233
# If processing fails, extend visibility timeout for retry
234
updated_message = queue_client.update_message(
235
message,
236
visibility_timeout=300 # Make visible again in 5 minutes
237
)
238
print(f"Message processing failed, will retry. New pop_receipt: {updated_message.pop_receipt}")
239
```
240
241
### Message Content Updates
242
243
```python
244
# Receive message
245
message = queue_client.receive_message()
246
247
if message:
248
# Update message content and extend visibility
249
updated_message = queue_client.update_message(
250
message,
251
content="Updated message content",
252
visibility_timeout=180 # Extend visibility by 3 minutes
253
)
254
255
print(f"Message updated. New pop_receipt: {updated_message.pop_receipt}")
256
257
# Process and delete
258
queue_client.delete_message(updated_message)
259
```
260
261
### Peek Operations
262
263
```python
264
# Peek at messages without dequeuing
265
peeked_messages = queue_client.peek_messages(max_messages=10)
266
267
print(f"Found {len(peeked_messages)} messages in queue:")
268
for i, message in enumerate(peeked_messages, 1):
269
print(f"{i}. ID: {message.id}, Content: {message.content}")
270
print(f" Inserted: {message.inserted_on}, Expires: {message.expires_on}")
271
print(f" Dequeue count: {message.dequeue_count}")
272
```
273
274
### Batch Processing
275
276
```python
277
def process_messages_in_batches():
278
while True:
279
# Receive batch of messages
280
messages = list(queue_client.receive_messages(messages_per_page=32))
281
282
if not messages:
283
print("No more messages to process")
284
break
285
286
print(f"Processing batch of {len(messages)} messages")
287
288
for message in messages:
289
try:
290
# Process message
291
process_single_message(message.content)
292
293
# Delete on success
294
queue_client.delete_message(message)
295
296
except Exception as e:
297
print(f"Failed to process message {message.id}: {e}")
298
# Message will become visible again after timeout
299
```
300
301
### Error Handling
302
303
```python
304
from azure.core.exceptions import ResourceNotFoundError, RequestTooLargeError
305
306
try:
307
# Send large message
308
large_content = "x" * 70000 # > 64KB limit
309
queue_client.send_message(large_content)
310
311
except RequestTooLargeError:
312
print("Message too large, must be ≤ 64KB")
313
314
try:
315
# Try to delete message with invalid pop receipt
316
queue_client.delete_message("invalid-message-id", "invalid-pop-receipt")
317
318
except ResourceNotFoundError:
319
print("Message not found or pop receipt is invalid")
320
```
321
322
## Types
323
324
### Message Types
325
326
```python { .api }
327
class QueueMessage:
328
id: str # Message GUID
329
content: Any # Message content (decoded by policy)
330
pop_receipt: Optional[str] # Receipt for delete/update operations
331
inserted_on: Optional[datetime] # UTC insertion timestamp
332
expires_on: Optional[datetime] # UTC expiration timestamp
333
dequeue_count: Optional[int] # Number of times message was dequeued
334
next_visible_on: Optional[datetime] # UTC time when message becomes visible
335
336
@classmethod
337
def _from_generated(cls, generated) -> 'QueueMessage': ...
338
```
339
340
### Pagination Types
341
342
```python { .api }
343
from azure.core.paging import ItemPaged
344
from typing import Iterator
345
346
# ItemPaged[QueueMessage] provides:
347
# - Iteration over messages
348
# - Automatic pagination handling
349
# - by_page() method for page-by-page access
350
```
351
352
### Message Size Limits
353
354
```python { .api }
355
# Message size constraints:
356
MAX_MESSAGE_SIZE_BYTES = 65536 # 64KB maximum
357
MAX_MESSAGES_PER_GET = 32 # Maximum messages per receive operation
358
MAX_PEEK_MESSAGES = 32 # Maximum messages per peek operation
359
MAX_VISIBILITY_TIMEOUT = 43200 # 12 hours maximum visibility timeout
360
MAX_TIME_TO_LIVE = 604800 # 7 days maximum message lifetime
361
```