0
# Event Hub Consumer Groups
1

2
Management of Event Hub consumer groups for IoT Hub's built-in Event Hub endpoints, enabling multiple applications to independently read device-to-cloud messages with separate offsets and processing states for distributed telemetry processing architectures.
3

4
## Capabilities
5

6
### List Consumer Groups
7

8
Retrieve all consumer groups configured for a specific Event Hub endpoint to understand the current processing topology and identify available consumer group names.
9

10
```python { .api }
11
def list_event_hub_consumer_groups(
12
    resource_group_name: str, 
13
    resource_name: str, 
14
    event_hub_endpoint_name: str, 
15
    **kwargs
16
) -> ItemPaged[EventHubConsumerGroupInfo]:
17
    """
18
    Get list of all consumer groups for the Event Hub-compatible endpoint.
19
    
20
    Args:
21
        resource_group_name: Name of the resource group
22
        resource_name: Name of the IoT hub resource
23
        event_hub_endpoint_name: Name of the Event Hub endpoint (e.g., "events")
24
        
25
    Returns:
26
        ItemPaged[EventHubConsumerGroupInfo]: Paginated list of consumer groups with metadata
27
    """
28
```
29

30
### Get Consumer Group Details
31

32
Retrieve detailed information about a specific consumer group including its configuration and metadata for monitoring and validation purposes.
33

34
```python { .api }
35
def get_event_hub_consumer_group(
36
    resource_group_name: str, 
37
    resource_name: str, 
38
    event_hub_endpoint_name: str, 
39
    name: str, 
40
    **kwargs
41
) -> EventHubConsumerGroupInfo:
42
    """
43
    Get details of a specific consumer group for Event Hub endpoint.
44
    
45
    Args:
46
        resource_group_name: Name of the resource group
47
        resource_name: Name of the IoT hub resource
48
        event_hub_endpoint_name: Name of the Event Hub endpoint (e.g., "events")
49
        name: Name of the consumer group
50
        
51
    Returns:
52
        EventHubConsumerGroupInfo: Consumer group details and metadata
53
    """
54
```
55

56
### Create Consumer Group
57

58
Create a new consumer group for independent processing of device-to-cloud messages, enabling parallel processing by multiple applications or services.
59

60
```python { .api }
61
def create_event_hub_consumer_group(
62
    resource_group_name: str, 
63
    resource_name: str, 
64
    event_hub_endpoint_name: str, 
65
    name: str, 
66
    consumer_group_body: EventHubConsumerGroupBodyDescription, 
67
    **kwargs
68
) -> EventHubConsumerGroupInfo:
69
    """
70
    Create a new consumer group for the Event Hub-compatible endpoint.
71
    
72
    Args:
73
        resource_group_name: Name of the resource group
74
        resource_name: Name of the IoT hub resource
75
        event_hub_endpoint_name: Name of the Event Hub endpoint (e.g., "events")
76
        name: Name for the new consumer group
77
        consumer_group_body: Consumer group configuration and properties
78
        
79
    Returns:
80
        EventHubConsumerGroupInfo: Details of the created consumer group
81
    """
82
```
83

84
### Delete Consumer Group
85

86
Remove a consumer group when it's no longer needed, ensuring proper cleanup of Event Hub endpoint resources and consumer group allocations.
87

88
```python { .api }
89
def delete_event_hub_consumer_group(
90
    resource_group_name: str, 
91
    resource_name: str, 
92
    event_hub_endpoint_name: str, 
93
    name: str, 
94
    **kwargs
95
) -> None:
96
    """
97
    Delete a consumer group from the Event Hub-compatible endpoint.
98
    
99
    Args:
100
        resource_group_name: Name of the resource group
101
        resource_name: Name of the IoT hub resource
102
        event_hub_endpoint_name: Name of the Event Hub endpoint (e.g., "events")
103
        name: Name of the consumer group to delete
104
        
105
    Returns:
106
        None: Operation completed successfully
107
    """
108
```
109

110
## Usage Examples
111

112
### Creating and managing consumer groups for telemetry processing
113

114
```python
115
from azure.identity import DefaultAzureCredential
116
from azure.mgmt.iothub import IotHubClient
117
from azure.mgmt.iothub.models import EventHubConsumerGroupBodyDescription
118

119
# Initialize client
120
credential = DefaultAzureCredential()
121
client = IotHubClient(credential, "subscription-id")
122

123
resource_group = "myResourceGroup"
124
hub_name = "myIoTHub"
125
events_endpoint = "events"  # Built-in Event Hub endpoint
126

127
# List existing consumer groups
128
print("Existing consumer groups:")
129
for group in client.iot_hub_resource.list_event_hub_consumer_groups(
130
    resource_group, hub_name, events_endpoint
131
):
132
    print(f"  - {group.name}")
133

134
# Create a new consumer group for analytics processing
135
analytics_group_config = EventHubConsumerGroupBodyDescription(
136
    properties={"name": "analytics-processor"}
137
)
138

139
analytics_group = client.iot_hub_resource.create_event_hub_consumer_group(
140
    resource_group, 
141
    hub_name, 
142
    events_endpoint,
143
    "analytics-processor",
144
    analytics_group_config
145
)
146
print(f"Created consumer group: {analytics_group.name}")
147

148
# Create consumer group for real-time alerts
149
alerts_group_config = EventHubConsumerGroupBodyDescription(
150
    properties={"name": "alerts-processor"}
151
)
152

153
alerts_group = client.iot_hub_resource.create_event_hub_consumer_group(
154
    resource_group, 
155
    hub_name, 
156
    events_endpoint,
157
    "alerts-processor", 
158
    alerts_group_config
159
)
160
print(f"Created consumer group: {alerts_group.name}")
161
```
162

163
### Monitoring and cleanup of consumer groups
164

165
```python
166
# Get details of a specific consumer group
167
try:
168
    group_details = client.iot_hub_resource.get_event_hub_consumer_group(
169
        resource_group, hub_name, events_endpoint, "analytics-processor"
170
    )
171
    print(f"Consumer group '{group_details.name}' exists")
172
    print(f"  Resource type: {group_details.type}")
173
    print(f"  ETag: {group_details.etag}")
174
except Exception as e:
175
    print(f"Consumer group not found: {e}")
176

177
# Clean up unused consumer groups
178
unused_groups = ["old-processor", "test-consumer"]
179
for group_name in unused_groups:
180
    try:
181
        client.iot_hub_resource.delete_event_hub_consumer_group(
182
            resource_group, hub_name, events_endpoint, group_name
183
        )
184
        print(f"Deleted consumer group: {group_name}")
185
    except Exception as e:
186
        print(f"Failed to delete {group_name}: {e}")
187

188
# Verify final consumer group list
189
print("\nRemaining consumer groups:")
190
for group in client.iot_hub_resource.list_event_hub_consumer_groups(
191
    resource_group, hub_name, events_endpoint
192
):
193
    print(f"  - {group.name}")
194
```
195

196
### Setting up distributed processing architecture
197

198
```python
199
# Create consumer groups for different processing functions
200
processing_groups = [
201
    ("telemetry-storage", "Long-term telemetry storage processor"),
202
    ("real-time-dashboard", "Real-time dashboard data processor"), 
203
    ("anomaly-detection", "ML-based anomaly detection processor"),
204
    ("device-health", "Device health monitoring processor")
205
]
206

207
created_groups = []
208
for group_name, description in processing_groups:
209
    try:
210
        group_config = EventHubConsumerGroupBodyDescription(
211
            properties={"name": group_name}
212
        )
213
        
214
        group = client.iot_hub_resource.create_event_hub_consumer_group(
215
            resource_group, hub_name, events_endpoint, group_name, group_config
216
        )
217
        created_groups.append(group_name)
218
        print(f"✓ Created consumer group: {group_name}")
219
    except Exception as e:
220
        print(f"✗ Failed to create {group_name}: {e}")
221

222
print(f"\nSuccessfully created {len(created_groups)} consumer groups")
223
print("Each group can now independently process device messages with separate offsets")
224
```
225

226
## Types
227

228
### EventHubConsumerGroupInfo
229
Primary model representing a consumer group configuration and metadata.
230

231
```python
232
class EventHubConsumerGroupInfo:
233
    """Consumer group information for Event Hub endpoints."""
234
    name: str                    # Consumer group name
235
    type: str                    # Resource type identifier
236
    etag: str                    # ETag for concurrency control
237
    properties: Dict[str, Any]   # Consumer group properties and metadata
238
```
239

240
### EventHubConsumerGroupBodyDescription  
241
Configuration model for creating new consumer groups with specified properties and settings.
242

243
```python
244
class EventHubConsumerGroupBodyDescription:
245
    """Consumer group creation configuration."""
246
    properties: Dict[str, Any]   # Consumer group properties to set during creation
247
```