[EventGrid] Improve docs (Azure#16986)

* 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]>

Author: Rakshith Bhyravabhotla

sdk/eventgrid/azure-eventgrid/README.md

@@ -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.

sdk/eventgrid/azure-eventgrid/azure/eventgrid/_models.py

@@ -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",
@@ -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)

sdk/eventgrid/azure-eventgrid/migration_guide.md

@@ -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

sdk/eventgrid/azure-eventgrid/samples/README.md

@@ -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",	

sdk/eventgrid/azure-eventgrid/samples/async_samples/sample_publish_cloud_event_using_dict_async.py

@@ -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",

sdk/eventgrid/azure-eventgrid/samples/async_samples/sample_publish_events_using_cloud_events_1.0_schema_async.py

@@ -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:

sdk/eventgrid/azure-eventgrid/samples/consume_samples/consume_cloud_events_from_storage_queue.py

@@ -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: