{"id":496,"date":"2020-09-15T10:00:03","date_gmt":"2020-09-15T17:00:03","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/azure-sdk\/?p=496"},"modified":"2020-09-15T15:18:52","modified_gmt":"2020-09-15T22:18:52","slug":"event-grid-client-libraries","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/azure-sdk\/event-grid-client-libraries\/","title":{"rendered":"Introducing the new Azure Event Grid Client Libraries with CloudEvents v1.0 Support"},"content":{"rendered":"

For those looking to build applications with event-based architectures, Azure Event Grid<\/a> is a cloud-based service that provides reliable event delivery at a massive scale, insulating users from infrastructure concerns. The service fully manages all routing of events from any source, to any destination, for any application. Azure service events and custom events can be published directly to the service, where the events can then be filtered and sent to various recipients, such as built-in handlers or custom webhooks. These features help vastly improve serverless, ops automation, and integration work (for more information, read What can I do with Event Grid?<\/a>). Included below is an image that demonstrates how Event Grid connects to various event sources and handlers.<\/p>\n

\"Event<\/p>\n

We are excited to announce the release of the new Azure Event Grid client library’s first beta for .NET<\/a>, Java<\/a>, JavaScript<\/a>, and Python<\/a>! Check out the links to learn more about how to install the package for each language.<\/p>\n

The new client libraries simplify the process of authenticating and publishing messages. You can use the new Azure Event Grid client library to publish events to the Event Grid service in various event schemas (EventGrid, CloudEvents v1.0, or a custom schema) and to consume events that have been delivered to event handlers. This post will explore both event publishing and event consuming in more detail. Another notable difference from the previous Event Grid client library is the ability to specify a custom ObjectSerializer<\/a> to use when serializing event data to\/from JSON (by default, using JsonObjectSerializer<\/a>).<\/p>\n

Read on to learn more about the CloudEvents v1.0 schema<\/a>, and how you can now use Event Grid to work with CloudEvents!<\/p>\n

What is CloudEvents?<\/h2>\n

CloudEvents<\/a> is a collaborative effort between numerous companies and individuals in the industry (Microsoft included) to produce a vendor-neutral specification for “describing event data in a common way”. Simply stated, the CloudEvents spec<\/a> defines a set of common metadata attributes<\/em> that describe the event being transferred (such as a unique identifier or the time of the event occurrence). The self-described goal of CloudEvents is \u201cto define interoperability of event systems that allow services to produce or consume events, where the producer and consumer can be developed and deployed independently\u201d. The common event format thus allows for easy integration of work across platforms and services and can help standardize how events are consumed.<\/p>\n

The new Event Grid client libraries support the JSON format for CloudEvents, meaning that JSON-serialized events of the CloudEvents schema that are sent and received by the service must adhere to the given specification<\/a>.<\/p>\n

Below is an example of an Azure Blob Storage event in CloudEvents format:<\/p>\n

{\n    \"specversion\": \"1.0\",\n    \"type\": \"Microsoft.Storage.BlobCreated\",  \n    \"source\": \"\/subscriptions\/{subscription-id}\/resourceGroups\/{resource-group}\/providers\/Microsoft.Storage\/storageAccounts\/{storage-account}\",\n    \"id\": \"9aeb0fdf-c01e-0131-0922-9eb54906e209\",\n    \"time\": \"2019-11-18T15:13:39.4589254Z\",\n    \"subject\": \"blobServices\/default\/containers\/{storage-container}\/blobs\/{new-file}\",\n    \"dataschema\": \"#\",\n    \"data\": {\n        \"api\": \"PutBlockList\",\n        \"clientRequestId\": \"4c5dd7fb-2c48-4a27-bb30-5361b5de920a\",\n        \"requestId\": \"9aeb0fdf-c01e-0131-0922-9eb549000000\",\n        \"eTag\": \"0x8D76C39E4407333\",\n        \"contentType\": \"image\/png\",\n        \"contentLength\": 30699,\n        \"blobType\": \"BlockBlob\",\n        \"url\": \"https:\/\/gridtesting.blob.core.windows.net\/testcontainer\/{new-file}\",\n        \"sequencer\": \"000000000000000000000000000099240000000000c41c18\",\n        \"storageDiagnostics\": {\n            \"batchId\": \"681fe319-3006-00a8-0022-9e7cde000000\"\n        }\n    }\n}\n<\/code><\/pre>\n
Now, let\u2019s use the Azure Event Grid client library to send and receive some CloudEvents!<\/p>\n
Prerequisites<\/h2>\n
You must have an Azure subscription<\/a> and an Azure resource group with a custom Event Grid topic or domain. Follow this step-by-step tutorial<\/a> to register the Event Grid resource provider and create Event Grid topics using the Azure portal<\/a>. Importantly, when creating your Event Grid topic, you must set the input schema to \u201cCloudEvents v1.0\u201d in the \u201cAdvanced\u201d tab. After creating your custom topic, navigate to your newly-created topic page to retrieve the topic endpoint and access key, both of which are required in order for the client library to interact with that topic.<\/p>\n
Creating and Authenticating the Client<\/h2>\n
Once you have your access key and topic endpoint, you can create the publisher client as follows:<\/p>\n
.NET<\/h4>\n
EventGridPublisherClient client = new EventGridPublisherClient(\n    \"<endpoint>\",\n    new AzureKeyCredential(\"<access-key>\"));\n<\/code><\/pre>\n
Java<\/h4>\n
EventGridPublisherClient egClient = new EventGridPublisherClientBuilder()\n    .endpoint(\"<endpoint>\")\n    .keyCredential(new AzureKeyCredential(\"<access-key>\"))\n    .buildClient();\n<\/code><\/pre>\n
JavaScript<\/h4>\n
const { EventGridPublisherClient, AzureKeyCredential } = require(\"@azure\/eventgrid\");\n\nconst client = new EventGridPublisherClient(\"<endpoint>\", new AzureKeyCredential(\"<Access Key>\"));\n<\/code><\/pre>\n
Python<\/h4>\n
from azure.core.credentials import AzureKeyCredential\nfrom azure.eventgrid import EventGridPublisherClient\n\ncredential = AzureKeyCredential(\"<access-key>\")\neg_publisher_client = EventGridPublisherClient(\"<endpoint>\", credential)\n<\/code><\/pre>\n
We will be using the .NET SDK for the remainder of the article, but similar functionality is available for all libraries. Check out the samples for all languages in the Next Steps section<\/a>.<\/p>\n
Publishing CloudEvents to your Topic<\/h2>\n
The publisher sends events to the Event Grid service. Regardless of what schema your topic or domain is configured to use, EventGridPublisherClient<\/code> will be used to publish events to the service. After creating the EventGridPublisherClient<\/code> such that the custom topic is configured to accept events of the CloudEvents v1.0 schema, we can now create some events of the CloudEvent<\/code> type to publish to the topic.<\/p>\n
The CloudEvent<\/code> type represents the event format as described by the specification. Each CloudEvent<\/code> has a set of required, non-nullable properties. Notably for CloudEvents, you can include any number of extension attributes<\/em> such that additional metadata can be added to the event envelope as needed.<\/p>\n
\/\/ Add CloudEvents to a list to publish to the topic\nList<CloudEvent> eventsList = new List<CloudEvent>\n{\n    new CloudEvent(\n        \"\/cloudevents\/example\/source\",    \/\/ source - identifies the context in which an event happened\n        \"Example.EventType\",              \/\/ type - describing the type of event\n        \"This is the event data\")         \/\/ data - the event payload\n};\n<\/code><\/pre>\n
Following that, invoke SendEvents<\/code> or SendEventsAsync<\/code> to publish the events to Azure Event Grid.<\/p>\n
await client.SendEventsAsync(eventsList);\n<\/code><\/pre>\n
To see the events that you\u2019ve sent, the quickstart tutorial also includes instructions<\/a> on how to subscribe to your new topic with a pre-built web app, which will display the events you sent as JSON:<\/p>\n
\"Events<\/p>\n
Deserializing CloudEvents Delivered to an Event Handler<\/h2>\n
The Azure Event Grid client library can also be used to parse events from JSON to access event data. There are several different Azure services that act as event handlers<\/a>. Regardless of the event handler, events are always sent as UTF-8 encoded JSON<\/em>.<\/p>\n
Once events are delivered to the event handler, you can parse the JSON payload into list of events.<\/p>\n
CloudEvent[] cloudEvents = CloudEvent.Parse(jsonPayload);\n<\/code><\/pre>\n
From here, you can access the event data by deserializing to a specific type using GetData<T>()<\/code> and passing in a custom serializer if necessary. Calling GetData()<\/code> will either return a deserialized system event (an event generated by an Azure service), or the event data wrapped in BinaryData<\/code><\/a>, which represents the serialized JSON event data as bytes.<\/p>\n
Below is an example calling GetData<T>()<\/code> for CloudEvents. The Type<\/code> property for CloudEvents describes the event type related to the occurrence, which may help differentiate between events during deserialization. Custom event data should be deserialized using the generic method GetData<T>()<\/code>. There is also an overload for GetData<T>()<\/code> that accepts a custom ObjectSerializer<\/code><\/a> to deserialize the event data.<\/p>\n
foreach (CloudEvent cloudEvent in cloudEvents)\n{\n    switch (cloudEvent.Type)\n    {\n        case \"Contoso.Items.ItemReceived\":\n            \/\/ By default, GetData uses JsonObjectSerializer to deserialize the payload\n            ContosoItemReceivedEventData itemReceived = cloudEvent.GetData<ContosoItemReceivedEventData>();\n            Console.WriteLine(itemReceived.ItemSku);\n            break;\n        case \"MyApp.Models.CustomEventType\":\n            \/\/ You can also specify a custom ObjectSerializer as needed to deserialize the payload correctly\n            TestPayload testPayload = await cloudEvent.GetDataAsync<TestPayload>(myCustomSerializer);\n            Console.WriteLine(testPayload.Name);\n            break;\n        case \"Microsoft.Storage.BlobDeleted\":\n            \/\/ Example for deserializing system events using GetData<T>\n            StorageBlobDeletedEventData blobDeleted = cloudEvent.GetData<StorageBlobDeletedEventData>();\n            Console.WriteLine(blobDeleted.BlobType);\n            break;\n    }\n}\n<\/code><\/pre>\n
Summary<\/h2>\n
The new Azure Event Grid client library follows the Azure SDK Design guidelines<\/a>, bringing about SDKs that are approachable, consistent, and idiomatic for their target languages. As a result, the process of publishing and consuming events should be straightforward for both new and experienced users. Finally, the new support for CloudEvents v1.0 relies less on service specifics, allowing for greater interoperability.<\/p>\n
A big shout out to the other 2020 summer interns Soren Dahl<\/a> and Swathi Pillalamarri<\/a> who worked on getting these libraries shipped for Java and Python! You guys are amazing!!<\/strong><\/p>\n
Next Steps<\/h2>\n