IoT Hub endpoints
Azure IoT Hub exposes various endpoints to support the devices and services that interact with it.
Note
Some of the features mentioned in this article, like cloud-to-device messaging, device twins, and device management, are only available in the standard tier of IoT Hub. For more information about the basic and standard/free IoT Hub tiers, see Choose the right IoT Hub tier for your solution.
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.
Important
The following functionality for devices that use X.509 certificate authority (CA) authentication is not yet generally available, and preview mode must be enabled:
- HTTPS, MQTT over WebSockets, and AMQP over WebSockets protocols.
- File uploads (all protocols).
These features are generally available on devices that use X.509 thumbprint authentication. To learn more about X.509 authentication with IoT Hub, see Supported X.509 certificates.
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 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 the built-in 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. To use Azure Data Lake Gen2, your storage account must have hierarchical namespaces enabled. For more information, see Create a storage account to use with Azure Data Lake 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 elapses. IoT Hub defaults to the following file naming convention: {iothub}/{partition}/{YYYY}/{MM}/{DD}/{HH}/{mm}. You can 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 Microsoft-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(Microsoft.Azure.Storage.Auth.StorageCredentials storageCredentials, bool useHttps);
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 updated.
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.
Caution
If you're using the system assigned managed identity for authenticating to Cosmos DB, you must use Azure CLI or Azure PowerShell to assign the Cosmos DB Built-in Data Contributor built-in role definition to the identity. Role assignment for Cosmos DB isn't currently supported from the Azure portal. For more information about the various roles, see Configure role-based access for Azure Cosmos DB. To understand assigning roles via CLI, see Manage Azure Cosmos DB SQL role resources.
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: