Edit

Share via

Deliver events to Azure Event Hubs using namespace topics - Azure CLI

  • Article

The article provides step-by-step instructions to publish events to Azure Event Grid in the CloudEvents JSON format and deliver those events by using the push delivery model. To be specific, you use Azure CLI and Curl to publish events to a namespace topic in Event Grid and push those events from an event subscription to an Event Hubs handler destination. For more information about the push delivery model, see Push delivery overview.

Note

The Azure CLI Event Grid extension doesn't yet support namespaces and any of the resources it contains. We will use Azure CLI resource to create Event Grid resources.

If you don't have an Azure subscription, create an Azure free account before you begin.

Prerequisites

  • Use the Bash environment in Azure Cloud Shell. For more information, see Quickstart for Bash in Azure Cloud Shell.

  • If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.

    • If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Sign in with the Azure CLI.

    • When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use extensions with the Azure CLI.

    • Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

  • This article requires version 2.0.70 or later of the Azure CLI. If using Azure Cloud Shell, the latest version is already installed.

Enable the Event Grid resource provider

  1. If you haven't previously used Event Grid in your Azure subscription, you might need to register the Event Grid resource provider. Run the following command to register the provider:

    Azure CLI 
    az provider register --namespace Microsoft.EventGrid

  2. It might take a moment for the registration to finish. To check the status, run the following command:

    Azure CLI 
    az provider show --namespace Microsoft.EventGrid --query "registrationState"

    When registrationState is Registered, you're ready to continue.

Create a resource group

Create an Azure resource group with the az group create command. You use this resource group to contain all resources created in this article.

The general steps to use Cloud Shell to run commands are:

  • Select Open Cloud Shell to see an Azure Cloud Shell window on the right pane.
  • Copy the command and paste into the Azure Cloud Shell window.
  • Press ENTER to run the command.

  1. Declare a variable to hold the name of an Azure resource group. Specify a name for the resource group by replacing <your-resource-group-name> with a value you like.

    Azure CLI 
    resource_group="<your-resource-group-name>"
    Azure CLI 
    location="<your-resource-group-location>"

  2. Create a resource group. Change the location as you see fit.

    Azure CLI 
    az group create --name $resource_group --location $location

Create a namespace

An Event Grid namespace provides a user-defined endpoint to which you post your events. The following example creates a namespace in your resource group using Bash in Azure Cloud Shell. The namespace name must be unique because it's part of a Domain Name System (DNS) entry. A namespace name should meet the following rules:

  • It should be between 3-50 characters.
  • It should be regionally unique.
  • Only allowed characters are a-z, A-Z, 0-9 and -
  • It shouldn't start with reserved key word prefixes like Microsoft, System, or EventGrid.

  1. Declare a variable to hold the name for your Event Grid namespace. Specify a name for the namespace by replacing <your-namespace-name> with a value you like.

    Azure CLI 
    namespace="<your-namespace-name>"

  2. Create a namespace. You might want to change the location where it's deployed.

    Azure CLI 
    az eventgrid namespace create -g $resource_group -n $namespace -l $location

Create a namespace topic

Create a topic that's used to hold all events published to the namespace endpoint.

  1. Declare a variable to hold the name for your namespace topic. Specify a name for the namespace topic by replacing <your-topic-name> with a value you like.

    Azure CLI 
    topic="<your-topic-name>"

  2. Create your namespace topic:

    Azure CLI 
    az eventgrid namespace topic create -g $resource_group -n $topic --namespace-name $namespace

Create a new Event Hubs resource

Create an Event Hubs resource that is used as the handler destination for the namespace topic push delivery subscription.

  1. Declare a variable to hold the Event Hubs namespace name.

    Azure CLI 
    eventHubsNamespace="<your-event-hubs-namespace-name>"

  2. Create the Event Hubs namespace.

    Azure CLI 
    az eventhubs namespace create --resource-group $resource_group --name $eventHubsNamespace --location $location

  3. Declare a variable to hold the event hub name.

    Azure CLI 
    eventHubsEventHub="<your-event-hub-name>"

  4. Run the following command to create an event hub in the namespace.

    Azure CLI 
    az eventhubs eventhub create --resource-group $resource_group --namespace-name $eventHubsNamespace --name $eventHubsEventHub

Deliver events to Event Hubs using managed identity

To deliver events to event hubs in your Event Hubs namespace using managed identity, follow these steps:

  1. Enable system-assigned or user-assigned managed identity: namespaces. Continue reading to the next section to find how to enable managed identity using Azure CLI.
  2. Add the identity to the Azure Event Hubs Data Sender role on the Event Hubs namespace, continue reading to the next section to find how to add the role assignment.
  3. Enable the Allow trusted Microsoft services to bypass this firewall setting on your Event Hubs namespace.
  4. Configure the event subscription that uses an event hub as an endpoint to use the system-assigned or user-assigned managed identity.

Enable managed identity in the Event Grid namespace

Enable system assigned managed identity in the Event Grid namespace.

Azure CLI 
az eventgrid namespace update --resource-group $resource_group --name $namespace --identity {type:systemassigned}

Add role assignment in Event Hubs for the Event Grid managed identity

  1. Get Event Grid namespace system managed identity principal ID.

    Azure CLI 
    principalId=$(az eventgrid namespace show --resource-group $resource_group --name $namespace --query identity.principalId -o tsv)

  2. Get Event Hubs event hub resource ID.

    Azure CLI 
    eventHubResourceId=$(az eventhubs eventhub show --resource-group $resource_group --namespace-name $eventHubsNamespace --name $eventHubsEventHub --query id -o tsv)

  3. Add role assignment in Event Hubs for the Event Grid system managed identity.

    Azure CLI 
    az role assignment create --role "Azure Event Hubs Data Sender" --assignee $principalId --scope $eventHubResourceId

Create an event subscription

Create a new push delivery event subscription.

Azure CLI 
event_subscription="<your_event_subscription_name>"
Azure CLI 
az resource create --api-version 2023-06-01-preview --resource-group $resource_group --namespace Microsoft.EventGrid --resource-type eventsubscriptions --name $event_subscription --parent namespaces/$namespace/topics/$topic --location $location --properties "{\"deliveryConfiguration\":{\"deliveryMode\":\"Push\",\"push\":{\"maxDeliveryCount\":10,\"deliveryWithResourceIdentity\":{\"identity\":{\"type\":\"SystemAssigned\"},\"destination\":{\"endpointType\":\"EventHub\",\"properties\":{\"resourceId\":\"$eventHubResourceId\"}}}}}}"

Send events to your topic

Now, send a sample event to the namespace topic by following steps in this section.

List namespace access keys

  1. Get the access keys associated with the namespace you created. You use one of them to authenticate when publishing events. To list your keys, you need the full namespace resource ID first. Get it by running the following command:

    Azure CLI 
    namespace_resource_id=$(az eventgrid namespace show -g $resource_group -n $namespace --query "id" --output tsv)

  2. Get the first key from the namespace:

    Azure CLI 
    key=$(az eventgrid namespace list-key -g $resource_group --namespace-name $namespace --query "key1" --output tsv)

Publish an event

  1. Retrieve the namespace hostname. You use it to compose the namespace HTTP endpoint to which events are sent. The following operations were first available with API version 2023-06-01-preview.

    Azure CLI 
    publish_operation_uri="https://"$(az eventgrid namespace show -g $resource_group -n $namespace --query "topicsConfiguration.hostname" --output tsv)"/topics/"$topic:publish?api-version=2023-06-01-preview

  2. Create a sample CloudEvents compliant event:

    Azure CLI 
    event=' { "specversion": "1.0", "id": "'"$RANDOM"'", "type": "com.yourcompany.order.ordercreatedV2", "source" : "/mycontext", "subject": "orders/O-234595", "time": "'`date +%Y-%m-%dT%H:%M:%SZ`'", "datacontenttype" : "application/json", "data":{ "orderId": "O-234595", "url": "https://yourcompany.com/orders/o-234595"}} '

    The data element is the payload of your event. Any well-formed JSON can go in this field. For more information on properties (also known as context attributes) that can go in an event, see the CloudEvents specifications.

  3. Use CURL to send the event to the topic. CURL is a utility that sends HTTP requests.

    Azure CLI 
    curl -X POST -H "Content-Type: application/cloudevents+json" -H "Authorization:SharedAccessKey $key" -d "$event" $publish_operation_uri

    Navigate to the Event Hubs Namespace page in the Azure portal, refresh the page and verify that incoming messages counter in the chart indicates that an event has been received.

    Screenshot that shows the Event hub page with chart showing an event has been received.

Next steps

In this article, you created and configured the Event Grid namespace and Event Hubs resources. For step-by-step instructions to receive events from an event hub, see these tutorials: