Déclencheur Azure Service Bus pour Azure Functions

Article
10/21/2023

Utilisez le déclencheur Service Bus pour répondre aux messages provenant d'une file d’attente ou d'une rubrique Service Bus. À partir de la version d’extension 3.1.0, vous pouvez déclencher une file d’attente ou une rubrique activée par une session.

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

Les décisions de mise à l’échelle de Service Bus pour les plans Consommation et Premium sont prises en fonction 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.

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

Modèle de worker isolé
Modèle in-process

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 seul message de la file d'attente du Service Bus et l'écrit dans les journaux :

[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 montre une fonction C# qui reçoit plusieurs messages de la file d'attente du Service Bus en un seul lot et écrit chacun d'eux dans les journaux :

[Function(nameof(ServiceBusReceivedMessageBatchFunction))]
public void ServiceBusReceivedMessageBatchFunction(
    [ServiceBusTrigger("queue", Connection = "ServiceBusConnection", IsBatched = true)] ServiceBusReceivedMessage[] messages)
{
    foreach (ServiceBusReceivedMessage message in messages)
    {
        _logger.LogInformation("Message ID: {id}", message.MessageId);
        _logger.LogInformation("Message Body: {body}", message.Body);
        _logger.LogInformation("Message Content-Type: {contentType}", message.ContentType);
    }
}

Cet exemple montre une fonction C# qui reçoit plusieurs messages de la file d’attente Service Bus, les écrit dans les journaux, puis règle le message comme étant terminé :

[Function(nameof(ServiceBusMessageActionsFunction))]
public async Task ServiceBusMessageActionsFunction(
    [ServiceBusTrigger("queue", Connection = "ServiceBusConnection", AutoCompleteMessages = false)]
    ServiceBusReceivedMessage message,
    ServiceBusMessageActions messageActions)
{
    _logger.LogInformation("Message ID: {id}", message.MessageId);
    _logger.LogInformation("Message Body: {body}", message.Body);
    _logger.LogInformation("Message Content-Type: {contentType}", message.ContentType);

    // Complete the message
    await messageActions.CompleteMessageAsync(message);
}

L’exemple suivant montre une fonction C# qui lit les métadonnées du message et consigne un message de la file d’attente Service Bus :

[FunctionName("ServiceBusQueueTriggerCSharp")]                    
public static void Run(
    [ServiceBusTrigger("myqueue", Connection = "ServiceBusConnection")] 
    string myQueueItem,
    Int32 deliveryCount,
    DateTime enqueuedTimeUtc,
    string messageId,
    ILogger log)
{
    log.LogInformation($"C# ServiceBus queue trigger function processed message: {myQueueItem}");
    log.LogInformation($"EnqueuedTimeUtc={enqueuedTimeUtc}");
    log.LogInformation($"DeliveryCount={deliveryCount}");
    log.LogInformation($"MessageId={messageId}");
}

La fonction Java suivante utilise l’annotation @ServiceBusQueueTrigger provenant de la @ServiceBusQueueTrigger afin de décrire la configuration d’un déclencheur de file d’attente Service Bus. La fonction récupère le message placé dans la file d’attente et l’ajoute dans les journaux.

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

Les fonctions Java peuvent également être déclenchées lorsqu’un message est ajouté à une rubrique Service Bus. L’exemple suivant utilise l’annotation @ServiceBusTopicTrigger pour décrire la configuration du déclencheur.

@FunctionName("sbtopicprocessor")
    public void run(
        @ServiceBusTopicTrigger(
            name = "message",
            topicName = "mytopicname",
            subscriptionName = "mysubscription",
            connection = "ServiceBusConnection"
        ) String message,
        final ExecutionContext context
    ) {
        context.getLogger().info(message);
    }

Modèle v4
Modèle v3

L’exemple suivant montre une fonction TypeScript de déclencheur de Service Bus. La fonction lit les métadonnées du message et consigne un message de la file d’attente Service Bus.

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

export async function serviceBusQueueTrigger1(message: unknown, context: InvocationContext): Promise<void> {
    context.log('Service bus queue function processed message:', message);
    context.log('EnqueuedTimeUtc =', context.triggerMetadata.enqueuedTimeUtc);
    context.log('DeliveryCount =', context.triggerMetadata.deliveryCount);
    context.log('MessageId =', context.triggerMetadata.messageId);
}

app.serviceBusQueue('serviceBusQueueTrigger1', {
    connection: 'MyServiceBusConnection',
    queueName: 'testqueue',
    handler: serviceBusQueueTrigger1,
});

Modèle v4
Modèle v3

L’exemple suivant montre une fonction JavaScript de déclencheur de Service Bus. La fonction lit les métadonnées du message et consigne un message de la file d’attente Service Bus.

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

app.serviceBusQueue('serviceBusQueueTrigger1', {
    connection: 'MyServiceBusConnection',
    queueName: 'testqueue',
    handler: (message, context) => {
        context.log('Service bus queue function processed message:', message);
        context.log('EnqueuedTimeUtc =', context.triggerMetadata.enqueuedTimeUtc);
        context.log('DeliveryCount =', context.triggerMetadata.deliveryCount);
        context.log('MessageId =', context.triggerMetadata.messageId);
    },
});

L’exemple suivant montre une liaison de déclencheur Service Bus dans un fichier function.json et une fonction JavaScript qui utilise la liaison. La fonction lit les métadonnées du message et consigne un message de la file d’attente Service Bus.

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

{
"bindings": [
    {
    "queueName": "testqueue",
    "connection": "MyServiceBusConnection",
    "name": "myQueueItem",
    "type": "serviceBusTrigger",
    "direction": "in"
    }
],
"disabled": false
}

Voici le code de script JavaScript :

module.exports = async function(context, myQueueItem) {
    context.log('Node.js ServiceBus queue trigger function processed message', myQueueItem);
    context.log('EnqueuedTimeUtc =', context.bindingData.enqueuedTimeUtc);
    context.log('DeliveryCount =', context.bindingData.deliveryCount);
    context.log('MessageId =', context.bindingData.messageId);
};

L’exemple suivant montre une liaison de déclencheur 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": [
    {
      "name": "mySbMsg",
      "type": "serviceBusTrigger",
      "direction": "in",
      "topicName": "mytopic",
      "subscriptionName": "mysubscription",
      "connection": "AzureServiceBusConnectionString"
    }
  ]
}

Voici la fonction qui s’exécute lors de l’envoi d’un message Service Bus.

param([string] $mySbMsg, $TriggerMetadata)

Write-Host "PowerShell ServiceBus queue trigger function processed message: $mySbMsg"

L’exemple suivant montre comment lire un message de file d’attente Service Bus via un déclencheur. 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.function_name(name="ServiceBusQueueTrigger1")
@app.service_bus_queue_trigger(arg_name="msg", 
                               queue_name="<QUEUE_NAME>", 
                               connection="<CONNECTION_SETTING>")
def test_function(msg: func.ServiceBusMessage):
    logging.info('Python ServiceBus queue trigger processed message: %s',
                 msg.get_body().decode('utf-8'))

Une liaison Service Bus est définie dans function.json, où le type est défini sur serviceBusTrigger et la file d’attente est définie par queueName.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "name": "msg",
      "type": "serviceBusTrigger",
      "direction": "in",
      "queueName": "inputqueue",
      "connection": "AzureServiceBusConnectionString"
    }
  ]
}

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

import azure.functions as func

import logging
import json

def main(msg: func.ServiceBusMessage):
    logging.info('Python ServiceBus queue trigger processed message.')

    result = json.dumps({
        'message_id': msg.message_id,
        'body': msg.get_body().decode('utf-8'),
        'content_type': msg.content_type,
        'expiration_time': msg.expiration_time,
        'label': msg.label,
        'partition_key': msg.partition_key,
        'reply_to': msg.reply_to,
        'reply_to_session_id': msg.reply_to_session_id,
        'scheduled_enqueue_time': msg.scheduled_enqueue_time,
        'session_id': msg.session_id,
        'time_to_live': msg.time_to_live,
        'to': msg.to,
        'user_properties': msg.user_properties,
        'metadata' : msg.metadata
    }, default=str)

    logging.info(result)

L’exemple suivant montre comment lire un sujet de file d’attente Service Bus via un déclencheur.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="ServiceBusTopicTrigger1")
@app.service_bus_topic_trigger(arg_name="message", 
                               topic_name="TOPIC_NAME", 
                               connection="CONNECTION_SETTING", 
                               subscription_name="SUBSCRIPTION_NAME")
def test_function(message: func.ServiceBusMessage):
    message_body = message.get_body().decode("utf-8")
    logging.info("Python ServiceBus topic trigger processed message.")
    logging.info("Message Body: " + message_body)

Une liaison Service Bus est définie dans function.json, où le type est défini sur serviceBusTrigger et le sujet est défini par topicName.

{
  "scriptFile": "__init__.py",
  "bindings": [
   {
     "type": "serviceBusTrigger",
     "direction": "in",
     "name": "msg",
     "topicName": "inputtopic",
     "connection": "AzureServiceBusConnectionString"
   }
  ]
}

Le code dans _init_.py déclare un paramètre en tant que func.ServiceBusMessage, ce qui vous permet de lire le sujet dans votre fonction.

import json

import azure.functions as azf


def main(msg: azf.ServiceBusMessage) -> str:
    result = json.dumps({
        'message_id': msg.message_id,
        'body': msg.get_body().decode('utf-8'),
        'content_type': msg.content_type,
        'delivery_count': msg.delivery_count,
        'expiration_time': (msg.expiration_time.isoformat() if
                            msg.expiration_time else None),
        'label': msg.label,
        'partition_key': msg.partition_key,
        'reply_to': msg.reply_to,
        'reply_to_session_id': msg.reply_to_session_id,
        'scheduled_enqueue_time': (msg.scheduled_enqueue_time.isoformat() if
                                   msg.scheduled_enqueue_time else None),
        'session_id': msg.session_id,
        'time_to_live': msg.time_to_live,
        'to': msg.to,
        'user_properties': msg.user_properties,
    })

    logging.info(result)

Attributs

Les bibliothèques C# In-process et de processus Worker isolés utilisent l’attribut ServiceBusTriggerAttribute pour définir le déclencheur de 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é
Modèle in-process

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

Propriété	Description
QueueName	Nom de la file d’attente à surveiller. Défini uniquement en cas de surveillance d’une file d’attente, ne s’applique pas à une rubrique.
TopicName	Nom de la rubrique à surveiller. Défini uniquement en cas de surveillance d’une rubrique, ne s’applique pas à une file d’attente.
SubscriptionName	Nom de l’abonnement à surveiller. Défini uniquement en cas de surveillance d’une 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.
IsBatched	Les messages sont remis par lots. Requiert un type de tableau ou de collection.
IsSessionsEnabled	`true` en cas de connexion à une file d’attente ou à un abonnement `true`. Sinon `false`, qui est la valeur par défaut.
AutoCompleteMessages	`true` si le déclencheur doit terminer automatiquement le message après un appel réussi. `false` si ce n’est pas le cas, par exemple lorsque vous gérez le règlement des messages dans le code. S’il n’est pas défini explicitement, le comportement est basé sur la configuration dans `host.json`.`autoCompleteMessages`

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

Propriété	Description
QueueName	Nom de la file d’attente à surveiller. Défini uniquement en cas de surveillance d’une file d’attente, ne s’applique pas à une rubrique.
TopicName	Nom de la rubrique à surveiller. Défini uniquement en cas de surveillance d’une rubrique, ne s’applique pas à une file d’attente.
SubscriptionName	Nom de l’abonnement à surveiller. Défini uniquement en cas de surveillance d’une 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.
y accéder	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 une 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 versions 2.x et ultérieures, cette propriété n’est pas disponible parce que la version la plus récente du Kit de développement logiciel (SDK) Service Bus ne prend pas en charge les opérations de gestion.
IsBatched	Les messages sont remis par lots. Requiert un type de tableau ou de collection.
IsSessionsEnabled	`true` en cas de connexion à une file d’attente ou à un abonnement `true`. Sinon `false`, qui est la valeur par défaut.
AutoComplete	`true` Indique si le déclencheur doit terminer l’appel automatiquement après le traitement, ou si le code de la fonction termine manuellement l’appel. Si la valeur est `true`, le déclencheur termine automatiquement le message si l’exécution de la fonction se termine correctement et abandonne le message dans le cas contraire. Lorsque la valeur est `false`, il vous incombe d’appeler des méthodes ServiceBusReceiver pour terminer, abandonner ou mettre en file d’attente de lettres mortes le message, la session ou le lot. Lorsqu’une exception est levée (et qu’aucune des méthodes `ServiceBusReceiver` n’est appelée), le verrou reste. Une fois le verrou expiré, le message est de nouveau mis en file d’attente avec `DeliveryCount` incrémenté, et le verrou est automatiquement renouvelé.

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

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

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 à surveiller. Défini uniquement en cas de surveillance d’une file d’attente, ne s’applique pas à une rubrique.
`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

L’annotation ServiceBusQueueTrigger vous permet de créer une fonction qui s’exécute lors de la création d’un message de file d’attente Service Bus. Les options de configuration disponibles incluent les propriétés suivantes :

Propriété	Description
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.
queueName	Nom de la file d’attente à surveiller. Défini uniquement en cas de surveillance d’une file d’attente, ne s’applique pas à une rubrique.
topicName	Nom de la rubrique à surveiller. Défini uniquement en cas de surveillance d’une rubrique, ne s’applique pas à une file d’attente.
subscriptionName	Nom de l’abonnement à surveiller. Défini uniquement en cas de surveillance d’une 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.

L’annotation ServiceBusTopicTrigger vous permet de désigner une rubrique et un abonnement pour cibler les données qui déclenchent la fonction.

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

Pour plus de détails, voir l’exemple de déclencheur.

Configuration

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

Modèle v4
Modèle v3

Le tableau suivant décrit les propriétés que vous pouvez définir sur l’objet options passé aux méthodes app.serviceBusQueue() ou app.serviceBusTopic().

Propriété	Description
queueName	Nom de la file d’attente à surveiller. Défini uniquement en cas de surveillance d’une file d’attente, ne s’applique pas à une rubrique.
topicName	Nom de la rubrique à surveiller. Défini uniquement en cas de surveillance d’une rubrique, ne s’applique pas à une file d’attente.
subscriptionName	Nom de l’abonnement à surveiller. Défini uniquement en cas de surveillance d’une 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	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 une 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 versions 2.x et ultérieures, cette propriété n’est pas disponible parce que la version la plus récente du Kit de développement logiciel (SDK) Service Bus ne prend pas en charge les opérations de gestion.
isSessionsEnabled	`true` en cas de connexion à une file d’attente ou à un abonnement `true`. Sinon `false`, qui est la valeur par défaut.
autoComplete	Doit être `true` pour les fonctions non C#, ce qui signifie que le déclencheur doit automatiquement terminer l’appel après le traitement ou que le code de la fonction termine l’appel manuellement. Si la valeur est `true`, le déclencheur termine automatiquement le message si l’exécution de la fonction se termine correctement et abandonne le message dans le cas contraire. Les exceptions de la fonction entraînent l’appel par le runtime de `abandonAsync` en arrière-plan. Si aucune exception ne se produit, `completeAsync` est appelé en arrière-plan. Cette propriété est disponible uniquement dans Azure Functions 2.x et versions ultérieures.

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 `serviceBusTrigger`. Cette propriété est définie automatiquement lorsque vous créez le déclencheur dans le portail Azure.
direction	Doit être défini 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 représente le message de la file d’attente ou de la rubrique dans le code de la fonction.
queueName	Nom de la file d’attente à surveiller. Défini uniquement en cas de surveillance d’une file d’attente, ne s’applique pas à une rubrique.
topicName	Nom de la rubrique à surveiller. Défini uniquement en cas de surveillance d’une rubrique, ne s’applique pas à une file d’attente.
subscriptionName	Nom de l’abonnement à surveiller. Défini uniquement en cas de surveillance d’une 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	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 une 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 versions 2.x et ultérieures, cette propriété n’est pas disponible parce que la version la plus récente du Kit de développement logiciel (SDK) Service Bus ne prend pas en charge les opérations de gestion.
isSessionsEnabled	`true` en cas de connexion à une file d’attente ou à un abonnement `true`. Sinon `false`, qui est la valeur par défaut.
autoComplete	Doit être `true` pour les fonctions non C#, ce qui signifie que le déclencheur doit automatiquement terminer l’appel après le traitement ou que le code de la fonction termine l’appel manuellement. Si la valeur est `true`, le déclencheur termine automatiquement le message si l’exécution de la fonction se termine correctement et abandonne le message dans le cas contraire. Les exceptions de la fonction entraînent l’appel par le runtime de `abandonAsync` en arrière-plan. Si aucune exception ne se produit, `completeAsync` est appelé en arrière-plan. Cette propriété est disponible uniquement dans Azure Functions 2.x et versions ultérieures.

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 `serviceBusTrigger`. Cette propriété est définie automatiquement lorsque vous créez le déclencheur dans le portail Azure.
direction	Doit être défini 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 représente le message de la file d’attente ou de la rubrique dans le code de la fonction.
queueName	Nom de la file d’attente à surveiller. Défini uniquement en cas de surveillance d’une file d’attente, ne s’applique pas à une rubrique.
topicName	Nom de la rubrique à surveiller. Défini uniquement en cas de surveillance d’une rubrique, ne s’applique pas à une file d’attente.
subscriptionName	Nom de l’abonnement à surveiller. Défini uniquement en cas de surveillance d’une 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	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 une 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 versions 2.x et ultérieures, cette propriété n’est pas disponible parce que la version la plus récente du Kit de développement logiciel (SDK) Service Bus ne prend pas en charge les opérations de gestion.
isSessionsEnabled	`true` en cas de connexion à une file d’attente ou à un abonnement `true`. Sinon `false`, qui est la valeur par défaut.
autoComplete	Doit être `true` pour les fonctions non C#, ce qui signifie que le déclencheur doit automatiquement terminer l’appel après le traitement ou que le code de la fonction termine l’appel manuellement. Si la valeur est `true`, le déclencheur termine automatiquement le message si l’exécution de la fonction se termine correctement et abandonne le message dans le cas contraire. Les exceptions de la fonction entraînent l’appel par le runtime de `abandonAsync` en arrière-plan. Si aucune exception ne se produit, `completeAsync` est appelé en arrière-plan. Cette propriété est disponible uniquement dans Azure Functions 2.x et versions ultérieures.

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

Les types de paramètres suivants sont pris en charge par toutes les modalités C# et les versions d’extension :

Type	Description
System.String	À utiliser lorsque le message est du texte simple.
byte[]	À utiliser pour les messages de données binaires.
Object	Lorsqu’un message contient du code JSON, Functions tente de désérialiser les données JSON dans un type d’objet CLR traditionnel connu.

Les types de paramètres spécifiques à la messagerie contiennent des métadonnées de message supplémentaires. Les types spécifiques pris en charge par le déclencheur Service Bus dépendent de la version du runtime Functions, de la version du package d’extension et de la modalité C# utilisée.

Utilisez le type ServiceBusReceivedMessage pour recevoir les métadonnées de message des des abonnements et files d’attente Service Bus. Pour en savoir plus, consultez Messages, charges utiles et sérialisation.

Dans les bibliothèques de classes C#, le constructeur de l’attribut prend le nom de la file d’attente ou de la rubrique et de l’abonnement.

Vous pouvez également utiliser l’attribut ServiceBusAccountAttribute pour spécifier le compte Service Bus à utiliser. Le constructeur prend le nom d’un paramètre d’application comportant une chaîne de connexion Service Bus. 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 :

[ServiceBusAccount("ClassLevelServiceBusAppSetting")]
public static class AzureFunctions
{
    [ServiceBusAccount("MethodLevelServiceBusAppSetting")]
    [FunctionName("ServiceBusQueueTriggerCSharp")]
    public static void Run(
        [ServiceBusTrigger("myqueue", AccessRights.Manage)] 
        string myQueueItem, ILogger log)
{
    ...
}

Le compte Service Bus à utiliser est déterminé dans l’ordre suivant :

La propriété Connection de l’attribut ServiceBusTrigger.
L’attribut ServiceBusAccount appliqué au même paramètre que l’attribut ServiceBusTrigger.
L’attribut ServiceBusAccount appliqué à la fonction.
L’attribut ServiceBusAccount appliqué à la classe.
Le paramètre d’application AzureWebJobsServiceBus.

Utilisez le type Message pour recevoir des messages avec des métadonnées. Pour en savoir plus, consultez Messages, charges utiles et sérialisation.

Le 30 septembre 2026, nous retirerons les bibliothèques WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus et com.microsoft.azure.servicebus du SDK Azure Service Bus, qui ne sont pas conformes aux directives du SDK Azure. Nous mettrons également fin à la prise en charge du protocole SBMP. Vous ne pourrez donc plus utiliser ce protocole après le 30 septembre 2026. Migrez vers les dernières bibliothèques du kit de développement logiciel (SDK) Azure, qui offre des correctifs de sécurité critiques et des fonctionnalités améliorées, avant cette date.

Bien que les anciennes bibliothèques puissent toujours être utilisées au-delà du 30 septembre 2026, elles ne seront plus prises en charge officiellement et mises à jour par Microsoft. Pour plus d’informations, consultez l’annonce concernant l’arrêt de la prise en charge.

Dans les bibliothèques de classes C#, le constructeur de l’attribut prend le nom de la file d’attente ou de la rubrique et de l’abonnement.

[ServiceBusAccount("ClassLevelServiceBusAppSetting")]
public static class AzureFunctions
{
    [ServiceBusAccount("MethodLevelServiceBusAppSetting")]
    [FunctionName("ServiceBusQueueTriggerCSharp")]
    public static void Run(
        [ServiceBusTrigger("myqueue", AccessRights.Manage)] 
        string myQueueItem, ILogger log)
{
    ...
}

Le compte Service Bus à utiliser est déterminé dans l’ordre suivant :

La propriété Connection de l’attribut ServiceBusTrigger.
L’attribut ServiceBusAccount appliqué au même paramètre que l’attribut ServiceBusTrigger.
L’attribut ServiceBusAccount appliqué à la fonction.
L’attribut ServiceBusAccount appliqué à la classe.
Le paramètre d’application AzureWebJobsServiceBus.

Les types de paramètres suivants sont disponibles pour le message de la file d’attente ou de la rubrique :

BrokeredMessage : vous donne le message désérialisé avec la méthode BrokeredMessage.GetBody<T>().
MessageReceiver : permet de recevoir et d’accuser réception des messages du conteneur de messages, ce qui est obligatoire lorsque autoComplete est défini sur false.

Le 30 septembre 2026, nous retirerons les bibliothèques WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus et com.microsoft.azure.servicebus du SDK Azure Service Bus, qui ne sont pas conformes aux directives du SDK Azure. Nous mettrons également fin à la prise en charge du protocole SBMP. Vous ne pourrez donc plus utiliser ce protocole après le 30 septembre 2026. Migrez vers les dernières bibliothèques du kit de développement logiciel (SDK) Azure, qui offre des correctifs de sécurité critiques et des fonctionnalités améliorées, avant cette date.

Bien que les anciennes bibliothèques puissent toujours être utilisées au-delà du 30 septembre 2026, elles ne seront plus prises en charge officiellement et mises à jour par Microsoft. Pour plus d’informations, consultez l’annonce concernant l’arrêt de la prise en charge.

Dans les bibliothèques de classes C#, le constructeur de l’attribut prend le nom de la file d’attente ou de la rubrique et de l’abonnement. Dans Azure Functions version 1.x, vous pouvez également spécifier les droits d’accès de la connexion. Si vous ne spécifiez pas de droits d’accès, la valeur par défaut est Manage.

[ServiceBusAccount("ClassLevelServiceBusAppSetting")]
public static class AzureFunctions
{
    [ServiceBusAccount("MethodLevelServiceBusAppSetting")]
    [FunctionName("ServiceBusQueueTriggerCSharp")]
    public static void Run(
        [ServiceBusTrigger("myqueue", AccessRights.Manage)] 
        string myQueueItem, ILogger log)
{
    ...
}

Le compte Service Bus à utiliser est déterminé dans l’ordre suivant :

La propriété Connection de l’attribut ServiceBusTrigger.
L’attribut ServiceBusAccount appliqué au même paramètre que l’attribut ServiceBusTrigger.
L’attribut ServiceBusAccount appliqué à la fonction.
L’attribut ServiceBusAccount appliqué à la classe.
Le paramètre d’application AzureWebJobsServiceBus.

Lorsque vous souhaitez que la fonction traite un seul message, le déclencheur 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	Quand un événement contient des données JSON, Functions tente de désérialiser les données JSON dans un type d’Objet CLR traditionnel (OCT).
ServiceBusReceivedMessage¹	L’objet message. Lors de la liaison à `ServiceBusReceivedMessage`, vous pouvez également inclure un paramètre de type ServiceBusMessageActions^1,2 pour effectuer des actions de règlement des messages.

Lorsque vous souhaitez que la fonction traite un lot de messages, le déclencheur Service Bus peut se lier aux types suivants :

Type	Description
`T[]` où `T` est l’un des types de messages uniques	Tableau d’événements du lot. Chaque entrée représente un événement. Lors de la liaison à `ServiceBusReceivedMessage[]`, vous pouvez également inclure un paramètre de type ServiceBusMessageActions^1,2 pour effectuer des actions de règlement des messages.

¹ Pour utiliser ces types, vous devez référencer Microsoft.Azure.Functions.Worker.Extensions.ServiceBus 5.14.1 ou version ultérieure et les dépendances courantes des liaisons de type kit de développement logiciel (SDK).

² Lors de l’utilisation ServiceBusMessageActions, définissez la AutoCompleteMessages propriété de l’attribut de déclencheur sur false. Cela empêche le runtime de tenter de terminer les messages après un appel de fonction réussi.

Si la propriété Connection n’est pas définie, Functions recherche un paramètre d’application nommé AzureWebJobsServiceBus, qui est le nom par défaut de la chaîne de connexion Service Bus. Vous pouvez également définir la propriété Connection pour spécifier le nom d’un paramètre d’application contenant la chaîne de connexion Service Bus à utiliser.

Le message de Service Bus entrant est disponible via un paramètre ServiceBusQueueMessage ou ServiceBusTopicMessage.

Modèle v4
Modèle v3

Accédez à la file d’attente ou au message du sujet comme premier argument de votre fonction. Le message Service Bus est passé à la fonction en tant que chaîne ou en tant qu’objet JSON.

L’instance Service Bus est disponible via le paramètre configuré dans la propriété de nom du fichier function.json.

Le message de la file d’attente est disponible pour la fonction via un paramètre de type func.ServiceBusMessage. Le message Service Bus est passé à la fonction en tant que chaîne ou en tant qu’objet JSON.

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 :

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 à 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éclencheur¹	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

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

Messages incohérents

La gestion des messages incohérents ne peut pas être contrôlée ou configurée dans Azure Functions. Service Bus gère lui-même les messages incohérents.

Comportement de PeekLock

Le runtime Functions reçoit un message en mode PeekLock.

Par défaut, le runtime appelle Complete le message si la fonction se termine correctement, ou appelle Abandon si la fonction échoue. Vous pouvez désactiver la saisie semi-automatique avec la autoCompleteMessages propriété dans host.jsonou via une propriété sur l’attribut de déclencheur. Vous devez désactiver l’achèvement automatique si votre code de fonction gère le règlement des messages.

Si la fonction s’exécute au-delà du délai imparti PeekLock, le verrou est automatiquement renouvelé tant que la fonction s’exécute. Le maxAutoRenewDuration est configurable dans host.json, qui est mappé à ServiceBusProcessor.MaxAutoLockRenewalDuration. La valeur par défaut pour ce paramètre est de 5 minutes.

Métadonnées de message

Les types spécifiques à la messagerie vous permettent de récupérer facilement les métadonnées en tant que propriétés de l’objet. Ces propriétés dépendent de la version du runtime Functions, de la version du package d’extension et de la modalité C# utilisée.

Ces propriétés sont membres de la classe ServiceBusReceivedMessage.

Propriété	Type	Description
`ApplicationProperties`	`ApplicationProperties`	Propriétés définies par l’expéditeur.
`ContentType`	`string`	Identificateur de type de contenu utilisé par l’expéditeur et le récepteur pour une logique spécifique à l’application.
`CorrelationId`	`string`	L’ID de corrélation.
`DeliveryCount`	`Int32`	Le nombre de remises.
`EnqueuedTime`	`DateTime`	Le temps de file d’attente en UTC.
`ScheduledEnqueueTimeUtc`	`DateTime`	Le temps de file d’attente prévu en UTC.
`ExpiresAt`	`DateTime`	Le délai d'expiration en UTC.
`MessageId`	`string`	Valeur définie par l’utilisateur que Service Bus peut utiliser pour identifier les messages en double, si cette fonctionnalité est activée.
`ReplyTo`	`string`	L’adresse de file d’attente de réponse.
`Subject`	`string`	Étiquette propre à l’application qui peut être utilisée à la place de la propriété de métadonnées `Label`.
`To`	`string`	L’adresse de destination.

Ces propriétés sont membres de la classe Message.

Le 30 septembre 2026, nous retirerons les bibliothèques WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus et com.microsoft.azure.servicebus du SDK Azure Service Bus, qui ne sont pas conformes aux directives du SDK Azure. Nous mettrons également fin à la prise en charge du protocole SBMP. Vous ne pourrez donc plus utiliser ce protocole après le 30 septembre 2026. Migrez vers les dernières bibliothèques du kit de développement logiciel (SDK) Azure, qui offre des correctifs de sécurité critiques et des fonctionnalités améliorées, avant cette date.

Bien que les anciennes bibliothèques puissent toujours être utilisées au-delà du 30 septembre 2026, elles ne seront plus prises en charge officiellement et mises à jour par Microsoft. Pour plus d’informations, consultez l’annonce concernant l’arrêt de la prise en charge.

Propriété	Type	Description
`ContentType`	`string`	Identificateur de type de contenu utilisé par l’expéditeur et le récepteur pour une logique spécifique à l’application.
`CorrelationId`	`string`	L’ID de corrélation.
`DeliveryCount`	`Int32`	Le nombre de remises.
`ScheduledEnqueueTimeUtc`	`DateTime`	Le temps de file d’attente prévu en UTC.
`ExpiresAtUtc`	`DateTime`	Le délai d'expiration en UTC.
`Label`	`string`	L’étiquette spécifique de l’application.
`MessageId`	`string`	Valeur définie par l’utilisateur que Service Bus peut utiliser pour identifier les messages en double, si cette fonctionnalité est activée.
`ReplyTo`	`string`	L’adresse de file d’attente de réponse.
`To`	`string`	L’adresse de destination.
`UserProperties`	`IDictionary<string, object>`	Propriétés définies par l’expéditeur.

Ces propriétés sont des membres des classes BrokeredMessage et MessageReceiver.

Le 30 septembre 2026, nous retirerons les bibliothèques WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus et com.microsoft.azure.servicebus du SDK Azure Service Bus, qui ne sont pas conformes aux directives du SDK Azure. Nous mettrons également fin à la prise en charge du protocole SBMP. Vous ne pourrez donc plus utiliser ce protocole après le 30 septembre 2026. Migrez vers les dernières bibliothèques du kit de développement logiciel (SDK) Azure, qui offre des correctifs de sécurité critiques et des fonctionnalités améliorées, avant cette date.

Bien que les anciennes bibliothèques puissent toujours être utilisées au-delà du 30 septembre 2026, elles ne seront plus prises en charge officiellement et mises à jour par Microsoft. Pour plus d’informations, consultez l’annonce concernant l’arrêt de la prise en charge.

Propriété	Type	Description
`ContentType`	`string`	Identificateur de type de contenu utilisé par l’expéditeur et le récepteur pour une logique spécifique à l’application.
`CorrelationId`	`string`	L’ID de corrélation.
`DeadLetterSource`	`string`	La source de lettre morte.
`DeliveryCount`	`Int32`	Le nombre de remises.
`EnqueuedTimeUtc`	`DateTime`	Le temps de file d’attente en UTC.
`ExpiresAtUtc`	`DateTime`	Le délai d'expiration en UTC.
`Label`	`string`	L’étiquette spécifique de l’application.
`MessageId`	`string`	Valeur définie par l’utilisateur que Service Bus peut utiliser pour identifier les messages en double, si cette fonctionnalité est activée.
`MessageReceiver`	`MessageReceiver`	Récepteur du message Service Bus. Peut être utilisé pour abandonner, terminer ou mettre en file d’attente le message.
`MessageSession`	`MessageSession`	Récepteur de messages spécifiquement pour les files d’attente et les rubriques activées par la session.
`ReplyTo`	`string`	L’adresse de file d’attente de réponse.
`SequenceNumber`	`long`	Le numéro unique attribué à un message par Service Bus.
`To`	`string`	L’adresse de destination.
`UserProperties`	`IDictionary<string, object>`	Propriétés définies par l’expéditeur.

Ces propriétés sont membres de la classe ServiceBusReceivedMessage.

Propriété	Type	Description
`ApplicationProperties`	`ApplicationProperties`	Propriétés définies par l’expéditeur.
`ContentType`	`string`	Identificateur de type de contenu utilisé par l’expéditeur et le récepteur pour une logique spécifique à l’application.
`CorrelationId`	`string`	L’ID de corrélation.
`DeliveryCount`	`Int32`	Le nombre de remises.
`EnqueuedTime`	`DateTime`	Le temps de file d’attente en UTC.
`ScheduledEnqueueTimeUtc`	`DateTime`	Le temps de file d’attente prévu en UTC.
`ExpiresAt`	`DateTime`	Le délai d'expiration en UTC.
`MessageId`	`string`	Valeur définie par l’utilisateur que Service Bus peut utiliser pour identifier les messages en double, si cette fonctionnalité est activée.
`ReplyTo`	`string`	L’adresse de file d’attente de réponse.
`Subject`	`string`	Étiquette propre à l’application qui peut être utilisée à la place de la propriété de métadonnées `Label`.
`To`	`string`	L’adresse de destination.

Étapes suivantes

Envoyer des messages Azure Service Bus à partir d’Azure Functions (liaison de sortie)

Partager via

Déclencheur Azure Service Bus pour Azure Functions

Exemple

Attributs

Décorateurs

Annotations

Configuration

Utilisation

Connexions

Chaîne de connexion

Connexions basées sur l’identité

Accorder l’autorisation à l’identité

Messages incohérents

Comportement de PeekLock

Métadonnées de message

Étapes suivantes

Commentaires

Ressources supplémentaires