Tutorial: Use namespace topics to route MQTT messages to Azure Event Hubs (Azure CLI)

In this tutorial, you learn how to use a namespace topic to route data from MQTT clients to Azure Event Hubs. Here are the high-level steps:

Prerequisites

• If you don't have an Azure subscription, create an Azure free account before you begin.
• If you're new to Event Grid, read the Event Grid overview before you start this tutorial.
• Register the Event Grid resource provider according to the steps in Register the Event Grid resource provider.
• Make sure that port 8883 is open in your firewall. The sample in this tutorial uses the MQTT protocol, which communicates over port 8883. This port might be blocked in some corporate and educational network environments.

Launch Cloud Shell

1. Sign into the Azure portal.

2. Select the link to launch the Cloud Shell.

3. Switch to Bash.

   

Create an Event Grid namespace and topic

To create an Event Grid namespace and a topic in the namespace, copy the following script to an editor, replace placeholders with actual values, and run the commands.

rgName="RESOURCEGROUPNAME"
nsName="EVENTGRIDNAMESPACENAME"
location="REGION"
nsTopicName="NAMESPACETOPICNAME"

az group create -n $rgName -l $location
az eventgrid namespace create -g $rgName -n $nsName -l $location --topic-spaces-configuration "{state:Enabled}" --identity "{type:SystemAssigned}"
az eventgrid namespace topic create -g $rgName --name $nsTopicName --namespace-name $nsName

Create an Event Hubs namespace and an event hub

To create an Event Hubs namespace and an event hub in the namespace, replace placeholders with actual values, and run the following commands. This event hub is used as an event handler in the event subscription you create in this tutorial.

ehubNsName="EVENTHUBSNAMESPACENAME`"
ehubName="EVENTHUBNAME"

az eventhubs namespace create --resource-group $rgName --name $ehubNsName
az eventhubs eventhub create --resource-group $rgName --namespace-name $ehubNsName --name $ehubName

Give Event Grid namespace the access to send events to the event hub

Run the following command to add the service principal of the Event Grid namespace to the Azure Event Hubs Data Sender role on the Event Hubs namespace. It allows the Event Grid namespace and resources in it to send events to the event hub in the Event Hubs namespace.

egNamespaceServicePrincipalObjectID=$(az ad sp list --display-name $nsName --query [].id -o tsv)
namespaceresourceid=$(az eventhubs namespace show -n $ehubNsName -g $rgName --query "{I:id}" -o tsv) 

az role assignment create --assignee $egNamespaceServicePrincipalObjectID --role "Azure Event Hubs Data Sender" --scope $namespaceresourceid

Create an event subscription with Event Hubs as the endpoint

To create an event subscription for the namespace topic you created earlier, replace placeholders with actual values, and run the following commands. This subscription is configured to use the event hub as the event handler.

eventSubscriptionName="EVENTSUBSCRIPTIONNAME"
eventhubresourceid=$(az eventhubs eventhub show -n $ehubName --namespace-name $ehubNsName -g $rgName --query "{I:id}" -o tsv) 

az resource create --api-version 2023-06-01-preview --resource-group $rgName --namespace Microsoft.EventGrid --resource-type eventsubscriptions --name $eventSubscriptionName --parent namespaces/$nsName/topics/$nsTopicName --location $location --properties "{\"deliveryConfiguration\":{\"deliveryMode\":\"Push\",\"push\":{\"maxDeliveryCount\":10,\"deliveryWithResourceIdentity\":{\"identity\":{\"type\":\"SystemAssigned\"},\"destination\":{\"endpointType\":\"EventHub\",\"properties\":{\"resourceId\":\"$eventhubresourceid\"}}}}}}"

Configure routing in the Event Grid namespace

Run the following commands to enable routing on the namespace to route messages or events to the namespace topic you created earlier. The event subscription on that namespace topic forwards those events to the event hub that's configured as an event handler.

routeTopicResourceId=$(az eventgrid namespace topic show -g $rgName --namespace-name $nsName -n $nsTopicName --query "{I:id}" -o tsv) 
az eventgrid namespace create -g $rgName -n $nsName --topic-spaces-configuration "{state:Enabled,'routeTopicResourceId':$routeTopicResourceId}"

Client client, topic space, and permission bindings

Now, create a client to send a few messages for testing. In this step, you create a client, a topic space with a topic, and publisher and subscriber bindings.

For detailed instructions, see Quickstart: Publish and subscribe to MQTT messages on an Event Grid namespace with the Azure CLI.

clientName="CLIENTNAME"
clientAuthName="client1-authnID" 
clientThumbprint="CERTIFICATETHUMBPRINT"

topicSpaceName="TOPICSPACENAME"
publisherBindingName="PUBLSHERBINDINGNAME"
subscriberBindingName="SUBSCRIBERBINDINGNAME"

az eventgrid namespace client create -g $rgName --namespace-name $nsName -n $clientName --authentication-name $clientAuthName --client-certificate-authentication "{validationScheme:ThumbprintMatch,allowed-thumbprints:[$clientThumbprint]}"

az eventgrid namespace topic-space create -g $rgName --namespace-name $nsName -n $topicSpaceName --topic-templates ['contosotopics/topic1']

az eventgrid namespace permission-binding create -g $rgName --namespace-name $nsName -n $publisherBindingName --client-group-name '$all' --permission publisher --topic-space-name $topicSpaceName

az eventgrid namespace permission-binding create -g $rgName --namespace-name $nsName -n $subscriberBindingName --client-group-name '$all' --permission subscriber --topic-space-name $topicSpaceName

Send messages using MQTTX

Use MQTTX to send a few test messages. For step-by-step instructions, see the quickstart: Publish and subscribe on an MQTT topic.

Verify that the event hub received those messages on the Overview page for your Event Hubs namespace.

View routed MQTT messages in Event Hubs by using a Stream Analytics query

Navigate to the Event Hubs instance (event hub) within your event subscription in the Azure portal. Process data from your event hub by using Stream Analytics. For more information, see Process data from Azure Event Hubs using Stream Analytics - Azure Event Hubs | Microsoft Learn. You can see the MQTT messages in the query.

Next steps

For code samples, go to this GitHub repository.