CloudEvents APIs and Azure Event Grid

Akihiro Nishikawa
Oct 31, 2020 · 6 min read

[Initially created on October 31, 2020. Revised on December 3, 2020]

Japanese edition is listed below.

Azure Event Grid supports CloudEvents 1.0.

And Azure Event Grid client library also supports sending/receiving events in the form of CloudEvents.

If Azure Event Grid is the only system which consumes and posts cloud events in your environment, Azure Event Grid SDK should be chosen. However, if several systems which consume and post cloud events have already existed in your environment and you plan to introduce Azure Event Grid, you would feel happy industry standard APIs allow you to interact with not only existing services but also Azure Event Grid. In this article, I describe how to interact with Azure Event Grid using CloudEvents APIs.

Prerequisites and basic information

What is CloudEvents?

If you are not familiar with CloudEvents, please check the following URL.

What format does Azure Event Grid support?

As of now, Azure Event Grid supports Structured Content mode only (Binary Content mode is not supported). We have to follow JSON Event Format specification in case of creating events.

What language and SDK is available?

CloudEvents SDKs are provided in several languages. In this article, sample applications are created with Java APIs for CloudEvents. Json EventFormat implementation with Jackson and HTTP Protocol Binding APIs for Jakarta RESTful Web Services allows us to create applications much easier than using core APIs.

How do we post events to Azure Event Grid via CloudEvents APIs?

When posting events to Azure Event Grid through CloudEvents APIs, the following URL is helpful.

According to this document, we can post events to Azure Event Grid topic with the following URL (Access key or Shared Access Signature is required). We can get the access key in Azure Portal and via Azure CLI.

https://{topic-endpoint}?api-version=2018-01-01

Shared Access Signature is similar to access access key, but it can be configured with an expiration time. It might be suitable if access restriction to a topic or domain is required. The following URL describes how to create Shared Access Signature.

Send CloudEvents to Azure Event Grid

In this part, a REST client application which uses CloudEvents APIs is created in order to post events to Azure Event Grid topic. Azure Event Grid Viewer application verifies and shows these events. This viewer application is described in the following URL.

With following the document above, you can configure Event Grid topic. No special configuration is required.

Dependencies

As this client application requires JAX-RS related modules, the following dependencies should be added to pom.xml.

Create events using CloudEvents APIs

CloudEvents::v1() method allows us to create events. JSON is used as a format of custom data, and we use the withDataContentType() method to specify application/json as Content-Type.

Serialization

Serialization of created JSON formatted events is required. To do so, we use “Json EventFormat implementation with Jackson” APIs.

Create REST Client

We can follow typical ways to creating REST client. No special configuration is required. Access key of Event Grid should be set to HTTP Header. Note that not application/json but application/cloudevents+json should be set as Content-Type.

Creating a client application is completed.

Receive CloudEvents through Azure Event Grid

In this part, a JAX-RS application is created to subscribe the Event Grid topic. As Azure Event Grid send events using webhook, the JAX-RS application requires a POST endpoint to listen events.

Event Grid topic which we use is already configured in the previous section (precisely, the topic should be configured with following the tutorial).

Dependencies

In this case, Helidon MP is chosen to create JAX-RS application. Needless to say, you can choose any development framework freely.

This application depends on the following modules.

Create an endpoint

We can create a JAX-RS applications without special configuration. As Azure Event Grid supports Structured Content mode only, event format is JSON. So, the sample application waits for events using JsonObject. AndEventFormat::deserialize() method is used for deserialization of events.

Configure OPTIONS method for enabling webhook integration

When configuring Azure Event Grid integration through webhook, subscriber (i.e. this JAX-RS application) has to respond to Azure Event Grid using OPTIONS method.

Create Docker container and deploy to Azure App Service

After these steps are completed, we build the JAX-RS application, containerize it, and deploy it on Azure App Service.

Test

The following events are posted to Azure Event via the client application.

We can observe each event was successful delivered to each subscription in Azure Portal.

Azure Event Grid Viewer also shows delivered events.

And from JAX-RS application side, we can observe each delivered event in App Service console log. Three logs appears per each event.

Conclusion

CloudEvents APIs allow us to post structured events to Azure Event Grid, and to handle structured events delivered from Azure Event Grid. CloudEvents APIs supports various languages, and especially Java, if you are familiar with JAX-RS and Jackson, you would easily create applications with these APIs.

If Azure Event Grid were the only system which consumes and posts cloud events in your environment, Azure Event Grid SDK would be the best APIs. However, if Azure Event Grid is one of services which consume and post cloud events, industry standard APIs is often more suitable than Azure Event Grid SDK.

I hope this article helps you.

Microsoft Azure

Any language.

Microsoft Azure

Any language. Any platform. Our team is focused on making the world more amazing for developers and IT operations communities with the best that Microsoft Azure can provide. If you want to contribute in this journey with us, contact us at medium@microsoft.com

Akihiro Nishikawa

Written by

Cloud Solution Architect @Microsoft ❤️Java (JVM/GraalVM) and open source technologies. All views are my own.

Microsoft Azure

Any language. Any platform. Our team is focused on making the world more amazing for developers and IT operations communities with the best that Microsoft Azure can provide. If you want to contribute in this journey with us, contact us at medium@microsoft.com