Quickstart: Route custom events to web endpoint with Azure CLI and Event Grid

Article
09/27/2024

In this article, you use the Azure CLI to create a custom topic in Azure Event Grid, subscribe to the custom topic, and trigger the event to view the result.

Note

If you are new to Azure Event Grid, see What's Azure Event Grid to get an overview of the service before going through this tutorial.

Typically, you send events to an endpoint that processes the event data and takes actions. However, to simplify this article, you send the events to a web app that collects and displays the messages.

When you're finished, you see that the event data has been sent to the web app.

Screenshot showing the Event Grid Viewer sample with a sample event.

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

Prerequisites

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.

Create a resource group

Event Grid topics are Azure resources, and must be placed in an Azure resource group. The resource group is a logical collection into which Azure resources are deployed and managed.

Create a resource group with the az group create command. The following example creates a resource group named gridResourceGroup in the chinanorth2 location.

az group create --name gridResourceGroup --location chinanorth2

Enable the Event Grid resource provider

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:
```
az provider register --namespace Microsoft.EventGrid
```
It might take a moment for the registration to finish. To check the status, run the following command:
```
az provider show --namespace Microsoft.EventGrid --query "registrationState"
```
When registrationState is Registered, you're ready to continue.

Create a custom topic

An Event Grid topic provides a user-defined endpoint that you post your events to. The following example creates the custom topic in your resource group. Replace <your-topic-name> with a unique name for your topic. The custom topic name must be unique because it's part of the Domain Name System (DNS) entry. Additionally, it must be between 3-50 characters and contain only values a-z, A-Z, 0-9, and "-"

Copy the following command, specify a name for the topic, and press ENTER to run the command.
```
topicname=<your-topic-name>
```

Use the az eventgrid topic create command to create a custom topic.

az eventgrid topic create --name $topicname -l chinanorth2 -g gridResourceGroup

Create a message endpoint

Before subscribing to the custom topic, let's create the endpoint for the event message. Typically, the endpoint takes actions based on the event data. To simplify this quickstart, you deploy a prebuilt web app that displays the event messages. The deployed solution includes an App Service plan, an App Service web app, and source code from GitHub.

Copy the following command, specify a name for the web app (Event Grid Viewer sample), and press ENTER to run the command. Replace <your-site-name> with a unique name for your web app. The web app name must be unique because it's part of the DNS entry.
```
sitename=<your-site-name>
```

Run the az deployment group create to deploy the web app using an Azure Resource Manager template.

az deployment group create \
  --resource-group gridResourceGroup \
  --template-uri "https://raw.githubusercontent.com/Azure-Samples/azure-event-grid-viewer/master/azuredeploy.json" \
  --parameters siteName=$sitename hostingPlanName=viewerhost

The deployment might take a few minutes to complete. After the deployment has succeeded, view your web app to make sure it's running. In a web browser, navigate to: https://<your-site-name>.chinacloudsites.cn

You should see the site with no messages currently displayed.

You subscribe to an Event Grid topic to tell Event Grid which events you want to track and where to send those events. The following example subscribes to the custom topic you created, and passes the URL from your web app as the endpoint for event notification.

The endpoint for your web app must include the suffix /api/updates/.

Copy the following command, replace $sitename with the name of the web app you created in the previous step, and press ENTER to run the command.
```
endpoint=https://$sitename.chinacloudsites.cn/api/updates
```

Run the following command to get the resource ID of the topic you created.

topicresourceid=$(az eventgrid topic show --resource-group gridResourceGroup --name $topicname --query "id" --output tsv)

Run the following command to create a subscription to the custom topic using the endpoint.
```
az eventgrid event-subscription create \
  --source-resource-id $topicresourceid \
  --name demoViewerSub \
  --endpoint $endpoint      
```
View your web app again, and notice that a subscription validation event has been sent to it. Select the eye icon to expand the event data. Event Grid sends the validation event so the endpoint can verify that it wants to receive event data. The web app includes code to validate the subscription.

Send an event to your custom topic

Let's trigger an event to see how Event Grid distributes the message to your endpoint. First, let's get the URL and key for the custom topic.

endpoint=$(az eventgrid topic show --name $topicname -g gridResourceGroup --query "endpoint" --output tsv)
key=$(az eventgrid topic key list --name $topicname -g gridResourceGroup --query "key1" --output tsv)

To simplify this article, you use sample event data to send to the custom topic. Typically, an application or Azure service would send the event data. The following example creates sample event data:

event='[ {"id": "'"$RANDOM"'", "eventType": "recordInserted", "subject": "myapp/vehicles/motorcycles", "eventTime": "'`date +%Y-%m-%dT%H:%M:%S%z`'", "data":{ "make": "Ducati", "model": "Monster"},"dataVersion": "1.0"} ]'

The data element of the JSON is the payload of your event. Any well-formed JSON can go in this field. You can also use the subject field for advanced routing and filtering.

CURL is a utility that sends HTTP requests. In this article, use CURL to send the event to the topic.

curl -X POST -H "aeg-sas-key: $key" -d "$event" $endpoint

You've triggered the event, and Event Grid sent the message to the endpoint you configured when subscribing. View your web app to see the event you just sent.

[{
  "id": "1807",
  "eventType": "recordInserted",
  "subject": "myapp/vehicles/motorcycles",
  "eventTime": "2017-08-10T21:03:07+00:00",
  "data": {
    "make": "Ducati",
    "model": "Monster"
  },
  "dataVersion": "1.0",
  "metadataVersion": "1",
  "topic": "/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.EventGrid/topics/{topic}"
}]

Clean up resources

If you plan to continue working with this event or the event viewer app, don't clean up the resources created in this article. Otherwise, use the following command to delete the resources you created in this article.

az group delete --name gridResourceGroup

Next steps

Now that you know how to create topics and event subscriptions, learn more about what Event Grid can help you do:

See the following samples to learn about publishing events to and consuming events from Event Grid using different programming languages.