Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Ux study feedback #16124

Closed
wants to merge 3 commits into from
Closed

Ux study feedback #16124

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ffcd5d3
Ux study feedback
rakshith91 Jan 13, 2021
a04eebf
Update sdk/eventgrid/azure-eventgrid/azure/eventgrid/_models.py
Jan 13, 2021
c01bdc6
Apply suggestions from code review
Jan 14, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 49 additions & 5 deletions sdk/eventgrid/azure-eventgrid/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,26 +38,39 @@ 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. This will look like:
`"https://<event-grid-topic-name>.<topic-location>.eventgrid.azure.net/api/events"`
The topic hostname is the URL host component of this endpoint, which will be in the format:
`"https://<event-grid-topic-name>.<topic-location>.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. 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
from azure.eventgrid import EventGridPublisherClient

topic_hostname = "https://<name>.<region>.eventgrid.azure.net"
credential = AzureKeyCredential("<api_key>")
credential = AzureKeyCredential("<access_key>")
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](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.
Copy link
Contributor

@yunhaoling yunhaoling Jan 15, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

add a bit clarity on the second half, feel free to tweak my words.

Suggested change
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.
A channel within the EventGrid service to send events. Event 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 which is decided at creation time. In the case of wrong event type being used, errors will be raised.


### 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A little unclear on what is meant by Topics must not exist beforehand if using a domain, topic name can be provided at send time.? I tried creating a domain and publishing to the domain endpoint with the topic name specified, but the topic did not exist beforehand. It was published and reached the endpoint, but the event was not delivered to that topic. I had to manually name and create the domain topic in the portal (or management plane sdk) under the domain, and published again before it was delivered there.

Might be worthwhile to make it more clear how a domain topic works in comparison to other topics + to include things from this doc (https://docs.microsoft.com/en-us/azure/event-grid/event-domains) including the following:

  1. More info on what a domain is: "An event domain is a management tool for large numbers of Event Grid topics related to the same application. You can think of it as a meta-topic that can have thousands of individual topics." The way it's phrased now doesn't really show why domains are used, how the individual topics are related, etc.
  2. Publishing to a domain: "When you create an event domain, you're given a publishing endpoint similar to if you had created a topic in Event Grid...
    To publish events to any topic in an Event Domain, push the events to the domain's endpoint the same way you would for a custom topic. The only difference is that you must specify the topic you'd like the event to be delivered to."

Links + typo + something like this?

Suggested change
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.
A domain is a management tool that exists to route events to individual domain topics within it which are related to the same application. Publishing to a domain topic is similar to publishing to a custom topic. There are two key differences:
1. At client construction, the domain endpoint must be provided instead of topic endpoint.
2. The individual domain topic name must be specified in the event at send time. To be delivered to the domain topic provided, the domain topic must already exist in the domain.
More information about Event Domains can be found [here](https://docs.microsoft.com/en-us/azure/event-grid/event-domains).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

as @swathipil mentioned, echoing words from the service doc is good.

also I'm feeling that as it is the Key concepts section, Domain topic could just describe the service concepts and we leave the details of client constructor ("only domain endpoint at client construction for domain topic..." etc.) could be placed under the EventGridPublisherClient section.


### 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.
Expand All @@ -71,12 +84,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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Small, potential change, for clarity. Something like:

Suggested change
> **Note:** It is important to know if your topic supports Cloud or EventGrid events beforehand, otherwise send() will throw an exception.
> **Note:** It is important to know if your topic supports Cloud or EventGrid events before publishing. If you send to a topic that does not support the schema of the event you are sending, send() will throw an exception.


```Python
import os
Expand All @@ -97,11 +112,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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same as 92


```Python
import os
Expand All @@ -121,6 +138,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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This may add a little more clarity?

Suggested change
This example illustrates sending to a Domain, whereas the earlier samples sent to a Topic.
This example illustrates sending to a Domain Topic, whereas the earlier samples sent to a custom Topic.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why custom?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought it would be more consistent with the way we name the samples. For example, here or here. It may also make more sense to rename these samples to ...events_to_topic instead of events_to_custom_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
Expand All @@ -143,7 +186,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"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a reason for changing subscription-id and resource-group to fake-subscription-id and fake-resource-group? Same thing in line 208.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it's more clear according to some users in the ux study

}

deserialized_event = consumer.decode_eventgrid_event(eg_storage_dict)
Expand All @@ -164,7 +207,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",
},
Expand Down Expand Up @@ -251,6 +294,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/
Expand Down
14 changes: 11 additions & 3 deletions sdk/eventgrid/azure-eventgrid/azure/eventgrid/_models.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,11 +49,14 @@ 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.
Comment on lines +58 to +59
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

indentation

Suggested change
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
Expand Down Expand Up @@ -131,19 +134,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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

so if I send the event to a domain topic which doesn't exist yet, the EventGrid would create a new domain topic for me?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also, it seems over indented, not sure it would cause rendering issue

Suggested change
Is required for Domain topics, and a domain topic may be specified which doesn't yet exist.
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
Expand Down