Trigger

Use the Event Hubs trigger to respond to an event sent to an event hub event stream. You must have read access to the event hub to set up the trigger.

When an Event Hubs trigger function is triggered, the message that triggers it is passed into the function as a string.

Trigger - scaling

Each instance of an Event Hub-Triggered Function is backed by only 1 EventProcessorHost (EPH) instance. Event Hubs ensures that only 1 EPH can get a lease on a given partition.

For example, suppose we begin with the following setup and assumptions for an Event Hub:

10 partitions.

1000 events distributed evenly across all partitions => 100 messages in each partition.

When your function is first enabled, there is only 1 instance of the function. Let's call this function instance Function_0. Function_0 will have 1 EPH that manages to get a lease on all 10 partitions. It will start reading events from partitions 0-9. From this point forward, one of the following will happen:

Only 1 function instance is needed - Function_0 is able to process all 1000 before the Azure Functions' scaling logic kicks in. Hence, all 1000 messages are processed by Function_0.

Add 1 more function instance - Azure Functions' scaling logic determines that Function_0 has more messages than it can process, so a new instance, Function_1, is created. Event Hubs detects that a new EPH instance is trying read messages. Event Hubs will start load balancing the partitions across the EPH instances, e.g., partitions 0-4 are assigned to Function_0 and partitions 5-9 are assigned to Function_1.

Add N more function instances - Azure Functions' scaling logic determines that both Function_0 and Function_1 have more messages than they can process. It will scale again for Function_2...N, where N is greater than the Event Hub partitions. Event Hubs will load balance the partitions across Function_0...9 instances.

Unique to Azure Functions' current scaling logic is the fact that N is greater than the number of partitions. This is done to ensure that there are always instances of EPH readily available to quickly get a lock on the partition(s) as they become available from other instances. Users are only charged for the resources used when the function instance executes, and are not charged for this over-provisioning.

If all function executions succeed without errors, checkpoints are added to the associated storage account. When check-pointing succeeds, all 1000 messages should never be retrieved again.

To get access to event metadata in function code, bind to an EventData object (requires a using statement for Microsoft.ServiceBus.Messaging). You can also access the same properties by using binding expressions in the method signature. The following example shows both ways to get the same data:

To get access to event metadata in function code, bind to an EventData object (requires a using statement for Microsoft.ServiceBus.Messaging). You can also access the same properties by using binding expressions in the method signature. The following example shows both ways to get the same data:

Trigger - attributes

The attribute's constructor takes the name of the event hub, the name of the consumer group, and the name of an app setting that contains the connection string. For more information about these settings, see the trigger configuration section. Here's an EventHubTriggerAttribute attribute example:

Trigger - configuration

The following table explains the binding configuration properties that you set in the function.json file and the EventHubTrigger attribute.

function.json property

Attribute property

Description

type

n/a

Must be set to eventHubTrigger. This property is set automatically when you create the trigger in the Azure portal.

direction

n/a

Must be set to in. This property is set automatically when you create the trigger in the Azure portal.

name

n/a

The name of the variable that represents the event item in function code.

path

EventHubName

Functions 1.x only. The name of the event hub. When the event hub name is also present in the connection string, that value overrides this property at runtime.

eventHubName

EventHubName

Functions 2.x only. The name of the event hub. When the event hub name is also present in the connection string, that value overrides this property at runtime.

consumerGroup

ConsumerGroup

An optional property that sets the consumer group used to subscribe to events in the hub. If omitted, the $Default consumer group is used.

cardinality

n/a

For Javascript. Set to many in order to enable batching. If omitted or set to one, single message passed to function.

connection

Connection

The name of an app setting that contains the connection string to the event hub's namespace. Copy this connection string by clicking the Connection Information button for the namespace, not the event hub itself. This connection string must have at least read permissions to activate the trigger.

Trigger - event metadata

The Event Hubs trigger provides several metadata properties. These properties can be used as part of binding expressions in other bindings or as parameters in your code. These are properties of the EventData class.

The offset of the data relative to the Event Hub partition stream. The offset is a marker or identifier for an event within the Event Hubs stream. The identifier is unique within a partition of the Event Hubs stream.

Output - attributes

The attribute's constructor takes the name of the event hub and the name of an app setting that contains the connection string. For more information about these settings, see Output - configuration. Here's an EventHub attribute example:

Output - configuration

The following table explains the binding configuration properties that you set in the function.json file and the EventHub attribute.

function.json property

Attribute property

Description

type

n/a

Must be set to "eventHub".

direction

n/a

Must be set to "out". This parameter is set automatically when you create the binding in the Azure portal.

name

n/a

The variable name used in function code that represents the event.

path

EventHubName

Functions 1.x only. The name of the event hub. When the event hub name is also present in the connection string, that value overrides this property at runtime.

eventHubName

EventHubName

Functions 2.x only. The name of the event hub. When the event hub name is also present in the connection string, that value overrides this property at runtime.

connection

Connection

The name of an app setting that contains the connection string to the event hub's namespace. Copy this connection string by clicking the Connection Information button for the namespace, not the event hub itself. This connection string must have send permissions to send the message to the event stream.

Output - usage

In C# and C# script, send messages by using a method parameter such as out string paramName. In C# script, paramName is the value specified in the name property of function.json. To write multiple messages, you can use ICollector<string> or
IAsyncCollector<string> in place of out string.

In JavaScript, access the output event by using context.bindings.<name>. <name> is the value specified in the name property of function.json.