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 and size for your solution.
IoT Hub namesYou 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
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 isn't yet generally available, and preview mode must be enabled:
These features are generally available on devices that use X.509 thumbprint authentication.
Custom endpoints for message routingYou 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:
For the limits on endpoints per hub, see Quotas and throttling.
Built-in endpointYou 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 endpointThere 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 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 endpointApart 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 endpointYou 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 HealthYou 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 stepsLearn more about these topics:
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4