0
# Queue Operations
1
2
Queue-specific operations for managing individual queues, their properties, metadata, and access policies. The QueueClient provides comprehensive queue-level management capabilities.
3
4
## Capabilities
5
6
### QueueClient Creation
7
8
Create queue clients using various authentication methods and initialization patterns.
9
10
```python { .api }
11
class QueueClient:
12
def __init__(
13
self,
14
account_url: str,
15
queue_name: str,
16
credential=None,
17
*,
18
api_version: Optional[str] = None,
19
secondary_hostname: Optional[str] = None,
20
message_encode_policy=None,
21
message_decode_policy=None,
22
audience: Optional[str] = None,
23
**kwargs
24
):
25
"""
26
Create a QueueClient for a specific queue.
27
28
Parameters:
29
- account_url: Queue service endpoint URL
30
- queue_name: Name of the target queue
31
- credential: Authentication credential
32
- api_version: Storage service API version
33
- secondary_hostname: Secondary hostname for read access
34
- message_encode_policy: Custom message encoding policy
35
- message_decode_policy: Custom message decoding policy
36
- audience: Token audience for Azure AD authentication
37
"""
38
39
@classmethod
40
def from_queue_url(
41
cls,
42
queue_url: str,
43
credential=None,
44
**kwargs
45
) -> 'QueueClient':
46
"""
47
Create client from complete queue URL.
48
49
Parameters:
50
- queue_url: Complete URL to the queue
51
- credential: Authentication credential
52
53
Returns:
54
QueueClient instance
55
"""
56
57
@classmethod
58
def from_connection_string(
59
cls,
60
conn_str: str,
61
queue_name: str,
62
credential=None,
63
**kwargs
64
) -> 'QueueClient':
65
"""
66
Create client from connection string and queue name.
67
68
Parameters:
69
- conn_str: Storage account connection string
70
- queue_name: Target queue name
71
- credential: Optional additional credential
72
73
Returns:
74
QueueClient instance
75
"""
76
```
77
78
### Queue Lifecycle Management
79
80
Create, delete, and check queue existence.
81
82
```python { .api }
83
def create_queue(
84
self,
85
*,
86
metadata: Optional[Dict[str, str]] = None,
87
timeout: Optional[int] = None,
88
**kwargs
89
) -> None:
90
"""
91
Create the queue if it does not exist.
92
93
Parameters:
94
- metadata: User-defined metadata key-value pairs
95
- timeout: Request timeout in seconds
96
97
Raises:
98
ResourceExistsError: If queue already exists (when checking preconditions)
99
"""
100
101
def delete_queue(
102
self,
103
*,
104
timeout: Optional[int] = None,
105
**kwargs
106
) -> None:
107
"""
108
Delete the queue and all its messages.
109
110
Parameters:
111
- timeout: Request timeout in seconds
112
113
Raises:
114
ResourceNotFoundError: If queue does not exist
115
"""
116
```
117
118
### Queue Properties and Metadata
119
120
Get and set queue properties and user-defined metadata.
121
122
```python { .api }
123
def get_queue_properties(
124
self,
125
*,
126
timeout: Optional[int] = None,
127
**kwargs
128
) -> QueueProperties:
129
"""
130
Get queue properties including metadata and message count.
131
132
Parameters:
133
- timeout: Request timeout in seconds
134
135
Returns:
136
QueueProperties with name, metadata, and approximate message count
137
138
Raises:
139
ResourceNotFoundError: If queue does not exist
140
"""
141
142
def set_queue_metadata(
143
self,
144
metadata: Optional[Dict[str, str]] = None,
145
*,
146
timeout: Optional[int] = None,
147
**kwargs
148
) -> Dict[str, Any]:
149
"""
150
Set user-defined metadata for the queue.
151
152
Parameters:
153
- metadata: Metadata key-value pairs (keys must be valid HTTP header names)
154
- timeout: Request timeout in seconds
155
156
Returns:
157
Dictionary with response headers including ETag and last modified time
158
159
Raises:
160
ResourceNotFoundError: If queue does not exist
161
"""
162
163
# Property for queue name
164
queue_name: str
165
"""The name of the queue."""
166
```
167
168
### Access Policy Management
169
170
Manage stored access policies for fine-grained permissions control.
171
172
```python { .api }
173
def get_queue_access_policy(
174
self,
175
*,
176
timeout: Optional[int] = None,
177
**kwargs
178
) -> Dict[str, AccessPolicy]:
179
"""
180
Get stored access policies for the queue.
181
182
Parameters:
183
- timeout: Request timeout in seconds
184
185
Returns:
186
Dictionary mapping policy IDs to AccessPolicy objects
187
188
Raises:
189
ResourceNotFoundError: If queue does not exist
190
"""
191
192
def set_queue_access_policy(
193
self,
194
signed_identifiers: Dict[str, AccessPolicy],
195
*,
196
timeout: Optional[int] = None,
197
**kwargs
198
) -> None:
199
"""
200
Set stored access policies for the queue.
201
202
Parameters:
203
- signed_identifiers: Dictionary of policy ID to AccessPolicy mappings (max 5 policies)
204
- timeout: Request timeout in seconds
205
206
Raises:
207
ResourceNotFoundError: If queue does not exist
208
"""
209
```
210
211
## Usage Examples
212
213
### Basic Queue Operations
214
215
```python
216
from azure.storage.queue import QueueClient
217
218
# Create queue client
219
queue_client = QueueClient.from_connection_string(
220
conn_str="your_connection_string",
221
queue_name="myqueue"
222
)
223
224
# Create queue with metadata
225
queue_client.create_queue(metadata={"purpose": "test-queue", "env": "development"})
226
227
# Get queue properties
228
properties = queue_client.get_queue_properties()
229
print(f"Queue: {properties.name}")
230
print(f"Messages: {properties.approximate_message_count}")
231
print(f"Metadata: {properties.metadata}")
232
233
# Update metadata
234
queue_client.set_queue_metadata({"purpose": "production-queue", "env": "prod"})
235
236
# Delete queue
237
queue_client.delete_queue()
238
```
239
240
### Access Policy Management
241
242
```python
243
from azure.storage.queue import AccessPolicy, QueueSasPermissions
244
from datetime import datetime, timedelta
245
246
# Create access policies
247
read_policy = AccessPolicy(
248
permission=QueueSasPermissions(read=True, process=True),
249
expiry=datetime.utcnow() + timedelta(hours=24),
250
start=datetime.utcnow()
251
)
252
253
write_policy = AccessPolicy(
254
permission=QueueSasPermissions(add=True, update=True),
255
expiry=datetime.utcnow() + timedelta(hours=12),
256
start=datetime.utcnow()
257
)
258
259
# Set access policies
260
queue_client.set_queue_access_policy({
261
"read-access": read_policy,
262
"write-access": write_policy
263
})
264
265
# Get access policies
266
policies = queue_client.get_queue_access_policy()
267
for policy_id, policy in policies.items():
268
print(f"Policy: {policy_id}, Permissions: {policy.permission}")
269
```
270
271
### Error Handling
272
273
```python
274
from azure.storage.queue import QueueClient
275
from azure.core.exceptions import ResourceExistsError, ResourceNotFoundError
276
277
queue_client = QueueClient.from_connection_string(conn_str, "myqueue")
278
279
try:
280
queue_client.create_queue()
281
print("Queue created successfully")
282
except ResourceExistsError:
283
print("Queue already exists")
284
285
try:
286
properties = queue_client.get_queue_properties()
287
print(f"Queue has {properties.approximate_message_count} messages")
288
except ResourceNotFoundError:
289
print("Queue does not exist")
290
```
291
292
## Types
293
294
### Queue Property Types
295
296
```python { .api }
297
class QueueProperties:
298
name: str
299
metadata: Optional[Dict[str, str]]
300
approximate_message_count: Optional[int]
301
302
@classmethod
303
def _from_generated(cls, generated) -> 'QueueProperties': ...
304
305
class AccessPolicy:
306
permission: Optional[Union[QueueSasPermissions, str]]
307
expiry: Optional[Union[datetime, str]]
308
start: Optional[Union[datetime, str]]
309
310
class QueueSasPermissions:
311
read: bool # Read metadata and properties, peek messages
312
add: bool # Add messages to queue
313
update: bool # Update messages in queue
314
process: bool # Get and delete messages
315
316
def __str__(self) -> str: ...
317
318
@classmethod
319
def from_string(cls, permission: str) -> 'QueueSasPermissions': ...
320
```