Liaisons de stockage File d’attente Azure pour Azure FunctionsAzure Queue storage bindings for Azure Functions

Cet article explique comment utiliser les liaisons Stockage File d’attente Azure dans Azure Functions.This article explains how to work with Azure Queue storage bindings in Azure Functions. Azure Functions prend en charge les liaisons de déclencheur et de sortie pour les files d’attente.Azure Functions supports trigger and output bindings for queues.

Il s’agit des informations de référence pour les développeurs Azure Functions.This is reference information for Azure Functions developers. Si vous ne connaissez pas bien Azure Functions, commencez par consulter les ressources suivantes :If you're new to Azure Functions, start with the following resources:

Packages - Functions 1.xPackages - Functions 1.x

Les liaisons du Stockage File d’attente sont fournies dans le package NuGet Microsoft.Azure.WebJobs, version 2.x.The Queue storage bindings are provided in the Microsoft.Azure.WebJobs NuGet package, version 2.x. Le code source du package se trouve dans le référentiel GitHub azure-webjobs-sdk.Source code for the package is in the azure-webjobs-sdk GitHub repository.

La prise en charge de cette liaison est automatique dans tous les environnements de développement.Support for this binding is automatically provided in all development environments. Vous n’avez pas besoin d’installer manuellement le package ou d’enregistrer l’extension.You don't have to manually install the package or register the extension.

Version du kit SDK Stockage Azure dans Functions 1.xAzure Storage SDK version in Functions 1.x

Dans Functions 1.x, les déclencheurs et les liaisons de stockage utilisent la version 7.2.1 du kit SDK Stockage Azure (package NuGet WindowsAzure.Storage).In Functions 1.x, the Storage triggers and bindings use version 7.2.1 of the Azure Storage SDK (WindowsAzure.Storage NuGet package). Si vous référencez une version différente du kit SDK Stockage Azure et établissez une liaison avec un type du kit SDK Stockage Azure dans votre signature de fonction, le runtime de Functions peut signaler ne pas pouvoir établir de liaison avec ce type.If you reference a different version of the Storage SDK, and you bind to a Storage SDK type in your function signature, the Functions runtime may report that it can't bind to that type. La solution consiste à s’assurer que votre projet référence WindowsAzure.Storage 7.2.1.The solution is to make sure your project references WindowsAzure.Storage 7.2.1.

Packages – Functions 2.x et versions ultérieuresPackages - Functions 2.x and higher

Les liaisons du Stockage File d’attente sont fournies dans le package NuGet Microsoft.Azure.WebJobs.Extensions.Storage, version 3.x.The Queue storage bindings are provided in the Microsoft.Azure.WebJobs.Extensions.Storage NuGet package, version 3.x. Le code source du package se trouve dans le référentiel GitHub azure-webjobs-sdk.Source code for the package is in the azure-webjobs-sdk GitHub repository.

Le tableau suivant indique comment ajouter la prise en charge de cette liaison dans chaque environnement de développement.The following table tells how to add support for this binding in each development environment.

Environnement de développementDevelopment environment Pour ajouter la prise en chargeTo add support
Développement local - Bibliothèque de classes C#Local development - C# class library Installer le package.Install the package
Développement local - Script C#, JavaScript, F#, Java et PythonLocal development - C# script, JavaScript, F#, Java and Python Enregistrer l’extensionRegister the extension
Développement sur le portailPortal development Installer lors de l’ajout d’une liaison de sortieInstall when adding output binding

Pour apprendre comment mettre à jour les extensions de liaison existantes dans le portail sans avoir à republier votre projet d'application de fonction, voir Mettre à jour vos extensions.To learn how to update existing binding extensions in the portal without having to republish your function app project, see Update your extensions.

EncodageEncoding

Les fonctions attendent une chaîne codée en base64.Functions expect a base64 encoded string. 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.Any adjustments to the encoding type (in order to prepare data as a base64 encoded string) need to be implemented in the calling service.

DéclencheurTrigger

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.Use the queue trigger to start a function when a new item is received on a queue. Le message de file d’attente est fourni comme entrée pour la fonction.The queue message is provided as input to the function.

Déclencheur - exempleTrigger - example

Consultez l’exemple propre à un langage particulier :See the language-specific example:

Déclencheur - exemple C#Trigger - C# example

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é.The following example shows a C# function that polls the myqueue-items queue and writes a log each time a queue item is processed.

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

Déclencheur - exemple Script C#Trigger - C# script example

L’exemple suivant montre une liaison de déclencheur de file d’attente dans un fichier function.json, ainsi que le code du script C# (.csx) qui utilise cette liaison.The following example shows a queue trigger binding in a function.json file and C# script (.csx) code that uses the binding. 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é.The function polls the myqueue-items queue and writes a log each time a queue item is processed.

Voici le fichier function.json :Here's the function.json file:

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

La section configuration décrit ces propriétés.The configuration section explains these properties.

Voici le code Script C# :Here's the C# script code:

#r "Microsoft.WindowsAzure.Storage"

using Microsoft.Extensions.Logging;
using Microsoft.WindowsAzure.Storage.Queue;
using System;

public static void Run(CloudQueueMessage myQueueItem, 
    DateTimeOffset expirationTime, 
    DateTimeOffset insertionTime, 
    DateTimeOffset nextVisibleTime,
    string queueTrigger,
    string id,
    string popReceipt,
    int dequeueCount,
    ILogger log)
{
    log.LogInformation($"C# Queue trigger function processed: {myQueueItem.AsString}\n" +
        $"queueTrigger={queueTrigger}\n" +
        $"expirationTime={expirationTime}\n" +
        $"insertionTime={insertionTime}\n" +
        $"nextVisibleTime={nextVisibleTime}\n" +
        $"id={id}\n" +
        $"popReceipt={popReceipt}\n" + 
        $"dequeueCount={dequeueCount}");
}

La section utilisation explique myQueueItem, qui est nommé par la propriété name dans function.json.The usage section explains myQueueItem, which is named by the name property in function.json. La section sur les métadonnées de message détaille toutes les autres variables indiquées.The message metadata section explains all of the other variables shown.

Déclencheur - exemple JavaScriptTrigger - JavaScript example

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.The following example shows a queue trigger binding in a function.json file and a JavaScript function that uses the binding. 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é.The function polls the myqueue-items queue and writes a log each time a queue item is processed.

Voici le fichier function.json :Here's the function.json file:

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

La section configuration décrit ces propriétés.The configuration section explains these properties.

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.The name parameter reflects as context.bindings.<name> in the JavaScript code which contains the queue item payload. Cette charge utile est également passée comme deuxième paramètre à la fonction.This payload is also passed as the second parameter to the function.

Voici le code JavaScript :Here's the JavaScript code:

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);
    context.done();
};

La section utilisation explique myQueueItem, qui est nommé par la propriété name dans function.json.The usage section explains myQueueItem, which is named by the name property in function.json. La section sur les métadonnées de message détaille toutes les autres variables indiquées.The message metadata section explains all of the other variables shown.

Déclencheur - exemple JavaTrigger - Java example

L’exemple Java ci-après présente une fonction de déclencheur de file d’attente de stockage qui enregistre le message déclenché placé dans la file d’attente myqueuename.The following Java example shows a storage queue trigger functions which logs the triggered message placed into queue myqueuename.

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

Déclencheur – Exemple PythonTrigger - Python example

L’exemple suivant montre comment lire un message de file d’attente passé à une fonction via un déclencheur.The following example demonstrates how to read a queue message passed to a function via a trigger.

Un déclencheur de file d’attente de stockage est défini dans function.json, où Type est défini sur queueTrigger.A Storage queue trigger is defined in function.json where type is set to 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.ServiceBusMessage qui vous permet de lire le message de la file d’attente dans votre fonction.The code _init_.py declares a parameter as func.ServiceBusMessage which allows you to read the queue message in your function.

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)

Déclencheur - attributsTrigger - attributes

Dans les bibliothèques de classes C#, utilisez les attributs suivants pour configurer un déclencheur de file d’attente :In C# class libraries, use the following attributes to configure a queue trigger:

  • QueueTriggerAttributeQueueTriggerAttribute

    Le constructeur de l’attribut prend le nom de la file d’attente à surveiller, comme illustré dans l’exemple suivant :The attribute's constructor takes the name of the queue to monitor, as shown in the following example:

    [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 compte de stockage à utiliser, comme indiqué dans l’exemple suivant :You can set the Connection property to specify the storage account to use, as shown in the following example:

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

    Pour obtenir un exemple complet, consultez Déclencheur - exemple C#.For a complete example, see Trigger - C# example.

  • StorageAccountAttributeStorageAccountAttribute

    Fournit une autre manière de spécifier le compte de stockage à utiliser.Provides another way to specify the storage account to use. Le constructeur prend le nom d’un paramètre d’application comportant une chaîne de connexion de stockage.The constructor takes the name of an app setting that contains a storage connection string. L’attribut peut être appliqué au niveau du paramètre, de la méthode ou de la classe.The attribute can be applied at the parameter, method, or class level. L’exemple suivant montre le niveau de la classe et celui de la méthode :The following example shows class level and method level:

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

Le compte de stockage à utiliser est déterminé dans l’ordre suivant :The storage account to use is determined in the following order:

  • La propriété Connection de l’attribut QueueTrigger.The QueueTrigger attribute's Connection property.
  • L’attribut StorageAccount appliqué au même paramètre que l’attribut QueueTrigger.The StorageAccount attribute applied to the same parameter as the QueueTrigger attribute.
  • L’attribut StorageAccount appliqué à la fonction.The StorageAccount attribute applied to the function.
  • L’attribut StorageAccount appliqué à la classe.The StorageAccount attribute applied to the class.
  • Le paramètre d’application « AzureWebJobsStorage ».The "AzureWebJobsStorage" app setting.

Déclencheur - configurationTrigger - configuration

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.The following table explains the binding configuration properties that you set in the function.json file and the QueueTrigger attribute.

Propriété function.jsonfunction.json property Propriété d’attributAttribute property DescriptionDescription
typetype n/an/a Cette propriété doit être définie sur queueTrigger.Must be set to queueTrigger. Cette propriété est définie automatiquement lorsque vous créez le déclencheur dans le portail Azure.This property is set automatically when you create the trigger in the Azure portal.
directiondirection n/an/a Dans le fichier function.json uniquement.In the function.json file only. Cette propriété doit être définie sur in.Must be set to in. Cette propriété est définie automatiquement lorsque vous créez le déclencheur dans le portail Azure.This property is set automatically when you create the trigger in the Azure portal.
namename n/an/a Nom de la variable qui contient la charge utile de l’élément de file d’attente dans le code de fonction.The name of the variable that contains the queue item payload in the function code.
queueNamequeueName QueueNameQueueName Nom de la file d’attente à interroger.The name of the queue to poll.
connectionconnection ConnectionConnection Nom d’un paramètre d’application comportant la chaîne de connexion de stockage à utiliser pour cette liaison.The name of an app setting that contains the Storage connection string to use for this binding. Si le nom du paramètre d’application commence par « AzureWebJobs », vous ne pouvez spécifier que le reste du nom ici.If the app setting name begins with "AzureWebJobs", you can specify only the remainder of the name here. Par exemple, si vous définissez connection sur « MyStorage », le runtime Functions recherche un paramètre d’application qui est nommé « MyStorage ».For example, if you set connection to "MyStorage", the Functions runtime looks for an app setting that is named "MyStorage." 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.If you leave connection empty, the Functions runtime uses the default Storage connection string in the app setting that is named AzureWebJobsStorage.

Quand vous développez localement, les paramètres d’application vont dans le fichier local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Déclencheur - utilisationTrigger - usage

Dans du code C# ou un script C#, accédez aux données du message en utilisant un paramètre de méthode comme string paramName.In C# and C# script, access the message data by using a method parameter such as string paramName. Dans Script C#, paramName est la valeur spécifiée dans la propriété name de function.json.In C# script, paramName is the value specified in the name property of function.json. Vous pouvez lier aux types suivants :You can bind to any of the following types:

  • Objet : le runtime Functions désérialise une charge utile JSON dans une instance d’une classe arbitraire définie dans votre code.Object - The Functions runtime deserializes a JSON payload into an instance of an arbitrary class defined in your code.
  • string
  • byte[]
  • CloudQueueMessageCloudQueueMessage

Si vous essayez de lier à CloudQueueMessage et obtenez un message d’erreur, vérifiez que vous avez une référence à la bonne version du SDK Stockage.If you try to bind to CloudQueueMessage and get an error message, make sure that you have a reference to the correct Storage SDK version.

Dans JavaScript, utilisez context.bindings.<name> pour accéder à la charge utile de l’élément de file d’attente.In JavaScript, use context.bindings.<name> to access the queue item payload. Si la charge utile est JSON, elle est désérialisée en objet.If the payload is JSON, it's deserialized into an object.

Déclencheur - métadonnées de messageTrigger - message metadata

Le déclencheur de file d’attente fournit plusieurs propriétés de métadonnées.The queue trigger provides several metadata properties. Ces propriétés peuvent être utilisées dans les expressions de liaison dans d’autres liaisons ou en tant que paramètres dans votre code.These properties can be used as part of binding expressions in other bindings or as parameters in your code. Ce sont les propriétés de la classe CloudQueueMessage.These are properties of the CloudQueueMessage class.

PropriétéProperty TypeType DescriptionDescription
QueueTrigger string Charge utile de file d’attente (s’il s’agit d’une chaîne valide).Queue payload (if a valid string). Si la charge utile du message de file d’attente est une chaîne, QueueTrigger a la même valeur que la variable nommée par la propriété name dans function.json.If the queue message payload as a string, QueueTrigger has the same value as the variable named by the name property in function.json.
DequeueCount int Nombre de fois que ce message a été enlevé de la file d’attente.The number of times this message has been dequeued.
ExpirationTime DateTimeOffset Heure à laquelle le message expire.The time that the message expires.
Id string ID de message de la file d’attente.Queue message ID.
InsertionTime DateTimeOffset Heure à laquelle le message a été ajouté à la file d’attente.The time that the message was added to the queue.
NextVisibleTime DateTimeOffset Heure à laquelle le message sera de nouveau visible.The time that the message will next be visible.
PopReceipt string Réception pop du message.The message's pop receipt.

Déclencheur - messages incohérentsTrigger - poison messages

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é.When a queue trigger function fails, Azure Functions retries the function up to five times for a given queue message, including the first try. Si les cinq tentatives échouent, le runtime Functions ajoute un message à une file d’attente nommée <nom_file_d’attente_d’origine>-poison.If all five attempts fail, the functions runtime adds a message to a queue named <originalqueuename>-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.You can write a function to process messages from the poison queue by logging them or sending a notification that manual attention is needed.

Pour gérer manuellement les messages incohérents, vérifiez la propriété dequeueCount dans le message de file d’attente.To handle poison messages manually, check the dequeueCount of the queue message.

Déclencheur : algorithme d’interrogationTrigger - polling algorithm

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.The queue trigger implements a random exponential back-off algorithm to reduce the effect of idle-queue polling on storage transaction costs.

L’algorithme utilise la logique suivante :The algorithm uses the following logic:

  • Lorsqu’un message est trouvé, le runtime attend deux secondes, puis vérifie s’il existe un autre message.When a message is found, the runtime waits two seconds and then checks for another message
  • Lorsqu’aucun message n’est trouvé, il attend environ quatre secondes avant de réessayer.When no message is found, it waits about four seconds before trying again.
  • 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).After subsequent failed attempts to get a queue message, the wait time continues to increase until it reaches the maximum wait time, which defaults to one minute.
  • La durée d’attente maximale est configurable via la propriété maxPollingInterval dans le fichier host.json.The maximum wait time is configurable via the maxPollingInterval property in the host.json file.

Pour le développement local, l’intervalle d’interrogation maximal par défaut est de deux secondes.For local development the maximum polling interval defaults to two seconds.

En ce qui concerne la facturation, le temps passé par le runtime à interroger est « gratuit » et n’est pas compté sur votre compte.In regard to billing, time spent polling by the runtime is "free" and not counted against your account.

Déclencheur : concurrenceTrigger - concurrency

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.When there are multiple queue messages waiting, the queue trigger retrieves a batch of messages and invokes function instances concurrently to process them. Par défaut, la taille de lot est de 16.By default, the batch size is 16. Quand le nombre de messages en cours de traitement descend à 8, le runtime obtient un autre lot et commence à traiter ces messages.When the number being processed gets down to 8, the runtime gets another batch and starts processing those messages. Par conséquent, le nombre maximal de messages traités simultanément par fonction sur une machine virtuelle est de 24.So the maximum number of concurrent messages being processed per function on one virtual machine (VM) is 24. Cette limite s’applique séparément à chaque fonction déclenchée par une file d’attente sur chaque machine virtuelle.This limit applies separately to each queue-triggered function on each VM. Si votre application de fonction est étendue à plusieurs machines virtuelles, chaque machine virtuelle attend des déclencheurs et essaie d’exécuter les fonctions.If your function app scales out to multiple VMs, each VM will wait for triggers and attempt to run functions. 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.For example, if a function app scales out to 3 VMs, the default maximum number of concurrent instances of one queue-triggered function is 72.

La taille du lot et le seuil d’obtention d’un nouveau lot sont configurables dans le fichier host.json.The batch size and the threshold for getting a new batch are configurable in the host.json file. 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.If you want to minimize parallel execution for queue-triggered functions in a function app, you can set the batch size to 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.This setting eliminates concurrency only so long as your function app runs on a single virtual machine (VM).

Le déclencheur de la file d’attente empêche automatiquement une fonction de traiter un message de file d’attente plusieurs fois ; les fonctions ne doivent pas nécessairement être écrites pour être idempotent.The queue trigger automatically prevents a function from processing a queue message multiple times; functions do not have to be written to be idempotent.

Déclencheur - propriétés de host.jsonTrigger - host.json properties

Le fichier host.json contient les paramètres qui contrôlent le comportement du déclencheur de file d’attente.The host.json file contains settings that control queue trigger behavior. Consultez la section Paramètres host.json pour plus d’informations concernant les paramètres disponibles.See the host.json settings section for details regarding available settings.

OutputOutput

Utilisez la liaison de sortie Stockage File d’attente Azure pour écrire des messages dans une file d’attente.Use the Azure Queue storage output binding to write messages to a queue.

Sortie - exempleOutput - example

Consultez l’exemple propre à un langage particulier :See the language-specific example:

Sortie - exemple C#Output - C# example

L’exemple suivant montre un code de fonction C# qui crée un message de file d’attente pour chaque requête HTTP reçue.The following example shows a C# function that creates a queue message for each HTTP request received.

[StorageAccount("AzureWebJobsStorage")]
public static class QueueFunctions
{
    [FunctionName("QueueOutput")]
    [return: Queue("myqueue-items")]
    public static string QueueOutput([HttpTrigger] dynamic input,  ILogger log)
    {
        log.LogInformation($"C# function processed: {input.Text}");
        return input.Text;
    }
}

Sortie - exemple Script C#Output - C# script example

L’exemple suivant montre une liaison de déclencheur HTTP dans un fichier function.json, ainsi que le code du script C# (.csx) qui utilise cette liaison.The following example shows an HTTP trigger binding in a function.json file and C# script (.csx) code that uses the binding. La fonction crée un élément de file d’attente avec une charge utile d’objet CustomQueueMessage pour chaque requête HTTP reçue.The function creates a queue item with a CustomQueueMessage object payload for each HTTP request received.

Voici le fichier function.json :Here's the function.json file:

{
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "authLevel": "function",
      "name": "input"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "return"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "$return",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

La section configuration décrit ces propriétés.The configuration section explains these properties.

Voici le code Script C# qui crée un message de file d’attente unique :Here's C# script code that creates a single queue message:

public class CustomQueueMessage
{
    public string PersonName { get; set; }
    public string Title { get; set; }
}

public static CustomQueueMessage Run(CustomQueueMessage input, ILogger log)
{
    return input;
}

Vous pouvez envoyer plusieurs messages à la fois en utilisant un paramètre ICollector ou IAsyncCollector.You can send multiple messages at once by using an ICollector or IAsyncCollector parameter. Voici le code Script C# qui envoie plusieurs messages, l’un avec les données de requête HTTP, et l’autre avec des valeurs codées en dur :Here's C# script code that sends multiple messages, one with the HTTP request data and one with hard-coded values:

public static void Run(
    CustomQueueMessage input, 
    ICollector<CustomQueueMessage> myQueueItems, 
    ILogger log)
{
    myQueueItems.Add(input);
    myQueueItems.Add(new CustomQueueMessage { PersonName = "You", Title = "None" });
}

Sortie - exemple JavaScriptOutput - JavaScript example

L’exemple suivant montre une liaison de déclencheur HTTP dans un fichier function.json, et une fonction JavaScript qui utilise la liaison.The following example shows an HTTP trigger binding in a function.json file and a JavaScript function that uses the binding. La fonction crée un élément de file d’attente pour chaque requête HTTP reçue.The function creates a queue item for each HTTP request received.

Voici le fichier function.json :Here's the function.json file:

{
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "authLevel": "function",
      "name": "input"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "return"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "$return",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

La section configuration décrit ces propriétés.The configuration section explains these properties.

Voici le code JavaScript :Here's the JavaScript code:

module.exports = function (context, input) {
    context.done(null, input.body);
};

Vous pouvez envoyer plusieurs messages à la fois en définissant un tableau de messages pour la liaison de sortie myQueueItem.You can send multiple messages at once by defining a message array for the myQueueItem output binding. Le code JavaScript suivant envoie deux messages de file d’attente avec des valeurs codées en dur pour chaque requête HTTP reçue.The following JavaScript code sends two queue messages with hard-coded values for each HTTP request received.

module.exports = function(context) {
    context.bindings.myQueueItem = ["message 1","message 2"];
    context.done();
};

Sortie : exemple JavaOutput - Java example

L’exemple ci-après présente une fonction Java qui crée un message de file d’attente en cas de déclenchement par une requête HTTP.The following example shows a Java function that creates a queue message for when triggered by a HTTP request.

@FunctionName("httpToQueue")
@QueueOutput(name = "item", queueName = "myqueue-items", connection = "AzureWebJobsStorage")
 public String pushToQueue(
     @HttpTrigger(name = "request", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
     final String message,
     @HttpOutput(name = "response") final OutputBinding&lt;String&gt; result) {
       result.setValue(message + " has been added.");
       return message;
 }

Dans la bibliothèque runtime des fonctions Java, utilisez l’annotation @QueueOutput sur les paramètres dont la valeur serait écrite dans Stockage File d’attente.In the Java functions runtime library, use the @QueueOutput annotation on parameters whose value would be written to Queue storage. Le type de paramètre doit être OutputBinding<T>, où T désigne n’importe quel type Java natif d’un POJO.The parameter type should be OutputBinding<T>, where T is any native Java type of a POJO.

Sortie - Exemple PythonOutput - Python example

L’exemple suivant montre comment sortir des valeurs uniques et multiples dans les files d’attente de stockage.The following example demonstrates how to output single and multiple values to storage queues. La configuration requise pour function.json est la même dans les deux sens.The configuration needed for function.json is the same either way.

Une liaison de file d’attente de stockage est définie dans function.json, où Type est défini sur queue.A Storage queue binding is defined in function.json where type is set to queue.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "msg",
      "queueName": "outqueue",
      "connection": "AzureStorageQueuesConnectionString"
    }
  ]
}

Pour définir un message individuel dans la file d’attente, vous transmettez une valeur set unique à la méthode.To set a individual message on the queue, you pass a single value to the set method.

import azure.functions as func

def main(req: func.HttpRequest, msg: func.Out[str]) -> func.HttpResponse:

    input_msg = req.params.get('message')

    msg.set(input_msg)

    return 'OK'

Pour créer plusieurs messages dans la file d’attente, déclarez un paramètre comme type de liste approprié et transmettez un tableau de valeurs (correspondant au type de liste) à la méthode set.To create multiple messages on the queue, declare a parameter as the appropriate list type and pass an array of values (that match the list type) to the set method.

import azure.functions as func
import typing

def main(req: func.HttpRequest, msg: func.Out[typing.List[str]]) -> func.HttpResponse:

    msg.set(['one', 'two'])

    return 'OK'

Sortie - attributsOutput - attributes

Dans les bibliothèques de classes C#, utilisez l’attribut QueueAttribute.In C# class libraries, use the QueueAttribute.

L’attribut s’applique à un paramètre out ou à la valeur de retour de la fonction.The attribute applies to an out parameter or the return value of the function. Le constructeur de l’attribut prend le nom de la file d’attente, comme illustré dans l’exemple suivant :The attribute's constructor takes the name of the queue, as shown in the following example:

[FunctionName("QueueOutput")]
[return: Queue("myqueue-items")]
public static string Run([HttpTrigger] dynamic input,  ILogger log)
{
    ...
}

Vous pouvez définir la propriété Connection pour spécifier le compte de stockage à utiliser, comme indiqué dans l’exemple suivant :You can set the Connection property to specify the storage account to use, as shown in the following example:

[FunctionName("QueueOutput")]
[return: Queue("myqueue-items", Connection = "StorageConnectionAppSetting")]
public static string Run([HttpTrigger] dynamic input,  ILogger log)
{
    ...
}

Pour obtenir un exemple complet, consultez Sortie - exemple C#.For a complete example, see Output - C# example.

Vous pouvez utiliser l’attribut StorageAccount pour spécifier le compte de stockage au niveau de la classe, de la méthode ou du paramètre.You can use the StorageAccount attribute to specify the storage account at class, method, or parameter level. Pour plus d’informations, consultez Déclencheur - attributs.For more information, see Trigger - attributes.

Sortie - configurationOutput - configuration

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 Queue.The following table explains the binding configuration properties that you set in the function.json file and the Queue attribute.

Propriété function.jsonfunction.json property Propriété d’attributAttribute property DescriptionDescription
typetype n/an/a Cette propriété doit être définie sur queue.Must be set to queue. Cette propriété est définie automatiquement lorsque vous créez le déclencheur dans le portail Azure.This property is set automatically when you create the trigger in the Azure portal.
directiondirection n/an/a Cette propriété doit être définie sur out.Must be set to out. Cette propriété est définie automatiquement lorsque vous créez le déclencheur dans le portail Azure.This property is set automatically when you create the trigger in the Azure portal.
namename n/an/a Nom de la variable qui représente la file d’attente dans le code de la fonction.The name of the variable that represents the queue in function code. La valeur doit être $return pour faire référence à la valeur de retour de la fonction.Set to $return to reference the function return value.
queueNamequeueName QueueNameQueueName Nom de la file d'attente.The name of the queue.
connectionconnection ConnectionConnection Nom d’un paramètre d’application comportant la chaîne de connexion de stockage à utiliser pour cette liaison.The name of an app setting that contains the Storage connection string to use for this binding. Si le nom du paramètre d’application commence par « AzureWebJobs », vous ne pouvez spécifier que le reste du nom ici.If the app setting name begins with "AzureWebJobs", you can specify only the remainder of the name here. Par exemple, si vous définissez connection sur « MyStorage », le runtime Functions recherche un paramètre d’application qui est nommé « MyStorage ».For example, if you set connection to "MyStorage", the Functions runtime looks for an app setting that is named "MyStorage." 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.If you leave connection empty, the Functions runtime uses the default Storage connection string in the app setting that is named AzureWebJobsStorage.

Quand vous développez localement, les paramètres d’application vont dans le fichier local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Sortie - utilisationOutput - usage

En C# et Script C#, écrivez un message de file d’attente unique en utilisant un paramètre de méthode tel que out T paramName.In C# and C# script, write a single queue message by using a method parameter such as out T paramName. Dans Script C#, paramName est la valeur spécifiée dans la propriété name de function.json.In C# script, paramName is the value specified in the name property of function.json. Vous pouvez utiliser le type de retour de la méthode au lieu d’un paramètre out, et T peut être un des types suivants :You can use the method return type instead of an out parameter, and T can be any of the following types:

Si vous essayez de lier à CloudQueueMessage et obtenez un message d’erreur, vérifiez que vous avez une référence à la bonne version du SDK Stockage.If you try to bind to CloudQueueMessage and get an error message, make sure that you have a reference to the correct Storage SDK version.

En C# et Script C#, écrivez plusieurs messages de file d’attente à l’aide d’un des types suivants :In C# and C# script, write multiple queue messages by using one of the following types:

Dans les fonctions JavaScript, utilisez context.bindings.<name> pour accéder au message de file d’attente de sortie.In JavaScript functions, use context.bindings.<name> to access the output queue message. Vous pouvez utiliser une chaîne ou un objet sérialisable JSON pour la charge utile de l’élément de file d’attente.You can use a string or a JSON-serializable object for the queue item payload.

Exceptions et codes de retourExceptions and return codes

LiaisonBinding Informations de référenceReference
File d'attenteQueue Codes d’erreur de file d’attenteQueue Error Codes
Objet blob, Table, File d’attenteBlob, Table, Queue Codes d’erreur de stockageStorage Error Codes
Objet blob, Table, File d’attenteBlob, Table, Queue DépannageTroubleshooting

Paramètres host.jsonhost.json settings

Cette section décrit les paramètres de configuration globaux disponibles pour cette liaison dans les versions 2.x et ultérieures.This section describes the global configuration settings available for this binding in versions 2.x and higher. L’exemple de fichier host.json ci-dessous contient seulement les paramètres des versions 2.x et ultérieures pour cette liaison.The example host.json file below contains only the version 2.x+ settings for this binding. Pour plus d’informations sur les paramètres de configuration globaux dans les versions 2.x et ultérieures, consultez Informations de référence sur le fichier host.json pour Azure Functions.For more information about global configuration settings in versions 2.x and beyond, see host.json reference for 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.For a reference of host.json in Functions 1.x, see host.json reference for Azure Functions 1.x.

{
    "version": "2.0",
    "extensions": {
        "queues": {
            "maxPollingInterval": "00:00:02",
            "visibilityTimeout" : "00:00:30",
            "batchSize": 16,
            "maxDequeueCount": 5,
            "newBatchThreshold": 8
        }
    }
}
PropriétéProperty DefaultDefault DescriptionDescription
maxPollingIntervalmaxPollingInterval 00:00:0100:00:01 Intervalle maximal entre les interrogations de la file d’attente.The maximum interval between queue polls. L’intervalle minimum est de 00:00:00.100 (100 ms) et il est augmenté par incréments de 00:01:00 (1 minute).Minimum is 00:00:00.100 (100 ms) and increments up to 00:01:00 (1 min). Dans 1.x, le type de données est « milliseconds » (millisecondes) et, dans 2.x et ultérieur, il s’agit de « TimeSpan » (intervalle de temps).In 1.x the data type is milliseconds, and in 2.x and higher it is a TimeSpan.
visibilityTimeoutvisibilityTimeout 00:00:0000:00:00 Intervalle de temps entre les nouvelles tentatives en cas d’échec du traitement d’un message.The time interval between retries when processing of a message fails.
batchSizebatchSize 1616 Le nombre de messages de file d’attente que le runtime Functions récupère simultanément et traite en parallèle.The number of queue messages that the Functions runtime retrieves simultaneously and processes in parallel. Quand le nombre de messages en cours de traitement descend à newBatchThreshold, le runtime obtient un autre lot et commence à traiter ces messages.When the number being processed gets down to the newBatchThreshold, the runtime gets another batch and starts processing those messages. Par conséquent, le nombre maximal de messages traités simultanément par fonction est batchSize plus newBatchThreshold.So the maximum number of concurrent messages being processed per function is batchSize plus newBatchThreshold. Cette limite s’applique séparément à chaque fonction déclenchée par une file d’attente.This limit applies separately to each queue-triggered function.

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.If you want to avoid parallel execution for messages received on one queue, you can set batchSize to 1. Toutefois, ce paramètre évite les opérations simultanées uniquement pendant l’exécution de votre application de fonction sur une machine virtuelle unique.However, this setting eliminates concurrency only so long as your function app runs on a single virtual machine (VM). 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.If the function app scales out to multiple VMs, each VM could run one instance of each queue-triggered function.

La valeur batchSize maximale est de 32.The maximum batchSize is 32.
maxDequeueCountmaxDequeueCount 55 Nombre de tentatives de traitement d’un message avant de le placer dans la file d’attente de messages incohérents.The number of times to try processing a message before moving it to the poison queue.
newBatchThresholdnewBatchThreshold batchSize/2batchSize/2 Quand le nombre de messages traités simultanément passe en dessous de cette valeur, le runtime récupère un autre lot.Whenever the number of messages being processed concurrently gets down to this number, the runtime retrieves another batch.

Étapes suivantesNext steps