Create and delete routes and endpoints by using Azure PowerShell

This article shows you how to create a route and endpoint in your hub in Azure IoT Hub and then delete your route and endpoint. Learn how to use Azure PowerShell to create routes and endpoints for Azure Event Hubs, Azure Service Bus queues and topics, 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 then testing on a simulated device, see Tutorial: Send device data to Azure Storage by using IoT Hub message routing.

Prerequisites

The procedures that are described in the article use the following resources:

  • Azure PowerShell
  • An IoT hub
  • An endpoint service in Azure

Azure PowerShell

This article uses Azure PowerShell to work with IoT Hub and other Azure services. To use Azure PowerShell locally, install the Azure PowerShell module on your computer.

IoT hub

To create an IoT hub route, you need an IoT hub that you created by using Azure IoT Hub. Device messages and event logs originate in your IoT hub.

Be sure to have the following hub resource to use when you create your IoT hub route:

Endpoint service

To create an IoT hub route, you need at least one other Azure service to use as an endpoint to the route. The endpoint receives device messages and event logs. You can choose which Azure service you use for an endpoint to connect with your IoT hub route: Event Hubs, Service Bus queues or topics, or Azure Storage.

Be sure to have one of the following resources to use when you create an endpoint your IoT hub route:

Create resources and endpoints

In IoT Hub, you can create a route to send messages or capture events. Each route has a data source and an endpoint. The data source is where messages or event logs originate. The endpoint is where the messages or event logs end up. You choose locations for the data source and endpoint when you create a new route in your IoT hub. Then, you use routing queries to filter messages or events before they go to the endpoint.

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

Note

If you use a local version of Azure PowerShell, sign in to Azure PowerShell before you begin.

The commands in the following procedures use these references:

Create an event hub

To create a new Event Hubs resource that has an authorization rule:

  1. Create a new Event Hubs namespace. For NamespaceName, use a unique value.

    New-AzEventHubNamespace -ResourceGroupName MyResourceGroup -NamespaceName MyNamespace -Location MyLocation
    
  2. Create your new Event Hubs entity. For Name, use a unique value. For NamespaceName, use the name of the namespace you created in the preceding step.

    New-AzEventHub -Name MyEventHub -NamespaceName MyNamespace -ResourceGroupName MyResourceGroup
    
  3. Create a new authorization rule. For Name, use the name of your entity for EventHubName. For the name of your authorization rule, use a unique value.

    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. Get the primary connection string from your event hub. Copy the connection string to use later.

    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 preceding step. The value for EndpointType must be EventHub. For all other parameters, use the values for your scenario.

    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

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. Choose a different option for your custom route, such as DeviceConnectionStateEvents. For more information about source options, see Add-AzIotHubRoute. The Enabled parameter is a switch, so you don't need to use a value with the parameter.

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

PowerShell displays a confirmation that looks similar to this example:

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

Update an IoT Hub route

To make changes to an existing route, use the following command. For example, try changing the name of your route by using the command.

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 an endpoint

To delete an endpoint:

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

Delete an IoT Hub route

To delete an IoT Hub route:

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

Tip

Deleting a route doesn't delete any endpoints in your Azure account. You must delete an endpoint separately from deleting a route.

Next steps

In this how-to article, you learned how to create a route and endpoint for Event Hubs, Service Bus queues and topics, and Azure Storage.

To learn more about message routing, see Tutorial: Send device data to Azure Storage by using IoT Hub message routing. In the tutorial, you create a storage route and test it with a device in your IoT hub.