Partager via

Déclencheur Azure IoT Hub pour Azure Functions

  • Article

Cet article explique comment utiliser des liaisons Azure Functions pour IoT Hub. La prise en charge d'IoT Hub repose sur la liaison Azure Event Hubs.

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

Important

Si les exemples de code suivants utilisent l'API Event Hub, la syntaxe donnée s'applique aux fonctions IoT Hub.

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.

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.

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.

Exemple

L’exemple suivant montre une fonction C# qui est déclenchée en fonction d’un Event Hub, où la chaîne de message d’entrée est écrite dans les journaux :

{
    private readonly ILogger<EventHubsFunction> _logger;

    public EventHubsFunction(ILogger<EventHubsFunction> logger)
    {
        _logger = logger;
    }

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

L’exemple suivant montre une fonction TypeScript du déclencheur Event Hubs. La fonction lit les métadonnées d’événement et enregistre le message.

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

export async function eventHubTrigger1(message: unknown, context: InvocationContext): Promise<void> {
    context.log('Event hub function processed message:', message);
    context.log('EnqueuedTimeUtc =', context.triggerMetadata.enqueuedTimeUtc);
    context.log('SequenceNumber =', context.triggerMetadata.sequenceNumber);
    context.log('Offset =', context.triggerMetadata.offset);
}

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'one',
    handler: eventHubTrigger1,
});

Pour recevoir des événements dans un lot, définissez cardinality sur many comme le montre l’exemple suivant.

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

export async function eventHubTrigger1(messages: unknown[], context: InvocationContext): Promise<void> {
    context.log(`Event hub function processed ${messages.length} messages`);
    for (let i = 0; i < messages.length; i++) {
        context.log('Event hub message:', messages[i]);
        context.log(`EnqueuedTimeUtc = ${context.triggerMetadata.enqueuedTimeUtcArray[i]}`);
        context.log(`SequenceNumber = ${context.triggerMetadata.sequenceNumberArray[i]}`);
        context.log(`Offset = ${context.triggerMetadata.offsetArray[i]}`);
    }
}

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'many',
    handler: eventHubTrigger1,
});

L’exemple suivant montre une fonction JavaScript du déclencheur Event Hubs. La fonction lit les métadonnées d’événement et enregistre le message.

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

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'one',
    handler: (message, context) => {
        context.log('Event hub function processed message:', message);
        context.log('EnqueuedTimeUtc =', context.triggerMetadata.enqueuedTimeUtc);
        context.log('SequenceNumber =', context.triggerMetadata.sequenceNumber);
        context.log('Offset =', context.triggerMetadata.offset);
    },
});

Pour recevoir des événements dans un lot, définissez cardinality sur many comme le montre l’exemple suivant.

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

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'many',
    handler: (messages, context) => {
        context.log(`Event hub function processed ${messages.length} messages`);
        for (let i = 0; i < messages.length; i++) {
            context.log('Event hub message:', messages[i]);
            context.log(`EnqueuedTimeUtc = ${context.triggerMetadata.enqueuedTimeUtcArray[i]}`);
            context.log(`SequenceNumber = ${context.triggerMetadata.sequenceNumberArray[i]}`);
            context.log(`Offset = ${context.triggerMetadata.offsetArray[i]}`);
        }
    },
});

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 comme décrit dans le guide de script C#.

Utilisez EventHubTriggerAttribute pour définir un déclencheur sur 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. 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 event_hub_message_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 explique les propriétés que vous pouvez définir pour l’objet options passé à la méthode app.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. Peut être référencé via les paramètres d’application %eventHubName%
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.

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 %eventHubName%
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 Values.

Usage

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.

Quand vous souhaitez que la fonction traite un seul événement, le déclencheur 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 Quand un événement contient des données JSON, Functions tente de désérialiser les données JSON dans un type d’Objet CLR traditionnel (OCT).
Azure.Messaging.EventHubs.EventData1 Objet événement.
Si vous effectuez une migration à partir d’anciennes versions des kits de développement logiciel (SDK) Event Hubs, notez que cette version supprime la prise en charge du type hérité Body au profit d’EventBody.

Quand vous souhaitez que la fonction traite un lot d’événements, le déclencheur Event Hubs peut se lier aux types suivants :

Type Description
string[] Tableau d’événements du lot, sous forme de chaînes. Chaque entrée représente un événement.
EventData[] 1 Tableau d’événements du lot, en tant qu’instances d’Azure.Messaging.EventHubs.EventData. Chaque entrée représente un événement.
T[] where T est un type sérialisable JSON1 Tableau d’événements du lot, en tant qu’instances d’un type POCO personnalisé. Chaque entrée représente un événement.

1 Pour utiliser ces types, vous devez référencer Microsoft.Azure.Functions.Worker.Extensions.EventHubs 5.5.0 ou une version ultérieure et les dépendances courantes pour les liaisons de type kit de développement logiciel (SDK).

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 contient le nom d’un paramètre d’application contenant une chaîne de connexion. Vous pouvez obtenir cette chaîne de connexion en sélectionnant le bouton Informations de connexion pour l'espace de noms. La chaîne de connexion doit correspondre à un espace de noms Event Hubs, pas au Event Hub lui-même.

Cette chaîne de connexion doit avoir au moins des droits de « lecture » pour activer la fonction.

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.

Notes

Les connexions basées sur l’identité ne sont pas prises en charge par le déclencheur IoT Hub. Si vous devez utiliser des identités managées de bout en bout, vous pouvez plutôt utiliser le routage IoT Hub pour envoyer des données à un Event Hub que vous contrôlez. De cette façon, le routage sortant peut être authentifié avec une identité managée. L’événement peut alors être lu à partir de cet Event Hub à l’aide de l’identité managée.

Propriétés host.json

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

Étapes suivantes