CloudEvents APIs and Azure Event Grid
[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-01Shared 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.
