Create and route custom events with the Azure portal and Event Grid

Azure Event Grid is an eventing service for the cloud. In this article, you use the Azure portal to create a custom topic, subscribe to the topic, and trigger the event to view the result. You send the event to an Azure Function that logs the event data. When you're finished, you see that the event data has been sent to an endpoint and logged.

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

Enable Event Grid resource provider

If you haven't previously used Event Grid in your Azure subscription, you may need to register the Event Grid resource provider.

In the Azure portal:

  1. Select Subscriptions.
  2. Select the subscription you're using for Event Grid.
  3. Under Settings, select Resource providers.
  4. Find Microsoft.EventGrid.
  5. If not registered, select Register.

It may take a moment for the registration to finish. Select Refresh to update the status. When Status 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.

  1. Log in to Azure portal.

  2. To create a custom topic, select Create a resource.

    Create a resource

  3. Search for Event Grid Topic and select it from the available options.

    Search event grid topic

  4. Select Create.

    Start steps

  5. Provide a unique name for the custom topic. The topic name must be unique because it is represented by a DNS entry. Do not use the name shown in the image. Instead, create your own name. Select one of the supported regions. Provide a name for the resource group. Select Create.

    Provide event grid topic values

  6. After the custom topic has been created, you see the successful notification.

    See succeed notification

    If the deployment didn't succeed, find out what caused the error. Select Deployment failed.

    Select deployment failed

    Select the error message.

    Select deployment failed

    The following image shows a deployment that failed because the name for the custom topic is already in use. If you see this error, retry the deployment with a different name.

    Name conflict

Create an Azure Function

Before subscribing to the topic, let's create the endpoint for the event message. In this article, you use Azure Functions to create a function app for the endpoint.

  1. To create a function, select Create a resource.

    Create a resource

  2. Select Compute and Function App.

    Create function

  3. Provide a unique name for the Azure Function. Do not use the name shown in the image. Select the resource group you created in this article. For hosting plan, use Consumption Plan. Use the suggested new storage account. You can turn off Application Insights. After providing the values, select Create.

    Provide function values

  4. When the deployment finishes, select Go to resource.

    Go to resource

  5. Next to Functions, select +.

    Add function

  6. From the available options, select Custom function.

    Custom function

  7. Scroll down until you find Event Grid trigger. Select C#.

    Select event grid trigger

  8. Accept the default values, and select Create.

    New function

Your function is now ready to receive events.

Subscribe to a topic

You subscribe to a topic to tell Event Grid which events you want to track, and where to send the events.

  1. In your Azure function, select Add Event Grid Subscription.

    Add event grid subscription

  2. Provide values for the subscription. Select Event Grid Topics for the topic type. For subscription and resource group, select the subscription and resource group where you created your custom topic. For instance, select the name of your custom topic. The subscriber endpoint is prepopulated with the URL for the function.

    Provide subscription values

  3. Before triggering the event, open the logs for the function so you can see the event data when it is sent. At the bottom of your Azure function, select Logs.

    Select logs

Now, let's trigger an event to see how Event Grid distributes the message to your endpoint. To simplify this article, use Cloud Shell to send sample event data to the custom topic. Typically, an application or Azure service would send the event data.

Open Azure Cloud Shell

Azure Cloud Shell is a free, interactive shell that you can use to run the steps in this article. Common Azure tools are preinstalled and configured in Cloud Shell for you to use with your account. Just select the Copy button to copy the code, paste it in Cloud Shell, and then press Enter to run it. There are a few ways to open Cloud Shell:

Select Try It in the upper-right corner of a code block. Cloud Shell in this article
Open Cloud Shell in your browser. https://shell.azure.com/bash
Select the Cloud Shell button on the menu in the upper-right corner of the Azure portal. Cloud Shell in the portal

Send an event to your topic

Use either Azure CLI or PowerShell to send a test event to your custom topic.

The first example uses Azure CLI. It gets the URL and key for the topic, and sample event data. Use your topic name for <topic_name>. To see the full event, use echo "$body". 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.

endpoint=$(az eventgrid topic show --name <topic_name> -g myResourceGroup --query "endpoint" --output tsv)
key=$(az eventgrid topic key list --name <topic_name> -g myResourceGroup --query "key1" --output tsv)

body=$(eval echo "'$(curl https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/event-grid/customevent.json)'")

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

The second example uses PowerShell to perform similar steps.

$endpoint = (Get-AzureRmEventGridTopic -ResourceGroupName gridResourceGroup -Name <topic-name>).Endpoint
$keys = Get-AzureRmEventGridTopicKey -ResourceGroupName gridResourceGroup -Name <topic-name>

$eventID = Get-Random 99999

#Date format should be SortableDateTimePattern (ISO 8601)
$eventDate = Get-Date -Format s

#Construct body using Hashtable
$htbody = @{
    id= $eventID
    eventType="recordInserted"
    subject="myapp/vehicles/motorcycles"
    eventTime= $eventDate   
    data= @{
        make="Ducati"
        model="Monster"
    }
    dataVersion="1.0"
}

#Use ConvertTo-Json to convert event body from Hashtable to JSON Object
#Append square brackets to the converted JSON payload since they are expected in the event's JSON payload syntax
$body = "["+(ConvertTo-Json $htbody)+"]"

Invoke-WebRequest -Uri $endpoint -Method POST -Body $body -Headers @{"aeg-sas-key" = $keys.Key1}

You've triggered the event, and Event Grid sent the message to the endpoint you configured when subscribing. Look at the logs to see the event data.

View logs

Clean up resources

If you plan to continue working with this event, don't clean up the resources created in this article. Otherwise, delete the resources you created in this article.

Select the resource group, and select Delete resource group.

Next steps

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