Message routing with IoT Hub — PowerShell

This article shows you how to create a route and endpoint in your IoT hub, then delete your route and endpoint. We use the PowerShell to create routes and endpoints to Event Hubs, Service Bus queue, Service Bus topic, and Azure Storage.

To learn more about how routing works in IoT Hub, see Use IoT Hub message routing to send device-to-cloud messages to different endpoints. To walk through setting up a route that sends messages to storage and testing on a simulated device, see Tutorial: Send device data to Azure Storage using IoT Hub message routing.

Prerequisites

Azure PowerShell

To use PowerShell locally, install the Azure PowerShell module. Alternatively, to use the Azure PowerShell in a browser enable Azure Cloud Shell.

IoT Hub and an endpoint service

You need an IoT hub and at least one other service to serve as an endpoint to an IoT hub route. You can choose which Azure service (Event Hubs, Service Bus queue or topic, or Azure Storage) endpoint that you'd like to connect with your IoT Hub route.

Create, update, or remove endpoints and routes

In IoT Hub, you can create a route to send messages or capture events. Each route has an endpoint, where the messages or events end up, and a data source, where the messages or events originate. You choose these locations when creating a new route in the IoT Hub. Routing queries are then used to filter messages or events before they go to the endpoint.

You can use Events Hubs, a Service Bus queue or topic, or an Azure storage to be the endpoint for your IoT hub route. The service must first exist in your Azure account.

Note

If you're using a local version of PowerShell, Sign in with Azure PowerShell before proceeding.

References used in the following commands:

Create an Event hub

Let's create a new Event Hubs resource with an authorization rule.

  1. Create a new Event Hubs namespace. Use a unique NamespaceName.

    New-AzEventHubNamespace -ResourceGroupName MyResourceGroup -NamespaceName MyNamespace -Location MyLocation
    
  2. Create your new Event hubs entity. Use a unique Name. Use the same NamespaceName you created in the previous step.

    New-AzEventHub -Name MyEventHub -NamespaceName MyNamespace -ResourceGroupName MyResourceGroup
    
  3. Create a new authorization rule. Use the Name of your entity for EventHubName. Use a unique Name for your authorization rule.

    New-AzEventHubAuthorizationRule -ResourceGroupName MyResourceGroup -NamespaceName MyNamespace -EventHubName MyEventHub -Name MyAuthRule -Rights @('Manage', 'Send', 'Listen')
    

    For more information about access, see Authorize access to Azure Event Hubs.

Create an Event Hubs endpoint

  1. Retrieve the primary connection string from your Event hub. Copy the connection string for later use.

    Get-AzEventHubKey -ResourceGroupName MyResourceGroup -NamespaceName MyNamespace -EventHubName MyEventHub -Name MyAuthRule
    
  2. Create a new IoT hub endpoint to Event Hubs. Use your primary connection string from the previous step. The EndpointType must be EventHub, otherwise all other values should be your own.

    Add-AzIotHubRoutingEndpoint -ResourceGroupName MyResourceGroup -Name MyIotHub -EndpointName MyEndpoint -EndpointType EventHub -EndpointResourceGroup MyResourceGroup -EndpointSubscriptionId xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -ConnectionString "Endpoint=<my connection string>"
    

    To see all routing endpoint options, see Add-AzIotHubRoutingEndpoint.

Create an IoT Hub route

Finally, with your new endpoint in your IoT hub, you can create a new route.

The default fallback route in IoT Hub collects messages from DeviceMessages, so let's choose another option for our custom route, such as DeviceConnectionStateEvents. For more information on source options, see Add-AzIotHubRoute. The Enabled parameter is a switch, so no value needs to follow it.

Add-AzIotHubRoute -ResourceGroupName MyResourceGroup -Name MyIotHub -RouteName MyRoute -Source DeviceLifecycleEvents -EndpointName MyEndpoint -Enabled

You see a confirmation in your console:

RouteName     : MyIotHub 
DataSource    : DeviceLifecycleEvents
EndpointNames : MyEndpoint
Condition     : true
IsEnabled     : True

Update your IoT hub route

To make changes to an existing route, use the following command. Try changing the name of your route.

Set-AzIotHubRoute -ResourceGroupName MyResourceGroup -Name MyIotHub -RouteName MyRoute

Use the Get-AzIotHubRoute command to confirm the change in your route.

Get-AzIotHubRoute -ResourceGroupName MyResourceGroup -Name MyIotHub

Delete your Event hubs endpoint

Remove-AzIotHubRoutingEndpoint -ResourceGroupName MyResourceGroup -Name MyIotHub -EndpointName MyEndpoint -PassThru

Delete your IoT hub route

Remove-AzIotHubRoute -ResourceGroupName MyResourceGroup -Name MyIotHub -RouteName MyRoute -PassThru

Tip

Deleting a route won't delete endpoints in your Azure account. The endpoints must be deleted separately.

Next Steps

In this how-to article you learned how to create a route and endpoint for your Event Hubs, Service Bus queue or topic, and Azure Storage.

To further your exploration into message routing, see Tutorial: Send device data to Azure Storage using IoT Hub message routing. In this tutorial, you'll create a storage route and test it with a device in your IoT hub.