Partage via

Présentation du déclencheur et des liaisons de Stockage File d'attente Azure pour Azure Functions

  • Article

Azure Functions peut s’exécuter lorsque des messages de Stockage File d’attente Azure sont créés et écrire des messages de file d’attente dans une fonction.

Action Type
Exécuter une fonction pour modifier des données de stockage de file d’attente Déclencheur
Écrire des messages de stockage de file d’attente Liaison de sortie

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 Création d’une application de fonction avec des connexions basées sur l’identité.

Cette version vous permet de lier des types à partir de Azure.Storage.Queues.

Cette version prend en charge la configuration des déclencheurs et des liaisons via l’intégration de .NET Aspire.

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

Utilisation de l’interface CLI .NET :

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues

Notes

Les objets blob Azure, les files d’attente Azure et les tables Azure utilisent désormais des extensions distinctes, et sont référencés individuellement. Par exemple, pour utiliser les déclencheurs et les liaisons pour les trois services de votre application à processus isolé .NET, vous devez ajouter les packages suivants à votre projet :

Auparavant, les extensions étaient fournies en tant que Microsoft.Azure.Functions.Worker.Extensions.Storage, version 4.x. Ce même package a également une version 5.x, qui fait référence aux packages fractionnés pour les objets blob et les files d’attente uniquement. Lors de la mise à niveau de vos références de package à partir d’anciennes versions, vous devrez peut-être également référencer le nouveau package NuGet Microsoft.Azure.Functions.Worker.Extensions.Tables. En outre, lors du référencement de ces packages fractionnés plus récents, veillez à ne pas référencer une version antérieure du package de stockage combiné, car cela entraîne des conflits à partir de deux définitions des mêmes liaisons.

Installer le bundle

La liaison de stockage Blob 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 la préversion 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 tables ci-dessous. La prise en charge de la liaison aux types à partir d’Azure.Storage.Queues est en préversion.

Déclencheur de file d’attente

Le déclencheur de file d’attente peut être lié aux types suivants :

Type Description
string Le contenu du message en tant que chaîne. À utiliser lorsque le message est du texte simple.
byte[] Octets du message.
Types sérialisables JSON Lorsqu’un message en file d’attente contient des données JSON, Functions tente de désérialiser les données JSON dans un type d’objet CLR (POCO) traditionnel connu.
QueueMessage1 Message.
BinaryData1 Les octets du message.

1 Pour utiliser ces types, vous devez référencer Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues 5.2.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 de file d’attente

Lorsque vous souhaitez que la fonction écrive un seul message, la liaison de sortie de file d’attente peut se lier aux types suivants :

Type Description
string Le contenu du message en tant que chaîne. À utiliser lorsque le message est du texte simple.
byte[] Les octets du message.
Types sérialisables JSON Un objet représentant le contenu d'un message JSON. Functions tente de sérialiser un objet CLR classique (POCO) en données JSON.

Lorsque vous souhaitez que la fonction écrive plusieurs messages, la liaison de sortie de file d’attente peut se lier aux types suivants :

Type Description
T[] où T est l’un des types de messages uniques Un tableau contenant le contenu de plusieurs messages. Chaque entrée représente un message.

Pour d’autres scénarios de sortie, créez et utilisez un QueueClient avec d’autres types à partir d’Azure.Storage.Queues 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.

Paramètres host.json

Cette section décrit les paramètres de configuration disponibles pour cette liaison dans les versions 2.x et ultérieures. Les paramètres dans le fichier host.json s’appliquent à toutes les fonctions dans une instance de l’application de fonction. L’exemple de fichier host.json ci-dessous contient seulement les paramètres des versions 2.x et ultérieures pour cette liaison. Pour plus d’informations sur les paramètres de configuration de l’application de fonction dans les versions 2.x et ultérieures, consultez Référence host.json pour Azure Functions.

Notes

Pour obtenir une référence de host.json dans Functions 1.x, consultez Informations de référence sur le fichier host.json pour Azure Functions 1.x.

{
    "version": "2.0",
    "extensions": {
        "queues": {
            "maxPollingInterval": "00:00:02",
            "visibilityTimeout" : "00:00:30",
            "batchSize": 16,
            "maxDequeueCount": 5,
            "newBatchThreshold": 8,
            "messageEncoding": "base64"
        }
    }
}
Propriété Default Description
maxPollingInterval 00:01:00 Intervalle maximal entre les interrogations de la file d’attente. L’intervalle minimal est 00:00:00.100 (100 ms). Les intervalles sont incrémentés jusqu’à maxPollingInterval. La valeur par défaut de maxPollingInterval est 00:01:00 (1 min). maxPollingInterval ne doit pas être inférieur à 00:00:00.100 (100 ms). Dans Functions 2.x et versions ultérieures, le type de données est TimeSpan. Dans Functions 1.x, il correspond aux millisecondes.
visibilityTimeout 00:00:00 Intervalle de temps entre les nouvelles tentatives en cas d’échec du traitement d’un message.
batchSize 16 Le nombre de messages de file d’attente que le runtime Functions récupère simultanément et traite en parallèle. Quand le nombre de messages en cours de traitement descend à newBatchThreshold, le runtime obtient un autre lot et commence à traiter ces messages. Par conséquent, le nombre maximal de messages traités simultanément par fonction est batchSize plus newBatchThreshold. Cette limite s’applique séparément à chaque fonction déclenchée par une file d’attente.

Si vous souhaitez éviter les exécutions parallèles pour les messages reçus sur une file d’attente, vous pouvez définir batchSize sur 1. Toutefois, ce paramètre évite les opérations simultanées tant que votre application de fonction s’exécute uniquement sur une machine virtuelle unique. Si l’application de fonction augmente la taille des instances sur plusieurs machines virtuelles, chaque machine virtuelle peut exécuter une instance de chaque fonction déclenchée par une file d’attente.

La valeur batchSize maximale est de 32.
maxDequeueCount 5 Nombre de tentatives de traitement d’un message avant de le placer dans la file d’attente de messages incohérents.
newBatchThreshold N*batchSize/2 Quand le nombre de messages traités simultanément passe en dessous de cette valeur, le runtime récupère un autre lot.

N représente le nombre de processeurs virtuels disponibles lors de l’exécution sur App Service ou les plans Premium. Sa valeur est 1 pour le plan Consommation.
messageEncoding base64 Ce paramètre est disponible seulement dans les versions 5.0.0 et supérieures du bundle d’extensions. Il représente le format d’encodage des messages. Les valeurs valides sont base64 et none.

Étapes suivantes