Skip to content

Commit

Permalink
[EventGrid] Improve docs (#16986)
Browse files Browse the repository at this point in the history
* intital

* read me improvements

* migration guide

* blundera

* nit

* Apply suggestions from code review

Co-authored-by: swathipil <[email protected]>

Co-authored-by: swathipil <[email protected]>
  • Loading branch information
Rakshith Bhyravabhotla and swathipil authored Mar 1, 2021
1 parent adfce6b commit 36f2003
Show file tree
Hide file tree
Showing 8 changed files with 219 additions and 19 deletions.
201 changes: 188 additions & 13 deletions sdk/eventgrid/azure-eventgrid/README.md

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion sdk/eventgrid/azure-eventgrid/azure/eventgrid/_models.py
Original file line number Diff line number Diff line change
Expand Up @@ -173,7 +173,7 @@ class EventGridEvent(InternalEventGridEvent, EventMixin):
If not provided, will be stamped with an empty value.
:type data_version: str
:keyword topic: Optional. The resource path of the event source. If not provided, Event Grid will
stamp onto the event.
stamp onto the event. This is required when sending event(s) to a domain.
:type topic: str
:keyword metadata_version: Optional. The schema version of the event metadata. If provided,
must match Event Grid Schema exactly. If not provided, EventGrid will stamp onto event.
Expand Down
25 changes: 24 additions & 1 deletion sdk/eventgrid/azure-eventgrid/migration_guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ The modern Event Grid client library also provides the ability to share in some
The v2.x major version comes with support for [CloudEvents](https://github.com/cloudevents/spec). Now the cloud native Cloud Events can be directly published using the `CloudEvent` constructor or as a dictionary as follows:

```Python
from azure.eventgrid import CloudEvent
from azure.core.messaging import CloudEvent

cloud_event = CloudEvent(
type="Contoso.Items.ItemReceived",
Expand Down Expand Up @@ -73,6 +73,29 @@ The `publish_events` API is replaced with `send` in v2.0. Additionally, `send` A
|---|---|---|
|`EventGridClient(credentials).publish_events(topic_hostname, events)`|`EventGridPublisherClient(endpoint, credential).send(events)`|[Sample for client construction](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/eventgrid/azure-eventgrid/samples/sync_samples/sample_publish_events_using_cloud_events_1.0_schema.py)|

### Consuming Events

The v2.x major version supports deserializing dictionaries into strongly typed objects. The `from_dict` methods in the `CloudEvent` and `EventGridEvent` models can be used for the same.

This example consumes a payload message received from ServiceBus and deserializes it to an EventGridEvent object.

```Python
from azure.eventgrid import EventGridEvent
from azure.servicebus import ServiceBusClient
import os
import json

# all types of EventGridEvents below produce same DeserializedEvent
connection_str = os.environ['SERVICE_BUS_CONN_STR']
queue_name = os.environ['SERVICE_BUS_QUEUE_NAME']

with ServiceBusClient.from_connection_string(connection_str) as sb_client:
payload = sb_client.get_queue_receiver(queue_name).receive_messages()

## deserialize payload into a list of typed Events
events = [EventGridEvent.from_dict(json.loads(next(msg.body).decode('utf-8'))) for msg in payload]
```

## Additional samples

More examples can be found at [here](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/eventgrid/azure-eventgrid/samples)
2 changes: 2 additions & 0 deletions sdk/eventgrid/azure-eventgrid/samples/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,4 +71,6 @@ To publish events, dict representation of the models could also be used as follo
[python-eg-publish-samples]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/eventgrid/azure-eventgrid/samples/publish_samples
[python-eg-consume-samples]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/eventgrid/azure-eventgrid/samples/consume_samples

[python-eg-sample-consume-custom-payload]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/eventgrid/azure-eventgrid/samples/sync_samples/sample_consume_custom_payload.py

[publisher-service-doc]: https://docs.microsoft.com/azure/event-grid/concepts
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ async def publish():

# [START publish_cloud_event_dict_async]
async with client:
client.send([
await client.send([
{
"type": "Contoso.Items.ItemReceived",
"source": "/contoso/items",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ async def publish():
credential = AzureKeyCredential(topic_key)
client = EventGridPublisherClient(endpoint, credential)

client.send([
await client.send([
CloudEvent(
type="Contoso.Items.ItemReceived",
source="/contoso/items",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@
message_decode_policy=BinaryBase64DecodePolicy()
).peek_messages()

## deserialize payload into a lost of typed Events
## deserialize payload into a list of typed Events
events = [CloudEvent.from_dict(json.loads(msg.content)) for msg in payload]

for event in events:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@
with ServiceBusClient.from_connection_string(connection_str) as sb_client:
payload = sb_client.get_queue_receiver(queue_name).receive_messages()

## deserialize payload into a lost of typed Events
## deserialize payload into a list of typed Events
events = [EventGridEvent.from_dict(json.loads(next(msg.body).decode('utf-8'))) for msg in payload]

for event in events:
Expand Down

0 comments on commit 36f2003

Please sign in to comment.