Partager via

Liaison de sortie Azure Service Bus pour Azure Functions

  • Article

Utilisez la liaison de sortie Azure Service Bus pour envoyer des messages de file d’attente ou de rubrique.

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

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

Ce code définit et initialise ILogger :

private readonly ILogger<ServiceBusReceivedMessageFunctions> _logger;

public ServiceBusReceivedMessageFunctions(ILogger<ServiceBusReceivedMessageFunctions> logger)
{
    _logger = logger;
}

Cet exemple montre une fonction C# qui reçoit un message et l’écrit dans une deuxième file d’attente :

[Function(nameof(ServiceBusReceivedMessageFunction))]
[ServiceBusOutput("outputQueue", Connection = "ServiceBusConnection")]
public string ServiceBusReceivedMessageFunction(
    [ServiceBusTrigger("queue", Connection = "ServiceBusConnection")] ServiceBusReceivedMessage message)
{
    _logger.LogInformation("Message ID: {id}", message.MessageId);
    _logger.LogInformation("Message Body: {body}", message.Body);
    _logger.LogInformation("Message Content-Type: {contentType}", message.ContentType);

    var outputMessage = $"Output message created at {DateTime.Now}";
    return outputMessage;
}

 

Cet exemple utilise un déclencheur HTTP avec un OutputType objet pour envoyer une réponse HTTP et écrire le message de sortie.

[Function("HttpSendMsg")]
public async Task<OutputType> Run([HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequestData req, FunctionContext context)
{
   _logger.LogInformation($"C# HTTP trigger function processed a request for {context.InvocationId}.");

   HttpResponseData response = req.CreateResponse(HttpStatusCode.OK);
   await response.WriteStringAsync("HTTP response: Message sent");

   return new OutputType()
   {
       OutputEvent = "MyMessage",
       HttpResponse = response
   };
}

Ce code définit le type OutputTypede sortie multiple, qui inclut la définition de liaison de sortie Service Bus sur OutputEvent:

 public class OutputType
{
   [ServiceBusOutput("TopicOrQueueName", Connection = "ServiceBusConnection")]
   public string OutputEvent { get; set; }

   public HttpResponseData HttpResponse { get; set; }
}

L’exemple suivant montre une fonction Java qui envoie un message à une file d’attente Service Bus myqueue lorsqu’elle est déclenchée par une requête HTTP.

@FunctionName("httpToServiceBusQueue")
@ServiceBusQueueOutput(name = "message", queueName = "myqueue", connection = "AzureServiceBusConnection")
public String pushToQueue(
  @HttpTrigger(name = "request", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
  final String message,
  @HttpOutput(name = "response") final OutputBinding<T> result ) {
      result.setValue(message + " has been sent.");
      return message;
 }

Dans la bibliothèque du runtime des fonctions Java, utilisez l’annotation @QueueOutput sur les paramètres de fonction dont la valeur serait écrite dans une file d’attente Service Bus. Le type de paramètre doit être OutputBinding<T>, où T est n’importe quel type Java natif d’un ancien objet Java (POJO).

Les fonctions Java peuvent également écrire dans une rubrique Service Bus. L’exemple suivant utilise l’annotation @ServiceBusTopicOutput afin de décrire la configuration pour la liaison de sortie.

@FunctionName("sbtopicsend")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> request,
            @ServiceBusTopicOutput(name = "message", topicName = "mytopicname", subscriptionName = "mysubscription", connection = "ServiceBusConnection") OutputBinding<String> message,
            final ExecutionContext context) {

        String name = request.getBody().orElse("Azure Functions");

        message.setValue(name);
        return request.createResponseBuilder(HttpStatus.OK).body("Hello, " + name).build();

    }

L’exemple suivant montre une fonction TypeScript déclenchée par le minuteur qui envoie un message de file d'attente toutes les cinq minutes.

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

export async function timerTrigger1(myTimer: Timer, context: InvocationContext): Promise<string> {
    const timeStamp = new Date().toISOString();
    return `Message created at: ${timeStamp}`;
}

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: output.serviceBusQueue({
        queueName: 'testqueue',
        connection: 'MyServiceBusConnection',
    }),
    handler: timerTrigger1,
});

Pour sortir plusieurs messages, retournez un tableau au lieu d’un seul objet. Par exemple :

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

L’exemple suivant montre une fonction JavaScript déclenchée par le minuteur qui envoie un message de file d'attente toutes les cinq minutes.

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

const serviceBusOutput = output.serviceBusQueue({
    queueName: 'testqueue',
    connection: 'MyServiceBusConnection',
});

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: serviceBusOutput,
    handler: (myTimer, context) => {
        const timeStamp = new Date().toISOString();
        return `Message created at: ${timeStamp}`;
    },
});

Pour sortir plusieurs messages, retournez un tableau au lieu d’un seul objet. Par exemple :

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

L’exemple suivant montre une liaison de sortie Service Bus dans un fichier function.json et une fonction PowerShell qui utilise la liaison.

Voici les données de liaison dans le fichier function.json :

{
  "bindings": [
    {
      "type": "serviceBus",
      "direction": "out",
      "connection": "AzureServiceBusConnectionString",
      "name": "outputSbMsg",
      "queueName": "outqueue",
      "topicName": "outtopic"
    }
  ]
}

Voici le code PowerShell qui crée un message en tant que sortie de la fonction.

param($QueueItem, $TriggerMetadata) 

Push-OutputBinding -Name outputSbMsg -Value @{ 
    name = $QueueItem.name 
    employeeId = $QueueItem.employeeId 
    address = $QueueItem.address 
}

L’exemple suivant montre comment écrire dans une file d’attente Service Bus en Python. L’exemple varie selon l’utilisation du modèle de programmation Python v1 ou v2.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.route(route="put_message")
@app.service_bus_topic_output(arg_name="message",
                              connection="<CONNECTION_SETTING>",
                              topic_name="<TOPIC_NAME>")
def main(req: func.HttpRequest, message: func.Out[str]) -> func.HttpResponse:
    input_msg = req.params.get('message')
    message.set(input_msg)
    return 'OK'

Attributs

Les bibliothèques C# In-process et de processus Worker isolé utilisent des attributs pour définir la liaison de sortie. Le script C# utilise à la place un fichier de configuration function.json comme décrit dans le guide de script C#.

Dans les bibliothèques de classes C#, utilisez ServiceBusOutputAttribute pour définir la file d’attente ou la rubrique dans laquelle la sortie doit être écrite.

Le tableau suivant décrit les propriétés que vous pouvez définir à l’aide de l’attribut :

Propriété Description
EntityType Définit le type d’entité en tant que Queue pour l’envoi de messages à une file d’attente ou Topic lors de l’envoi de messages à une rubrique.
QueueOrTopicName Nom de la rubrique ou de la file d’attente à laquelle envoyer les messages. Utilisez EntityType pour définir le type de destination.
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 à Service Bus. Consultez Connexions.

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 service_bus_topic_output :

Propriété Description
arg_name Nom de la variable qui représente le message de la file d’attente ou de la rubrique dans le code de la fonction.
queue_name Nom de la file d’attente. Défini uniquement en cas d’envoi de messages de file d’attente, ne s’applique pas à une rubrique.
topic_name Nom de la rubrique. Défini uniquement en cas d’envoi de messages de rubrique, ne s’applique pas à une 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 à Service Bus. Consultez Connexions.

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

Annotations

Les annotations ServiceBusQueueOutput et ServiceBusTopicOutput sont disponibles pour écrire un message en tant que sortie de fonction. Le paramètre assorti de ces annotations doit être déclaré en tant que OutputBinding<T> où T est le type correspondant au type du message.

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

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.serviceBusQueue().

Propriété Description
queueName Nom de la file d’attente.
connexion 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 à Service Bus. Consultez Connexions.

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

Propriété Description
topicName Nom de la rubrique.
connexion 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 à Service Bus. 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 et l’attribut ServiceBus.

Propriété function.json Description
type Cette propriété doit être définie sur serviceBus. 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 le message de la file d’attente ou de la rubrique dans le code de la fonction. Défini sur « $return » pour faire référence à la valeur de retour de la fonction.
queueName Nom de la file d’attente. Défini uniquement en cas d’envoi de messages de file d’attente, ne s’applique pas à une rubrique.
topicName Nom de la rubrique. Défini uniquement en cas d’envoi de messages de rubrique, ne s’applique pas à une 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 à Service Bus. Consultez Connexions.
accessRights (v1 uniquement) Droits d’accès de la chaîne de connexion. Les valeurs disponibles sont manage et listen. La valeur par défaut est manage, ce qui indique que connection a l'autorisation manage. Si vous utilisez un chaîne de connexion qui n’a pas l’autorisation Gérer, définissez accessRights sur « écouter ». Sinon, le runtime Functions pourrait échouer à effectuer des opérations qui nécessitent des droits de gestion. Dans Azure Functions version 2.x et ultérieure, cette propriété n’est pas disponible, car la dernière version du Kit de développement logiciel (SDK) Service Bus ne prend pas en charge les opérations de gestion.

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

Toutes les modalités C# et les versions d’extension prennent en charge les types de paramètres de sortie suivants :

Type Description
System.String À utiliser lorsque le message à écrire est un texte simple. Lorsque la valeur du paramètre est Null à la sortie de la fonction, Functions ne crée pas de message.
byte[] À utiliser pour écrire des messages de données binaires. Lorsque la valeur du paramètre est Null à la sortie de la fonction, Functions ne crée pas de message.
Object Lorsqu’un message contient du code JSON, Functions sérialise l’objet dans une charge utile de message JSON. Lorsque la valeur du paramètre est Null à la sortie de la fonction, Functions crée un message avec un objet Null.

Les types de paramètres spécifiques à la messagerie contiennent des métadonnées de message supplémentaires et ne sont pas compatibles avec la sérialisation JSON. Par conséquent, il n’est pas possible d’utiliser ServiceBusMessage avec la liaison de sortie dans le modèle isolé. Les types spécifiques pris en charge par la liaison de sortie dépendent de la version du runtime Functions, de la version du package d’extension et de la modalité C# utilisée.

Lorsque vous souhaitez que la fonction écrive un seul message, la liaison de sortie Service Bus peut se lier aux types suivants :

Type Description
string Message en tant que chaîne. À utiliser lorsque le message est du texte simple.
byte[] Les octets du message.
Types sérialisables JSON Objet représentant le message. Les fonctions tentent de sérialiser un ancien type d'objet CLR (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 plusieurs messages. Chaque entrée représente un message.

Pour d’autres scénarios de sortie, créez et utilisez un ServiceBusClient avec d’autres types d’Azure.Messaging.ServiceBus directement. Consultez Inscrire des clients Azure pour obtenir un exemple d’utilisation de l’injection de dépendances pour créer un type de client à partir du Kit de développement logiciel (SDK) Azure.

Dans Azure Functions version 1.x, le runtime crée la file d’attente si elle n’existe pas et si vous avez défini accessRights sur manage. Dans Azure Functions version 2.x et ultérieures, la file d’attente ou la rubrique doit déjà exister. Si vous spécifiez une file d’attente ou une rubrique qui n’existe pas, la fonction échoue.

Utilisez le Kit de développement logiciel (SDK) Azure Service Bus plutôt que la liaison de sortie intégrée.

Accédez au message de sortie en retournant la valeur directement ou en utilisant context.extraOutputs.set().

La sortie dans Service Bus est disponible par le biais de l’applet de commande Push-OutputBinding, où vous passer des arguments qui correspondent au nom désigné par le paramètre du nom de la liaison dans le fichier Push-OutputBinding.

Utilisez le Kit de développement logiciel (SDK) Azure Service Bus plutôt que la liaison de sortie intégrée.

Pour obtenir un exemple complet, consultez la section Exemples.

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 au Service Bus. 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 à la section Obtenir les informations d’identification de gestion. La chaîne de connexion doit être destinée à un espace de noms Service Bus, et non limitée à une file d’attente ou une rubrique spécifique.

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. Par exemple, si vous définissez connection sur « MyServiceBus », le runtime Functions recherche un paramètre d’application qui est nommé « AzureWebJobsMyServiceBus ». Si vous laissez connection vide, le runtime Functions utilise la chaîne de connexion Service Bus par défaut dans le paramètre d’application nommé « AzureWebJobsServiceBus ».

Connexions basées sur l’identité

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

Dans ce mode, l’extension nécessite les propriétés suivantes :

Propriété Modèle de variable d’environnement Description Valeur d'exemple
Espace de noms complet <CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace Espace de noms complet Service Bus. <service_bus_namespace>.servicebus.windows.net

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

Notes

Lorsque vous utilisez Azure App Configuration ou Key Vault pour fournir des paramètres pour les connexions d’identité managée, les noms de paramètres doivent utiliser un séparateur de clé valide tel que : ou / à la place de __ pour s’assurer que les noms sont résolus correctement.

Par exemple : <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace.

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 à vos rubriques et files 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 Service Bus 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éclencheur1 Récepteur de données Azure Service Bus, Propriétaire de données Azure Service Bus
Liaison de sortie Expéditeur de données Azure Service Bus

1 Pour le déclenchement à partir de rubriques Service Bus, l’attribution de rôle doit avoir une étendue effective sur la ressource d’abonnement Service Bus. Si seule la rubrique est incluse, une erreur se produit. Certains clients, tels que le Portail Azure, n’exposent pas la ressource d’abonnement Service Bus en tant qu’étendue pour l’attribution de rôle. En pareil cas, Azure CLI peut être utilisé à la place. Pour plus d’informations, consultez Rôles Azure intégrés pour Azure Service Bus.

Exceptions et codes de retour

Liaison Informations de référence
Service Bus Codes d’erreur de Service Bus
Service Bus Limites de Service Bus

Étapes suivantes