Azure Event Hubs output binding for Azure Functions
This article explains how to work with Azure Event Hubs bindings for Azure Functions. Azure Functions supports trigger and output bindings for Event Hubs.
For information on setup and configuration details, see the overview.
Use the Event Hubs output binding to write events to an event stream. You must have send permission to an event hub to write events to it.
Make sure the required package references are in place before you try to implement an output binding.
The following example shows a C# function that writes a message to an event hub, using the method return value as the output:
[FunctionName("EventHubOutput")]
[return: EventHub("outputEventHubMessage", Connection = "EventHubConnectionAppSetting")]
public static string Run([TimerTrigger("0 */5 * * * *")] TimerInfo myTimer, ILogger log)
{
log.LogInformation($"C# Timer trigger function executed at: {DateTime.Now}");
return $"{DateTime.Now}";
}
The following example shows how to use the IAsyncCollector interface to send a batch of messages. This scenario is common when you are processing messages coming from one Event Hub and sending the result to another Event Hub.
[FunctionName("EH2EH")]
public static async Task Run(
[EventHubTrigger("source", Connection = "EventHubConnectionAppSetting")] EventData[] events,
[EventHub("dest", Connection = "EventHubConnectionAppSetting")]IAsyncCollector<string> outputEvents,
ILogger log)
{
foreach (EventData eventData in events)
{
// do some processing:
var myProcessedEvent = DoSomething(eventData);
// then send the message
await outputEvents.AddAsync(JsonConvert.SerializeObject(myProcessedEvent));
}
}
Attributes and annotations
For C# class libraries, use the EventHubAttribute attribute.
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:
[FunctionName("EventHubOutput")]
[return: EventHub("outputEventHubMessage", Connection = "EventHubConnectionAppSetting")]
public static string Run([TimerTrigger("0 */5 * * * *")] TimerInfo myTimer, ILogger log)
{
...
}
For a complete example, see Output - C# example.
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 and higher. 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 or setting collection that specifies how to connect to Event Hubs. See Connections. |
When you're developing locally, app settings go into the local.settings.json file.
Connections
The connection property is a reference to environment configuration which specifies how the app should connect to Event Hubs. It may specify:
- The name of an application setting containing a connection string
- The name of a shared prefix for multiple application settings, together defining an identity-based connection.
If the configured value is both an exact match for a single setting and a prefix match for other settings, the exact match is used.
Connection string
Obtain this connection string by clicking the Connection Information button for the namespace, not the event hub itself. The connection string must be for an Event Hubs namespace, not the event hub itself.
When used for triggers, the connection string must have at least "read" permissions to activate the function. When used for output bindings, the connection string must have "send" permissions to send messages to the event stream.
This connection string should be stored in an application setting with a name matching the value specified by the connection property of the binding configuration.
Identity-based connections
If you are using version 5.x or higher of the extension, instead of using a connection string with a secret, you can have the app use an Azure Active Directory identity. To do this, you would define settings under a common prefix which maps to the connection property in the trigger and binding configuration.
In this mode, the extension requires the following properties:
| Property | Environment variable template | Description | Example value |
|---|---|---|---|
| Fully Qualified Namespace | <CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace |
The fully qualified Event Hubs namespace. | <event_hubs_namespace>.servicebus.windows.net |
Additional properties may be set to customize the connection. See Common properties for identity-based connections.
When hosted in the Azure Functions service, identity-based connections use a managed identity. The system-assigned identity is used by default, although a user-assigned identity can be specified with the credential and clientID properties. When run in other contexts, such as local development, your developer identity is used instead, although this can be customized. See Local development with identity-based connections.
Grant permission to the identity
Whatever identity is being used must have permissions to perform the intended actions. You will need to assign a role in Azure RBAC, using either built-in or custom roles which provide those permissions.
Important
Some permissions might be exposed by the target service that are not necessary for all contexts. Where possible, adhere to the principle of least privilege, granting the identity only required privileges. For example, if the app only needs to be able to read from a data source, use a role that only has permission to read. It would be inappropriate to assign a role that also allows writing to that service, as this would be excessive permission for a read operation. Similarly, you would want to ensure the role assignment is scoped only over the resources that need to be read.
You will need to create a role assignment that provides access to your event hub at runtime. The scope of the role assignment must be for an Event Hubs namespace, not the event hub itself. Management roles like Owner are not sufficient. The following table shows built-in roles that are recommended when using the Event Hubs extension in normal operation. Your application may require additional permissions based on the code you write.
| Binding type | Example built-in roles |
|---|---|
| Trigger | Azure Event Hubs Data Receiver, Azure Event Hubs Data Owner |
| Output binding | Azure Event Hubs Data Sender |
Usage
Default
You can use the following parameter types for the output binding of Event Hub:
stringbyte[]POCOEventData- The default properties of EventData are provided in the for the Microsoft.Azure.EventHubs namespace.
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.
Additional types
Apps using the 5.0.0 or higher version of the Event Hub extension use the EventData type in Azure.Messaging.EventHubs instead of the one in Microsoft.Azure.EventHubs namespace. This version drops support for the legacy Body type in favor of the following types:
Exceptions and return codes
| Binding | Reference |
|---|---|
| Event Hub | Operations Guide |