0
# Administrative Operations
1

2
Complete Service Bus entity management including queues, topics, subscriptions, and rules. Supports creation, configuration, monitoring, and deletion of messaging entities.
3

4
## Capabilities
5

6
### ServiceBusAdministrationClient Initialization
7

8
Create an administration client for managing Service Bus entities.
9

10
```python { .api }
11
class ServiceBusAdministrationClient:
12
    def __init__(
13
        self,
14
        fully_qualified_namespace: str,
15
        credential: TokenCredential,
16
        *,
17
        api_version: Union[str, ApiVersion] = DEFAULT_VERSION,
18
        **kwargs
19
    ):
20
        """
21
        Create a Service Bus administration client.
22

23
        Parameters:
24
        - fully_qualified_namespace: The fully qualified Service Bus namespace URL
25
        - credential: Azure credential for authentication (Azure Active Directory)
26
        - api_version: Service Bus management API version to use
27
        """
28

29
    @classmethod
30
    def from_connection_string(
31
        cls,
32
        conn_str: str,
33
        **kwargs
34
    ) -> 'ServiceBusAdministrationClient':
35
        """
36
        Create administration client from connection string.
37

38
        Parameters:
39
        - conn_str: Service Bus connection string with management permissions
40

41
        Returns:
42
        ServiceBusAdministrationClient instance
43
        """
44
```
45

46
#### Usage Example
47

48
```python
49
from azure.servicebus.management import ServiceBusAdministrationClient
50
from azure.identity import DefaultAzureCredential
51

52
# Using Azure Active Directory credential
53
credential = DefaultAzureCredential()
54
admin_client = ServiceBusAdministrationClient(
55
    fully_qualified_namespace="myservicebus.servicebus.windows.net",
56
    credential=credential
57
)
58

59
# Or using connection string
60
admin_client = ServiceBusAdministrationClient.from_connection_string(
61
    "Endpoint=sb://myservicebus.servicebus.windows.net/;SharedAccessKeyName=..."
62
)
63
```
64

65
### Queue Management
66

67
Create, configure, monitor, and delete Service Bus queues.
68

69
```python { .api }
70
def create_queue(
71
    self,
72
    queue_name: str,
73
    **kwargs
74
) -> QueueProperties:
75
    """
76
    Create a new queue.
77

78
    Parameters:
79
    - queue_name: Name of the queue to create
80
    - **kwargs: Queue configuration options (max_size_in_megabytes, default_message_time_to_live, etc.)
81

82
    Returns:
83
    QueueProperties with the created queue configuration
84

85
    Raises:
86
    - MessagingEntityAlreadyExistsError: If queue already exists
87
    - ServiceBusError: For other Service Bus related errors
88
    """
89

90
def get_queue(
91
    self,
92
    queue_name: str,
93
    **kwargs
94
) -> QueueProperties:
95
    """
96
    Get queue properties and configuration.
97

98
    Parameters:
99
    - queue_name: Name of the queue
100

101
    Returns:
102
    QueueProperties with queue configuration
103

104
    Raises:
105
    - MessagingEntityNotFoundError: If queue does not exist
106
    - ServiceBusError: For other Service Bus related errors
107
    """
108

109
def get_queue_runtime_properties(
110
    self,
111
    queue_name: str,
112
    **kwargs
113
) -> QueueRuntimeProperties:
114
    """
115
    Get queue runtime information and metrics.
116

117
    Parameters:
118
    - queue_name: Name of the queue
119

120
    Returns:
121
    QueueRuntimeProperties with runtime metrics
122

123
    Raises:
124
    - MessagingEntityNotFoundError: If queue does not exist
125
    - ServiceBusError: For other Service Bus related errors
126
    """
127

128
def update_queue(
129
    self,
130
    queue: Union[QueueProperties, Mapping[str, Any]],
131
    **kwargs
132
) -> None:
133
    """
134
    Update queue configuration.
135

136
    Parameters:
137
    - queue: QueueProperties object or dictionary with queue settings
138

139
    Raises:
140
    - MessagingEntityNotFoundError: If queue does not exist
141
    - ServiceBusError: For other Service Bus related errors
142
    """
143

144
def delete_queue(
145
    self,
146
    queue_name: str,
147
    **kwargs
148
) -> None:
149
    """
150
    Delete a queue.
151

152
    Parameters:
153
    - queue_name: Name of the queue to delete
154

155
    Raises:
156
    - MessagingEntityNotFoundError: If queue does not exist
157
    - ServiceBusError: For other Service Bus related errors
158
    """
159

160
def list_queues(self, **kwargs) -> ItemPaged[QueueProperties]:
161
    """
162
    List all queues in the namespace.
163

164
    Returns:
165
    ItemPaged iterator of QueueProperties objects
166

167
    Raises:
168
    - ServiceBusError: For Service Bus related errors
169
    """
170

171
def list_queues_runtime_properties(self, **kwargs) -> ItemPaged[QueueRuntimeProperties]:
172
    """
173
    List runtime properties for all queues.
174

175
    Returns:
176
    ItemPaged iterator of QueueRuntimeProperties objects
177

178
    Raises:
179
    - ServiceBusError: For Service Bus related errors
180
    """
181
```
182

183
#### Usage Example
184

185
```python
186
from azure.servicebus.management import ServiceBusAdministrationClient, QueueProperties
187
from datetime import timedelta
188

189
admin_client = ServiceBusAdministrationClient.from_connection_string("your_connection_string")
190

191
# Create a queue with custom settings
192
queue_properties = admin_client.create_queue(
193
    "my-new-queue",
194
    max_size_in_megabytes=2048,
195
    default_message_time_to_live=timedelta(days=7),
196
    enable_dead_lettering_on_message_expiration=True,
197
    max_delivery_count=5
198
)
199
print(f"Created queue: {queue_properties.name}")
200

201
# Get queue information
202
queue_info = admin_client.get_queue("my-new-queue")
203
print(f"Queue max size: {queue_info.max_size_in_megabytes} MB")
204

205
# Get runtime metrics
206
runtime_info = admin_client.get_queue_runtime_properties("my-new-queue")
207
print(f"Active messages: {runtime_info.active_message_count}")
208
print(f"Dead letter messages: {runtime_info.dead_letter_message_count}")
209

210
# List all queues
211
for queue in admin_client.list_queues():
212
    print(f"Queue: {queue.name}, Size: {queue.max_size_in_megabytes} MB")
213

214
# Update queue settings
215
queue_info.max_delivery_count = 10
216
admin_client.update_queue(queue_info)
217

218
# Delete queue when no longer needed
219
admin_client.delete_queue("my-new-queue")
220
```
221

222
### Topic Management
223

224
Create, configure, monitor, and delete Service Bus topics.
225

226
```python { .api }
227
def create_topic(
228
    self,
229
    topic_name: str,
230
    **kwargs
231
) -> TopicProperties:
232
    """
233
    Create a new topic.
234

235
    Parameters:
236
    - topic_name: Name of the topic to create
237
    - **kwargs: Topic configuration options
238

239
    Returns:
240
    TopicProperties with the created topic configuration
241

242
    Raises:
243
    - MessagingEntityAlreadyExistsError: If topic already exists
244
    - ServiceBusError: For other Service Bus related errors
245
    """
246

247
def get_topic(
248
    self,
249
    topic_name: str,
250
    **kwargs
251
) -> TopicProperties:
252
    """
253
    Get topic properties and configuration.
254

255
    Parameters:
256
    - topic_name: Name of the topic
257

258
    Returns:
259
    TopicProperties with topic configuration
260

261
    Raises:
262
    - MessagingEntityNotFoundError: If topic does not exist
263
    - ServiceBusError: For other Service Bus related errors
264
    """
265

266
def get_topic_runtime_properties(
267
    self,
268
    topic_name: str,
269
    **kwargs
270
) -> TopicRuntimeProperties:
271
    """
272
    Get topic runtime information and metrics.
273

274
    Parameters:
275
    - topic_name: Name of the topic
276

277
    Returns:
278
    TopicRuntimeProperties with runtime metrics
279

280
    Raises:
281
    - MessagingEntityNotFoundError: If topic does not exist
282
    - ServiceBusError: For other Service Bus related errors
283
    """
284

285
def update_topic(
286
    self,
287
    topic: Union[TopicProperties, Mapping[str, Any]],
288
    **kwargs
289
) -> None:
290
    """
291
    Update topic configuration.
292

293
    Parameters:
294
    - topic: TopicProperties object or dictionary with topic settings
295

296
    Raises:
297
    - MessagingEntityNotFoundError: If topic does not exist
298
    - ServiceBusError: For other Service Bus related errors
299
    """
300

301
def delete_topic(
302
    self,
303
    topic_name: str,
304
    **kwargs
305
) -> None:
306
    """
307
    Delete a topic and all its subscriptions.
308

309
    Parameters:
310
    - topic_name: Name of the topic to delete
311

312
    Raises:
313
    - MessagingEntityNotFoundError: If topic does not exist
314
    - ServiceBusError: For other Service Bus related errors
315
    """
316

317
def list_topics(self, **kwargs) -> ItemPaged[TopicProperties]:
318
    """
319
    List all topics in the namespace.
320

321
    Returns:
322
    ItemPaged iterator of TopicProperties objects
323

324
    Raises:
325
    - ServiceBusError: For Service Bus related errors
326
    """
327

328
def list_topics_runtime_properties(self, **kwargs) -> ItemPaged[TopicRuntimeProperties]:
329
    """
330
    List runtime properties for all topics.
331

332
    Returns:
333
    ItemPaged iterator of TopicRuntimeProperties objects
334

335
    Raises:
336
    - ServiceBusError: For Service Bus related errors
337
    """
338
```
339

340
### Subscription Management
341

342
Create, configure, monitor, and delete topic subscriptions.
343

344
```python { .api }
345
def create_subscription(
346
    self,
347
    topic_name: str,
348
    subscription_name: str,
349
    **kwargs
350
) -> SubscriptionProperties:
351
    """
352
    Create a new subscription for a topic.
353

354
    Parameters:
355
    - topic_name: Name of the parent topic
356
    - subscription_name: Name of the subscription to create
357
    - **kwargs: Subscription configuration options
358

359
    Returns:
360
    SubscriptionProperties with the created subscription configuration
361

362
    Raises:
363
    - MessagingEntityNotFoundError: If topic does not exist
364
    - MessagingEntityAlreadyExistsError: If subscription already exists
365
    - ServiceBusError: For other Service Bus related errors
366
    """
367

368
def get_subscription(
369
    self,
370
    topic_name: str,
371
    subscription_name: str,
372
    **kwargs
373
) -> SubscriptionProperties:
374
    """
375
    Get subscription properties and configuration.
376

377
    Parameters:
378
    - topic_name: Name of the parent topic
379
    - subscription_name: Name of the subscription
380

381
    Returns:
382
    SubscriptionProperties with subscription configuration
383

384
    Raises:
385
    - MessagingEntityNotFoundError: If topic or subscription does not exist
386
    - ServiceBusError: For other Service Bus related errors
387
    """
388

389
def get_subscription_runtime_properties(
390
    self,
391
    topic_name: str,
392
    subscription_name: str,
393
    **kwargs
394
) -> SubscriptionRuntimeProperties:
395
    """
396
    Get subscription runtime information and metrics.
397

398
    Parameters:
399
    - topic_name: Name of the parent topic
400
    - subscription_name: Name of the subscription
401

402
    Returns:
403
    SubscriptionRuntimeProperties with runtime metrics
404

405
    Raises:
406
    - MessagingEntityNotFoundError: If topic or subscription does not exist
407
    - ServiceBusError: For other Service Bus related errors
408
    """
409

410
def update_subscription(
411
    self,
412
    topic_name: str,
413
    subscription: Union[SubscriptionProperties, Mapping[str, Any]],
414
    **kwargs
415
) -> None:
416
    """
417
    Update subscription configuration.
418

419
    Parameters:
420
    - topic_name: Name of the parent topic
421
    - subscription: SubscriptionProperties object or dictionary with subscription settings
422

423
    Raises:
424
    - MessagingEntityNotFoundError: If topic or subscription does not exist
425
    - ServiceBusError: For other Service Bus related errors
426
    """
427

428
def delete_subscription(
429
    self,
430
    topic_name: str,
431
    subscription_name: str,
432
    **kwargs
433
) -> None:
434
    """
435
    Delete a subscription.
436

437
    Parameters:
438
    - topic_name: Name of the parent topic
439
    - subscription_name: Name of the subscription to delete
440

441
    Raises:
442
    - MessagingEntityNotFoundError: If topic or subscription does not exist
443
    - ServiceBusError: For other Service Bus related errors
444
    """
445

446
def list_subscriptions(
447
    self,
448
    topic_name: str,
449
    **kwargs
450
) -> ItemPaged[SubscriptionProperties]:
451
    """
452
    List all subscriptions for a topic.
453

454
    Parameters:
455
    - topic_name: Name of the parent topic
456

457
    Returns:
458
    ItemPaged iterator of SubscriptionProperties objects
459

460
    Raises:
461
    - MessagingEntityNotFoundError: If topic does not exist
462
    - ServiceBusError: For Service Bus related errors
463
    """
464

465
def list_subscriptions_runtime_properties(
466
    self,
467
    topic_name: str,
468
    **kwargs
469
) -> ItemPaged[SubscriptionRuntimeProperties]:
470
    """
471
    List runtime properties for all subscriptions of a topic.
472

473
    Parameters:
474
    - topic_name: Name of the parent topic
475

476
    Returns:
477
    ItemPaged iterator of SubscriptionRuntimeProperties objects
478

479
    Raises:
480
    - MessagingEntityNotFoundError: If topic does not exist
481
    - ServiceBusError: For Service Bus related errors
482
    """
483
```
484

485
#### Usage Example
486

487
```python
488
from azure.servicebus.management import ServiceBusAdministrationClient
489
from datetime import timedelta
490

491
admin_client = ServiceBusAdministrationClient.from_connection_string("your_connection_string")
492

493
# Create a topic
494
topic_properties = admin_client.create_topic(
495
    "my-topic",
496
    max_size_in_megabytes=5120,
497
    enable_partitioning=True
498
)
499
print(f"Created topic: {topic_properties.name}")
500

501
# Create subscriptions for the topic
502
subscription1 = admin_client.create_subscription(
503
    "my-topic",
504
    "subscription1",
505
    default_message_time_to_live=timedelta(hours=24),
506
    enable_dead_lettering_on_message_expiration=True
507
)
508

509
subscription2 = admin_client.create_subscription(
510
    "my-topic", 
511
    "subscription2",
512
    max_delivery_count=3
513
)
514

515
# List all subscriptions
516
for sub in admin_client.list_subscriptions("my-topic"):
517
    print(f"Subscription: {sub.subscription_name}")
518
    
519
    # Get runtime metrics for each subscription
520
    runtime = admin_client.get_subscription_runtime_properties("my-topic", sub.subscription_name)
521
    print(f"  Active messages: {runtime.active_message_count}")
522
    print(f"  Dead letter messages: {runtime.dead_letter_message_count}")
523
```
524

525
### Rule Management
526

527
Create, configure, and delete subscription rules for message filtering.
528

529
```python { .api }
530
def create_rule(
531
    self,
532
    topic_name: str,
533
    subscription_name: str,
534
    rule_name: str,
535
    **kwargs
536
) -> RuleProperties:
537
    """
538
    Create a new rule for a subscription.
539

540
    Parameters:
541
    - topic_name: Name of the parent topic
542
    - subscription_name: Name of the subscription
543
    - rule_name: Name of the rule to create
544
    - **kwargs: Rule configuration (filter, action)
545

546
    Returns:
547
    RuleProperties with the created rule configuration
548

549
    Raises:
550
    - MessagingEntityNotFoundError: If topic or subscription does not exist
551
    - MessagingEntityAlreadyExistsError: If rule already exists
552
    - ServiceBusError: For other Service Bus related errors
553
    """
554

555
def get_rule(
556
    self,
557
    topic_name: str,
558
    subscription_name: str,
559
    rule_name: str,
560
    **kwargs
561
) -> RuleProperties:
562
    """
563
    Get rule properties and configuration.
564

565
    Parameters:
566
    - topic_name: Name of the parent topic
567
    - subscription_name: Name of the subscription
568
    - rule_name: Name of the rule
569

570
    Returns:
571
    RuleProperties with rule configuration
572

573
    Raises:
574
    - MessagingEntityNotFoundError: If topic, subscription, or rule does not exist
575
    - ServiceBusError: For other Service Bus related errors
576
    """
577

578
def update_rule(
579
    self,
580
    topic_name: str,
581
    subscription_name: str,
582
    rule: Union[RuleProperties, Mapping[str, Any]],
583
    **kwargs
584
) -> None:
585
    """
586
    Update rule configuration.
587

588
    Parameters:
589
    - topic_name: Name of the parent topic
590
    - subscription_name: Name of the subscription
591
    - rule: RuleProperties object or dictionary with rule settings
592

593
    Raises:
594
    - MessagingEntityNotFoundError: If topic, subscription, or rule does not exist
595
    - ServiceBusError: For other Service Bus related errors
596
    """
597

598
def delete_rule(
599
    self,
600
    topic_name: str,
601
    subscription_name: str,
602
    rule_name: str,
603
    **kwargs
604
) -> None:
605
    """
606
    Delete a rule.
607

608
    Parameters:
609
    - topic_name: Name of the parent topic
610
    - subscription_name: Name of the subscription
611
    - rule_name: Name of the rule to delete
612

613
    Raises:
614
    - MessagingEntityNotFoundError: If topic, subscription, or rule does not exist
615
    - ServiceBusError: For other Service Bus related errors
616
    """
617

618
def list_rules(
619
    self,
620
    topic_name: str,
621
    subscription_name: str,
622
    **kwargs
623
) -> ItemPaged[RuleProperties]:
624
    """
625
    List all rules for a subscription.
626

627
    Parameters:
628
    - topic_name: Name of the parent topic
629
    - subscription_name: Name of the subscription
630

631
    Returns:
632
    ItemPaged iterator of RuleProperties objects
633

634
    Raises:
635
    - MessagingEntityNotFoundError: If topic or subscription does not exist
636
    - ServiceBusError: For Service Bus related errors
637
    """
638
```
639

640
#### Usage Example
641

642
```python
643
from azure.servicebus.management import (
644
    ServiceBusAdministrationClient,
645
    SqlRuleFilter,
646
    CorrelationRuleFilter,
647
    SqlRuleAction
648
)
649

650
admin_client = ServiceBusAdministrationClient.from_connection_string("your_connection_string")
651

652
# Create rules with different filter types
653
sql_rule = admin_client.create_rule(
654
    "my-topic",
655
    "subscription1", 
656
    "high-priority-rule",
657
    filter=SqlRuleFilter("priority = 'high'"),
658
    action=SqlRuleAction("SET priority = 'processed'")
659
)
660

661
correlation_rule = admin_client.create_rule(
662
    "my-topic",
663
    "subscription2",
664
    "order-rule", 
665
    filter=CorrelationRuleFilter(
666
        correlation_id="order-12345",
667
        properties={"type": "order", "region": "west"}
668
    )
669
)
670

671
# List and examine rules
672
for rule in admin_client.list_rules("my-topic", "subscription1"):
673
    print(f"Rule: {rule.name}")
674
    print(f"Filter: {rule.filter}")
675
    if rule.action:
676
        print(f"Action: {rule.action}")
677

678
# Delete a rule
679
admin_client.delete_rule("my-topic", "subscription1", "high-priority-rule")
680
```
681

682
### Namespace Operations
683

684
Get information about the Service Bus namespace.
685

686
```python { .api }
687
def get_namespace_properties(self, **kwargs) -> NamespaceProperties:
688
    """
689
    Get namespace properties and information.
690

691
    Returns:
692
    NamespaceProperties with namespace information
693

694
    Raises:
695
    - ServiceBusError: For Service Bus related errors
696
    """
697
```
698

699
#### Usage Example
700

701
```python
702
admin_client = ServiceBusAdministrationClient.from_connection_string("your_connection_string")
703

704
# Get namespace information
705
namespace_info = admin_client.get_namespace_properties()
706
print(f"Namespace: {namespace_info.name}")
707
print(f"SKU: {namespace_info.messaging_sku}")
708
print(f"Created: {namespace_info.created_at_utc}")
709
print(f"Modified: {namespace_info.modified_at_utc}")
710
```
711

712
## Management Model Properties
713

714
### QueueProperties
715

716
Configuration settings for Service Bus queues.
717

718
```python { .api }
719
class QueueProperties:
720
    @property
721
    def name(self) -> str: ...
722
    @property
723
    def max_size_in_megabytes(self) -> int: ...
724
    @property
725
    def default_message_time_to_live(self) -> timedelta: ...
726
    @property
727
    def lock_duration(self) -> timedelta: ...
728
    @property
729
    def max_delivery_count(self) -> int: ...
730
    @property
731
    def enable_dead_lettering_on_message_expiration(self) -> bool: ...
732
    @property
733
    def enable_sessions(self) -> bool: ...
734
    @property
735
    def enable_duplicate_detection(self) -> bool: ...
736
    @property
737
    def duplicate_detection_history_time_window(self) -> timedelta: ...
738
    @property
739
    def enable_batched_operations(self) -> bool: ...
740
    @property
741
    def status(self) -> EntityStatus: ...
742
    @property
743
    def enable_partitioning(self) -> bool: ...
744
    @property
745
    def forward_to(self) -> Optional[str]: ...
746
    @property
747
    def forward_dead_lettered_messages_to(self) -> Optional[str]: ...
748
    @property
749
    def auto_delete_on_idle(self) -> timedelta: ...
750
    @property
751
    def authorization_rules(self) -> List[AuthorizationRule]: ...
752
```
753

754
### QueueRuntimeProperties
755

756
Runtime metrics and information for Service Bus queues.
757

758
```python { .api }
759
class QueueRuntimeProperties:
760
    @property
761
    def name(self) -> str: ...
762
    @property
763
    def active_message_count(self) -> int: ...
764
    @property
765
    def dead_letter_message_count(self) -> int: ...
766
    @property
767
    def scheduled_message_count(self) -> int: ...
768
    @property
769
    def transfer_dead_letter_message_count(self) -> int: ...
770
    @property
771
    def transfer_message_count(self) -> int: ...
772
    @property
773
    def size_in_bytes(self) -> int: ...
774
    @property
775
    def created_at_utc(self) -> datetime: ...
776
    @property
777
    def updated_at_utc(self) -> datetime: ...
778
    @property
779
    def accessed_at_utc(self) -> datetime: ...
780
```
781

782
## Asynchronous Administrative Operations
783

784
For asynchronous operations, use the async version from the `azure.servicebus.aio.management` module.
785

786
```python { .api }
787
from azure.servicebus.aio.management import ServiceBusAdministrationClient
788

789
# All methods have async equivalents
790
class ServiceBusAdministrationClient:
791
    async def create_queue(self, queue_name: str, **kwargs) -> QueueProperties: ...
792
    async def get_queue(self, queue_name: str, **kwargs) -> QueueProperties: ...
793
    async def delete_queue(self, queue_name: str, **kwargs) -> None: ...
794
    # ... (all other methods similarly async)
795
```
796

797
#### Usage Example
798

799
```python
800
import asyncio
801
from azure.servicebus.aio.management import ServiceBusAdministrationClient
802

803
async def manage_entities():
804
    admin_client = ServiceBusAdministrationClient.from_connection_string("your_connection_string")
805
    
806
    # Create queue asynchronously
807
    queue = await admin_client.create_queue("async-queue")
808
    print(f"Created queue: {queue.name}")
809
    
810
    # List queues asynchronously
811
    async for queue in admin_client.list_queues():
812
        print(f"Queue: {queue.name}")
813
        
814
        # Get runtime properties
815
        runtime = await admin_client.get_queue_runtime_properties(queue.name)
816
        print(f"  Active messages: {runtime.active_message_count}")
817

818
asyncio.run(manage_entities())
819
```