Edit

Azure IoT Hub bindings for Azure Functions

  • Article
  • 7 minutes to read

This set of articles explains how to work with Azure Functions bindings for IoT Hub. The IoT Hub support is based on the Azure Event Hubs Binding.

Important

While the following code samples use the Event Hub API, the given syntax is applicable for IoT Hub functions.

Action Type
Respond to events sent to an IoT hub event stream. Trigger

Install extension

The extension NuGet package you install depends on the C# mode you're using in your function app:

Functions execute in the same process as the Functions host. To learn more, see Develop C# class library functions using Azure Functions.

The functionality of the extension varies depending on the extension version:

This version introduces the ability to connect using an identity instead of a secret. For a tutorial on configuring your function apps with managed identities, see the creating a function app with identity-based connections tutorial.

This version uses the newer Event Hubs binding type Azure.Messaging.EventHubs.EventData.

This extension version is available by installing the NuGet package, version 5.x.

Install bundle

The Event Hubs extension is part of an extension bundle, which is specified in your host.json project file. You may need to modify this bundle to change the version of the Event Grid binding, or if bundles aren't already installed. To learn more, see extension bundle.

This version introduces the ability to connect using an identity instead of a secret. For a tutorial on configuring your function apps with managed identities, see the creating a function app with identity-based connections tutorial.

You can add this version of the extension from the extension bundle v3 by adding or replacing the following code in your host.json file:

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

To learn more, see Update your extensions.

host.json settings

The host.json file contains settings that control behavior for the Event Hubs trigger. The configuration is different depending on the extension version.

{
    "version": "2.0",
    "extensions": {
        "eventHubs": {
            "maxEventBatchSize" : 10,
            "targetUnprocessedEventThreshold" : 75,
            "batchCheckpointFrequency" : 1,
            "prefetchCount" : 300,
            "transportType" : "amqpWebSockets",
            "webProxy" : "https://proxyserver:8080",
            "customEndpointAddress" : "amqps://company.gateway.local",
            "initialOffsetOptions" : {
                "type" : "fromStart",
                "enqueuedTimeUtc" : ""
            },
            "clientRetryOptions":{
                "mode" : "exponential",
                "tryTimeout" : "00:01:00",
                "delay" : "00:00:00.80",
                "maximumDelay" : "00:01:00",
                "maximumRetries" : 3
            }
        }
    }
}
Property Default Description
maxEventBatchSize 10 The maximum number of events that will be included in a batch for a single invocation. Must be at least 1.
targetUnprocessedEventThreshold null The desired number of unprocessed events per function instance. This is used in target-based scaling to override the default scaling threshold inferred from the maxEventBatchSize option. When set, the total unprocessed event count is divided by this value to determine the number of function instances needed, which is rounded up to a count that creates a balanced partition distribution.
batchCheckpointFrequency 1 The number of batches to process before creating a checkpoint for the event hub.
prefetchCount 300 The number of events that will be eagerly requested from Event Hubs and held in a local cache to allow reads to avoid waiting on a network operation
transportType amqpTcp The protocol and transport that is used for communicating with Event Hubs. Available options: amqpTcp, amqpWebSockets
webProxy null The proxy to use for communicating with Event Hubs over web sockets. A proxy cannot be used with the amqpTcp transport.
customEndpointAddress null The address to use when establishing a connection to Event Hubs, allowing network requests to be routed through an application gateway or other path needed for the host environment. The fully qualified namespace for the event hub is still needed when a custom endpoint address is used and must be specified explicitly or via the connection string.
initialOffsetOptions/type fromStart The location in the event stream to start processing when a checkpoint does not exist in storage. Applies to all partitions. For more information, see the OffsetType documentation. Available options: fromStart, fromEnd, fromEnqueuedTime
initialOffsetOptions/enqueuedTimeUtc null Specifies the enqueued time of the event in the stream from which to start processing. When initialOffsetOptions/type is configured as fromEnqueuedTime, this setting is mandatory. Supports time in any format supported by DateTime.Parse(), such as 2020-10-26T20:31Z. For clarity, you should also specify a timezone. When timezone isn't specified, Functions assumes the local timezone of the machine running the function app, which is UTC when running on Azure.
clientRetryOptions/mode exponential The approach to use for calculating retry delays. Exponential mode will retry attempts with a delay based on a back-off strategy where each attempt will increase the duration that it waits before retrying. The fixed mode will retry attempts at fixed intervals with each delay having a consistent duration. Available options: exponential, fixed
clientRetryOptions/tryTimeout 00:01:00 The maximum duration to wait for an Event Hubs operation to complete, per attempt.
clientRetryOptions/delay 00:00:00.80 The delay or back-off factor to apply between retry attempts.
clientRetryOptions/maximumDelay 00:00:01 The maximum delay to allow between retry attempts.
clientRetryOptions/maximumRetries 3 The maximum number of retry attempts before considering the associated operation to have failed.

The clientRetryOptions are used to retry operations between the Functions host and Event Hubs (such as fetching events and sending events). Please refer to guidance on Azure Functions error handling and retries for information on applying retry policies to individual functions.

For a reference of host.json in Azure Functions 2.x and beyond, see host.json reference for Azure Functions.

Next steps