Liaison de sortie Azure Event Hubs pour Azure Functions

Cet article explique comment utiliser des liaisons Azure Event Hubs pour Azure Functions. Azure Functions prend en charge des liaisons de déclencheur et de sortie pour des Event Hubs.

Pour plus d’informations sur les détails d’installation et de configuration, consultez la vue d’ensemble.

Utilisez la liaison de sortie Event Hubs pour écrire des événements dans un flux d’événements du hub d’événements. Vous devez disposer de l’autorisation d’envoi à un hub d’événements pour y écrire les événements.

Vérifiez que les références de package nécessaires sont en place avant d’essayer d’implémenter une liaison de sortie.

Important

Cet article utilise des onglets pour prendre en charge plusieurs versions du modèle de programmation Node.js. Le modèle v4 est en disponibilité générale. Il est conçu pour offrir une expérience plus flexible et intuitive aux développeurs JavaScript et TypeScript. Pour plus d’informations sur le fonctionnement du modèle v4, reportez-vous au guide du développeur Azure Functions Node.js. Pour plus d’informations sur les différences entre v3 et v4, consultez le guide de migration.

Azure Functions prend en charge deux modèles de programmation pour Python. La façon dont vous définissez vos liaisons dépend du modèle de programmation choisi.

v2

Le modèle de programmation Python v2 vous permet de définir des liaisons à l'aide d’éléments décoratifs directement dans le code de votre fonction Python. Pour plus d’informations, consultez le guide des développeurs Python.

v1

Le modèle de programmation Python v1 vous oblige à définir des liaisons dans un fichier function.json distinct dans le dossier de fonction. Pour plus d’informations, consultez le guide des développeurs Python.

Cet article prend en compte les deux modèles de programmation.

Exemple

Modèle de worker isolé

L’exemple suivant illustre une fonction C# qui écrit une chaîne de messages dans un Event Hub, en utilisant la valeur renvoyée par la méthode comme sortie :

[Function(nameof(EventHubFunction))]
[FixedDelayRetry(5, "00:00:10")]
[EventHubOutput("dest", Connection = "EventHubConnection")]
public string EventHubFunction(
    [EventHubTrigger("src", Connection = "EventHubConnection")] string[] input,
    FunctionContext context)
{
    _logger.LogInformation("First Event Hubs triggered message: {msg}", input[0]);

    var message = $"Output message created at {DateTime.Now}";
    return message;
}

Modèle in-process

Important

La prise en charge du modèle in-process prendra fin le 10 novembre 2026. Pour continuer à bénéficier d’une prise en charge complète, nous vous recommandons vivement de migrer vos applications vers le modèle worker isolé.

L’exemple suivant illustre une fonction C# qui écrit un message dans un hub d’événements, en utilisant la valeur retournée par la méthode comme sortie :

[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}";
}

L’exemple suivant montre comment utiliser l’interface IAsyncCollector pour envoyer un lot de messages. Ce scénario est courant lorsque vous traitez des messages provenant d’un hub d’événements et que vous envoyez le résultat à un autre hub d’événements.

[FunctionName("EH2EH")]
public static async Task Run(
    [EventHubTrigger("source", Connection = "EventHubConnectionAppSetting")] EventData[] events,
    [EventHub("dest", Connection = "EventHubConnectionAppSetting")]IAsyncCollector<EventData> outputEvents,
    ILogger log)
{
    foreach (EventData eventData in events)
    {
        // Do some processing:
        string newEventBody = DoSomething(eventData);

        // Queue the message to be sent in the background by adding it to the collector.
        // If only the event is passed, an Event Hubs partition to be assigned via
        // round-robin for each batch.
        await outputEvents.AddAsync(new EventData(newEventBody));

        // If your scenario requires that certain events are grouped together in an
        // Event Hubs partition, you can specify a partition key.  Events added with 
        // the same key will always be assigned to the same partition.        
        await outputEvents.AddAsync(new EventData(newEventBody), "sample-key");
    }
}

Modèle v4

L’exemple suivant montre une fonction TypeScript déclenchée par le minuteur qui envoie un seul message à un Event hub :

import { app, InvocationContext, output, Timer } from '@azure/functions';

export async function timerTrigger1(myTimer: Timer, context: InvocationContext): Promise<string> {
    const timeStamp = new Date().toISOString();
    return `Message created at: ${timeStamp}`;
}

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: output.eventHub({
        eventHubName: 'myeventhub',
        connection: 'MyEventHubSendAppSetting',
    }),
    handler: timerTrigger1,
});

Pour générer plusieurs messages, retournez un tableau au lieu d’un seul objet. Par exemple :

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

Modèle v3

Les exemples TypeScript ne sont pas documentés pour le modèle v3.

Modèle v4

L’exemple suivant montre une fonction JavaScript déclenchée par le minuteur qui envoie un seul message à un Event hub :

const { app, output } = require('@azure/functions');

const eventHubOutput = output.eventHub({
    eventHubName: 'myeventhub',
    connection: 'MyEventHubSendAppSetting',
});

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: eventHubOutput,
    handler: (myTimer, context) => {
        const timeStamp = new Date().toISOString();
        return `Message created at: ${timeStamp}`;
    },
});

Pour générer plusieurs messages, retournez un tableau au lieu d’un seul objet. Par exemple :

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

Modèle v3

L’exemple suivant illustre une liaison de déclencheur d’Event Hub dans un fichier function.json et une fonction qui utilise la liaison. La fonction écrit un message de sortie dans un Event Hub.

L’exemple suivant montre des données de liaison Event Hubs dans le fichier function.json, qui est différent pour la version 1.x du runtime Functions par rapport aux versions ultérieures.

{
    "type": "eventHub",
    "name": "outputEventHubMessage",
    "eventHubName": "myeventhub",
    "connection": "MyEventHubSendAppSetting",
    "direction": "out"
}

Voici le code JavaScript qui envoie un message unique :

module.exports = function (context, myTimer) {
    var timeStamp = new Date().toISOString();
    context.log('Message created at: ', timeStamp);   
    context.bindings.outputEventHubMessage = "Message created at: " + timeStamp;
    context.done();
};

Voici le code JavaScript qui envoie plusieurs messages :

module.exports = function(context) {
    var timeStamp = new Date().toISOString();
    var message = 'Message created at: ' + timeStamp;

    context.bindings.outputEventHubMessage = [];

    context.bindings.outputEventHubMessage.push("1 " + message);
    context.bindings.outputEventHubMessage.push("2 " + message);
    context.done();
};

Des exemples PowerShell complets sont à venir.

L'exemple suivant illustre une liaison entre un déclencheur Event Hub et une fonction Python qui utilise la liaison. La fonction écrit un message dans un hub d’événements. L’exemple varie selon l’utilisation du modèle de programmation Python v1 ou v2.

v2

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="eventhub_output")
@app.route(route="eventhub_output")
@app.event_hub_output(arg_name="event",
                      event_hub_name="<EVENT_HUB_NAME>",
                      connection="<CONNECTION_SETTING>")
def eventhub_output(req: func.HttpRequest, event: func.Out[str]):
    body = req.get_body()
    if body is not None:
        event.set(body.decode('utf-8'))
    else:    
        logging.info('req body is none')
    return 'ok'

Voici le code Python qui envoie plusieurs messages :

import logging
import azure.functions as func
from typing import List

app = func.FunctionApp()

@app.function_name(name="eventhub_output")
@app.route(route="eventhub_output")
@app.event_hub_output(arg_name="event",
                      event_hub_name="<EVENT_HUB_NAME>",
                      connection="<CONNECTION_SETTING>")

def eventhub_output(req: func.HttpRequest, event: func.Out[List[str]]) -> func.HttpResponse:
    my_messages=["message1", "message2","message3"]
    event.set(my_messages)
    return func.HttpResponse(f"Messages sent")

v1

Les exemples suivants illustrent les données de liaison Event Hubs dans le fichier function.json.

{
    "type": "eventHub",
    "name": "$return",
    "eventHubName": "myeventhub",
    "connection": "MyEventHubSendAppSetting",
    "direction": "out"
}

Voici le code Python qui envoie un message unique :

import datetime
import logging
import azure.functions as func


def main(timer: func.TimerRequest) -> str:
    timestamp = datetime.datetime.utcnow()
    logging.info('Message created at: %s', timestamp)
    return 'Message created at: {}'.format(timestamp)

Voici le code Python qui envoie plusieurs messages :

import logging
from typing import List
import azure.functions as func


def main(req: func.HttpRequest, messages:func.Out[List[str]]) -> func.HttpResponse:
    logging.info('Python HTTP trigger function processed a request.')
    messages.set([{"message1"}, {"message2"}])
    return func.HttpResponse(f"Messages sent")

L’exemple suivant illustre une fonction Java qui écrit un message contenant l’heure actuelle à l’attention d’un event hub.

@FunctionName("sendTime")
@EventHubOutput(name = "event", eventHubName = "samples-workitems", connection = "AzureEventHubConnection")
public String sendTime(
   @TimerTrigger(name = "sendTimeTrigger", schedule = "0 */5 * * * *") String timerInfo)  {
     return LocalDateTime.now().toString();
 }

Dans la bibliothèque du runtime des fonctions Java, utilisez l’annotation @EventHubOutput sur les paramètres dont la valeur serait publiée à l’attention d’Event Hubs. Le type de paramètre doit être OutputBinding<T>, où T désigne un POJO ou n’importe quel type Java natif.

Attributs

Les bibliothèques C# In-process et de processus Worker isolé utilisent des attributs pour configurer la liaison. Le script C# utilise à la place un fichier de configuration function.json comme décrit dans le guide de script C#.

Modèle de worker isolé

Utilisez l’attribut [EventHubOutputAttribute] pour définir une liaison de sortie vers un Event Hub, qui prend en charge les propriétés suivantes.

Paramètres	Description
EventHubName	Nom du hub d’événements. Lorsque le nom d’Event Hub est également présent dans la chaîne de connexion, sa valeur remplace cette propriété lors de l’exécution.
Connection	Nom d’un paramètre d’application ou d’une collection de paramètres qui spécifie la façon de se connecter à Event Hubs. Pour en savoir plus, consultez Connexions.

Modèle in-process

Utilisez l’attribut EventHubAttribute pour définir une liaison de sortie vers un Event Hub, qui prend en charge les propriétés suivantes.

Paramètres	Description
EventHubName	Nom du hub d’événements. Lorsque le nom d’Event Hub est également présent dans la chaîne de connexion, sa valeur remplace cette propriété lors de l’exécution.
Connection	Nom d’un paramètre d’application ou d’une collection de paramètres qui spécifie la façon de se connecter à Event Hubs. Pour en savoir plus, consultez Connexions.

Décorateurs

S’applique uniquement au modèle de programmation Python v2.

Pour les fonctions Python v2 définies à l’aide d’un décorateur, ces propriétés sont prises en charge pour event_hub_output:

Propriété	Description
arg_name	Nom de variable utilisé dans le code de la fonction qui représente l’événement.
event_hub_name	Nom de l’Event Hub. Lorsque le nom d’Event Hub est également présent dans la chaîne de connexion, sa valeur remplace cette propriété lors de l’exécution.
connection	Nom d’un paramètre d’application ou d’une collection de paramètres qui spécifie la façon de se connecter à Event Hubs. Pour en savoir plus, consultez Connexions.

Pour les fonctions Python définies à l'aide de function.json, consultez la section Configuration.

Annotations

Dans la bibliothèque du runtime des fonctions Java, utilisez l’annotation EventHubOutput sur les paramètres dont la valeur serait publiée à l’attention d’Event Hubs. Les paramètres suivants sont pris en charge sur l’annotation :

• name
• dataType
• eventHubName
• connection

Configuration

S’applique uniquement au modèle de programmation Python v1.

Modèle v4

Le tableau suivant explique les propriétés que vous pouvez définir pour l’objet options passé à la méthode output.eventHub().

Propriété	Description
eventHubName	Nom du hub d’événements. Lorsque le nom d’Event Hub est également présent dans la chaîne de connexion, sa valeur remplace cette propriété lors de l’exécution.
connection	Nom d’un paramètre d’application ou d’une collection de paramètres qui spécifie la façon de se connecter à Event Hubs. Pour en savoir plus, consultez Connexions.

Modèle v3

Le tableau suivant décrit les propriétés de configuration de liaison que vous définissez dans le fichier function.json.

Propriété	Description
type	Cette propriété doit être définie sur eventHub.
direction	Cette propriété doit être définie sur out. Ce paramètre est défini automatiquement lorsque vous créez la liaison dans le portail Azure.
name	Nom de variable utilisé dans le code de la fonction qui représente l’événement.
eventHubName	Nom du hub d’événements. Lorsque le nom d’Event Hub est également présent dans la chaîne de connexion, sa valeur remplace cette propriété lors de l’exécution.
connection	Nom d’un paramètre d’application ou d’une collection de paramètres qui spécifie la façon de se connecter à Event Hubs. Pour en savoir plus, consultez Connexions.

Le tableau suivant décrit les propriétés de configuration de la liaison que vous définissez dans le fichier function.json, qui diffère selon la version du runtime.

Functions 2.x et versions ultérieures

Propriété function.json	Description
type	Cette propriété doit être définie sur eventHub.
direction	Cette propriété doit être définie sur out. Ce paramètre est défini automatiquement lorsque vous créez la liaison dans le portail Azure.
name	Nom de variable utilisé dans le code de la fonction qui représente l’événement.
eventHubName	Functions 2.x et versions ultérieures. Nom du hub d’événements. Lorsque le nom d’Event Hub est également présent dans la chaîne de connexion, sa valeur remplace cette propriété lors de l’exécution.
connection	Nom d’un paramètre d’application ou d’une collection de paramètres qui spécifie la façon de se connecter à Event Hubs. Pour en savoir plus, consultez Connexions.

Functions 1.x

Propriété function.json	Description
type	Cette propriété doit être définie sur eventHub.
direction	Cette propriété doit être définie sur out. Ce paramètre est défini automatiquement lorsque vous créez la liaison dans le portail Azure.
name	Nom de variable utilisé dans le code de la fonction qui représente l’événement.
path	Functions 1.x uniquement. Nom du hub d’événements. Lorsque le nom d’Event Hub est également présent dans la chaîne de connexion, sa valeur remplace cette propriété lors de l’exécution.
connection	Nom d’un paramètre d’application ou d’une collection de paramètres qui spécifie la façon de se connecter à Event Hubs. Pour en savoir plus, consultez Connexions.

Lorsque vous développez en local, ajoutez vos paramètres d’application dans le fichier local.settings.json de la collection Values.

Usage

Le type de paramètre pris en charge par la liaison de sortie Event Hubs dépend de la version du runtime Functions, de la version du package d’extension et de la modalité C# utilisée.

Extension v5.x et versions ultérieures

Les fonctions de la bibliothèque de classes C# In-process prennent en charge les types suivants :

• Azure.Messaging.EventHubs.EventData
• String
• Tableau d’octets
• Objet CLR traditionnel (OCT)

Cette version d’EventData ne prend plus en charge le type hérité Body en faveur d’EventBody.

Envoyez des messages en utilisant un paramètre de méthode comme out string paramName. Pour écrire plusieurs messages, vous pouvez utiliser ICollector<EventData> ou IAsyncCollector<EventData> à la place de out string. Les clés de partition ne peuvent être utilisées qu’avec IAsyncCollector<EventData>.

Extension v3.x et versions ultérieures

Les fonctions de la bibliothèque de classes C# In-process prennent en charge les types suivants :

• Microsoft.Azure.EventHubs.EventData
• String
• Tableau d’octets
• Objet CLR traditionnel (OCT)

Envoyez des messages en utilisant un paramètre de méthode comme out string paramName. Pour écrire plusieurs messages, vous pouvez utiliser ICollector<string> ou IAsyncCollector<string> à la place de out string.

Extension v5.x et versions ultérieures

Lorsque vous souhaitez que la fonction écrive un seul événement, la liaison de sortie Event Hubs peut se lier aux types suivants :

Type	Description
string	Événement sous forme de chaîne. À utiliser quand l’événement est un texte simple.
byte[]	Octets de l’événement.
Types sérialisables JSON	Objet représentant l'événement. Cette fonction tente de sérialiser un objet CLR traditionnel (OCT) en données JSON.

Lorsque vous souhaitez que la fonction écrive plusieurs événements, la liaison de sortie Event Hubs peut se lier aux types suivants :

Type	Description
T[] où T est l’un des types d’événements uniques	Tableau contenant plusieurs événements. Chaque entrée représente un événement.

Pour d’autres scénarios de sortie, créez et utilisez un EventHubProducerClient avec d’autres types à partir d’Azure.Messaging.EventHubs directement. Consultez Inscrire des clients Azure pour obtenir un exemple d’utilisation de l’injection de dépendances pour créer un type de client à partir du Kit de développement logiciel (SDK) Azure.

Extension v3.x et versions ultérieures

Requiert la définition d’un type personnalisé ou l’utilisation d’une chaîne. Des options supplémentaires sont disponibles dans Extension v5.x+.

Il existe deux options pour produire en sortie un message Event Hubs à partir d’une fonction en utilisant l’annotation EventHubOutput :

• Valeur de retour : En appliquant l’annotation à la fonction elle-même, la valeur de retour de la fonction est conservée sous la forme d’un message Event Hubs.

• Impératif : pour définir explicitement la valeur du message, appliquez l’annotation à un paramètre spécifique du type OutputBinding<T>, où T est un POJO ou n’importe quel type Java natif. Avec cette configuration, le passage d’une valeur à la méthode setValue rend la valeur persistante en tant que message Event Hubs.

Des exemples PowerShell complets sont à venir.

Modèle v4

Accédez au message de sortie en retournant la valeur directement ou en utilisant context.extraOutputs.set().

Modèle v3

Accédez à l’événement de sortie à l’aide de context.bindings.<name> où <name> est la valeur spécifiée dans la propriété name de context.bindings.<name>.

Il existe deux options pour produire en sortie un message Event Hubs à partir d’une fonction :

• Valeur de retour : Définissez la propriété name dans function.json sur $return. Avec cette configuration, la valeur renvoyée de la fonction est conservée sous la forme d’un message Event Hubs.

• Impératif : Passez une valeur à la méthode set du paramètre déclaré en tant que type Out. La valeur transmise à set est conservée en tant que message d’Event Hubs.

Connexions

La propriété connection est une référence à la configuration de l’environnement qui spécifie la façon dont l’application doit se connecter à Event Hubs. Elle peut spécifier :

• Le nom d’un paramètre d’application contenant une chaîne de connexion
• Le nom d’un préfixe partagé pour plusieurs paramètres d’application, définissant ensemble une connexion basée sur l’identité.

Si la valeur configurée est à la fois une correspondance exacte pour un paramètre unique et une correspondance de préfixe pour d’autres paramètres, la correspondance exacte est utilisée.

Chaîne de connexion

Obtenez cette chaîne de connexion en cliquant sur le bouton Informations de connexion pour l’espace de noms, pas sur l’Event Hub lui-même. La chaîne de connexion doit correspondre à un espace de noms Event Hubs, pas au Event Hub lui-même.

Quand la chaîne de connexion est utilisée pour les déclencheurs, elle doit disposer au moins des autorisation d’accès en lecture pour activer la fonction. Quand elle est utilisée pour les liaisons de sortie, la chaîne de connexion doit disposer des autorisations « Envoyer » pour envoyer des messages au flux d’événements.

Cette chaîne de connexion doit être stockée dans un paramètre d’application dont le nom correspond à la valeur spécifiée par la propriété connection de la configuration de liaison.

Connexions basées sur l’identité

Si vous utilisez la version 5.x ou ultérieure de l’extension, au lieu d’utiliser une chaîne de connexion avec un secret, vous pouvez faire en sorte que l’application utilise une identité Microsoft Entra. Pour ce faire, vous devez définir les paramètres sous un préfixe commun qui correspond à la propriété connection dans le déclencheur et la configuration de liaison.

Dans ce mode, l’extension nécessite les propriétés suivantes :

Propriété	Modèle de variable d’environnement	Description	Valeur d'exemple
Espace de noms complet	<CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace	Espace de noms complet Event Hubs.	myeventhubns.servicebus.windows.net

Des propriétés supplémentaires peuvent être définies pour personnaliser la connexion. Consultez Propriétés communes pour les connexions basées sur l’identité.

Notes

Lorsque vous utilisez Azure App Configuration ou Key Vault pour fournir des paramètres pour les connexions d’identité managée, les noms de paramètres doivent utiliser un séparateur de clé valide tel que : ou / à la place de __ pour s’assurer que les noms sont résolus correctement.

Par exemple : <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace.

Quand elles sont hébergées dans le service Azure Functions, les connexions basées sur une identité utilisent une identité managée. L’identité attribuée par le système est utilisée par défaut, bien qu’une identité attribuée par l’utilisateur puisse être spécifiée avec les propriétés credential et clientID. Notez que la configuration d’une identité affectée par l’utilisateur avec un ID de ressource n’est pas prise en charge. Lors d’une exécution dans d’autres contextes, tels que le développement local, votre identité de développeur est utilisée à la place, même si cela peut être personnalisé. Consultez Développement local avec connexions basées sur une identité.

Accorder l’autorisation à l’identité

Quelle que soit l’identité utilisée, elle doit avoir les autorisations nécessaires pour effectuer les actions prévues. Pour la plupart des services Azure, cela signifie que vous devez attribuer un rôle dans Azure RBAC en utilisant des rôles intégrés ou personnalisés qui fournissent ces autorisations.

Important

Parmi les autorisations exposées par le service cible, certaines ne sont peut-être pas nécessaires pour tous les contextes. Dans la mesure du possible, adhérez au principe du privilège minimum, en accordant à l’identité uniquement les privilèges nécessaires. Par exemple, si l’application a juste besoin de pouvoir lire à partir d’une source de données, utilisez un rôle qui a uniquement l’autorisation de lecture. Il serait inapproprié d’attribuer un rôle qui autorise aussi l’écriture dans ce service, car ce serait une autorisation excessive pour une opération de lecture. De même, vous voudrez vous assurer que l’attribution de rôle est limitée aux seules ressources qui doivent être lues.

Vous devrez créer une attribution de rôle qui donne accès à votre Event Hub au moment de l’exécution. L’étendue de l’attribution de rôle peut être pour un espace de noms Event Hubs, ou pour le Event Hub lui-même. Les rôles de gestion comme Propriétaire ne sont pas suffisants. Le tableau suivant présente les rôles intégrés qui sont recommandés lors de l’utilisation de l’extension Event Hubs dans le cadre d’un fonctionnement normal. Votre application peut nécessiter des autorisations supplémentaires en fonction du code que vous écrivez.

Type de liaison	Exemples de rôles intégrés
Déclencheur	Récepteur de données Azure Event Hubs, Propriétaire de données Azure Event Hubs
Liaison de sortie	Expéditeur de données Azure Event Hubs

Exceptions et codes de retour

Liaison	Informations de référence
Event Hubs	Guide des opérations

Étapes suivantes

• Répondre aux événements envoyés à un flux d’événements Event Hub (déclencheur)