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.

Note

Currently, PowerShell doesn't support managed identity authentication types for creating endpoints. If you can't use SAS authentication in your scenario, use one of the other management tools to create endpoints.

Also, PowerShell currently doesn't support creating Cosmos DB endpoints.

Prerequisites

Review the prerequisites for this article based on the type of endpoint you want to route the messages to.

Event Hubs

• An Azure subscription. If you don't have an Azure subscription, create a free Azure account before you begin.

• An IoT hub. If you don't have a hub, you can follow the steps to create an IoT hub.

• Azure PowerShell. To use Azure PowerShell locally, install the Azure PowerShell module on your computer. Alternatively, to use Azure PowerShell in a web browser, enable Azure Cloud Shell.

• An Event Hubs resource (with container). If you need to create a new Event Hubs resource, see Quickstart: Create an event hub.

• (Recommended) A managed identity with role-based access control permissions for the Event Hubs namespace. For more information, see Authenticate a managed identity with Microsoft Entra ID to access Event Hubs resources.

Service Bus queue

• An Azure subscription. If you don't have an Azure subscription, create a free Azure account before you begin.

• An IoT hub. If you don't have a hub, you can follow the steps to create an IoT hub.

• Azure PowerShell. To use Azure PowerShell locally, install the Azure PowerShell module on your computer. Alternatively, to use Azure PowerShell in a web browser, enable Azure Cloud Shell.

• A Service Bus queue resource. If you need to create a new Service Bus queue, see Quickstart: Create a Service Bus namespace and a queue.

• (Recommended) A managed identity with role-based access control permissions for the Service Bus namespace or queue. For more information, see Authenticate a managed identity with Microsoft Entra ID to access Azure Service Bus resources

Service Bus topic

• An Azure subscription. If you don't have an Azure subscription, create a free Azure account before you begin.

• An IoT hub. If you don't have a hub, you can follow the steps to create an IoT hub.

• Azure PowerShell. To use Azure PowerShell locally, install the Azure PowerShell module on your computer. Alternatively, to use Azure PowerShell in a web browser, enable Azure Cloud Shell.

• A Service Bus topic resource. If you need to create a new Service Bus topic, see Quickstart: Create a Service Bus namespace with topic and subscription by using a Resource Manager template.

• (Recommended) A managed identity with role-based access control permissions for the Service Bus namespace or topic. For more information, see Authenticate a managed identity with Microsoft Entra ID to access Azure Service Bus resources

Azure Storage

• An Azure subscription. If you don't have an Azure subscription, create a free Azure account before you begin.

• An IoT hub. If you don't have a hub, you can follow the steps to create an IoT hub.

• Azure PowerShell. To use Azure PowerShell locally, install the Azure PowerShell module on your computer. Alternatively, to use Azure PowerShell in a web browser, enable Azure Cloud Shell.

• An Azure Storage resource. If you need to create a new Azure Storage account, see Create a storage account.

• (Recommended) A managed identity with role-based access control permissions for the Storage account. For more information, see Assign an Azure role for access to blob data.

Create 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.

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.

Event Hubs

The commands in the following procedures use these references:

• Az.IotHub
• Az.EventHub

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.

Service Bus queue

The commands in the following procedures use these references:

• Az.IotHub
• Az.ServiceBus

To create a new Service Bus queue endpoint:

1. Retrieve the primary connection string from your Service Bus namespace. Copy the connection string to use later.

   Get-AzServiceBusKey -ResourceGroupName MyResourceGroup -Namespace MyNamespace -Name RootManageSharedAccessKey
   

2. Create a new IoT hub endpoint to your Service Bus queue. Use your primary connection string from the preceding step with ;EntityPath=MyServiceBusQueue added to the end. The value for EndpointType must be ServiceBusQueue. For all other parameters, use the values for your scenario. For EndpointName, use a unique value.

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

   For a list of all routing endpoint options, see Add-AzIotHubRoutingEndpoint.

Service Bus topic

The commands in the following procedures use these references:

• Az.IotHub
• Az.ServiceBus

1. Retrieve the primary connection string from your Service Bus namespace. Copy the connection string to use later.

   Get-AzServiceBusKey -ResourceGroupName MyResourceGroup -Namespace MyNamespace -Name RootManageSharedAccessKey
   

2. Create a new IoT hub endpoint to your Service Bus topic. Use your primary connection string from the preceding step with ;EntityPath=MyServiceBusTopic added to the end. The value for EndpointType must be ServiceBusTopic. For all other parameters, use the values for your scenario. For EndpointName, use a unique value.

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

   For a list of all routing endpoint options, see Add-AzIotHubRoutingEndpoint.

Azure Storage

The commands in the following procedures use these references:

• Az.IotHub
• Az.Storage

To create an endpoint to Azure Storage, you need your access key to construct a connection string. The connection string is then part of the IoT Hub command to create an endpoint.

1. Retrieve your access key from your storage account, and then copy it.

   Get-AzStorageAccountKey -ResourceGroupName MyResourceGroup -Name mystorageaccount
   

2. Construct a primary connection string for your storage account based on the following template. Replace mystorageaccount (in two places) with the name of your storage account. Replace mykey with your key from the preceding step.

   "DefaultEndpointsProtocol=https;BlobEndpoint=https://mystorageaccount.blob.core.windows.net;AccountName=mystorageaccount;AccountKey=mykey"
   

   This connection string is required in the step to create the endpoint.

3. Create your Azure Storage endpoint with the connection string you constructed. EndpointType must have the value azurestorage. For all other parameters, use the values for your scenario. For EndpointName, use a unique value.

   Add-AzIotHubRoutingEndpoint -ResourceGroupName MyResourceGroup -Name MyIotHub -EndpointName MyEndpoint -EndpointType azurestorage -EndpointResourceGroup MyResourceGroup -EndpointSubscriptionId xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -ConnectionString "my connection string"
   

4. When you're prompted for your container name, enter your container name, and then select Enter to create the endpoint.

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.