Create and delete routes and endpoints by using the Azure portal

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 the Azure portal to create routes and endpoints for Azure Event Hubs, Azure Service Bus queues and topics, Azure Storage, and Azure Cosmos DB.

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:

• The Azure portal
• An IoT hub
• An endpoint service in Azure

Azure portal

This article uses the Azure portal to work with IoT Hub and other Azure services. To learn more about how to use the Azure portal, see What is the Azure portal?.

IoT hub

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

Be sure to have the following hub resource to use when you create 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.

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 events. 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, Azure Storage, or Azure Cosmos DB.

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

• An Event Hubs resource (namespace and entity). If you need to create a new Event Hubs resource, see Quickstart: Create an event hub by using the Azure portal.

• A Service Bus queue resource (namespace and queue). If you need to create a new Service Bus queue, see Use the Azure portal to create a Service Bus namespace and queue.

• A Service Bus topic resource (namespace and topic). If you need to create a new Service Bus topic, see Use the Azure portal to create a Service Bus topic and subscriptions to the topic.

• An Azure Storage resource (account and container). If you need to create a new storage account in Azure, see Create a storage account. When you create a storage account, you have many options, but you need only a new container in your account for this article.

• An Azure Cosmos DB resource (account, database, and container). If you need to create a new instance of Azure Cosmos DB, see Create an Azure Cosmos DB account. For the API option, select Azure Cosmos DB for NoSQL.

Create a route and endpoint

Routes send messages or event logs to an Azure service for storage or processing. Each route has a data source, where the messages or event logs originate, and an endpoint, where the messages or event logs end up. You can use routing queries to filter messages or events before they go to the endpoint. The endpoint can be an event hub, a Service Bus queue or topic, a storage account, or an Azure Cosmos DB resource.

1. In the Azure portal, go to your IoT hub.

2. In the resource menu under Hub settings, select Message routing then select Add.

   

3. On the Endpoint tab, select an existing endpoint or create a new one by providing the following information:

   Cosmos DB

   Parameter	Value
   Endpoint type	Select Cosmos DB.
   Endpoint name	Provide a unique name for a new endpoint, or select Select existing to choose an existing Storage endpoint.
   Cosmos DB account	Use the drop-down menu to select an existing Cosmos DB account in your subscription.
   Database	Use the drop-down menu to select an existing database in your Cosmos DB account.
   Collection	Use the drop-down menu to select an existing collection (or container).
   Generate a synthetic partition key for messages	Select Enable to support data storage for high-scale scenarios. Otherwise, select Disable For more information, see Partitioning and horizontal scaling in Azure Cosmos DB and Synthetic partition keys.
   Partition key name	If you enable synthetic partition keys, provide a name for the partition key. The partition key property name is defined at the container level and can't be changed once it has been set.
   Partition key template	Provide a template that is used to configure the synthetic partition key value. The generated partition key value is automatically added to the partition key property for each new Cosmos DB record.

   

   Event Hubs

   Parameter	Value
   Endpoint type	Select Event Hubs.
   Endpoint name	Provide a unique name for a new endpoint, or select Select existing to choose an existing Event Hubs endpoint.
   Event Hubs namespace	Use the drop-down menu to select an existing Event Hubs namespace in your subscription.
   Event hub instance	Use the drop-down menu to select an existing event hub in your namespace.

   

   Service Bus topic

   Parameter	Value
   Endpoint type	Select Service Bus topic.
   Endpoint name	Provide a unique name for a new endpoint, or select Select existing to choose an existing Service Bus topic endpoint.
   Service Bus namespace	Use the drop-down menu to select an existing Service Bus namespace in your subscription.
   Service Bus topic	Use the drop-down menu to select an existing topic in your namespace.

   

   Service Bus queue

   Parameter	Value
   Endpoint type	Select Service Bus queue.
   Endpoint name	Provide a unique name for a new endpoint, or select Select existing to choose an existing Service Bus queue endpoint.
   Service Bus namespace	Use the drop-down menu to select an existing Service Bus namespace in your subscription.
   Service Bus queue	Use the drop-down menu to select an existing queue in your namespace.

   

   Storage

   Parameter	Value
   Endpoint type	Select Storage.
   Endpoint name	Provide a unique name for a new endpoint, or select Select existing to choose an existing Storage endpoint.
   Azure Storage container	Select Pick a container. Follow the prompts to select an existing storage account and container in your subscription.

   

---

4. Select Create + next to create the endpoint and continue to create a route.

5. On the Route tab, create a new route to your endpoint by providing the following information:

   Parameter	Value
   Name	Provide a unique name for the route.
   Data source	Use the drop-down menu to select a data source for the route. You can route data from telemetry messages or non-telemetry events
   Routing query	Optionally, add a query to filter the data before routing. For more information, see IoT Hub message routing query syntax.

   

6. If you added a routing query, use the Test feature to provide a sample message and test the route against it.

7. If you want to add a message enrichment to your route, select Create + add enrichments. For more information, see Message enrichments. If not, select Create + skip enrichments.

8. Back on the Message routing overview, confirm that your new route appears on the Routes tab, and that your new endpoint appears on the Custom endpoints tab.

Update a route

To update a route in the Azure portal:

1. In the Azure portal, go to your IoT hub.

2. In the resource menu under Hub settings, select Message routing.

3. In the Routes tab, select the route that you want to modify.

4. You can change the following parameters of an existing route:

   • Endpoint: You can create a new endpoint or select a different existing endpoint.
   • Data source.
   • Enable route.
   • Routing query.

5. Select Save.

Delete a route

To delete a route in the Azure portal:

1. In Message routing for your IoT hub, select the route to delete.

2. Select Delete.

   

Update a custom endpoint

To update a custom endpoint in the Azure portal:

1. In the Azure portal, go to your IoT hub.

2. In the resource menu under Hub settings, select Message routing.

3. In the Custom endpoints tab, select the endpoint that you want to modify.

4. You can change the following parameters of an existing endpoint:

   Cosmos DB

   • Generate a synthetic partition key for messages
   • Partition key name
   • Partition key template

   Event Hubs

   • Event Hub status
   • Retention time (hrs)

   Service Bus topic

   You can't modify a Service Bus topic endpoint.

   Service Bus queue

   You can't modify a Service Bus queue endpoint.

   Storage

   • Batch frequency
   • Chunk size window
   • File name format

---

5. Select Save.

Delete a custom endpoint

To delete a custom endpoint in the Azure portal:

1. In the Azure portal, go to your IoT hub.

2. In the resource menu under Hub settings, select Message routing.

3. In the Custom endpoints tab, use the checkbox to select the endpoint that you want to delete.

4. Select Delete.

   

Next steps

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.