Skip to content

Latest commit

 

History

History
98 lines (58 loc) · 7 KB

iot-hub-devguide-endpoints.md

File metadata and controls

98 lines (58 loc) · 7 KB
title description author manager ms.author ms.service services ms.topic ms.date ms.custom
Understand Azure IoT Hub endpoints | Microsoft Docs
Developer guide - reference information about IoT Hub device-facing and service-facing endpoints.
robinsh
philmea
robinsh
iot-hub
iot-hub
conceptual
06/10/2019
amqp
mqtt
Role: Cloud Development
Role: System Architecture

Reference - IoT Hub endpoints

[!INCLUDE iot-hub-basic]

IoT Hub names

You can find the hostname of the IoT hub that hosts your endpoints in the portal on your hub's Overview page. By default, the DNS name of an IoT hub looks like: {your iot hub name}.azure-devices.net.

List of built-in IoT Hub endpoints

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.

IoT Hub endpoints

The following list describes the endpoints:

  • Resource provider. The IoT Hub resource provider exposes 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 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 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. Each IoT hub exposes a set of service-facing HTTPS REST endpoint to query and update device twins (update tags and properties).

  • Jobs management. Each IoT hub exposes a set of service-facing HTTPS REST endpoint to query and manage jobs.

  • Device endpoints. For each device in the identity registry, IoT Hub exposes a set of endpoints. 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.

    • Send device-to-cloud messages. A device uses 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. HTTPS is not supported.

    • Receive direct method requests. A device uses this endpoint to listen for direct method's requests. HTTPS is not supported.

    [!INCLUDE iot-hub-include-x509-ca-signed-support-note]

  • Service endpoints. Each IoT hub exposes 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 compatible with Azure Event Hubs. 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. 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.

    • Receive operations monitoring events. This endpoint allows you to receive operations monitoring events if your IoT hub has been configured to emit them. For more information, see IoT Hub operations monitoring.

The Azure IoT 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

You can link existing Azure services in your subscription 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 cannot write directly to the additional endpoints. Learn more about message routing.

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

  • Azure Storage containers
  • Event Hubs
  • Service Bus Queues
  • Service Bus Topics

For the limits on the number of endpoints you can add, see Quotas and throttling.

Endpoint Health

[!INCLUDE iot-hub-endpoint-health]

Field gateways

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 might be a dedicated hardware device or a low-power computer running custom gateway software.

You can use Azure IoT Edge to implement a field gateway. IoT Edge offers functionality such as multiplexing communications from multiple devices onto the same IoT Hub connection.

Next steps

Other reference topics in this IoT Hub developer guide include: