Déclencheur Stockage File d’attente Azure pour Azure Functions

Le déclencheur de stockage de file d’attente exécute une fonction lorsque des messages sont ajoutés à Stockage File d’attente Azure.

Les décisions de mise à l’échelle du Stockage File d’attente Azure 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 Mise à l’échelle basée sur la cible.

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.

v2

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.

v1

Le modèle de programmation Python v1 vous oblige à définir des liaisons dans un fichier function.json distinct dans le dossier de fonction. Pour plus d’informations, consultez le guide des développeurs Python.

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

Exemple

Utilisez le déclencheur de file d’attente pour démarrer une fonction lorsqu’un nouvel élément est reçu sur une file d’attente. Le message de file d’attente est fourni comme entrée pour la fonction.

Une fonction C# peut être créée à l’aide de l’un des modes C# suivants :

• Modèle worker isolé : fonction C# compilée exécutée dans un processus worker isolé du runtime. Le processus Worker isolé est requis pour prendre en charge les fonctions C# exécutées sur les versions LTS et non-LTS de .NET et de .NET Framework. Les extensions pour les fonctions de processus de travail isolés utilisent des espaces de noms Microsoft.Azure.Functions.Worker.Extensions.*.
• Modèle In-process : fonction C# compilée exécutée dans le même processus que le runtime Functions. Dans une variation de ce modèle, Functions peut être exécuté à l’aide de scripts C#, principalement pris en charge pour la modification du portail C#. Les extensions pour les fonctions in-process utilisent des espaces de noms Microsoft.Azure.WebJobs.Extensions.*.

Important

La prise en charge du modèle in-process prendra fin le 10 novembre 2026. Pour continuer à bénéficier d’une prise en charge complète, nous vous recommandons vivement de migrer vos applications vers le modèle worker isolé.

Modèle de worker isolé

L’exemple suivant montre une fonction C# qui interroge la file d’attente input-queue et écrit plusieurs messages dans une file d’attente de sortie chaque fois qu’un élément de la file d’attente est traité.

[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)
{
    // Use a string array to return more than one message.
    string[] messages = {
        $"Album name = {myQueueItem.Name}",
        $"Album songs = {myQueueItem.Songs}"};

    _logger.LogInformation("{msg1},{msg2}", messages[0], messages[1]);

    // Queue Output messages
    return messages;
}

Modèle in-process

L’exemple suivant montre un code de fonction C# qui interroge la file d’attente myqueue-items et écrit un journal chaque fois qu’un élément de la file d’attente est traité.

public static class QueueFunctions
{
    [FunctionName("QueueTrigger")]
    public static void QueueTrigger(
        [QueueTrigger("myqueue-items")] string myQueueItem, 
        ILogger log)
    {
        log.LogInformation($"C# function processed: {myQueueItem}");
    }
}

L’exemple Java suivant montre une fonction de déclencheur de file d’attente de stockage, qui consigne le message déclenché placé dans la file d’attente myqueuename.

@FunctionName("queueprocessor")
public void run(
    @QueueTrigger(name = "msg",
                queueName = "myqueuename",
                connection = "myconnvarname") String message,
    final ExecutionContext context
) {
    context.getLogger().info(message);
}

Modèle v4

L’exemple suivant montre une fonction TypeScript de déclencheur de file d’attente. La fonction interroge la file d’attente myqueue-items et écrit un journal chaque fois qu’un élément de la file d’attente est traité.

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

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<void> {
    context.log('Storage queue function processed work item:', queueItem);
    context.log('expirationTime =', context.triggerMetadata.expirationTime);
    context.log('insertionTime =', context.triggerMetadata.insertionTime);
    context.log('nextVisibleTime =', context.triggerMetadata.nextVisibleTime);
    context.log('id =', context.triggerMetadata.id);
    context.log('popReceipt =', context.triggerMetadata.popReceipt);
    context.log('dequeueCount =', context.triggerMetadata.dequeueCount);
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'myqueue-items',
    connection: 'MyStorageConnectionAppSetting',
    handler: storageQueueTrigger1,
});

La section utilisation explique queueItem. La section sur les métadonnées de message détaille toutes les autres variables indiquées.

Modèle v3

Les échantillons TypeScript ne sont pas consignés pour le modèle v3.

Modèle v4

L’exemple suivant montre une fonction JavaScript de déclencheur de file d’attente. La fonction interroge la file d’attente myqueue-items et écrit un journal chaque fois qu’un élément de la file d’attente est traité.

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

app.storageQueue('storageQueueTrigger1', {
    queueName: 'myqueue-items',
    connection: 'MyStorageConnectionAppSetting',
    handler: (queueItem, context) => {
        context.log('Storage queue function processed work item:', queueItem);
        context.log('expirationTime =', context.triggerMetadata.expirationTime);
        context.log('insertionTime =', context.triggerMetadata.insertionTime);
        context.log('nextVisibleTime =', context.triggerMetadata.nextVisibleTime);
        context.log('id =', context.triggerMetadata.id);
        context.log('popReceipt =', context.triggerMetadata.popReceipt);
        context.log('dequeueCount =', context.triggerMetadata.dequeueCount);
    },
});

La section utilisation explique queueItem. La section sur les métadonnées de message détaille toutes les autres variables indiquées.

Modèle v3

L’exemple suivant montre une liaison de déclencheur de file d’attente dans un fichier function.json et une fonction JavaScript qui utilise la liaison. La fonction interroge la file d’attente myqueue-items et écrit un journal chaque fois qu’un élément de la file d’attente est traité.

Voici le fichier function.json :

{
    "disabled": false,
    "bindings": [
        {
            "type": "queueTrigger",
            "direction": "in",
            "name": "myQueueItem",
            "queueName": "myqueue-items",
            "connection":"MyStorageConnectionAppSetting"
        }
    ]
}

La section configuration décrit ces propriétés.

Notes

Le paramètre de nom se reflète en tant que context.bindings.<name> dans le code JavaScript qui contient la charge utile de l’élément de file d’attente. Cette charge utile est également passée comme deuxième paramètre à la fonction.

Voici le code JavaScript :

module.exports = async function (context, message) {
    context.log('Node.js queue trigger function processed work item', message);
    // OR access using context.bindings.<name>
    // context.log('Node.js queue trigger function processed work item', context.bindings.myQueueItem);
    context.log('expirationTime =', context.bindingData.expirationTime);
    context.log('insertionTime =', context.bindingData.insertionTime);
    context.log('nextVisibleTime =', context.bindingData.nextVisibleTime);
    context.log('id =', context.bindingData.id);
    context.log('popReceipt =', context.bindingData.popReceipt);
    context.log('dequeueCount =', context.bindingData.dequeueCount);
};

La section utilisation explique myQueueItem, qui est nommé par la propriété name dans function.json. La section sur les métadonnées de message détaille toutes les autres variables indiquées.

L’exemple suivant montre comment lire un message de file d’attente passé à une fonction via un déclencheur.

Un déclencheur de file d’attente de stockage est défini dans le fichier function.json, où type est défini sur queueTrigger.

{
  "bindings": [
    {
      "name": "QueueItem",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "messages",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

Le code du fichier dans Run.ps1 déclare un paramètre $QueueItem, ce qui vous permet de lire le message de la file d’attente dans votre fonction.

# Input bindings are passed in via param block.
param([string] $QueueItem, $TriggerMetadata)

# Write out the queue message and metadata to the information log.
Write-Host "PowerShell queue trigger function processed work item: $QueueItem"
Write-Host "Queue item expiration time: $($TriggerMetadata.ExpirationTime)"
Write-Host "Queue item insertion time: $($TriggerMetadata.InsertionTime)"
Write-Host "Queue item next visible time: $($TriggerMetadata.NextVisibleTime)"
Write-Host "ID: $($TriggerMetadata.Id)"
Write-Host "Pop receipt: $($TriggerMetadata.PopReceipt)"
Write-Host "Dequeue count: $($TriggerMetadata.DequeueCount)"

L’exemple suivant montre comment lire un message de file d’attente passé à une fonction via un déclencheur. L’exemple varie selon l’utilisation du modèle de programmation Python v1 ou v2.

v2

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="QueueFunc")
@app.queue_trigger(arg_name="msg", queue_name="inputqueue",
                   connection="storageAccountConnectionString")  # Queue trigger
@app.queue_output(arg_name="outputQueueItem", queue_name="outqueue",
                 connection="storageAccountConnectionString")  # Queue output binding
def test_function(msg: func.QueueMessage,
                  outputQueueItem: func.Out[str]) -> None:
    logging.info('Python queue trigger function processed a queue item: %s',
                 msg.get_body().decode('utf-8'))
    outputQueueItem.set('hello')

v1

Un déclencheur de file d’attente de stockage est défini dans function.json, où Type est défini sur queueTrigger.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "name": "msg",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "messages",
      "connection": "AzureStorageQueuesConnectionString"
    }
  ]
}

Le code dans _init_.py déclare un paramètre func.QueueMessage qui vous permet de lire le message de la file d’attente dans votre fonction.

import logging
import json

import azure.functions as func

def main(msg: func.QueueMessage):
    logging.info('Python queue trigger function processed a queue item.')

    result = json.dumps({
        'id': msg.id,
        'body': msg.get_body().decode('utf-8'),
        'expiration_time': (msg.expiration_time.isoformat()
                            if msg.expiration_time else None),
        'insertion_time': (msg.insertion_time.isoformat()
                           if msg.insertion_time else None),
        'time_next_visible': (msg.time_next_visible.isoformat()
                              if msg.time_next_visible else None),
        'pop_receipt': msg.pop_receipt,
        'dequeue_count': msg.dequeue_count
    })

    logging.info(result)

Attributs

Les bibliothèques C# in-process et de processus Worker isolés utilisent l’attribut QueueTriggerAttribute pour définir la fonction. Le script C# utilise à la place un fichier de configuration function.json comme décrit dans le guide de script C#.

Modèle de worker isolé

Dans les bibliothèques de classes C#, le constructeur de l’attribut prend le nom de la file d’attente à surveiller, comme illustré dans l’exemple suivant :

[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)

Cet exemple montre également comment définir le paramètre de chaîne de connexion dans l’attribut lui-même.

Modèle in-process

Dans les bibliothèques de classes C#, le constructeur de l’attribut prend le nom de la file d’attente à surveiller, comme illustré dans l’exemple suivant :

[FunctionName("QueueTrigger")]
public static void Run(
    [QueueTrigger("myqueue-items")] string myQueueItem, 
    ILogger log)
{
    ...
}

Vous pouvez définir la propriété Connection pour spécifier le paramètre d’application qui contient la chaîne de connexion du compte de stockage à utiliser, comme illustré dans l’exemple suivant :

[FunctionName("QueueTrigger")]
public static void Run(
    [QueueTrigger("myqueue-items", Connection = "StorageConnectionAppSetting")] string myQueueItem, 
    ILogger log)
{
    ....
}

Annotations

L’annotation QueueTrigger vous donne accès à la file d’attente qui déclenche la fonction. L’exemple suivant rend le message de file d’attente disponible pour la fonction via le paramètre message.

package com.function;
import com.microsoft.azure.functions.annotation.*;
import java.util.Queue;
import com.microsoft.azure.functions.*;

public class QueueTriggerDemo {
    @FunctionName("QueueTriggerDemo")
    public void run(
        @QueueTrigger(name = "message", queueName = "messages", connection = "MyStorageConnectionAppSetting") String message,
        final ExecutionContext context
    ) {
        context.getLogger().info("Queue message: " + message);
    }
}

Propriété	Description
name	Déclare le nom du paramètre dans la signature de la fonction. Quand la fonction est déclenchée, la valeur de ce paramètre a le contenu du message de la file d’attente.
queueName	Déclare le nom de la file d’attente dans le compte de stockage.
connection	Pointe vers la chaîne de connexion du compte de stockage.

Décorateurs

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

Pour les fonctions Python v2 définies à l’aide de décorateurs, les propriétés suivantes du décorateur queue_trigger définissent le déclencheur Stockage File d'attente :

Propriété	Description
arg_name	Déclare le nom du paramètre dans la signature de la fonction. Quand la fonction est déclenchée, la valeur de ce paramètre a le contenu du message de la file d’attente.
queue_name	Déclare le nom de la file d’attente dans le compte de stockage.
connection	Pointe vers la chaîne de connexion du compte de stockage.

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

Configuration

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

Modèle v4

Le tableau suivant explique les propriétés que vous pouvez définir pour l’objet options passé à la méthode app.storageQueue().

Propriété	Description
queueName	Nom de la file d’attente à interroger.
connection	Nom d’un paramètre d’application ou d’une collection de paramètres d’application qui spécifie la façon de se connecter à des files d’attente Azure. Consultez Connexions.

Modèle v3

Le tableau suivant décrit les propriétés de configuration de liaison que vous définissez dans le fichier function.json.

Propriété	Description
type	Cette propriété doit être définie sur queueTrigger. Cette propriété est définie automatiquement lorsque vous créez le déclencheur dans le portail Azure.
direction	Dans le fichier function.json uniquement. 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 contient la charge utile de l’élément de file d’attente dans le code de fonction.
queueName	Nom de la file d’attente à interroger.
connection	Nom d’un paramètre d’application ou d’une collection de paramètres d’application qui spécifie la façon de se connecter à des files d’attente Azure. Consultez Connexions.

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 QueueTrigger.

Propriété function.json	Description
type	Cette propriété doit être définie sur queueTrigger. Cette propriété est définie automatiquement lorsque vous créez le déclencheur dans le portail Azure.
direction	Dans le fichier function.json uniquement. 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 contient la charge utile de l’élément de file d’attente dans le code de fonction.
queueName	Nom de la file d’attente à interroger.
connection	Nom d’un paramètre d’application ou d’une collection de paramètres d’application qui spécifie la façon de se connecter à des files d’attente Azure. Consultez Connexions.

Pour obtenir des exemples complets, consultez la section Exemple.

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

Usage

Notes

Les fonctions attendent une chaîne codée en base64. Tout ajustement du type d’encodage (afin de préparer les données sous forme de chaîne codée en base64) doit être effectué dans le service appelant.

L’utilisation du déclencheur file d’attente dépend de la version du package d’extension et de la modalité C# utilisée dans votre application de fonction, qui peut être l’un des modes suivants :

Modèle de worker isolé

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.

Bibliothèque de classes In-process

Une bibliothèque de classes in-process est une fonction C# compilée exécutée dans le même processus que le runtime Functions.

Choisissez une version pour afficher les détails d’utilisation du mode et de la version.

Extension 5.x et versions ultérieures

Accédez aux données du message en utilisant un paramètre de méthode comme string paramName. Le paramName est la valeur spécifiée dans l’attribut QueueTriggerAttribute. Vous pouvez lier aux types suivants :

• Objet CLR .NET simple (POCO)
• string
• byte[]
• QueueMessage

Lorsqu’il se lie à un objet, le runtime Functions tente de désérialiser la charge utile JSON en une instance d’une classe arbitraire définie dans votre code. Pour obtenir des exemples d’utilisation de QueueMessage, consultez le référentiel GitHub pour l’extension.

Tandis que l’attribut prend une propriété Connection, vous pouvez également utiliser Connection pour spécifier une connexion à un compte de stockage. Vous pouvez le faire lorsque vous avez besoin d’utiliser un compte de stockage différent de celui utilisé par les autres fonctions de la bibliothèque. Le constructeur prend le nom d’un paramètre d’application comportant une chaîne de connexion de stockage. L’attribut peut être appliqué au niveau du paramètre, de la méthode ou de la classe. L’exemple suivant montre le niveau de la classe et celui de la méthode :

[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
    [FunctionName("StorageTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ...
}

Le compte de stockage à utiliser est déterminé dans l’ordre suivant :

• Propriété Connection du déclencheur ou de l’attribut de liaison.
• Attribut StorageAccount appliqué au même paramètre que le déclencheur ou l’attribut de liaison.
• L’attribut StorageAccount appliqué à la fonction.
• L’attribut StorageAccount appliqué à la classe.
• Compte de stockage par défaut pour l’application de fonction, lequel est défini dans le paramètre d’application AzureWebJobsStorage.

Extension 2.x et versions ultérieures

Accédez aux données du message en utilisant un paramètre de méthode comme string paramName. Le paramName est la valeur spécifiée dans l’attribut QueueTriggerAttribute. Vous pouvez lier aux types suivants :

• Objet CLR traditionnel (OCT)
• string
• byte[]
• CloudQueueMessage

Lorsqu’il se lie à un objet, le runtime Functions tente de désérialiser la charge utile JSON en une instance d’une classe arbitraire définie dans votre code. Si vous essayez de créer une liaison avec CloudQueueMessage et obtenez un message d’erreur, vérifiez que vous faites référence à la bonne version du Kit de développement logiciel (SDK) Stockage.

Tandis que l’attribut prend une propriété Connection, vous pouvez également utiliser Connection pour spécifier une connexion à un compte de stockage. Vous pouvez le faire lorsque vous avez besoin d’utiliser un compte de stockage différent de celui utilisé par les autres fonctions de la bibliothèque. Le constructeur prend le nom d’un paramètre d’application comportant une chaîne de connexion de stockage. L’attribut peut être appliqué au niveau du paramètre, de la méthode ou de la classe. L’exemple suivant montre le niveau de la classe et celui de la méthode :

[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
    [FunctionName("StorageTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ...
}

Le compte de stockage à utiliser est déterminé dans l’ordre suivant :

• Propriété Connection du déclencheur ou de l’attribut de liaison.
• Attribut StorageAccount appliqué au même paramètre que le déclencheur ou l’attribut de liaison.
• L’attribut StorageAccount appliqué à la fonction.
• L’attribut StorageAccount appliqué à la classe.
• Compte de stockage par défaut pour l’application de fonction, lequel est défini dans le paramètre d’application AzureWebJobsStorage.

Extension 5.x et versions ultérieures

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.

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

Extension 2.x et versions ultérieures

Les versions antérieures de cette extension dans le processus de travail isolé ne prennent en charge que la liaison aux chaînes. D’autres options sont disponibles pour l’extension 5.x+.

L’annotation QueueTrigger vous donne accès au message de la file d’attente qui a déclenché la fonction.

Modèle v4

Accédez à l’élément de la file d’attente comme premier argument de votre fonction. Si la charge utile est JSON, la valeur est désérialisée en objet.

Modèle v3

Accédez à l’élément de la file d’attente en utilisant context.bindings.<NAME>, où <NAME> correspond à la valeur définie dans function.json. Si la charge utile est JSON, la valeur est désérialisée en objet.

Accédez au message de la file d’attente via un paramètre de chaîne correspondant au nom désigné par le paramètre name de liaison du fichier name.

Accédez au message de la file d’attente via le paramètre typé en QueueMessage.

Métadonnées

Le déclencheur de file d’attente fournit plusieurs propriétés de métadonnées. Ces propriétés peuvent être utilisées dans le cadre d’expressions de liaison dans d’autres liaisons ou en tant que paramètres dans votre code, pour les workers linguistiques qui fournissent cet accès aux métadonnées de message.

Les propriétés des métadonnées de message sont membres de la classe CloudQueueMessage .

Les propriétés des métadonnées de message sont accessibles à partir de context.triggerMetadata.

Les propriétés des métadonnées de message sont accessibles à partir du paramètre passé $TriggerMetadata .

Propriété	Type	Description
QueueTrigger	string	Charge utile de file d’attente (s’il s’agit d’une chaîne valide). Si la charge utile du message de la file d’attente est une chaîne, QueueTrigger a la même valeur que la variable nommée par la propriété name dans QueueTrigger.
DequeueCount	long	Nombre de fois que ce message a été enlevé de la file d’attente.
ExpirationTime	DateTimeOffset	Heure à laquelle le message expire.
Id	string	ID de message de la file d’attente.
InsertionTime	DateTimeOffset	Heure à laquelle le message a été ajouté à la file d’attente.
NextVisibleTime	DateTimeOffset	Heure à laquelle le message sera de nouveau visible.
PopReceipt	string	Réception pop du message.

Les propriétés de métadonnées de message suivantes sont accessibles à partir du paramètre de liaison passé (msgdans les exemples précédents).

Propriété	Description
body	Charge utile de file d’attente sous forme de chaîne.
dequeue_count	Nombre de fois que ce message a été enlevé de la file d’attente.
expiration_time	Heure à laquelle le message expire.
id	ID de message de la file d’attente.
insertion_time	Heure à laquelle le message a été ajouté à la file d’attente.
time_next_visible	Heure à laquelle le message sera de nouveau visible.
pop_receipt	Réception pop du message.

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 aux files d’attente Azure. Elle peut spécifier :

• Le nom d’un paramètre d’application contenant une chaîne de connexion
• Le nom d’un préfixe partagé pour plusieurs paramètres d’application, définissant ensemble une connexion basée sur l’identité.

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

Pour obtenir une chaîne de connexion, suivez les étapes indiquées dans Gérer les clés d’accès au compte de stockage.

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.

Si le nom du paramètre d’application commence par « AzureWebJobs », vous ne pouvez spécifier que le reste du nom ici. Par exemple, si vous définissez connection sur « MyStorage », le runtime Functions recherche un paramètre d’application nommé « AzureWebJobsMyStorage ». Si vous laissez connection vide, le runtime Functions utilise la chaîne de connexion de stockage par défaut dans le paramètre d’application nommé AzureWebJobsStorage.

Connexions basées sur l’identité

Si vous utilisez la version 5.x ou ultérieure de l’extension (bundle 3.x ou version ultérieure pour les piles linguistiques non-.NET), au lieu d’utiliser un chaîne de connexion avec un secret, vous pouvez faire en sorte que l’application utilise une identité Microsoft Entra. Pour utiliser une identité, 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.

Si vous définissez connection sur « AzureWebJobsStorage », consultez la section Connexion au stockage hôte avec une identité. Pour toutes les autres connexions, l’extension nécessite les propriétés suivantes :

Propriété	Modèle de variable d’environnement	Description	Valeur d'exemple
URI du service de file d’attente	<CONNECTION_NAME_PREFIX>__queueServiceUri1	URI du plan de données du service de file d’attente auquel vous vous connectez, à l’aide du même schéma HTTPS.	https://<storage_account_name>.queue.core.windows.net

¹ <CONNECTION_NAME_PREFIX>__serviceUri peut être utilisé comme alias. Si les deux formes sont fournies, la forme queueServiceUri est utilisée. La forme serviceUri ne peut pas être utilisée lorsque la configuration globale de la connexion doit être utilisée sur des objets blob, des files d’attente et/ou des tables.

D’autres propriétés peuvent être définies pour personnaliser la connexion. Consultez Propriétés communes pour les connexions basées sur l’identité.

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 file d’attente au moment de l’exécution. 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 Stockage File d’attente 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	Lecteur de données en file d’attente du stockage, Processeur de messages de données en file d’attente du stockage
Liaison de sortie	Contributeur aux données en file d’attente du stockage, Expéditeur de messages de données en file d’attente du stockage

Messages incohérents

En cas d’échec d’une fonction de déclenchement de file d’attente, Azure Functions réessaie la fonction jusqu’à cinq fois (première tentative comprise) pour un message de file d’attente donné. Si les cinq tentatives échouent, le runtime Functions ajoute un message à une file d’attente nommée <nom_file_d’attente_d’origine>-poison. Vous pouvez écrire une fonction pour traiter les messages de la file d’attente de messages incohérents en les consignant dans un journal ou en envoyant une notification signalant qu’une attention manuelle est nécessaire.

Pour gérer manuellement les messages incohérents, vérifiez la propriété dequeueCount dans le message de file d’attente.

Afficher-verrouiller

Le modèle peek-lock se produit automatiquement pour les déclencheurs de file d’attente, à l’aide des mécanismes de visibilité fournis par le service de stockage. Comme les messages sont mis en file d’attente par la fonction déclenchée, ils sont marqués comme invisibles. L’exécution d’une fonction déclenchée par une file d’attente peut avoir l’un des résultats suivants sur le message de la file d’attente :

• L’exécution de la fonction se termine correctement et le message est supprimé de la file d’attente.
• L’exécution de la fonction échoue et l’hôte Functions met à jour la visibilité du message en fonction du visibilityTimeout paramètre dans le fichier host.json. Le délai d’expiration de visibilité par défaut est égal à zéro, ce qui signifie que le message réapparaît immédiatement dans la file d’attente pour le retraitement. Utilisez le visibilityTimeout paramètre pour retarder le retraitement des messages qui ne parviennent pas à traiter. Ce paramètre de délai d’attente s’applique à toutes les fonctions déclenchées par la file d’attente dans l’application de fonction.
• L’hôte Functions se bloque pendant l’exécution de la fonction. Lorsque cet événement rare se produit, l’hôte ne peut pas appliquer le visibilityTimeout message en cours de traitement. Au lieu de cela, le message est laissé avec le délai d’expiration par défaut de 10 minutes défini par le service de stockage. Après 10 minutes, le message réapparaît dans la file d’attente pour le retraitement. Ce délai d’expiration par défaut défini par le service ne peut pas être modifié.

Algorithme d’interrogation

Le déclencheur de file d’attente implémente un algorithme d’interruption exponentiel et aléatoire pour réduire l’effet de l’interrogation de file d’attente inactive sur les coûts de transactions de stockage.

L’algorithme utilise la logique suivante :

• Lorsqu’un message est trouvé, le runtime attend 100 millisecondes, puis recherche un autre message.
• Quand aucun message n’est trouvé, il attend environ 200 millisecondes avant de réessayer.
• Après plusieurs échecs de tentatives d’obtention d’un message de file d’attente, le temps d’attente continue à augmenter jusqu’à ce qu’il atteigne le délai d’attente maximal par défaut (une minute).
• La durée d’attente maximale est configurable via la propriété maxPollingInterval dans le maxPollingInterval.

Pendant le développement local, l’intervalle d’interrogation maximal est défini par défaut sur deux secondes.

Remarque

Pour ce qui est de la facturation lors de l’hébergement d’applications de fonction dans le plan de consommation, vous n’êtes pas facturé pour le temps que le runtime consacre à l’interrogation.

Accès concurrentiel

Lorsque plusieurs messages de file d’attente attendent, le déclencheur de file d’attente récupère un lot de messages et appelle les instances de fonction simultanément pour les traiter. Par défaut, la taille de lot est de 16. Quand le nombre de messages en cours de traitement descend à 8, 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 sur une machine virtuelle est de 24. Cette limite s’applique séparément à chaque fonction déclenchée par une file d’attente sur chaque machine virtuelle. Si votre application de fonction effectue un scale-out vers plusieurs machines virtuelles, chaque machine virtuelle attend les déclencheurs et tente d’exécuter des fonctions. Par exemple, si une application de fonction est étendue à 3 machines virtuelles, le nombre maximal d’instances simultanées d’une fonction déclenché par une file d’attente est par défaut de 72.

La taille du lot et le seuil d’obtention d’un nouveau lot sont configurables dans le fichier host.json. Si vous souhaitez minimiser l’exécution en parallèle des fonctions déclenchées par une file d’attente dans une application de fonction, vous pouvez définir la taille du lot sur 1. Ce paramètre évite les opérations simultanées uniquement pendant l’exécution de votre application de fonction sur une machine virtuelle unique.

Le déclencheur de la file d’attente empêche automatiquement une fonction de traiter un message de file d’attente plusieurs fois de manière simultanée.

Propriétés host.json

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

Étapes suivantes

• Écrire des messages de stockage de file d’attente (liaison de sortie)