Liaisons Azure IoT Hub pour Azure Functions

  • Article

Ces articles expliquent comment utiliser des liaisons Azure Functions pour IoT Hub. La prise en charge d'IoT Hub repose sur la liaison Azure Event Hubs.

Important

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

Action Type
Répondez aux événements envoyés à un flux d’événements IoT Hub. Déclencheur

Installer l’extension

Le package NuGet de l’extension que vous installez dépend du mode C# que vous utilisez dans votre application de fonction :

Les fonctions s’exécutent dans un processus de travail C# isolé. Pour en savoir plus, consultez Guide pour l’exécution d’Azure Functions C# dans un processus Worker isolé.

La fonctionnalité de l’extension varie en fonction de la version de l’extension :

Cette version introduit la possibilité de se connecter à l’aide d’une identité au lieu d’un secret. Pour obtenir un tutoriel sur la configuration de vos applications de fonction avec des identités managées, consultez le tutoriel sur la création d’une application de fonction avec des connexions basées sur l’identité.

Ajoutez l’extension à votre projet en installant le package NuGet, version 5.x.

Installer le bundle

L’extension Event Hubs fait partie d’une offre groupée d’extension, qui est spécifiée dans votre fichier projet host.json. Vous devrez peut-être modifier cette offre groupée pour modifier la version de la liaison ou si les offres groupées ne sont pas encore installées. Pour plus d’informations, consultez le bundle d’extensions.

Cette version introduit la possibilité de se connecter à l’aide d’une identité au lieu d’un secret. Pour obtenir un tutoriel sur la configuration de vos applications de fonction avec des identités managées, consultez le tutoriel sur la création d’une application de fonction avec des connexions basées sur l’identité.

Vous pouvez ajouter cette version de l’extension à partir de l’offre groupée d’extension v3 en ajoutant ou en remplaçant le code suivant dans votre fichier host.json :

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

Pour en savoir plus, consultez Mettre à jour vos extensions.

Types de liaisons

Les types de liaisons pris en charge pour .NET dépendent à la fois de la version de l’extension et du mode d’exécution C#, qui peut être l’un des suivants :

Une bibliothèque de classes de processus Worker isolé est une fonction C# compilée exécutée dans un processus Worker isolé du runtime.

Choisissez une version pour afficher les détails des types de liaison du mode et de la version.

Le processus Worker isolé prend en charge les types de paramètres en fonction des tableaux ci-dessous. La prise en charge de la liaison aux types à partir d’Azure.Messaging.EventHubs est en préversion.

Déclencheur Event Hubs

Lorsque 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).

Liaison de sortie Event Hubs

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 directement des types à partir de Microsoft.Azure.EventHubs.

Paramètres host.json

Le fichier host.json contient les paramètres qui contrôlent le comportement du déclencheur Event Hubs. La configuration diffère selon la version de l’extension.

{
    "version": "2.0",
    "extensions": {
        "eventHubs": {
            "maxEventBatchSize" : 100,
            "minEventBatchSize" : 25,
            "maxWaitTime" : "00:05:00",            
            "batchCheckpointFrequency" : 1,
            "prefetchCount" : 300,
            "transportType" : "amqpWebSockets",
            "webProxy" : "https://proxyserver:8080",
            "customEndpointAddress" : "amqps://company.gateway.local",
            "targetUnprocessedEventThreshold" : 75,
            "initialOffsetOptions" : {
                "type" : "fromStart",
                "enqueuedTimeUtc" : ""
            },
            "clientRetryOptions":{
                "mode" : "exponential",
                "tryTimeout" : "00:01:00",
                "delay" : "00:00:00.80",
                "maximumDelay" : "00:01:00",
                "maximumRetries" : 3
            }
        }
    }
}
Propriété Default Description
maxEventBatchSize2 100 Nombre maximal d’événements inclus dans un lot pour un seul appel. Doit être au moins égal à 1.
minEventBatchSize1 1 Nombre minimal d’événements souhaités dans un lot. La valeur minimale s’applique uniquement lorsque la fonction reçoit plusieurs événements et doit être inférieure à maxEventBatchSize.
La taille minimale n’est pas strictement garantie. Un lot partiel est distribué quand un lot complet ne peut pas être préparé avant l’expiration du maxWaitTime. Il est probable que des lots partiels le soient également en ce qui concerne le premier appel de la fonction après mise à l’échelle.
maxWaitTime1 00:01:00 Intervalle maximal devant être observé par le déclencheur pour remplir un lot avant d’appeler la fonction. Le temps d’attente est uniquement pris en compte lorsque minEventBatchSize est supérieur à 1 et est ignoré dans d’autres cas. Si moins de minEventBatchSize événements étaient disponibles avant l’expiration du temps d’attente, la fonction est appelée à l’aide d’un lot partiel. Le plus long temps d’attente autorisé est de 10 minutes.

REMARQUE : cet intervalle n’est pas une stricte garantie du minutage exact sur lequel la fonction est appelée. Il existe une petite marge d’erreur en raison de la précision du minuteur. Lorsque la mise à l’échelle a lieu, le premier appel avec un lot partiel peut se produire plus rapidement ou prendre jusqu’à deux fois le temps d’attente configuré.
batchCheckpointFrequency 1 Nombre de lots à traiter avant de créer un point de contrôle pour Event Hub.
prefetchCount 300 Nombre d’événements qui sont demandés de manière anticipée à partir d’Event Hubs et maintenus dans un cache local pour permettre aux lectures d’éviter d’attendre une opération réseau
transportType amqpTcp Protocole et transport utilisés pour communiquer avec Event Hubs. Options disponibles : amqpTcp, amqpWebSockets
webProxy null Proxy à utiliser pour communiquer avec Event Hubs sur des sockets Web. Un proxy ne peut pas être utilisé avec le transport amqpTcp.
customEndpointAddress null Adresse à utiliser lors de l’établissement d’une connexion à Event Hubs, ce qui permet de router les demandes réseau via une passerelle d’application ou un autre chemin d’accès nécessaire pour l’environnement hôte. L’espace de noms complet d’Event Hub est toujours nécessaire lorsqu’une adresse de point de terminaison personnalisée est utilisée et doit être spécifiée explicitement ou via la chaîne de connexion.
targetUnprocessedEventThreshold1 null Le nombre souhaité d’événements non traités par instance de fonction. Ce seuil est utilisé dans une mise à l’échelle basée sur la cible pour remplacer le seuil de mise à l’échelle par défaut déduit de l’option maxEventBatchSize. Une fois défini, le nombre total d’événements non traités est divisé par cette valeur pour déterminer le nombre nécessaire d’instances de fonction. Le nombre d’instances est arrondi à un nombre qui crée une distribution de partition équilibrée.
initialOffsetOptions/type fromStart Emplacement dans le flux d’événements pour démarrer le traitement lorsqu’il n’existe pas de point de contrôle dans le stockage. S’applique à toutes les partitions. Pour plus d’informations, consultez la documentation d’OffsetType. Options disponibles : fromStart, fromEnd, fromEnqueuedTime
initialOffsetOptions/enqueuedTimeUtc null Spécifie la durée de mise en file d’attente de l’événement dans le flux à partir duquel commencer le traitement. Lorsque initialOffsetOptions/type est configuré sur fromEnqueuedTime, ce paramètre est obligatoire. Prend en charge une valeur temporelle dans n’importe quel format pris en charge par DateTime.Parse(), par exemple 2020-10-26T20:31Z. Par souci de clarté, vous devez également spécifier un fuseau horaire. 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.
clientRetryOptions/mode exponential Approche à utiliser pour calculer les délais de nouvelle tentative. Le mode exponentiel effectue de nouvelles tentatives avec un délai basé sur une stratégie de backoff, où chaque tentative augmente la durée d’attente avant une nouvelle tentative. Le mode fixe effectue de nouvelles tentatives à intervalles fixes, chaque délai ayant la même durée. Options disponibles : exponential, fixed
clientRetryOptions/tryTimeout 00:01:00 Durée maximale à attendre pour qu’une opération Event Hubs soit terminée, par tentative.
clientRetryOptions/delay 00:00:00.80 Délai ou facteur de backoff à appliquer entre les nouvelles tentatives.
clientRetryOptions/maximumDelay 00:00:01 Délai maximal à accorder entre les nouvelles tentatives.
clientRetryOptions/maximumRetries 3 Nombre maximal de nouvelles tentatives avant de considérer que l’opération associée a échoué.

1 L’utilisation de minEventBatchSize et de maxWaitTime requiert la version v5.3.0 ou ultérieure du package Microsoft.Azure.WebJobs.Extensions.EventHubs.

2 La valeur par défaut maxEventBatchSize a été modifiée dans v6.0.0 du package Microsoft.Azure.WebJobs.Extensions.EventHubs. Dans les versions antérieures, il s’agissait de 10.

Les clientRetryOptions sont utilisés pour effectuer de nouvelles tentatives entre l’hôte Functions et Event Hubs (telles que la récupération (fetch) d’événements et l’envoi d’événements). Reportez-vous à l’aide sur la Gestion des erreurs et nouvelles tentatives dans Azure Functions pour obtenir plus d’informations sur l’application de stratégies de nouvelles tentatives à des fonctions individuelles.

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.

Étapes suivantes