Table of Contents

Overview

This wiki article provides an example of using Azure Event Grid by providing an example of posting a message to an Event Grid Topic and using a Subscription to create a new queue item.

This example will use a combination of Azure CLI commands, the Azure Portal, and Postman. The purpose of the example is to show the simplicity of using Event Grid to react to events in Azure resources as well using a custom topic to show how Event Grid can be extended.

This article does assume some basic understanding of Event Grid terminology. Please see the community post Event Grid for background.

Note: You will most likely find that you need to create a unique topic name and storage name. These are unique as they are used to generate the endpoint for the created resource.

Setup

Azure CLI is a great way to issue commands to an Azure subscription. These commands can be issued in a local Bash or Powershell command shell, or the Azure Cloud Shell.

The following instructions were used in a local command shell so the first step is to set the Azure Subscription. In the local command shell, issue the following to verify you have Azure CLI installed and the version is equal to or more recent than 2.2.0:

az --version

If the version is older or you do not have Azure CLI installed, issue the following command:
Invoke-WebRequest -Uri https://aka.ms/installazurecliwindows -OutFile .\AzureCLI.msi; Start-Process msiexec.exe -Wait -ArgumentList '/I AzureCLI.msi /quiet'

Next, log into an Azure subscription:
az login

And set the subscription you would like to use:
az account set --subscription "{your subscription id}"

The next step will create a new Resource Group. Think of this as a container that will contain this example. The example will comprise of a collection of resources so having a single resource group makes it easy for us to delete everything at once when we are done.

Creating a Resource Group

We will refer to the Resource Group multiple times so we will issue two commands. The first creates a variable to contain the name of the resource group while the second creates the group:

$rg="TechNetEventGrid"
az group create --name $rg --location southeastasia

Now that we have a resource group, we will create a storage account that will contain a queue.

Creating a Storage Queue

Azure Storage is a resource that has multiple features. For this example, we will look at blob storage and queues. Blob storage provides a repository for storing unstructured objects. Storage queues provide a messaging platform. 

First, let's create a new storage account:

$storage="technetsamplestorage"
az storage account create --name $storage --location southeastasia --resource-group $rg --sku Standard_LRS
$storageid=$(az storage account show --name $storage --resource-group $rg --query id --output tsv)

The first line creates a variable containing the name of the storage account. The second line creates the storage account in the Southeast Asia region, and the last line will store the id of the storage account.

Next we will create a sample queue name "queue1":
$queuename="queue1"
az storage queue create --name $queuename --account-name $storage
$queueid="$storageid/queueservices/default/queues/$queuename"

We will store the id of the queue as we will need it in the Creating a subscription step below.

Creating a Custom Topic

An Event Grid Topic will be used to receive a http post.

$topic="TechNetEventGrid-tpc"
az eventgrid topic create --resource-group $rg --name $topic --location southeastasia

Think of the topic as an onramp for receiving events. The events are received but they don't go anywhere without a subscription. Because of this, we need to retrieve some information to be used in the next step:
$endpoint=$(az eventgrid topic show --name $topic -g $rg --query "endpoint" --output tsv)
$key=$(az eventgrid topic key list --name $topic -g $rg --query "key1" --output tsv)
$topicid=$(az eventgrid topic show --name $topic -g $rg --query id --output tsv)

Creating a Subscription

With events being received, we now need a subscription. The subscription will direct an event towards a handler. In this example we will create a subscription to send the event to the queue we created earlier (Note: update the expiration date value to be in the future if you are running these steps after May 25th):

az eventgrid event-subscription create --source-resource-id $topicid --name TopicToStorageQueue-sub --endpoint-type storagequeue --endpoint $queueid --expiration-date "2020-05-25"

This completes the initial setup. Let's pop into the portal to view the changes we have made: 

Portal Review

In the created resource group, TechNetEventGrid, we can see to resources that have been created:


If we look at the Event Grid Topic, TechNetEventGrid-tpc, we can see that there is one subscription, TopicToStorageQueue-sub. This is indicated by the arrow below:


Let's use Postman to create some activity next.

Postman

In Postman, let's create a new request. We need the endpoint we are going to post to and the key. Both of these we captured in the steps previously and their values are in $endpoint and $key.

In Post, we will put the $endpoint value as the url and be sure to set the request to POST:


A header needs to be sent that contains the $key value as shown below:

The payload will be sent as json content. A sample is shown below:
[
    {
        "id": "1231123123q2312",
        "eventType": "a value to indicate the type ofevent",
        "subject": "a subject that this event is about",
        "eventTime": "2020-03-17T15:12:13Z",
        "data": {
            "note": "the data section can be any valid json so this is where you want to extend"
        },
        "dataVersion": "1.0"
    }
]

This is set in the Body in Postman as shown below:


You should now be able to send the request and receive a 200 response.


If you forget to set the key then you will receive a message to indicate that it is required:
{
  "error": {
    "code": "Unauthorized",
    "message": "Request must contain one of the following authorization signature: aeg-sas-token, aeg-sas-key. Report 'fe5d5108-383c-430c-b054-64a79322d4c7:4:3/17/2020 2:10:27 AM (UTC)' to our forums for assistance or raise a support ticket.",
    "details": [
      {
        "code": "Unauthorized",
        "message": "Request must contain one of the following authorization signature: aeg-sas-token, aeg-sas-key. Report 'fe5d5108-383c-430c-b054-64a79322d4c7:4:3/17/2020 2:10:27 AM (UTC)' to our forums for assistance or raise a support ticket."
      }
    ]
  }
}

Portal Review

Back in the Portal, we can now see some activity.


At the bottom of the graph are three values: Published Events, Publish Failed Events, Unmatched Events.

  • Publish Succeeded: Event successfully sent to the topic and handled
  • Publish Failed: Event sent to the topic but was not handled successfully
  • Unmatched: Event successfully published to the topic but was not matched to an event subscription

If the subscription is selected below the graph, you will be taken to a view that shows the handling of the messages by the subscription:

This view shows the following information:

  • Delivery Succeeded: Event successfully delivered and handled by the subscription's endpoint
  • Delivery Failed: Event sent to subscription's endpoint but was not successfully handled
  • Expired Events: Event was not delivered and all retry attempts were sent
  • Matched Events: Event in the topic was matched by the event subscription
For more detail on the handling of the message, the individual handler's logs should be reviewed in more detail. For example, if the handler was an Azure Function, then Application Insights or the function monitoring should be reviewed.

References

This article pulled content from several docs: