| title | description | services | documentationcenter | author | manager | editor | ms.assetid | ms.service | ms.devlang | ms.topic | ms.tgt_pltfrm | ms.workload | ms.date | ms.author |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Understand Azure IoT Hub IoT Hub endpoints | Microsoft Docs |
Developer guide - reference information about IoT Hub device-facing and service-facing endpoints. |
iot-hub |
.net |
dominicbetts |
timlt |
57ba52ae-19c6-43e4-bc6c-d8a5c2476e95 |
iot-hub |
multiple |
article |
na |
na |
01/04/2017 |
dobett |
Azure IoT Hub is a multi-tenant service that exposes its functionality to various actors. The following diagram shows the various endpoints that IoT Hub exposes.
The following is a description of the endpoints:
-
Resource provider. The IoT Hub resource provider exposes an Azure Resource Manager interface that enables Azure subscription owners to create and delete IoT hubs, and update IoT hub properties. IoT Hub properties govern hub-level security 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. Each IoT hub exposes a set of HTTP REST endpoints to manage device identities (create, retrieve, update, and delete). Device identities are used for device authentication and access control.
-
Device twin management. Each IoT hub exposes a set of service-facing HTTP REST endpoint to query and update device twins (update tags and properties).
-
Jobs management. Each IoT hub exposes a set of service-facing HTTP REST endpoint to query and manage jobs.
-
Device endpoints. For each device provisioned in the identity registry, IoT Hub exposes a set of endpoints that a device can use to send and receive messages:
-
Send device-to-cloud messages. Use this endpoint to send device-to-cloud messages.
-
Receive cloud-to-device messages. A device uses this endpoint to receive targeted cloud-to-device messages.
-
Initiate file uploads. A device uses this endpoint to receive an Azure Storage SAS URI from IoT Hub to upload a file.
-
Retrieve and update device twin properties. A device uses this endpoint to access its device twin's properties.
-
Receive direct methods requests. A device uses this endpoint to listen to direct methods's requests.
These endpoints are exposed using MQTT v3.1.1, HTTP 1.1, and AMQP 1.0 protocols. Note that AMQP is also available over WebSockets on port 443.
The device twins and methods endpoints are available only using MQTT v3.1.1.
-
-
Service endpoints. Each IoT hub exposes a set of endpoints your solution back end can use to communicate with your devices. These endpoints are currently only exposed using the AMQP protocol, except for the method invocation endpoint that is exposed via HTTP 1.1.
- Receive device-to-cloud messages. This endpoint is compatible with Azure Event Hubs. A back-end service can use it to read all the device-to-cloud messages sent by your devices. You can add custom routing endpoints to your IoT hub in addition to this endpoint.
- Send cloud-to-device messages and receive delivery acknowledgments. These endpoints enable your solution back end to send reliable cloud-to-device messages, and to receive the corresponding delivery or expiration acknowledgments.
- Receive file notifications. This messaging endpoint allows you to receive notifications of when your devices successfully upload a file.
- Direct method invocation. This endpoint allows a back-end service to invoke a direct method on a device.
The Azure IoT SDKs article describes the various ways to access these endpoints.
Finally, it is important to note that all IoT Hub endpoints use the TLS protocol, and no endpoint is ever exposed on unencrypted/unsecured channels.
You can link existing Azure services in your subscription to your IoT Hub to be used as endpoints for message routing. These service endpoints are used as "sinks" for message routes. Devices cannot directly write to the additional endpoints. To learn more about message routes, see the developer guide entry on sending and receiving messages with IoT hub.
IoT Hub currently supports the following Azure services as additional endpoints:
- Event Hubs
- Service Bus Queues
- Service Bus Topics
IoT Hub needs write access to these endpoints for message routing to work. If you configure your endpoints through the Azure portal, the necessary permissions are added for you. Make sure you configure your services to support the expected throughput. You may need to monitor your additional endpoints when you first configure your IoT solution and then make any necessary adjustments for the actual load.
If a message matches multiple routes which all point to the same endpoint, IoT Hub delivers message to that endpoint only once. Therefore, you do not need to configure deduplication on your Service Bus queue or topic. In partitioned queues, partition affinity guarantees message ordering. Queues with sessions enabled are not supported as endpoints. Partitioned queues and topics with deduplication enabled are also not supported.
For the limits on the number of endpoints you may add, see Quotas and throttling.
In an IoT solution, a field gateway sits between your devices and your IoT Hub endpoints. It is typically located close to your devices. Your devices communicate directly with the field gateway by using a protocol supported by the devices. The field gateway connects to an IoT Hub endpoint using a protocol that is supported by IoT Hub. A field gateway can be highly specialized hardware or a low-power computer running software that accomplishes the end-to-end scenario for which the gateway is intended.
You can use the Azure IoT Gateway SDK to implement a field gateway. This SDK offers specific functionality such as the ability to multiplex the communication from multiple devices onto the same IoT Hub connection.
Other reference topics in this IoT Hub developer guide include: