Déclencheur Azure Event Hubs pour Azure Functions

  • Article

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

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

Utilisez le déclencheur de fonction pour répondre à un événement envoyé à un flux d’événements d’un hub d’événements. Vous devez disposer de l’accès en lecture au hub d’événements sous-jacent pour configurer le déclencheur. Une fois la fonction déclenchée, le message passé à la fonction est du type chaîne.

Les décisions de mise à l’échelle d’Event Hubs pour les plans Consommation et Premium sont effectuées au moyen de la mise à l’échelle basée sur la cible. Pour plus d’informations, consultez l’article Mise à l’échelle basée sur la cible.

Pour plus d’informations sur la façon dont Azure Functions répond aux événements envoyés à un flux d’événements Event Hub au moyen de déclencheurs, consultez Intégrer Event Hubs à des fonctions serverless dans Azure.

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.

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.

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

Important

Le modèle de programmation Python v2 est actuellement en préversion.

Exemple

L’exemple suivant illustre une fonction C# qui consigne le corps du message du déclencheur Event Hubs.

[FunctionName("EventHubTriggerCSharp")]
public 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 dans le code de la fonction, effectuez une liaison avec l’objet EventData. Vous pouvez également accéder aux mêmes propriétés à l’aide d’expressions de liaison dans la signature de la méthode. L’exemple suivant montre deux façons d’obtenir les mêmes données :

[FunctionName("EventHubTriggerCSharp")]
public 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.

Notes

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.

[FunctionName("EventHubTriggerCSharp")]
public 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}");
    }
}

L’exemple suivant illustre une liaison de déclencheur Event Hubs dans un fichier function.json et une fonction JavaScript qui utilise la liaison. La fonction lit les métadonnées d’événement et enregistre le message.

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": "eventHubTrigger",
  "name": "myEventHubMessage",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

Voici le code JavaScript :

module.exports = function (context, myEventHubMessage) {
    context.log('Function triggered to process a message: ', myEventHubMessage);
    context.log('EnqueuedTimeUtc =', context.bindingData.enqueuedTimeUtc);
    context.log('SequenceNumber =', context.bindingData.sequenceNumber);
    context.log('Offset =', context.bindingData.offset);

    context.done();
};

Pour recevoir les événements dans un lot, définissez cardinality sur many dans le fichier cardinality, comme le montrent les exemples suivants.

{
  "type": "eventHubTrigger",
  "name": "eventHubMessages",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "cardinality": "many",
  "connection": "myEventHubReadConnectionAppSetting"
}

Voici le code JavaScript :

module.exports = function (context, eventHubMessages) {
    context.log(`JavaScript eventhub trigger function called for message array ${eventHubMessages}`);

    eventHubMessages.forEach((message, index) => {
        context.log(`Processed message ${message}`);
        context.log(`EnqueuedTimeUtc = ${context.bindingData.enqueuedTimeUtcArray[index]}`);
        context.log(`SequenceNumber = ${context.bindingData.sequenceNumberArray[index]}`);
        context.log(`Offset = ${context.bindingData.offsetArray[index]}`);
    });

    context.done();
};

Voici le code PowerShell :

param($eventHubMessages, $TriggerMetadata)

Write-Host "PowerShell eventhub trigger function called for message array: $eventHubMessages"

$eventHubMessages | ForEach-Object { Write-Host "Processed message: $_" }

L'exemple suivant illustre une liaison entre un déclencheur Event Hubs et une fonction Python qui utilise la liaison. La fonction lit les métadonnées d’événement et enregistre le message. L’exemple varie selon l’utilisation du modèle de programmation Python v1 ou v2.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="EventHubTrigger1")
@app.event_hub_message_trigger(arg_name="myhub", 
                               event_hub_name="<EVENT_HUB_NAME>",
                               connection="<CONNECTION_SETTING>") 
def test_function(myhub: func.EventHubEvent):
    logging.info('Python EventHub trigger processed an event: %s',
                myhub.get_body().decode('utf-8'))

L’exemple suivant illustre une liaison de déclencheur Event Hubs qui journalise le corps du message du déclencheur Event Hubs.

@FunctionName("ehprocessor")
public void eventHubProcessor(
  @EventHubTrigger(name = "msg",
                  eventHubName = "myeventhubname",
                  connection = "myconnvarname") String message,
       final ExecutionContext context )
       {
          context.getLogger().info(message);
 }

Dans la bibliothèque du runtime des fonctions Java, utilisez l’annotation EventHubTrigger sur les paramètres dont la valeur provient d’Event Hub. Les paramètres ayant ces annotations entraînent l’exécution de la fonction quand un événement se produit. Vous pouvez utiliser cette annotation avec des types Java natifs, des objets POJO ou des valeurs Null à l’aide de Optional<T>.

L’exemple suivant illustre une utilisation poussée de SystemProperties et autres options de liaison pour une plus grande introspection de l’événement, ainsi qu’un chemin BlobOutput bien formé qui suit une hiérarchie selon la date.

package com.example;
import java.util.Map;
import java.time.ZonedDateTime;

import com.microsoft.azure.functions.annotation.*;
import com.microsoft.azure.functions.*;

/**
 * Azure Functions with Event Hub trigger.
 * and Blob Output using date in path along with message partition ID
 * and message sequence number from EventHub Trigger Properties
 */
public class EventHubReceiver {

    @FunctionName("EventHubReceiver")
    @StorageAccount("bloboutput")

    public void run(
            @EventHubTrigger(name = "message",
                eventHubName = "%eventhub%",
                consumerGroup = "%consumergroup%",
                connection = "eventhubconnection",
                cardinality = Cardinality.ONE)
            String message,

            final ExecutionContext context,

            @BindingName("Properties") Map<String, Object> properties,
            @BindingName("SystemProperties") Map<String, Object> systemProperties,
            @BindingName("PartitionContext") Map<String, Object> partitionContext,
            @BindingName("EnqueuedTimeUtc") Object enqueuedTimeUtc,

            @BlobOutput(
                name = "outputItem",
                path = "iotevents/{datetime:yy}/{datetime:MM}/{datetime:dd}/{datetime:HH}/" +
                       "{datetime:mm}/{PartitionContext.PartitionId}/{SystemProperties.SequenceNumber}.json")
            OutputBinding<String> outputItem) {

        var et = ZonedDateTime.parse(enqueuedTimeUtc + "Z"); // needed as the UTC time presented does not have a TZ
                                                             // indicator
        context.getLogger().info("Event hub message received: " + message + ", properties: " + properties);
        context.getLogger().info("Properties: " + properties);
        context.getLogger().info("System Properties: " + systemProperties);
        context.getLogger().info("partitionContext: " + partitionContext);
        context.getLogger().info("EnqueuedTimeUtc: " + et);

        outputItem.setValue(message);
    }
}

Attributs

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

Dans les bibliothèques de classes C#, utilisez l’attribut EventHubTriggerAttribute, 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. Peut être référencé dans les paramètres d’application, par exemple %eventHubName%.
ConsumerGroup Propriété facultative qui définit le groupe de consommateurs utilisé pour l’abonnement à des événements dans le hub. S’il est omis, le groupe de consommateurs $Default est utilisé.
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 élément décoratif, les propriétés suivantes sur cosmos_db_trigger :

Propriété Description
arg_name Nom de la variable qui représente l’élément d’événement dans le code de la fonction.
event_hub_name 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. Consultez Connexions.

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

Annotations

Dans la bibliothèque du runtime Functions Java, utilisez l’annotation EventHubTrigger, qui prend en charge les paramètres suivants :

Configuration

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

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

Propriété function.json Description
type Cette propriété doit être définie sur eventHubTrigger. Cette propriété est définie automatiquement lorsque vous créez le déclencheur dans le portail Azure.
direction Cette propriété doit être définie sur in. Cette propriété est définie automatiquement lorsque vous créez le déclencheur dans le portail Azure.
name Nom de la variable qui représente l’élément d’événement dans le code de la fonction.
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. Peut être référencé via les paramètres d’application
consumerGroup Propriété facultative qui définit le groupe de consommateurs utilisé pour l’abonnement à des événements dans le hub. En cas d’omission, le groupe de consommateurs $Default est utilisé.
cardinalité Définissez sur many afin d’activer le traitement par lot. Si omis ou défini sur one, un message unique est transmis à la fonction.
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. Consultez Connexions.

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

Utilisation

Pour en savoir plus sur la mise à l’échelle des déclencheurs Event Hubs et IoT Hub, consultez Consommation d’événements avec Azure Functions.

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.

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

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

Le type de paramètre peut être l’un des suivants :

  • Tout type Java natif, tel que int, String, byte[].
  • Valeurs Null utilisant l’option Facultatif.
  • Tout type POJO.

Pour en savoir plus, consultez la référence EventHubTrigger.

Métadonnées d’événement

Le déclencheur Event Hubs fournit plusieurs propriétés de métadonnées. 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. Les propriétés proviennent de la classe EventData.

Propriété Type Description
PartitionContext PartitionContext Instance PartitionContext.
EnqueuedTimeUtc DateTime Le temps de file d’attente en UTC.
Offset string Le décalage des données par rapport au flux de données de la partition Event Hub. Le décalage est une marque ou un identificateur pour un événement au sein du flux Event Hubs. L’identificateur est unique au sein d’une partition du flux Event Hubs.
PartitionKey string La partition vers laquelle les données d’événement doivent être envoyées.
Properties IDictionary<String,Object> Les propriétés d’utilisateur pour les données d’événements.
SequenceNumber Int64 Le numéro de séquence logique de l’événement.
SystemProperties IDictionary<String,Object> Les propriétés système, y compris les données d’événement.

Consultez les exemples de code qui utilisent ces propriétés précédemment dans cet article.

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 :

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 une version 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é Azure Active Directory. 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. <event_hubs_namespace>.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

Paramètres host.json

Le fichier host.json contient les paramètres qui contrôlent le comportement du déclencheur Event Hubs. Consultez la section Paramètres host.json pour plus d’informations concernant les paramètres disponibles.

Étapes suivantes