Déclencheur Azure Event Hubs pour Azure FunctionsAzure Event Hubs trigger for Azure Functions

Cet article explique comment utiliser un déclencheur Azure Event Hubs pour Azure Functions.This article explains how to work with Azure Event Hubs trigger for Azure Functions. Azure Functions prend en charge les liaisons de déclencheur et les liaisons de sortie relatives à Event Hubs.Azure Functions supports trigger and output bindings for Event Hubs.

Pour plus d’informations sur les détails d’installation et de configuration, consultez la vue d’ensemble.For information on setup and configuration details, see the overview.

Utilisez le déclencheur de fonction pour répondre à un événement envoyé à un flux d’événements d’un hub d’événements.Use the function trigger to respond to an event sent to an event hub event stream. Vous devez disposer de l’accès en lecture au hub d’événements sous-jacent pour configurer le déclencheur.You must have read access to the underlying event hub to set up the trigger. Une fois la fonction déclenchée, le message passé à la fonction est du type chaîne.When the function is triggered, the message passed to the function is typed as a string.

Mise à l'échelleScaling

Chaque instance d’une fonction déclenchée par un événement est sauvegardée par une seule instance EventProcessorHost.Each instance of an event triggered function is backed by a single EventProcessorHost instance. Le déclencheur (alimenté par Event Hubs) garantit qu’une seule instance EventProcessorHost peut obtenir un bail sur une partition donnée.The trigger (powered by Event Hubs) ensures that only one EventProcessorHost instance can get a lease on a given partition.

Prenons, par exemple, le hub d’événements suivant :For example, consider an Event Hub as follows:

  • 10 partitions10 partitions
  • 1 000 événements répartis uniformément sur toutes les partitions, avec 100 messages dans chaque partition1,000 events distributed evenly across all partitions, with 100 messages in each partition

Lorsque votre fonction est activée pour la première fois, il n’existe qu’une seule instance de cette fonction.When your function is first enabled, there is only one instance of the function. Nous appellerons la première instance de fonction Function_0.Let's call the first function instance Function_0. La fonction Function_0 comprend une seule instance de EventProcessorHost qui détient un bail sur les dix partitions.The Function_0 function has a single instance of EventProcessorHost that holds a lease on all ten partitions. Cette instance lit les événements des partitions 0 à 9.This instance is reading events from partitions 0-9. À partir de là, l’un des événements suivants se produit :From this point forward, one of the following happens:

  • Les nouvelles instances de fonction ne sont pas nécessaires : Function_0 est capable de traiter l’ensemble des 1 000 événements avant que la logique de mise à l’échelle Functions ne prenne effet.New function instances are not needed: Function_0 is able to process all 1,000 events before the Functions scaling logic take effect. Dans ce cas, l’intégralité des 1 000 messages sont traités par Function_0.In this case, all 1,000 messages are processed by Function_0.

  • Une instance de fonction supplémentaire est ajoutée : la logique de mise à l’échelle Functions détermine que si Function_0 a plus de messages qu’elle ne peut en traiter, une instance d’application de fonction (Function_1) est ajoutée.An additional function instance is added: If the Functions scaling logic determines that Function_0 has more messages than it can process, a new function app instance (Function_1) is created. Cette nouvelle fonction a également une instance associée de EventProcessorHost.This new function also has an associated instance of EventProcessorHost. Comme les Event Hubs sous-jacents détectent qu’une nouvelle instance d’hôte tente de lire des messages, ils équilibrent la charge des partitions entre les instances d’hôte.As the underlying Event Hubs detect that a new host instance is trying read messages, it load balances the partitions across the host instances. Par exemple, les partitions 0 à 4 peuvent être affectées à Function_0, et les partitions 5 à 9 à Function_1.For example, partitions 0-4 may be assigned to Function_0 and partitions 5-9 to Function_1.

  • N instances de fonction supplémentaires sont ajoutées : Si la logique de mise à l’échelle de Functions détermine que Function_0 et Function_1 ont plus de messages qu’elles ne peuvent en traiter, de nouvelles instances d’application de fonction Functions_N sont créées.N more function instances are added: If the Functions scaling logic determines that both Function_0 and Function_1 have more messages than they can process, new Functions_N function app instances are created. Des applications sont créées jusqu’au point où N est supérieur au nombre de partitions de hub d’événements.Apps are created to the point where N is greater than the number of event hub partitions. Dans notre exemple, Event Hubs équilibre la charge des partitions, en l’occurrence, sur les instances Function_0...Functions_9.In our example, Event Hubs again load balances the partitions, in this case across the instances Function_0...Functions_9.

Au fur et à mesure de la mise à l’échelle, N instances est un nombre supérieur à celui des partitions du Event Hub.As scaling occurs, N instances is a number greater than the number of event hub partitions. Ce modèle est utilisé pour garantir que les instances EventProcessorHost sont toujours disponibles pour obtenir des verrous sur les partitions, à mesure que celles-ci sont mises à disposition par les autres instances.This pattern is used to ensure EventProcessorHost instances are available to obtain locks on partitions as they become available from other instances. Vous n’êtes facturé que pour les ressources utilisées lors de l’exécution de l’instance de la fonction.You are only charged for the resources used when the function instance executes. En d’autres mots, vous n’êtes pas facturé pour cet approvisionnement excessif.In other words, you are not charged for this over-provisioning.

Quand toutes les exécutions de fonction se terminent (avec ou sans erreurs), des points de contrôle sont ajoutés au compte de stockage associé.When all function execution completes (with or without errors), checkpoints are added to the associated storage account. Une fois les points de contrôle correctement créés, les 1 000 messages ne sont plus jamais récupérés.When check-pointing succeeds, all 1,000 messages are never retrieved again.

L’exemple suivant illustre un code de fonction C# qui consigne le corps du message du déclencheur de hub d’événements.The following example shows a C# function that logs the message body of the event hub trigger.

[FunctionName("EventHubTriggerCSharp")]
public static void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] string myEventHubMessage, ILogger log)
{
    log.LogInformation($"C# function triggered to process a message: {myEventHubMessage}");
}

Pour accéder aux métadonnées d’événement en code de fonction, effectuez une liaison avec l’objet EventData (nécessite une instruction using pour Microsoft.Azure.EventHubs).To get access to event metadata in function code, bind to an EventData object (requires a using statement for Microsoft.Azure.EventHubs). Vous pouvez également accéder aux mêmes propriétés à l’aide d’expressions de liaison dans la signature de la méthode.You can also access the same properties by using binding expressions in the method signature. L’exemple suivant montre deux façons d’obtenir les mêmes données :The following example shows both ways to get the same data:

[FunctionName("EventHubTriggerCSharp")]
public static void Run(
    [EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] EventData myEventHubMessage,
    DateTime enqueuedTimeUtc,
    Int64 sequenceNumber,
    string offset,
    ILogger log)
{
    log.LogInformation($"Event: {Encoding.UTF8.GetString(myEventHubMessage.Body)}");
    // Metadata accessed by binding to EventData
    log.LogInformation($"EnqueuedTimeUtc={myEventHubMessage.SystemProperties.EnqueuedTimeUtc}");
    log.LogInformation($"SequenceNumber={myEventHubMessage.SystemProperties.SequenceNumber}");
    log.LogInformation($"Offset={myEventHubMessage.SystemProperties.Offset}");
    // Metadata accessed by using binding expressions in method parameters
    log.LogInformation($"EnqueuedTimeUtc={enqueuedTimeUtc}");
    log.LogInformation($"SequenceNumber={sequenceNumber}");
    log.LogInformation($"Offset={offset}");
}

Pour recevoir des événements en lot, transformez string ou EventData en tableau.To receive events in a batch, make string or EventData an array.

Nota

Lors de la réception dans un lot, vous ne pouvez pas établir de liaison avec les paramètres de la méthode comme dans l’exemple ci-dessus avec DateTime enqueuedTimeUtc et vous devez les recevoir de chaque objet EventData.When receiving in a batch you cannot bind to method parameters like in the above example with DateTime enqueuedTimeUtc and must receive these from each EventData object

[FunctionName("EventHubTriggerCSharp")]
public static void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] EventData[] eventHubMessages, ILogger log)
{
    foreach (var message in eventHubMessages)
    {
        log.LogInformation($"C# function triggered to process a message: {Encoding.UTF8.GetString(message.Body)}");
        log.LogInformation($"EnqueuedTimeUtc={message.SystemProperties.EnqueuedTimeUtc}");
    }
}

Attributs et annotationsAttributes and annotations

Dans les bibliothèques de classes C#, utilisez l’attribut EventHubTriggerAttribute.In C# class libraries, use the EventHubTriggerAttribute attribute.

Le constructeur de l’attribut prend le nom du hub d’événements, le nom du groupe de consommateurs et le nom d’un paramètre d’application qui contient la chaîne de connexion.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. Pour plus d’informations sur ces paramètres, consultez la section de configuration du déclencheur.For more information about these settings, see the trigger configuration section. Voici un exemple d’attribut EventHubTriggerAttribute :Here's an EventHubTriggerAttribute attribute example:

[FunctionName("EventHubTriggerCSharp")]
public static void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] string myEventHubMessage, ILogger log)
{
    ...
}

Pour obtenir un exemple complet, consultez Déclencheur - exemple C#.For a complete example, see Trigger - C# example.

ConfigurationConfiguration

Le tableau suivant décrit les propriétés de configuration de liaison que vous définissez dans le fichier function.json et l’attribut EventHubTrigger.The following table explains the binding configuration properties that you set in the function.json file and the EventHubTrigger attribute.

Propriété function.jsonfunction.json property Propriété d’attributAttribute property DescriptionDescription
typetype n/an/a Cette propriété doit être définie sur eventHubTrigger.Must be set to eventHubTrigger. Cette propriété est définie automatiquement lorsque vous créez le déclencheur dans le portail Azure.This property is set automatically when you create the trigger in the Azure portal.
directiondirection n/an/a Cette propriété doit être définie sur in.Must be set to in. Cette propriété est définie automatiquement lorsque vous créez le déclencheur dans le portail Azure.This property is set automatically when you create the trigger in the Azure portal.
namename n/an/a Nom de la variable qui représente l’élément d’événement dans le code de la fonction.The name of the variable that represents the event item in function code.
pathpath EventHubNameEventHubName Functions 1.x uniquement.Functions 1.x only. Nom du hub d’événements.The name of the 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.When the event hub name is also present in the connection string, that value overrides this property at runtime.
eventHubNameeventHubName EventHubNameEventHubName Functions 2.x et versions ultérieures.Functions 2.x and higher. Nom du hub d’événements.The name of the 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.When the event hub name is also present in the connection string, that value overrides this property at runtime. Peut être référencé via les paramètres d’application %eventHubName%Can be referenced via app settings %eventHubName%
consumerGroupconsumerGroup ConsumerGroupConsumerGroup Propriété facultative qui définit le groupe de consommateurs utilisé pour l’abonnement à des événements dans le hub.An optional property that sets the consumer group used to subscribe to events in the hub. En cas d’omission, le groupe de consommateurs $Default est utilisé.If omitted, the $Default consumer group is used.
cardinalitécardinality n/an/a Utilisé pour toutes les autres langages non-C#.Used for all non-C# languages. Définissez sur many afin d’activer le traitement par lot.Set to many in order to enable batching. Si omis ou défini sur one, un message unique est transmis à la fonction.If omitted or set to one, a single message is passed to the function.

En C#, cette propriété est affectée automatiquement chaque fois que le déclencheur a un tableau pour le type.In C#, this property is automatically assigned whenever the trigger has an array for the type.
connectionconnection ConnectionConnection Le nom d’un paramètre d’application qui contient la chaîne de connexion à l’espace de noms du hub d’événements.The name of an app setting that contains the connection string to the event hub's namespace. Copiez cette chaîne de connexion en cliquant sur le bouton Informations de connexion pour l’espace de noms, et non pour le hub d’événements lui-même.Copy this connection string by clicking the Connection Information button for the namespace, not the event hub itself. Cette chaîne de connexion doit avoir au moins des droits de lecture pour activer le déclencheur.This connection string must have at least read permissions to activate the trigger.

Quand vous développez localement, les paramètres d’application vont dans le fichier local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Métadonnées d’événementEvent metadata

Le déclencheur Event Hubs fournit plusieurs propriétés de métadonnées.The Event Hubs trigger provides several metadata properties. Les propriétés de métadonnées peuvent être utilisées dans le cadre d’expressions de liaison dans d’autres liaisons ou en tant que paramètres dans votre code.Metadata properties can be used as part of binding expressions in other bindings or as parameters in your code. Les propriétés proviennent de la classe EventData.The properties come from the EventData class.

PropriétéProperty TypeType DescriptionDescription
PartitionContext PartitionContextPartitionContext Instance PartitionContext.The PartitionContext instance.
EnqueuedTimeUtc DateTime Le temps de file d’attente en UTC.The enqueued time in UTC.
Offset string Le décalage des données par rapport au flux de données de la partition Event Hub.The offset of the data relative to the Event Hub partition stream. Le décalage est une marque ou un identificateur pour un événement au sein du flux Event Hubs.The offset is a marker or identifier for an event within the Event Hubs stream. L’identificateur est unique au sein d’une partition du flux Event Hubs.The identifier is unique within a partition of the Event Hubs stream.
PartitionKey string La partition vers laquelle les données d’événement doivent être envoyées.The partition to which event data should be sent.
Properties IDictionary<String,Object> Les propriétés d’utilisateur pour les données d’événements.The user properties of the event data.
SequenceNumber Int64 Le numéro de séquence logique de l’événement.The logical sequence number of the event.
SystemProperties IDictionary<String,Object> Les propriétés système, y compris les données d’événement.The system properties, including the event data.

Consultez les exemples de code qui utilisent ces propriétés précédemment dans cet article.See code examples that use these properties earlier in this article.

Propriétés host.jsonhost.json properties

Le fichier host.json contient les paramètres qui contrôlent le comportement du déclencheur Event Hubs.The host.json file contains settings that control Event Hubs trigger behavior. La configuration diffère selon la version d’Azure Functions.The configuration is different depending on the Azure Functions version.

Functions 2.x et versions ultérieuresFunctions 2.x and higher

{
    "version": "2.0",
    "extensions": {
        "eventHubs": {
            "batchCheckpointFrequency": 5,
            "eventProcessorOptions": {
                "maxBatchSize": 256,
                "prefetchCount": 512
            },
            "initialOffsetOptions": {
                "type": "fromStart",
                "enqueuedTime": ""
            }
        }
    }
}  
PropriétéProperty DefaultDefault DescriptionDescription
batchCheckpointFrequencybatchCheckpointFrequency 11 Nombre de lots d’événements à traiter avant de créer un point de contrôle de curseur EventHub.The number of event batches to process before creating an EventHub cursor checkpoint.
eventProcessorOptions/maxBatchSizeeventProcessorOptions/maxBatchSize 1010 Nombre d’événements maximal reçu par boucle de réception.The maximum event count received per receive loop.
eventProcessorOptions/prefetchCounteventProcessorOptions/prefetchCount 300300 Nombre de prérécupérations par défaut utilisé par le EventProcessorHost sous-jacent.The default pre-fetch count used by the underlying EventProcessorHost. La valeur minimale autorisée est de 10.The minimum allowed value is 10.
initialOffsetOptions/typeinitialOffsetOptions/type fromStartfromStart Emplacement dans le flux d’événements à partir duquel démarrer le traitement lorsqu’il n’existe pas de point de contrôle dans le stockage.The location in the event stream from which to start processing when a checkpoint doesn't exist in storage. Les options sont fromStart, fromEnd ou fromEnqueuedTime.Options are fromStart , fromEnd or fromEnqueuedTime. fromEnd traite les nouveaux événements qui ont été mis en file d’attente après le début de l’exécution de l’application de fonction.fromEnd processes new events that were enqueued after the function app started running. S’applique à toutes les partitions.Applies to all partitions. Pour plus d’informations, consultez la documentation sur EventProcessorOptions.For more information, see the EventProcessorOptions documentation.
initialOffsetOptions/enqueuedTimeinitialOffsetOptions/enqueuedTime N/AN/A Spécifie la durée de mise en file d’attente de l’événement dans le flux à partir duquel commencer le traitement.Specifies the enqueued time of the event in the stream from which to start processing. Lorsque initialOffsetOptions/type est configuré sur fromEnqueuedTime, ce paramètre est obligatoire.When initialOffsetOptions/type is configured as fromEnqueuedTime, this setting is mandatory. Prend en charge une valeur temporelle dans n’importe quel format pris en charge par DateTime.Parse(), par exemple 2020-10-26T20:31Z.Supports time in any format supported by DateTime.Parse(), such as 2020-10-26T20:31Z. Par souci de clarté, vous devez également spécifier un fuseau horaire.For clarity, you should also specify a timezone. Lorsque aucun fuseau horaire n’est spécifié, Functions adopte le fuseau horaire local de l’ordinateur exécutant l’application de fonction, qui est l’heure UTC en cas d’exécution sur Azure.When timezone isn't specified, Functions assumes the local timezone of the machine running the function app, which is UTC when running on Azure. Pour plus d’informations, consultez la documentation sur EventProcessorOptions.For more information, see the EventProcessorOptions documentation.

Nota

Pour obtenir des informations de référence sur le fichier host.json dans Azure Functions 2.x et ultérieur, consultez Informations de référence sur le fichier host.json pour Azure Functions.For a reference of host.json in Azure Functions 2.x and beyond, see host.json reference for Azure Functions.

Functions 1.xFunctions 1.x

{
    "eventHub": {
      "maxBatchSize": 64,
      "prefetchCount": 256,
      "batchCheckpointFrequency": 1
    }
}
PropriétéProperty DefaultDefault DescriptionDescription
maxBatchSizemaxBatchSize 6464 Nombre d’événements maximal reçu par boucle de réception.The maximum event count received per receive loop.
prefetchCountprefetchCount n/an/a Prérécupérations par défaut utilisées par le EventProcessorHost sous-jacent.The default pre-fetch that will be used by the underlying EventProcessorHost.
batchCheckpointFrequencybatchCheckpointFrequency 11 Nombre de lots d’événements à traiter avant de créer un point de contrôle de curseur EventHub.The number of event batches to process before creating an EventHub cursor checkpoint.

Nota

Pour obtenir des informations de référence sur le fichier host.json dans Azure Functions 1.x, consultez Informations de référence sur le fichier host.json pour Azure Functions 1.x.For a reference of host.json in Azure Functions 1.x, see host.json reference for Azure Functions 1.x.

Étapes suivantesNext steps