Liaisons de sortie de Stockage File d’attente Azure pour Azure Functions

  • Article

La solution Azure Functions peut créer des messages de Stockage File d’attente Azure en configurant une liaison de sortie.

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

Important

Cet article utilise des onglets pour prendre en charge plusieurs versions du modèle de programmation Node.js. Le modèle v4 est en disponibilité générale. Il est conçu pour offrir une expérience plus flexible et intuitive aux développeurs JavaScript et TypeScript. Pour plus d’informations sur le fonctionnement du modèle v4, reportez-vous au guide du développeur Azure Functions Node.js. Pour plus d’informations sur les différences entre v3 et v4, consultez le guide de migration.

Azure Functions prend en charge deux modèles de programmation pour Python. La façon dont vous définissez vos liaisons dépend du modèle de programmation choisi.

Le modèle de programmation Python v2 vous permet de définir des liaisons à l'aide d’éléments décoratifs directement dans le code de votre fonction Python. Pour plus d’informations, consultez le guide des développeurs Python.

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

Exemple

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

Le support prendra fin pour le modèle in-process le 10 novembre 2026. Nous vous recommandons vivement de migrer vos applications vers le modèle worker isolé pour une prise en charge complète.

[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.ToString()}"};

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

    // Queue Output messages
    return messages;
}

L’exemple ci-après montre une fonction Java qui crée un message de file d’attente en cas de déclenchement par une requête HTTP.

@FunctionName("httpToQueue")
@QueueOutput(name = "item", queueName = "myqueue-items", connection = "MyStorageConnectionAppSetting")
 public String pushToQueue(
     @HttpTrigger(name = "request", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
     final String message,
     @HttpOutput(name = "response") final OutputBinding<String> 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. Le type de paramètre doit être OutputBinding<T>, où T est n’importe quel type Java natif d’un POJO.

L’exemple suivant montre une fonction TypeScript déclenchée par un protocole HTTP qui crée un élément de file d’attente pour chaque requête HTTP reçue.

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

const queueOutput = output.storageQueue({
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
});

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const body = await request.text();
    context.extraOutputs.set(queueOutput, body);
    return { body: 'Created queue item.' };
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraOutputs: [queueOutput],
    handler: httpTrigger1,
});

Pour générer plusieurs messages, retournez un tableau au lieu d’un seul objet. Par exemple :

context.extraOutputs.set(queueOutput, ['message 1', 'message 2']);

L’exemple suivant montre une fonction JavaScript déclenchée par un protocole HTTP qui crée un élément de file d’attente pour chaque requête HTTP reçue.

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

const queueOutput = output.storageQueue({
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
});

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraOutputs: [queueOutput],
    handler: async (request, context) => {
        const body = await request.text();
        context.extraOutputs.set(queueOutput, body);
        return { body: 'Created queue item.' };
    },
});

Pour générer plusieurs messages, retournez un tableau au lieu d’un seul objet. Par exemple :

context.extraOutputs.set(queueOutput, ['message 1', 'message 2']);

Les exemples de code suivants montrent comment générer un message de file d’attente à partir d’une fonction déclenchée par le protocole HTTP. La section de configuration avec le typequeue définit la liaison de sortie.

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "Msg",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

Avec cette configuration de liaison, une fonction PowerShell peut créer un message de file d’attente à l’aide de Push-OutputBinding. Dans cet exemple, un message est créé à partir d’une chaîne de requête ou d’un paramètre de corps.

using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with query parameters or the body of the request.
$message = $Request.Query.Message
Push-OutputBinding -Name Msg -Value $message
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = 200
    Body = "OK"
})

Pour envoyer plusieurs messages à la fois, définissez un tableau de messages et utilisez Push-OutputBinding pour envoyer des messages à la liaison de sortie de file d’attente.

using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with query parameters or the body of the request.
$message = @("message1", "message2")
Push-OutputBinding -Name Msg -Value $message
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = 200
    Body = "OK"
})

L’exemple suivant montre comment sortir des valeurs uniques et multiples dans les files d’attente de stockage. La configuration requise pour function.json est la même dans les deux sens. L’exemple varie selon que vous utilisez le modèle de programmation Python v1 ou v2.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="QueueOutput1")
@app.route(route="message")
@app.queue_output(arg_name="msg", 
                  queue_name="<QUEUE_NAME>", 
                  connection="<CONNECTION_SETTING>")
def main(req: func.HttpRequest, msg: func.Out[str]) -> func.HttpResponse:
    input_msg = req.params.get('name')
    logging.info(input_msg)

    msg.set(input_msg)

    logging.info(f'name: {name}')
    return 'OK'

Attributs

L’attribut qui définit une liaison de sortie dans les bibliothèques C# dépend du mode d’exécution de la bibliothèque de classes C#.

Lors de l’exécution dans un processus Worker isolé, vous utilisez QueueOutputAttribute, qui prend le nom de la file d’attente, comme indiqué dans l’exemple suivant :

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

Seules les variables retournées sont prises en charge lors de l’exécution dans un processus Worker isolé. Les paramètres de sortie ne peuvent pas être utilisés.

Décorateurs

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

Pour les fonctions Python v2 définies à l’aide d’un élément décoratif, les propriétés suivantes sur queue_output :

Propriété Description
arg_name Nom de la variable qui représente la file d’attente dans le code de la fonction.
queue_name Nom de la file d'attente.
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 les fonctions Python définies à l’aide de function.json, consultez la section Configuration.

Annotations

L’annotation QueueOutput vous permet d’écrire un message de sortie d’une fonction. L’exemple suivant montre une fonction déclenchée par HTTP qui crée un message de file d’attente.

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

public class HttpTriggerQueueOutput {
    @FunctionName("HttpTriggerQueueOutput")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.FUNCTION) HttpRequestMessage<Optional<String>> request,
            @QueueOutput(name = "message", queueName = "messages", connection = "MyStorageConnectionAppSetting") OutputBinding<String> message,
            final ExecutionContext context) {

        message.setValue(request.getQueryParameters().get("name"));
        return request.createResponseBuilder(HttpStatus.OK).body("Done").build();
    }
}
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.

Le paramètre associé à l’annotation QueueOutput est typée en tant qu’instance OutputBinding<T>.

Configuration

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

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

Propriété Description
queueName Nom de la file d'attente.
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.

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

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

Propriété function.json Description
type Cette propriété doit être définie sur queue. Cette propriété est définie automatiquement lorsque vous créez le déclencheur dans le portail Azure.
direction Cette propriété doit être définie sur out. Cette propriété est définie automatiquement lorsque vous créez le déclencheur dans le portail Azure.
name Nom de la variable qui représente la file d’attente dans le code de la fonction. La valeur doit être $return pour faire référence à la valeur de retour de la fonction.
queueName Nom de la file d'attente.
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.

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

Pour obtenir des exemples complets, consultez la section Exemple.

Utilisation

L’utilisation de la liaison de sortie Queue 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’une des suivantes :

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 d’utilisation du mode et de la version.

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 directement des types à partir d’Azure.Storage.Queues.

Il existe deux options pour écrire dans une file d’attente à partir d’une fonction en utilisant l’annotation QueueOutput :

  • Valeur de retour : en appliquant l’annotation à la fonction elle-même, la valeur renvoyée de la fonction est écrite dans la file d’attente.

  • Impérative : pour définir explicitement la valeur du message, appliquez l’annotation à un paramètre spécifique du type OutputBinding<T>, où T est un POJO ou n’importe quel type Java natif. Avec cette configuration, la transmission d’une valeur à la méthode setValue écrit la valeur dans la file d’attente.

Accédez à l’élément de file d’attente de sortie en retournant la valeur directement ou en utilisant context.extraOutputs.set(). Vous pouvez utiliser une chaîne ou un objet sérialisable JSON pour la charge utile de l’élément de file d’attente.

La sortie dans le message de file d’attente est disponible via Push-OutputBinding, où vous transmettez les arguments qui correspondent au nom désigné par le paramètre name de la liaison dans le fichier function.json.

Il existe deux options pour l’écriture à partir de votre fonction dans la file d’attente configurée :

  • Valeur de retour : Définissez la propriété name dans function.json sur $return. Avec cette configuration, la valeur de retour de la fonction est conservée sous la forme d’un message de Stockage File d’attente.

  • Impératif : Passez une valeur à la méthode set du paramètre déclaré en tant que type Out. La valeur passée à set est conservée en tant que message de Stockage File d’attente.

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 :

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

1<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

Exceptions et codes de retour

Liaison Informations de référence
File d'attente Codes d’erreur de file d’attente
Objet blob, Table, File d’attente Codes d’erreur de stockage
Objet blob, Table, File d’attente Dépannage

Étapes suivantes