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.
An IoT hub in your Azure subscription. If you don't have a hub yet, you can follow the steps in Create an IoT hub using the New-AzIotHub cmdlet.
(Optional) An Event Hubs resource (with container). If you need to create a new Event Hubs resource, see Quickstart: Create an event hub using Azure PowerShell.
(Optional) A Service Bus queue resource. If you need to create a new Service Bus queue, see Use Azure PowerShell to create a Service Bus namespace and a queue.
(Optional) A Service Bus topic resource. If you need to create a new Service Bus topic, see the New-AzServiceBusTopic reference and the Azure Service Bus Messaging documentation.
(Optional) An Azure Storage resource. If you need to create a new Azure Storage, see Create a storage account.
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.
Create a new Event Hubs namespace. Use a unique NamespaceName.
New-AzEventHubNamespace -ResourceGroupName MyResourceGroup -NamespaceName MyNamespace -Location MyLocationCreate 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 MyResourceGroupCreate 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
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 MyAuthRuleCreate a new IoT hub endpoint to Event Hubs. Use your primary connection string from the previous step. The
EndpointTypemust beEventHub, 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.
Feedback
Submit and view feedback for