Tutorial: Route custom events to Azure Relay Hybrid Connections with Azure CLI and Event Grid

Azure Event Grid is an eventing service for the cloud. Azure Relay Hybrid Connections is one of the supported event handlers. You use hybrid connections as the event handler when you need to process events from applications that don't have a public endpoint. These applications might be within your corporate enterprise network. In this article, you use the Azure CLI to create a custom topic, subscribe to the custom topic, and trigger the event to view the result. You send the events to the hybrid connection.

Prerequisites

This article assumes you already have a hybrid connection and a listener application. To get started with hybrid connections, see Get started with Relay Hybrid Connections - .NET or Get started with Relay Hybrid Connections - Node.

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

This feature is in preview. To use it, you must install a preview extension or module.

Install extension for Azure CLI

For Azure CLI, you need the Event Grid extension.

In CloudShell:

  • If you've installed the extension previously, update it az extension update -n eventgrid
  • If you haven't installed the extension previously, install it az extension add -n eventgrid

For a local installation:

  1. Uninstall Azure CLI locally.
  2. Install the latest version of Azure CLI.
  3. Launch command window.
  4. Uninstall previous versions of the extension az extension remove -n eventgrid
  5. Install the extension az extension add -n eventgrid

Install module for PowerShell

For PowerShell, you need the AzureRM.EventGrid module.

In CloudShell:

  • Install the module Install-Module -Name AzureRM.EventGrid -AllowPrerelease -Force -Repository PSGallery

For a local installation:

  1. Open PowerShell console as administrator
  2. Install the module Install-Module -Name AzureRM.EventGrid -AllowPrerelease -Force -Repository PSGallery

If the -AllowPrerelease parameter isn't available, use the following steps:

  1. Run Install-Module PowerShellGet -Force
  2. Run Update-Module PowerShellGet
  3. Close the PowerShell console
  4. Restart PowerShell as administrator
  5. Install the module Install-Module -Name AzureRM.EventGrid -AllowPrerelease -Force -Repository PSGallery

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 westus2 location.

az group create --name gridResourceGroup --location westus2

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 <topic_name> with a unique name for your custom topic. The event grid topic name must be unique because it's represented by a DNS entry.

# if you have not already installed the extension, do it now.
# This extension is required for preview features.
az extension add --name eventgrid

az eventgrid topic create --name <topic_name> -l westus2 -g gridResourceGroup

Subscribe to a custom topic

You subscribe to an event grid topic to tell Event Grid which events you want to track. The following example subscribes to the custom topic you created, and passes the resource ID of the hybrid connection for the endpoint. The hybrid connection ID is in the format:

/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Relay/namespaces/<relay-namespace>/hybridConnections/<hybrid-connection-name>

The following script gets the resource ID of the relay namespace. It constructs the ID for the hybrid connection, and subscribes to an event grid topic. The script sets the endpoint type to hybridconnection and uses the hybrid connection ID for the endpoint.

relayname=<namespace-name>
relayrg=<resource-group-for-relay>
hybridname=<hybrid-name>

relayid=$(az resource show --name $relayname --resource-group $relayrg --resource-type Microsoft.Relay/namespaces --query id --output tsv)
hybridid="$relayid/hybridConnections/$hybridname"
topicid=$(az eventgrid topic show --name <topic_name> -g gridResourceGroup --query id --output tsv)

az eventgrid event-subscription create \
  --source-resource-id $topicid \
  --name <event_subscription_name> \
  --endpoint-type hybridconnection \
  --endpoint $hybridid \
  --expiration-date "<yyyy-mm-dd>"

Notice that an expiration date is set for the subscription.

Create application to process events

You need an application that can retrieve events from the hybrid connection. The Microsoft Azure Event Grid Hybrid Connection Consumer sample for C# performs that operation. You've already finished the prerequisite steps.

  1. Make sure you have Visual Studio 2017 Version 15.5 or later.

  2. Clone the repository to your local machine.

  3. Load HybridConnectionConsumer project in Visual Studio.

  4. In Program.cs, replace <relayConnectionString> and <hybridConnectionName> with the relay connection string and hybrid connection name that you created.

  5. Compile and run the application from Visual Studio.

Send an event to your topic

Let's trigger an event to see how Event Grid distributes the message to your endpoint. This article shows how to use Azure CLI to trigger the event. Alternatively, you can use Event Grid publisher application.

First, let's get the URL and key for the custom topic. Again, use your custom topic name for <topic_name>.

endpoint=$(az eventgrid topic show --name <topic_name> -g gridResourceGroup --query "endpoint" --output tsv)
key=$(az eventgrid topic key list --name <topic_name> -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. CURL is a utility that sends HTTP requests. In this article, use CURL to send the event to the custom topic.

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"} ]'
curl -X POST -H "aeg-sas-key: $key" -d "$event" $endpoint

Your listener application should receive the event message.

Clean up resources

If you plan to continue working with this event, 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: