IoT Hub endpoints

Azure IoT Hub exposes various endpoints to support the devices and services that interact with it.

IoT Hub names

You can find the hostname of an IoT hub in the Azure portal, on your IoT hub's Overview working pane. By default, the DNS name of an IoT hub looks like the following example:

{your iot hub name}.azure-devices.net

IoT Hub endpoints for development and management

Azure IoT Hub is a multitenant service that exposes its functionality to various actors. The following diagram shows the various endpoints that IoT Hub exposes.

The following list describes the endpoints:

• Resource provider: an Azure Resource Manager interface. This interface enables Azure subscription owners to create and delete IoT hubs, and to update IoT hub properties. IoT Hub properties govern hub-level shared access policies, as opposed to device-level access control, and functional options for cloud-to-device and device-to-cloud messaging. The IoT Hub resource provider also enables you to export device identities.

• Device identity management: a set of HTTPS REST endpoints to manage device identities (create, retrieve, update, and delete). Device identities are used for device authentication and access control.

• Device twin management: a set of service-facing HTTPS REST endpoint to query and update device twins (update tags and properties).

• Jobs management: a set of service-facing HTTPS REST endpoint to query and manage jobs.

• Device endpoints: a set of endpoints for each device in the identity registry. Except where noted, these endpoints are exposed using MQTT v3.1.1, HTTPS 1.1, and AMQP 1.0 protocols. AMQP and MQTT are also available over WebSockets on port 443. These device endpoints include:

  • Send device-to-cloud messages

  • Receive cloud-to-device messages

  • Initiate file uploads

  • Retrieve and update device twin properties (HTTPS isn't supported)

  • Receive direct method requests (HTTPS isn't supported)

• Service endpoints: a set of endpoints for your solution back end to communicate with your devices. With one exception, these endpoints are only exposed using the AMQP and AMQP over WebSockets protocols. The direct method invocation endpoint is exposed over the HTTPS protocol.

  • Receive device-to-cloud messages: This endpoint is the built-in endpoint discussed in message routing concepts. A back-end service can use it to read the device-to-cloud messages sent by your devices. You can create custom endpoints on your IoT hub in addition to this built-in endpoint.

  • Send cloud-to-device messages and receive delivery acknowledgments

  • Receive file upload notifications

  • Invoke direct method

The Azure IoT Hub SDKs article describes the various ways to access these endpoints.

All IoT Hub endpoints use the TLS protocol, and no endpoint is ever exposed on unencrypted/unsecured channels.

Custom endpoints for message routing

You can link existing Azure services in your Azure subscriptions to your IoT hub to act as endpoints for message routing. These endpoints act as service endpoints and are used as sinks for message routes. Devices can't write directly to these endpoints. For more information about message routing, see Use IoT Hub message routing to send device-to-cloud messages to different endpoints.

IoT Hub currently supports the following Azure services as custom endpoints:

• Storage containers
• Event Hubs
• Service Bus Queues
• Service Bus Topics
• Cosmos DB

For the limits on endpoints per hub, see Quotas and throttling.

Built-in endpoint

You can use standard Event Hubs integration and SDKs to receive device-to-cloud messages from the built-in endpoint (messages/events). Once any route is created, data stops flowing to the built-in endpoint unless a route is created to that endpoint. Even if no routes are created, a fallback route must be enabled to route messages to the built-in endpoint. The fallback is enabled by default if you create your hub using the portal or the CLI.

Azure Storage as a routing endpoint

There are two storage services IoT Hub can route messages to: Azure Blob Storage and Azure Data Lake Storage Gen2 (ADLS Gen2) accounts. Both of these use blobs for their storage.

IoT Hub supports writing data to Azure Storage in the Apache Avro format and the JSON format. The default is AVRO. To use JSON encoding set the contentType property to application/json and contentEncoding property to UTF-8 in the message system properties. Both of these values are case-insensitive. If the content encoding isn't set, then IoT Hub writes the messages in base 64 encoded format.

The encoding format can be set only when the blob storage endpoint is configured; it can't be edited for an existing endpoint.

IoT Hub batches messages and writes data to storage whenever the batch reaches a certain size or a certain amount of time has elapsed. IoT Hub defaults to the following file naming convention: {iothub}/{partition}/{YYYY}/{MM}/{DD}/{HH}/{mm}.

You may use any file naming convention, but you must use all listed tokens. IoT Hub writes to an empty blob if there's no data to write.

We recommend listing the blobs or files and then iterating over them, to ensure that all blobs or files are read without making any assumptions of partition. The partition range could potentially change during a Azure-initiated failover or IoT Hub manual failover. You can use the List Blobs API to enumerate the list of blobs or List ADLS Gen2 API for the list of files. For example:

public void ListBlobsInContainer(string containerName, string iothub)
{
    var storageAccount = CloudStorageAccount.Parse(this.blobConnectionString);
    var cloudBlobContainer = storageAccount.CreateCloudBlobClient().GetContainerReference(containerName);
    if (cloudBlobContainer.Exists())
    {
        var results = cloudBlobContainer.ListBlobs(prefix: $"{iothub}/");
        foreach (IListBlobItem item in results)
        {
            Console.WriteLine(item.Uri);
        }
    }
}

Service Bus queues and Service Bus topics as a routing endpoint

Service Bus queues and topics used as IoT Hub endpoints must not have Sessions or Duplicate Detection enabled. If either of those options are enabled, the endpoint appears as Unreachable in the Azure portal.

Event Hubs as a routing endpoint

Apart from the built-in-Event Hubs compatible endpoint, you can also route data to custom endpoints of type Event Hubs.

Azure Cosmos DB as a routing endpoint

You can send data directly to Azure Cosmos DB from IoT Hub. IoT Hub supports writing to Cosmos DB in JSON (if specified in the message content-type) or as base 64 encoded binary.

To support high-scale scenarios, you can enable synthetic partition keys for the Cosmos DB endpoint. As Cosmos DB is a hyperscale data store, all data/documents written to it must contain a field that represents a logical partition. Each logical partition has a maximum size of 20 GB. You can specify the partition key property name in Partition key name. The partition key property name is defined at the container level and can't be changed once it has been set.

You can configure the synthetic partition key value by specifying a template in Partition key template based on your estimated data volume. For example, in manufacturing scenarios, your logical partition might be expected to approach its maximum limit of 20 GB within a month. In that case, you can define a synthetic partition key as a combination of the device ID and the month. The generated partition key value is automatically added to the partition key property for each new Cosmos DB record, ensuring logical partitions are created each month for each device.

Endpoint Health

You can use the REST API Get Endpoint Health to get health status of the endpoints. We recommend using the IoT Hub routing metrics related to routing message latency to identify and debug errors when endpoint health is dead or unhealthy, as we expect latency to be higher when the endpoint is in one of those states. To learn more about using IoT Hub metrics, see Monitor IoT Hub.

Health Status	Description
healthy	The endpoint is accepting messages as expected.
unhealthy	The endpoint is not accepting messages and IoT Hub is retrying to send messages to this endpoint.
unknown	IoT Hub has not attempted to deliver messages to this endpoint.
degraded	The endpoint is accepting messages slower than expected or is recovering from an unhealthy state.
dead	IoT Hub is no longer delivering messages to this endpoint. Retries to send messages to this endpoint failed.

Next steps

Learn more about these topics:

• IoT Hub query language for device and module twins, jobs, and message routing
• IoT Hub quotas and throttling
• Communicate with your IoT hub using the MQTT protocol
• IoT Hub IP addresses