0
# Azure Event Grid
1
2
Microsoft Azure Event Grid Client Library for Python provides comprehensive support for both Event Grid Basic (legacy) and Event Grid Namespaces. This library enables event-driven applications to publish events to Event Grid topics and consume events from Event Grid Namespace subscriptions using reliable, scalable event routing and processing capabilities.
3
4
## Package Information
5
6
- **Package Name**: azure-eventgrid
7
- **Language**: Python
8
- **Installation**: `pip install azure-eventgrid`
9
10
## Core Imports
11
12
```python
13
from azure.eventgrid import EventGridPublisherClient, EventGridConsumerClient
14
```
15
16
For async operations:
17
18
```python
19
from azure.eventgrid.aio import EventGridPublisherClient, EventGridConsumerClient
20
```
21
22
For legacy Event Grid Basic support:
23
24
```python
25
from azure.eventgrid import EventGridEvent, SystemEventNames, generate_sas
26
```
27
28
For models and data types:
29
30
```python
31
from azure.eventgrid.models import (
32
AcknowledgeResult, ReleaseResult, RejectResult, RenewLocksResult,
33
ReceiveDetails, BrokerProperties, ReleaseDelay
34
)
35
```
36
37
## Basic Usage
38
39
### Event Grid Namespaces (Modern)
40
41
```python
42
from azure.eventgrid import EventGridPublisherClient, EventGridConsumerClient
43
from azure.core.credentials import AzureKeyCredential
44
from azure.core.messaging import CloudEvent
45
46
# Publisher client for sending events
47
publisher = EventGridPublisherClient(
48
endpoint="https://namespace.region.eventgrid.azure.net",
49
credential=AzureKeyCredential("access_key"),
50
namespace_topic="my-topic"
51
)
52
53
# Create and send events
54
cloud_event = CloudEvent(
55
source="myapp/products",
56
type="Product.Created",
57
data={
58
"product_id": "12345",
59
"name": "New Product",
60
"price": 29.99
61
}
62
)
63
64
publisher.send([cloud_event])
65
publisher.close()
66
67
# Consumer client for receiving events
68
consumer = EventGridConsumerClient(
69
endpoint="https://namespace.region.eventgrid.azure.net",
70
credential=AzureKeyCredential("access_key"),
71
namespace_topic="my-topic",
72
subscription="my-subscription"
73
)
74
75
# Receive and process events
76
events = consumer.receive(max_events=10, max_wait_time=60)
77
for event_detail in events:
78
print(f"Event: {event_detail.event.type}")
79
print(f"Data: {event_detail.event.data}")
80
81
# Process the event, then acknowledge
82
# consumer.acknowledge(lock_tokens=[event_detail.broker_properties.lock_token])
83
84
consumer.close()
85
```
86
87
### Event Grid Basic (Legacy)
88
89
```python
90
from azure.eventgrid import EventGridPublisherClient, EventGridEvent
91
from azure.core.credentials import AzureKeyCredential
92
93
# Publisher client for Event Grid Basic
94
publisher = EventGridPublisherClient(
95
endpoint="https://my-topic.region.eventgrid.azure.net/api/events",
96
credential=AzureKeyCredential("access_key")
97
# No namespace_topic specified for Basic
98
)
99
100
# Create EventGrid schema event
101
event = EventGridEvent(
102
subject="products/product-123",
103
event_type="Product.Created",
104
data={
105
"product_id": "123",
106
"name": "Example Product"
107
},
108
data_version="1.0"
109
)
110
111
publisher.send([event])
112
publisher.close()
113
```
114
115
## Architecture
116
117
Azure Event Grid supports two distinct models:
118
119
- **Event Grid Basic**: Traditional domain/topic model with push delivery to webhooks, Event Hubs, Service Bus, and other endpoints
120
- **Event Grid Namespaces**: Modern pull-based model with MQTT support, dead lettering, and advanced message handling
121
122
The Python SDK provides unified client APIs for both models:
123
124
- **EventGridPublisherClient**: Publishes events to both Basic topics/domains and Namespace topics
125
- **EventGridConsumerClient**: Consumes events from Namespace subscriptions with pull delivery
126
- **Async Support**: Full async/await support for both publisher and consumer operations
127
- **Legacy Components**: Backward compatibility for existing Event Grid Basic applications
128
129
## Capabilities
130
131
### Event Publishing
132
133
Send events to Event Grid Basic topics/domains or Event Grid Namespace topics. Supports CloudEvent schema (namespaces), EventGrid schema (basic), and raw dictionaries with automatic content type detection.
134
135
```python { .api }
136
def send(
137
events: Union[CloudEvent, EventGridEvent, dict, List[Union[CloudEvent, EventGridEvent, dict]]],
138
*,
139
channel_name: Optional[str] = None,
140
content_type: Optional[str] = None,
141
**kwargs
142
) -> None: ...
143
```
144
145
[Event Publishing](./publisher.md)
146
147
### Event Consumption
148
149
Receive and manage events from Event Grid Namespace subscriptions with operations for acknowledging, releasing, rejecting, and renewing locks on events.
150
151
```python { .api }
152
def receive(
153
*,
154
max_events: Optional[int] = None,
155
max_wait_time: Optional[int] = None,
156
**kwargs
157
) -> List[ReceiveDetails]: ...
158
159
def acknowledge(*, lock_tokens: List[str], **kwargs) -> AcknowledgeResult: ...
160
def release(*, lock_tokens: List[str], release_delay: Optional[Union[int, ReleaseDelay]] = None, **kwargs) -> ReleaseResult: ...
161
def reject(*, lock_tokens: List[str], **kwargs) -> RejectResult: ...
162
def renew_locks(*, lock_tokens: List[str], **kwargs) -> RenewLocksResult: ...
163
```
164
165
[Event Consumption](./consumer.md)
166
167
### Async Operations
168
169
Asynchronous versions of all publisher and consumer operations for non-blocking event processing and high-throughput scenarios.
170
171
```python { .api }
172
async def send(
173
events: Union[CloudEvent, EventGridEvent, dict, List[Union[CloudEvent, EventGridEvent, dict]]],
174
*,
175
channel_name: Optional[str] = None,
176
content_type: Optional[str] = None,
177
**kwargs
178
) -> None: ...
179
180
async def receive(
181
*,
182
max_events: Optional[int] = None,
183
max_wait_time: Optional[int] = None,
184
**kwargs
185
) -> List[ReceiveDetails]: ...
186
```
187
188
[Async Operations](./async-operations.md)
189
190
### Models and Data Types
191
192
Response models, event metadata, broker properties, and enums for comprehensive event handling and status reporting.
193
194
```python { .api }
195
class ReceiveDetails:
196
broker_properties: BrokerProperties
197
event: CloudEvent
198
199
class BrokerProperties:
200
lock_token: str
201
delivery_count: int
202
203
class AcknowledgeResult:
204
failed_lock_tokens: List[FailedLockToken]
205
succeeded_lock_tokens: List[str]
206
```
207
208
[Models and Data Types](./models.md)
209
210
### Legacy Support
211
212
Event Grid Basic support with EventGrid schema events, system event names, and SAS token generation for backward compatibility.
213
214
```python { .api }
215
class EventGridEvent:
216
def __init__(
217
self,
218
subject: str,
219
event_type: str,
220
data: Any,
221
data_version: str,
222
*,
223
topic: Optional[str] = None,
224
metadata_version: Optional[str] = None,
225
id: Optional[str] = None,
226
event_time: Optional[datetime] = None
227
) -> None: ...
228
229
def generate_sas(
230
endpoint: str,
231
shared_access_key: str,
232
expiration_date_utc: datetime,
233
*,
234
api_version: Optional[str] = None
235
) -> str: ...
236
```
237
238
[Legacy Support](./legacy.md)
239
240
## Types
241
242
```python { .api }
243
from typing import List, Optional, Union, Any
244
from datetime import datetime
245
from azure.core.credentials import AzureKeyCredential, AzureSasCredential, TokenCredential
246
from azure.core.credentials_async import AsyncTokenCredential
247
from azure.core.messaging import CloudEvent
248
from azure.core.rest import HttpRequest, HttpResponse
249
250
# Authentication types
251
Credential = Union[AzureKeyCredential, AzureSasCredential, TokenCredential]
252
AsyncCredential = Union[AzureKeyCredential, AsyncTokenCredential]
253
254
# Event types for publishing
255
EventType = Union[CloudEvent, EventGridEvent, dict]
256
EventList = List[EventType]
257
SendableEvents = Union[EventType, EventList]
258
```