From ffcd5d3f1d184defde851f587948ae005f0d053f Mon Sep 17 00:00:00 2001 From: Rakshith Bhyravabhotla Date: Tue, 12 Jan 2021 16:25:47 -0800 Subject: [PATCH 1/3] Ux study feedback --- sdk/eventgrid/azure-eventgrid/README.md | 52 +++++++++++++++++-- .../azure/eventgrid/_models.py | 13 +++-- 2 files changed, 57 insertions(+), 8 deletions(-) diff --git a/sdk/eventgrid/azure-eventgrid/README.md b/sdk/eventgrid/azure-eventgrid/README.md index 25f18e85d907..fb833c448d3d 100644 --- a/sdk/eventgrid/azure-eventgrid/README.md +++ b/sdk/eventgrid/azure-eventgrid/README.md @@ -38,26 +38,37 @@ In order to interact with the Event Grid service, you will need to create an ins A **topic_hostname** and **credential** are necessary to instantiate the client object. #### Looking up the endpoint -You can find the endpoint and the hostname on the Azure portal. +You can find the topic endpoint within the Event Grid Topic resource on the Azure portal. +The topic hostname is the URL host component of this endpoint. (Everything up-to and including "eventgrid.azure.net".) #### Create the client with AzureKeyCredential -To use an API key as the `credential` parameter, +To use an Access Key as the `credential` parameter, pass the key as a string into an instance of [AzureKeyCredential][azure-key-credential]. +> **Note:** The Access Key may be found in the azure portal in the "Access Keys" menu of the Event Grid Topic resource. They may also be obtained via the azure CLI, or the `azure-mgmt-eventgrid` library. + ```python from azure.core.credentials import AzureKeyCredential from azure.eventgrid import EventGridPublisherClient topic_hostname = "https://..eventgrid.azure.net" -credential = AzureKeyCredential("") +credential = AzureKeyCredential("") eg_publisher_client = EventGridPublisherClient(topic_hostname, credential) ``` +> **Note:** A client may also be authenticated via SAS signature, using the `EventGridSharedAccessSignatureCredential`. A sample demonstrating this, as well as how to generate that signature utilizing `generate_shared_access_signature` is available [here][python-eg-sample-publish-sas-signature]. + ## Key concepts Information about the key concepts on Event Grid, see [Concepts in Azure Event Grid][publisher-service-doc] +### Topic +A channel within the EventGrid service to send events. Must be of CloudEvent or EventGridEvent schema, (decided at creation time) and the corrosponding event type must be used. + +### Domain Topic +A domain exists to rout arbitrary named topics within it. Topics must not exist beforehand if using a domain, topic name can be provided at send time. Simply provide the domain endpoint at client construction instead of topic endpoint. + ### EventGridPublisherClient `EventGridPublisherClient` provides operations to send event data to topic hostname specified during client initialization. Either a list or a single instance of CloudEvent/EventGridEvent/CustomEvent can be sent. @@ -71,12 +82,14 @@ The following sections provide several code snippets covering some of the most c * [Send an Event Grid Event](#send-an-event-grid-event) * [Send a Cloud Event](#send-a-cloud-event) +* [Send to a Domain](#send-to-a-domain) * [Consume an eventgrid Event](#consume-an-event-grid-event) * [Consume a cloud Event](#consume-a-cloud-event) ### Send an Event Grid Event This example publishes an Event Grid event. +> **Note:** It is important to know if your topic supports Cloud or EventGrid events beforehand, otherwise send() will throw an exception. ```Python import os @@ -97,11 +110,13 @@ credential = AzureKeyCredential(key) client = EventGridPublisherClient(topic_hostname, credential) client.send(event) +# Note: Events may also be sent as a list, e.g: client.send([event]) ``` ### Send a Cloud Event This example publishes a Cloud event. +> **Note:** It is important to know if your topic supports Cloud or EventGrid events beforehand, otherwise send() will throw an exception. ```Python import os @@ -121,6 +136,32 @@ credential = AzureKeyCredential(key) client = EventGridPublisherClient(topic_hostname, credential) client.send(event) +# Note: Events may also be sent as a list, e.g: client.send([event]) +``` + +### Send to a Domain + +This example illustrates sending to a Domain, whereas the earlier samples sent to a Topic. + +The primary difference is that for `EventGridEvents` a topic must be defined in the event being sent, such that it can be routed within the Domain. + +```Python +import os +from azure.core.credentials import AzureKeyCredential +from azure.eventgrid import EventGridPublisherClient, EventGridEvent +key = os.environ["EG_ACCESS_KEY"] +domain_hostname = os.environ["EG_DOMAIN_HOSTNAME"] +event = EventGridEvent( + subject="Door1", + data={"team": "azure-sdk"}, + event_type="Azure.Sdk.Demo", + data_version="2.0", + topic="test" +) +credential = AzureKeyCredential(key) +client = EventGridPublisherClient(domain_hostname, credential) +client.send(event) +# Note: Events may also be sent as a list, e.g: client.send([event]) ``` ### Consume an Event Grid Event @@ -143,7 +184,7 @@ eg_storage_dict = { "dataVersion":"2.0", "metadataVersion":"1", "eventTime":"2020-08-07T02:28:23.867525Z", - "topic":"/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.EventGrid/topics/eventgridegsub" + "topic":"/subscriptions/fake-subscription-id/resourceGroups/fake-resource-group/providers/Microsoft.EventGrid/topics/eventgridegsub" } deserialized_event = consumer.decode_eventgrid_event(eg_storage_dict) @@ -164,7 +205,7 @@ consumer = EventGridConsumer() cloud_storage_dict = { "id":"a0517898-9fa4-4e70-b4a3-afda1dd68672", - "source":"/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Storage/storageAccounts/{storage-account}", + "source":"/subscriptions/fake-subscription-id/resourceGroups/fake-resource-group/providers/Microsoft.Storage/storageAccounts/fake-storage-account", "data":{ "api":"PutBlockList", }, @@ -251,6 +292,7 @@ This project has adopted the [Microsoft Open Source Code of Conduct][code_of_con [python-eg-sample-send-cloudevent]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/eventgrid/azure-eventgrid/samples/champion_scenarios/cs5_publish_events_using_cloud_events_1.0_schema.py [python-eg-sample-consume-cloudevent]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/eventgrid/azure-eventgrid/samples/champion_scenarios/cs6_consume_events_using_cloud_events_1.0_schema.py [publisher-service-doc]: https://docs.microsoft.com/azure/event-grid/concepts +[python-eg-sample-publish-sas-signature]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/eventgrid/azure-eventgrid/samples/publish_samples/publish_with_shared_access_signature_sample.py [cla]: https://cla.microsoft.com [code_of_conduct]: https://opensource.microsoft.com/codeofconduct/ diff --git a/sdk/eventgrid/azure-eventgrid/azure/eventgrid/_models.py b/sdk/eventgrid/azure-eventgrid/azure/eventgrid/_models.py index dca194c37dfe..d80938113d3d 100644 --- a/sdk/eventgrid/azure-eventgrid/azure/eventgrid/_models.py +++ b/sdk/eventgrid/azure-eventgrid/azure/eventgrid/_models.py @@ -49,11 +49,13 @@ def _from_json(event, encode): class CloudEvent(EventMixin): #pylint:disable=too-many-instance-attributes """Properties of an event published to an Event Grid topic using the CloudEvent 1.0 Schema. + Note: CloudEvents can only be sent to a topic of CloudEvent schema. + For EventGrid schema, use EventGridEvent. All required parameters must be populated in order to send to Azure. :param source: Required. Identifies the context in which an event happened. The combination of id and source must - be unique for each distinct event. If publishing to a domain topic, source must be the domain name. + be unique for each distinct event, and otherwise can be any user-defined string. If publishing to a domain topic, source must be the domain name. :type source: str :param data: Event data specific to the event type. :type data: object @@ -131,19 +133,24 @@ def _to_generated(self, **kwargs): class EventGridEvent(InternalEventGridEvent, EventMixin): """Properties of an event published to an Event Grid topic using the EventGrid Schema. + Note: EventGridEvents can only be sent to a topic of EventGridEvent schema. + For CloudEvent schema, use CloudEvent. Variables are only populated by the server, and will be ignored when sending a request. All required parameters must be populated in order to send to Azure. :param topic: The resource path of the event source. If not provided, Event Grid will stamp onto the event. + Is required for Domain topics, and a domain topic may be specified which doesn't yet exist. :type topic: str - :param subject: Required. A resource path relative to the topic path. + :param subject: Required. A resource path relative to the topic path. Can be any user-defined string. :type subject: str :param data: Event data specific to the event type. :type data: object - :param event_type: Required. The type of the event that occurred. + :param event_type: Required. The type of the event that occurred. Can be any user-defined string. :type event_type: str + :param data_version: Required. The schema version of the data object. Can be any user-defined string. + :type data_version: str :ivar metadata_version: The schema version of the event metadata. If provided, must match Event Grid Schema exactly. If not provided, EventGrid will stamp onto event. :vartype metadata_version: str From a04eebf1d8dac26f5c34a95af1bad6a480852300 Mon Sep 17 00:00:00 2001 From: Rakshith Bhyravabhotla Date: Tue, 12 Jan 2021 19:02:28 -0800 Subject: [PATCH 2/3] Update sdk/eventgrid/azure-eventgrid/azure/eventgrid/_models.py --- sdk/eventgrid/azure-eventgrid/azure/eventgrid/_models.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/sdk/eventgrid/azure-eventgrid/azure/eventgrid/_models.py b/sdk/eventgrid/azure-eventgrid/azure/eventgrid/_models.py index d80938113d3d..0f20f4edff1a 100644 --- a/sdk/eventgrid/azure-eventgrid/azure/eventgrid/_models.py +++ b/sdk/eventgrid/azure-eventgrid/azure/eventgrid/_models.py @@ -55,7 +55,8 @@ class CloudEvent(EventMixin): #pylint:disable=too-many-instance-attributes All required parameters must be populated in order to send to Azure. :param source: Required. Identifies the context in which an event happened. The combination of id and source must - be unique for each distinct event, and otherwise can be any user-defined string. If publishing to a domain topic, source must be the domain name. + be unique for each distinct event, and otherwise can be any user-defined string. +If publishing to a domain topic, source must be the domain name. :type source: str :param data: Event data specific to the event type. :type data: object From c01bdc6cda517fdf47557cca6abc35b34a0308c7 Mon Sep 17 00:00:00 2001 From: Rakshith Bhyravabhotla Date: Thu, 14 Jan 2021 11:03:12 -0800 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: swathipil <76007337+swathipil@users.noreply.github.com> --- sdk/eventgrid/azure-eventgrid/README.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/sdk/eventgrid/azure-eventgrid/README.md b/sdk/eventgrid/azure-eventgrid/README.md index fb833c448d3d..929fc9416c69 100644 --- a/sdk/eventgrid/azure-eventgrid/README.md +++ b/sdk/eventgrid/azure-eventgrid/README.md @@ -38,15 +38,17 @@ In order to interact with the Event Grid service, you will need to create an ins A **topic_hostname** and **credential** are necessary to instantiate the client object. #### Looking up the endpoint -You can find the topic endpoint within the Event Grid Topic resource on the Azure portal. -The topic hostname is the URL host component of this endpoint. (Everything up-to and including "eventgrid.azure.net".) +You can find the topic endpoint within the Event Grid Topic resource on the Azure portal. This will look like: +`"https://..eventgrid.azure.net/api/events"` +The topic hostname is the URL host component of this endpoint, which will be in the format: +`"https://..eventgrid.azure.net"` #### Create the client with AzureKeyCredential To use an Access Key as the `credential` parameter, pass the key as a string into an instance of [AzureKeyCredential][azure-key-credential]. -> **Note:** The Access Key may be found in the azure portal in the "Access Keys" menu of the Event Grid Topic resource. They may also be obtained via the azure CLI, or the `azure-mgmt-eventgrid` library. +> **Note:** The Access Key may be found in the azure portal in the "Access Keys" menu of the Event Grid Topic resource. They may also be obtained via the azure CLI, or the `azure-mgmt-eventgrid` library. A guide for getting access keys can be found [here](https://docs.microsoft.com/azure/event-grid/get-access-keys). ```python from azure.core.credentials import AzureKeyCredential @@ -64,7 +66,7 @@ eg_publisher_client = EventGridPublisherClient(topic_hostname, credential) Information about the key concepts on Event Grid, see [Concepts in Azure Event Grid][publisher-service-doc] ### Topic -A channel within the EventGrid service to send events. Must be of CloudEvent or EventGridEvent schema, (decided at creation time) and the corrosponding event type must be used. +A channel within the EventGrid service to send events. Must be of [CloudEvent](https://docs.microsoft.com/azure/event-grid/cloud-event-schema) or [EventGridEvent](https://docs.microsoft.com/azure/event-grid/event-schema) schema, (decided at creation time) and the corresponding event type must be used. ### Domain Topic A domain exists to rout arbitrary named topics within it. Topics must not exist beforehand if using a domain, topic name can be provided at send time. Simply provide the domain endpoint at client construction instead of topic endpoint.