Trigger del bus di servizio di Azure per Funzioni di Azure

Articolo
10/18/2023

Usare il trigger di bus di servizio per rispondere a messaggi da una coda o da un argomento del bus di servizio. A partire dalla versione di estensione 3.1.0, è possibile attivare una coda o un argomento abilitato per la sessione.

Per informazioni sui dettagli di impostazione e configurazione, vedere la panoramica.

bus di servizio decisioni di ridimensionamento per i piani a consumo e Premium vengono prese in base al ridimensionamento basato sulla destinazione. Per altre informazioni, vedere Scalabilità basata su destinazione.

Importante

Questo articolo usa schede per supportare le versioni diverse del modello di programmazione Node.js. Il modello v4 è disponibile a livello generale ed è progettato per offrire un'esperienza più flessibile e intuitiva per gli sviluppatori JavaScript e TypeScript. Per altre informazioni sul funzionamento del modello v4, vedere la guida per gli sviluppatori di Node.js per Funzioni di Azure. Altre informazioni sulle differenze tra i modelli v3 e v4 sono disponibili nella guida alla migrazione.

Funzioni di Azure supporta due modelli di programmazione per Python. Il modo in cui si definiscono le associazioni dipende dal modello di programmazione scelto.

Il modello di programmazione Python v2 consente di definire associazioni usando elementi Decorator direttamente nel codice della funzione Python. Per altre informazioni, vedere la Guida per sviluppatori Python.

Questo articolo supporta entrambi i modelli di programmazione.

Esempio

È possibile creare una funzione C# usando una delle modalità C# seguenti:

Modello di lavoro isolato: funzione C# compilata eseguita in un processo di lavoro isolato dal runtime. Il processo di lavoro isolato è necessario per supportare le funzioni C# in esecuzione in LTS e versioni non LTS .NET e .NET Framework. Le estensioni per le funzioni del processo di lavoro isolato usano Microsoft.Azure.Functions.Worker.Extensions.* spazi dei nomi.
Modello in-process: funzione C# compilata eseguita nello stesso processo del runtime di Funzioni. In una variante di questo modello, le funzioni possono essere eseguite usando script C#, che è supportato principalmente per la modifica del portale C#. Le estensioni per le funzioni in-process usano Microsoft.Azure.WebJobs.Extensions.* spazi dei nomi.

Importante

Il supporto terminerà per il modello in-process il 10 novembre 2026. È consigliabile eseguire la migrazione delle app al modello di lavoro isolato per il supporto completo.

Modello di lavoro isolato
Modello di processo

Questo codice definisce e inizializza :ILogger

private readonly ILogger<ServiceBusReceivedMessageFunctions> _logger;

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

Questo esempio mostra una funzione C# che riceve un singolo messaggio della coda bus di servizio e lo scrive nei log:

[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;
}

Questo esempio mostra una funzione C# che riceve più messaggi di coda bus di servizio in un singolo batch e scrive ognuno nei log:

[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);
    }
}

Questo esempio mostra una funzione C# che riceve più messaggi di coda bus di servizio, lo scrive nei log e quindi risolve il messaggio come completato:

[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'esempio seguente mostra una funzione C# che legge i metadati del messaggio e registra un messaggio della coda del bus di servizio:

[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 funzione Java seguente usa l'annotazione @ServiceBusQueueTrigger della libreria di runtime delle funzioni Java per descrivere la configurazione per un trigger della coda bus di servizio. La funzione afferra il messaggio inserito nella coda e lo aggiunge ai log.

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

Le funzioni Java possono essere attivate anche quando un messaggio viene aggiunto a un argomento bus di servizio. Nell'esempio seguente viene usata l'annotazione @ServiceBusTopicTrigger per descrivere la configurazione del trigger.

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

Modello v4
Modello v3

L'esempio seguente illustra una funzione TypeScript bus di servizio trigger. La funzione legge i metadati del messaggio e registra un messaggio della coda del bus di servizio.

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,
});

Modello v4
Modello v3

L'esempio seguente illustra una funzione JavaScript trigger bus di servizio. La funzione legge i metadati del messaggio e registra un messaggio della coda del bus di servizio.

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'esempio seguente mostra un'associazione di trigger del bus di servizio in un file function.json e una funzione JavaScript che usa l'associazione. La funzione legge i metadati del messaggio e registra un messaggio della coda del bus di servizio.

Ecco i dati di associazione nel file function.json:

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

Ecco il codice 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'esempio seguente illustra un'associazione di trigger bus di servizio in un file function.json e una funzione di PowerShell che usa l'associazione.

Ecco i dati di associazione nel file function.json:

{
  "bindings": [
    {
      "name": "mySbMsg",
      "type": "serviceBusTrigger",
      "direction": "in",
      "topicName": "mytopic",
      "subscriptionName": "mysubscription",
      "connection": "AzureServiceBusConnectionString"
    }
  ]
}

Ecco la funzione eseguita quando viene inviato un messaggio di bus di servizio.

param([string] $mySbMsg, $TriggerMetadata)

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

Nell'esempio seguente viene illustrato come leggere un messaggio della coda di bus di servizio tramite un trigger. L'esempio dipende dal fatto che si usi il modello di programmazione Python v1 o 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'))

Un'associazione bus di servizio viene definita in function.json dove il tipo è impostato su serviceBusTrigger e la coda viene impostata da queueName.

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

Il codice in _init_.py dichiara un parametro come func.ServiceBusMessage, che consente di leggere il messaggio della coda nella funzione.

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)

Nell'esempio seguente viene illustrato come leggere un argomento della coda bus di servizio tramite un trigger.

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)

Un'associazione bus di servizio viene definita in function.json dove il tipo è impostato su serviceBusTrigger e l'argomento viene impostato da topicName.

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

Il codice in _init_.py dichiara un parametro come func.ServiceBusMessage, che consente di leggere l'argomento nella funzione.

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)

Attributi

Sia le librerie C# in-process che il processo di lavoro isolato usano l'attributo ServiceBusTriggerAttribute per definire il trigger di funzione. Lo script C# usa invece un file di configurazione function.json come descritto nella guida per gli script C#.

Modello di lavoro isolato
Modello di processo

La tabella seguente illustra le proprietà che è possibile impostare usando questo attributo trigger:

Proprietà	Descrizione
QueueName	Nome della coda da monitorare. Impostare questa proprietà solo quando si monitora una coda, non un argomento.
topicName	Nome dell'argomento da monitorare. Impostare questa proprietà solo quando si monitora un argomento, non una coda.
SubscriptionName	Nome della sottoscrizione da monitorare. Impostare questa proprietà solo quando si monitora un argomento, non una coda.
Connessione	Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi a bus di servizio. Vedere Connessioni.
IsBatched	I messaggi vengono recapitati in batch. Richiede una matrice o un tipo di raccolta.
IsSessionsEnabled	`true` se ci si connette a una coda o a una sottoscrizione compatibile con la sessione. `false` in caso contrario, ovvero il valore predefinito.
Completamento automaticoMessages	`true` se il trigger deve completare automaticamente il messaggio dopo una chiamata riuscita. `false` in caso contrario, ad esempio quando si gestisce la liquidazione dei messaggi nel codice. Se non impostato in modo esplicito, il comportamento sarà basato sulla configurazione in `host.json`.`autoCompleteMessages`

La tabella seguente illustra le proprietà che è possibile impostare usando questo attributo trigger:

Proprietà	Descrizione
QueueName	Nome della coda da monitorare. Impostare questa proprietà solo quando si monitora una coda, non un argomento.
topicName	Nome dell'argomento da monitorare. Impostare questa proprietà solo quando si monitora un argomento, non una coda.
SubscriptionName	Nome della sottoscrizione da monitorare. Impostare questa proprietà solo quando si monitora un argomento, non una coda.
Connessione	Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi a bus di servizio. Vedere Connessioni.
Accesso	Diritti di accesso per la stringa di connessione. I valori disponibili sono `manage` e `listen`. Il valore predefinito è `manage`, che indica che `connection` dispone dell'autorizzazione Gestisci. Se si usa una stringa di connessione priva dell'autorizzazione Gestisci, impostare `accessRights` su "listen". In caso contrario, il runtime di Funzioni potrebbe non riuscire a eseguire operazioni che richiedono diritti di gestione. In Funzioni di Azure versione 2.x e successive questa proprietà non è disponibile perché la versione più recente di bus di servizio SDK non supporta le operazioni di gestione.
IsBatched	I messaggi vengono recapitati in batch. Richiede una matrice o un tipo di raccolta.
IsSessionsEnabled	`true` se ci si connette a una coda o a una sottoscrizione compatibile con la sessione. `false` in caso contrario, ovvero il valore predefinito.
Completamento automatico	`true` Se il trigger deve chiamare automaticamente il completamento dopo l'elaborazione o se il codice della funzione chiamerà manualmente il completamento. Se impostato su `true`, il trigger completa automaticamente il messaggio se l'esecuzione della funzione viene completata correttamente e il messaggio viene abbandonato in caso contrario. Quando è impostato su `false`, si è responsabili della chiamata dei metodi ServiceBusReceiver per completare, abbandonare o disattivare il messaggio, la sessione o il batch. Quando viene generata un'eccezione (e nessuno dei `ServiceBusReceiver` metodi viene chiamato), il blocco rimane. Una volta scaduto il blocco, il messaggio viene nuovamente accodato con l'incremento `DeliveryCount` e il blocco viene rinnovato automaticamente.

Quando si sviluppa in locale, aggiungere le impostazioni dell'applicazione nel file local.settings.json nella Values raccolta.

Elementi Decorator

Si applica solo al modello di programmazione Python v2.

Per le funzioni Python v2 definite usando un elemento Decorator, le proprietà seguenti in service_bus_queue_trigger:

Proprietà	Descrizione
`arg_name`	Nome della variabile che rappresenta il messaggio della coda o dell'argomento nel codice della funzione.
`queue_name`	Nome della coda da monitorare. Impostare questa proprietà solo quando si monitora una coda, non un argomento.
`connection`	Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi a bus di servizio. Vedere Connessioni.

Per le funzioni Python definite tramite function.json, vedere la sezione Configurazione .

Annotazioni

L'annotazione ServiceBusQueueTrigger consente di creare una funzione che viene eseguita quando viene creato un messaggio della coda di bus di servizio. Le opzioni di configurazione disponibili includono le proprietà seguenti:

Proprietà	Descrizione
name	Nome della variabile che rappresenta il messaggio della coda o dell'argomento nel codice della funzione.
queueName	Nome della coda da monitorare. Impostare questa proprietà solo quando si monitora una coda, non un argomento.
topicName	Nome dell'argomento da monitorare. Impostare questa proprietà solo quando si monitora un argomento, non una coda.
subscriptionName	Nome della sottoscrizione da monitorare. Impostare questa proprietà solo quando si monitora un argomento, non una coda.
connection	Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi a bus di servizio. Vedere Connessioni.

L'annotazione ServiceBusTopicTrigger consente di designare un argomento e una sottoscrizione per specificare i dati che attivano la funzione.

Quando si sviluppa in locale, aggiungere le impostazioni dell'applicazione nel file local.settings.json nella Values raccolta.

Per altri dettagli, vedere l'esempio di trigger.

Impostazione

Si applica solo al modello di programmazione Python v1.

Modello v4
Modello v3

Nella tabella seguente vengono illustrate le proprietà che è possibile impostare sull'oggetto options passato ai app.serviceBusQueue() metodi o app.serviceBusTopic() .

Proprietà	Descrizione
queueName	Nome della coda da monitorare. Impostare questa proprietà solo quando si monitora una coda, non un argomento.
topicName	Nome dell'argomento da monitorare. Impostare questa proprietà solo quando si monitora un argomento, non una coda.
subscriptionName	Nome della sottoscrizione da monitorare. Impostare questa proprietà solo quando si monitora un argomento, non una coda.
connection	Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi a bus di servizio. Vedere Connessioni.
accessRights	Diritti di accesso per la stringa di connessione. I valori disponibili sono `manage` e `listen`. Il valore predefinito è `manage`, che indica che `connection` dispone dell'autorizzazione Gestisci. Se si usa una stringa di connessione priva dell'autorizzazione Gestisci, impostare `accessRights` su "listen". In caso contrario, il runtime di Funzioni potrebbe non riuscire a eseguire operazioni che richiedono diritti di gestione. In Funzioni di Azure versione 2.x e successive questa proprietà non è disponibile perché la versione più recente di bus di servizio SDK non supporta le operazioni di gestione.
isSessionsEnabled	`true` se ci si connette a una coda o a una sottoscrizione compatibile con la sessione. `false` in caso contrario, ovvero il valore predefinito.
Completamento automatico	Deve essere `true` per le funzioni non C#, il che significa che il trigger deve chiamare automaticamente completato dopo l'elaborazione o il codice della funzione chiama manualmente completato. Se impostato su `true`, il trigger completa automaticamente il messaggio se l'esecuzione della funzione viene completata correttamente e abbandona il messaggio in caso contrario. Le eccezioni nella funzione generano chiamate `abandonAsync` di runtime in background. Se non si verifica alcuna eccezione, `completeAsync` viene chiamato in background. Questa proprietà è disponibile solo in Funzioni di Azure 2.x e versioni successive.

Nella tabella seguente sono illustrate le proprietà di configurazione dell'associazione impostate nel file function.json.

Proprietà	Descrizione
type	Deve essere impostato su `serviceBusTrigger`. Questa proprietà viene impostata automaticamente quando si crea il trigger nel portale di Azure.
direction	Il valore deve essere impostato su "in". Questa proprietà viene impostata automaticamente quando si crea il trigger nel portale di Azure.
name	Nome della variabile che rappresenta il messaggio della coda o dell'argomento nel codice della funzione.
queueName	Nome della coda da monitorare. Impostare questa proprietà solo quando si monitora una coda, non un argomento.
topicName	Nome dell'argomento da monitorare. Impostare questa proprietà solo quando si monitora un argomento, non una coda.
subscriptionName	Nome della sottoscrizione da monitorare. Impostare questa proprietà solo quando si monitora un argomento, non una coda.
connection	Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi a bus di servizio. Vedere Connessioni.
accessRights	Diritti di accesso per la stringa di connessione. I valori disponibili sono `manage` e `listen`. Il valore predefinito è `manage`, che indica che `connection` dispone dell'autorizzazione Gestisci. Se si usa una stringa di connessione priva dell'autorizzazione Gestisci, impostare `accessRights` su "listen". In caso contrario, il runtime di Funzioni potrebbe non riuscire a eseguire operazioni che richiedono diritti di gestione. In Funzioni di Azure versione 2.x e successive questa proprietà non è disponibile perché la versione più recente di bus di servizio SDK non supporta le operazioni di gestione.
isSessionsEnabled	`true` se ci si connette a una coda o a una sottoscrizione compatibile con la sessione. `false` in caso contrario, ovvero il valore predefinito.
Completamento automatico	Deve essere `true` per le funzioni non C#, il che significa che il trigger deve chiamare automaticamente completato dopo l'elaborazione o il codice della funzione chiama manualmente completato. Se impostato su `true`, il trigger completa automaticamente il messaggio se l'esecuzione della funzione viene completata correttamente e abbandona il messaggio in caso contrario. Le eccezioni nella funzione generano chiamate `abandonAsync` di runtime in background. Se non si verifica alcuna eccezione, `completeAsync` viene chiamato in background. Questa proprietà è disponibile solo in Funzioni di Azure 2.x e versioni successive.

Quando si sviluppa in locale, aggiungere le impostazioni dell'applicazione nel file local.settings.json nella Values raccolta.

Nella tabella seguente sono illustrate le proprietà di configurazione dell'associazione impostate nel file function.json.

Proprietà di function.json	Descrizione
type	Deve essere impostato su `serviceBusTrigger`. Questa proprietà viene impostata automaticamente quando si crea il trigger nel portale di Azure.
direction	Il valore deve essere impostato su "in". Questa proprietà viene impostata automaticamente quando si crea il trigger nel portale di Azure.
name	Nome della variabile che rappresenta il messaggio della coda o dell'argomento nel codice della funzione.
queueName	Nome della coda da monitorare. Impostare questa proprietà solo quando si monitora una coda, non un argomento.
topicName	Nome dell'argomento da monitorare. Impostare questa proprietà solo quando si monitora un argomento, non una coda.
subscriptionName	Nome della sottoscrizione da monitorare. Impostare questa proprietà solo quando si monitora un argomento, non una coda.
connection	Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi a bus di servizio. Vedere Connessioni.
accessRights	Diritti di accesso per la stringa di connessione. I valori disponibili sono `manage` e `listen`. Il valore predefinito è `manage`, che indica che `connection` dispone dell'autorizzazione Gestisci. Se si usa una stringa di connessione priva dell'autorizzazione Gestisci, impostare `accessRights` su "listen". In caso contrario, il runtime di Funzioni potrebbe non riuscire a eseguire operazioni che richiedono diritti di gestione. In Funzioni di Azure versione 2.x e successive questa proprietà non è disponibile perché la versione più recente di bus di servizio SDK non supporta le operazioni di gestione.
isSessionsEnabled	`true` se ci si connette a una coda o a una sottoscrizione compatibile con la sessione. `false` in caso contrario, ovvero il valore predefinito.
Completamento automatico	Deve essere `true` per le funzioni non C#, il che significa che il trigger deve chiamare automaticamente completato dopo l'elaborazione o il codice della funzione chiama manualmente completato. Se impostato su `true`, il trigger completa automaticamente il messaggio se l'esecuzione della funzione viene completata correttamente e abbandona il messaggio in caso contrario. Le eccezioni nella funzione generano chiamate `abandonAsync` di runtime in background. Se non si verifica alcuna eccezione, `completeAsync` viene chiamato in background. Questa proprietà è disponibile solo in Funzioni di Azure 2.x e versioni successive.

Quando si sviluppa in locale, aggiungere le impostazioni dell'applicazione nel file local.settings.json nella Values raccolta.

Per esempi completi, vedere la sezione di esempio.

Utilizzo

I tipi di parametro seguenti sono supportati da tutte le modalità C# e le versioni delle estensioni:

Tipo	Descrizione
System.String	Usare quando il messaggio è testo semplice.
byte[]	Usare per i messaggi di dati binari.
Oggetto	Quando un messaggio contiene JSON, Funzioni tenta di deserializzare i dati JSON in un tipo di oggetto CLR normale noto.

I tipi di parametro specifici della messaggistica contengono metadati di messaggio aggiuntivi. I tipi specifici supportati dal trigger bus di servizio dipendono dalla versione del runtime di Funzioni, dalla versione del pacchetto di estensione e dalla modalità C# usata.

Usare il tipo ServiceBusReceivedMessage per ricevere i metadati dei messaggi dalle code e dalle sottoscrizioni bus di servizio. Per altre informazioni, vedere Messaggi, payload e serializzazione.

Nelle librerie di classi C# il costruttore dell'attributo prende il nome della coda o dell'argomento e della sottoscrizione.

È anche possibile usare ServiceBusAccountAttribute per specificare l'account bus di servizio da usare. Il costruttore accetta il nome di un'impostazione dell'app che contiene una stringa di connessione del bus di servizio. L'attributo può essere applicato a livello di parametro, metodo o classe. L'esempio seguente illustra il livello classe e il livello metodo:

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

L'account per il bus di servizio da usare è determinato nell'ordine seguente:

La proprietà Connection dell'attributo ServiceBusTrigger.
L'attributo ServiceBusAccount applicato allo stesso parametro dell'attributo ServiceBusTrigger.
L'attributo ServiceBusAccount applicato alla funzione.
L'attributo ServiceBusAccount applicato alla classe.
Impostazione dell'app AzureWebJobsServiceBus .

Usare il tipo di messaggio per ricevere messaggi con metadati. Per altre informazioni, vedere Messaggi, payload e serializzazione.

Il 30 settembre 2026 verranno ritirate le librerie dell'SDK del bus di servizio di Azure WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus e com.microsoft.azure.servicebus, che non sono conformi alle linee guida di Azure SDK. Verrà terminato anche il supporto del protocollo SBMP, quindi non sarà più possibile usare questo protocollo dopo il 30 settembre 2026. Eseguire la migrazione alle librerie più recenti di Azure SDK, che offrono aggiornamenti critici della sicurezza e funzionalità migliorate, prima di tale data.

Anche se le librerie precedenti possono ancora essere usate oltre il 30 settembre 2026, non riceveranno più il supporto e gli aggiornamenti ufficiali da Microsoft. Per altre informazioni, vedere l'annuncio del ritiro del supporto.

Nelle librerie di classi C# il costruttore dell'attributo prende il nome della coda o dell'argomento e della sottoscrizione.

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

L'account per il bus di servizio da usare è determinato nell'ordine seguente:

La proprietà Connection dell'attributo ServiceBusTrigger.
L'attributo ServiceBusAccount applicato allo stesso parametro dell'attributo ServiceBusTrigger.
L'attributo ServiceBusAccount applicato alla funzione.
L'attributo ServiceBusAccount applicato alla classe.
Impostazione dell'app AzureWebJobsServiceBus .

Per il messaggio della coda o dell'argomento sono disponibili i tipi di parametro seguenti:

BrokeredMessage: fornisce il messaggio deserializzato con il metodo BrokeredMessage.GetBody<T>().
MessageReceiver : usato per ricevere e confermare i messaggi dal contenitore di messaggi, che è necessario quando autoComplete è impostato su false.

Il 30 settembre 2026 verranno ritirate le librerie dell'SDK del bus di servizio di Azure WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus e com.microsoft.azure.servicebus, che non sono conformi alle linee guida di Azure SDK. Verrà terminato anche il supporto del protocollo SBMP, quindi non sarà più possibile usare questo protocollo dopo il 30 settembre 2026. Eseguire la migrazione alle librerie più recenti di Azure SDK, che offrono aggiornamenti critici della sicurezza e funzionalità migliorate, prima di tale data.

Anche se le librerie precedenti possono ancora essere usate oltre il 30 settembre 2026, non riceveranno più il supporto e gli aggiornamenti ufficiali da Microsoft. Per altre informazioni, vedere l'annuncio del ritiro del supporto.

Nelle librerie di classi C# il costruttore dell'attributo prende il nome della coda o dell'argomento e della sottoscrizione. In Funzioni di Azure versione 1.x è anche possibile specificare i diritti di accesso della connessione. Se i diritti di accesso non vengono specificati, l'impostazione predefinita è Manage.

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

L'account per il bus di servizio da usare è determinato nell'ordine seguente:

La proprietà Connection dell'attributo ServiceBusTrigger.
L'attributo ServiceBusAccount applicato allo stesso parametro dell'attributo ServiceBusTrigger.
L'attributo ServiceBusAccount applicato alla funzione.
L'attributo ServiceBusAccount applicato alla classe.
Impostazione dell'app AzureWebJobsServiceBus .

Quando si vuole che la funzione elabori un singolo messaggio, il trigger bus di servizio può essere associato ai tipi seguenti:

Tipo	Descrizione
`string`	Messaggio come stringa. Usare quando il messaggio è testo semplice.
`byte[]`	Byte del messaggio.
Tipi serializzabili JSON	Quando un evento contiene dati JSON, Funzioni tenta di deserializzare i dati JSON in un tipo POCO (Plain-Old CLR Object).
ServiceBusReceivedMessage¹	Oggetto messaggio. Quando si esegue l'associazione a `ServiceBusReceivedMessage`, è anche possibile includere un parametro di tipo ServiceBusMessageActions1,2 per eseguire azioni di liquidazione dei messaggi.

Quando si vuole che la funzione elabori un batch di messaggi, il trigger bus di servizio può essere associato ai tipi seguenti:

Tipo	Descrizione
`T[]` dove `T` è uno dei singoli tipi di messaggio	Matrice di eventi del batch. Ogni voce rappresenta un evento. Quando si esegue l'associazione a `ServiceBusReceivedMessage[]`, è anche possibile includere un parametro di tipo ServiceBusMessageActions1,2 per eseguire azioni di liquidazione dei messaggi.

¹ Per usare questi tipi, è necessario fare riferimento a Microsoft.Azure.Functions.Worker.Extensions.ServiceBus 5.14.1 o versioni successive e alle dipendenze comuni per le associazioni di tipi SDK.

² Quando si usa ServiceBusMessageActions, impostare la AutoCompleteMessages proprietà dell'attributo trigger su false. Ciò impedisce al runtime di tentare di completare i messaggi dopo una chiamata di funzione riuscita.

Quando la Connection proprietà non è definita, Funzioni cerca un'impostazione dell'app denominata AzureWebJobsServiceBus, ovvero il nome predefinito per il bus di servizio stringa di connessione. È anche possibile impostare la Connection proprietà per specificare il nome di un'impostazione dell'applicazione contenente il bus di servizio stringa di connessione da usare.

Il messaggio bus di servizio in arrivo è disponibile tramite un ServiceBusQueueMessage parametro o ServiceBusTopicMessage .

Modello v4
Modello v3

Accedere alla coda o al messaggio dell'argomento come primo argomento per la funzione. Il messaggio del bus di servizio viene passato alla funzione come stringa o oggetto JSON.

L'istanza di bus di servizio è disponibile tramite il parametro configurato nella proprietà name del file function.json.

Il messaggio della coda è disponibile per la funzione tramite un parametro digitato come func.ServiceBusMessage. Il messaggio del bus di servizio viene passato alla funzione come stringa o oggetto JSON.

Per un esempio completo, vedere la sezione degli esempi.

Connessioni

La connection proprietà è un riferimento alla configurazione dell'ambiente che specifica come l'app deve connettersi a bus di servizio. Può specificare:

Nome di un'impostazione dell'applicazione contenente un stringa di connessione
Nome di un prefisso condiviso per più impostazioni dell'applicazione, definendo insieme una connessione basata sull'identità.

Se il valore configurato è una corrispondenza esatta per una singola impostazione e una corrispondenza di prefisso per altre impostazioni, viene usata la corrispondenza esatta.

Stringa di connessione

Per ottenere una stringa di connessione, seguire i passaggi indicati in Ottenere le credenziali di gestione. La stringa di connessione deve essere relativa a uno spazio dei nomi del bus di servizio e non limitata a una coda o un argomento specifico.

Questo stringa di connessione deve essere archiviato in un'impostazione dell'applicazione con un nome corrispondente al valore specificato dalla connection proprietà della configurazione dell'associazione.

Se il nome dell'impostazione dell'app inizia con "AzureWebJobs", è possibile specificare solo la parte restante del nome. Ad esempio, se si imposta connection su "MyServiceBus", il runtime di Funzioni cerca un'impostazione dell'app denominata "AzureWebJobsMyServiceBus". Se si lascia vuoto connection, il runtime di Funzioni di Azure usa la stringa di connessione del bus di servizio predefinita nell'impostazione dell'app denominata "AzureWebJobsServiceBus".

Connessioni basate su identità

Se si usa la versione 5.x o successiva dell'estensione, invece di usare un stringa di connessione con un segreto, è possibile che l'app usi un'identità di Microsoft Entra. A tale scopo, è necessario definire le impostazioni con un prefisso comune che esegue il connection mapping alla proprietà nella configurazione del trigger e dell'associazione.

In questa modalità, l'estensione richiede le proprietà seguenti:

Proprietà	Modello di variabile di ambiente	Descrizione	Valore di esempio
Namespace completi	`<CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace`	Spazio dei nomi completo bus di servizio.	<>service_bus_namespace.servicebus.windows.net

È possibile impostare proprietà aggiuntive per personalizzare la connessione. Vedere Proprietà comuni per le connessioni basate su identità.

Nota

Quando si usano Configurazione app di Azure o Key Vault per fornire le impostazioni per le connessioni di Identità gestita, i nomi delle impostazioni devono usare un separatore di chiavi valido, ad esempio : o / invece di __ per garantire che i nomi vengano risolti correttamente.

Ad esempio: <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace.

Quando sono ospitate nel servizio Azure Functions, le connessioni basate su identità usano una identità gestita. Per impostazione predefinita, viene usata l’identità assegnata a livello di sistema, ma è comunque possibile specificare un’identità assegnata dall’utente a cui siano associate le proprietà credential e clientID. Si noti che la configurazione di un'identità assegnata dall'utente con un ID risorsa non è supportata. Quando viene eseguita in altri contesti, ad esempio lo sviluppo locale, viene usata l'identità dello sviluppatore, anche se può essere personalizzata. Vedere Sviluppo locale con connessioni basate su identità.

Concedere l'autorizzazione all'identità

Qualsiasi identità usata deve avere le autorizzazioni necessarie per eseguire le azioni previste. Per la maggior parte dei servizi di Azure, questo significa che è necessario assegnare un ruolo nel controllo degli accessi in base al ruolo di Azure, usando ruoli predefiniti o personalizzati che forniscono tali autorizzazioni.

Importante

È possibile che alcune autorizzazioni esposte dal servizio di destinazione non siano necessarie per tutti i contesti. Laddove possibile, rispettare il principio dei privilegi minimi e concedere all’identità solo i privilegi necessari. Ad esempio, se l'app deve essere in grado di leggere solo da un'origine dati, usare un ruolo che disponga solo dell'autorizzazione per la lettura. Sarebbe inappropriato assegnare un ruolo che consenta anche la scrittura in tale servizio, in quanto sarebbe eccessiva l'autorizzazione per un'operazione di lettura. Analogamente, è consigliabile assicurarsi che l'assegnazione di ruolo sia con ambito solo sulle risorse che devono essere lette.

È necessario creare un'assegnazione di ruolo che fornisce l'accesso agli argomenti e alle code in fase di esecuzione. I ruoli di gestione come Proprietario non sono sufficienti. La tabella seguente illustra i ruoli predefiniti consigliati quando si usa l'estensione del bus di servizio in condizioni di normale funzionamento. L'applicazione potrebbe richiedere autorizzazioni aggiuntive in base al codice scritto.

Tipo di associazione	Ruoli predefiniti di esempio
Trigger¹	Ricevitore dei dati del bus di servizio di Azure, Proprietario dei dati del bus di servizio di Azure
Associazione di output	Mittente dei dati del bus di servizio di Azure

¹ Per l'attivazione dagli argomenti del bus di servizio, l'assegnazione di ruolo deve avere un ambito effettivo sulla risorsa di sottoscrizione del bus di servizio. Se viene incluso solo l'argomento, si verificherà un errore. Alcuni client, ad esempio il portale di Azure, non espongono la risorsa sottoscrizione del bus di servizio come ambito per l'assegnazione di ruoli. In questi casi, è possibile usare l'interfaccia della riga di comando di Azure. Per altre informazioni, vedere Ruoli predefiniti di Azure per il bus di servizio di Azure.

Messaggi non elaborabili

La gestione dei messaggi non elaborabili non può essere controllata o configurata in Funzioni di Azure. I messaggi non elaborabili vengono gestiti dal bus di servizio stesso.

Comportamento di PeekLock

Il runtime di Funzioni di Azure riceve un messaggio in modalità PeekLock.

Per impostazione predefinita, il runtime chiama Complete sul messaggio se la funzione termina correttamente o chiama Abandon se la funzione non riesce. È possibile disabilitare il completamento automatico tramite la autoCompleteMessages proprietà in host.jsono tramite una proprietà sull'attributo trigger. È consigliabile disabilitare il completamento automatico se il codice della funzione gestisce la liquidazione dei messaggi.

Se il tempo di esecuzione della funzione supera il timeout di PeekLock, il blocco viene rinnovato automaticamente finché la funzione è in esecuzione. maxAutoRenewDuration è configurabile in host.json, che esegue il mapping a ServiceBusProcessor.MaxAutoLockRenewalDuration. Il valore predefinito di questa impostazione è 5 minuti.

Metadati del messaggio

I tipi specifici della messaggistica consentono di recuperare facilmente i metadati come proprietà dell'oggetto. Queste proprietà dipendono dalla versione del runtime di Funzioni, dalla versione del pacchetto di estensione e dalla modalità C# usata.

Queste proprietà sono membri della classe ServiceBusReceivedMessage .

Proprietà	Type	Descrizione
`ApplicationProperties`	`ApplicationProperties`	Proprietà impostate dal mittente.
`ContentType`	`string`	Identificatore del tipo di contenuto utilizzato dal mittente e dal destinatario per la logica specifica dell'applicazione.
`CorrelationId`	`string`	L'ID di correlazione.
`DeliveryCount`	`Int32`	Il numero di recapiti.
`EnqueuedTime`	`DateTime`	Il tempo di accodamento in formato UTC.
`ScheduledEnqueueTimeUtc`	`DateTime`	Ora di accodamento pianificata in formato UTC.
`ExpiresAt`	`DateTime`	L'ora di scadenza in formato UTC.
`MessageId`	`string`	Valore definito dall'utente che il bus di servizio può usare per identificare i messaggi duplicati, se abilitato.
`ReplyTo`	`string`	La risposta all'indirizzo della coda.
`Subject`	`string`	Etichetta specifica dell'applicazione che può essere usata al posto della `Label` proprietà dei metadati.
`To`	`string`	L'indirizzo di destinazione.

Queste proprietà sono membri della classe Message .

Il 30 settembre 2026 verranno ritirate le librerie dell'SDK del bus di servizio di Azure WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus e com.microsoft.azure.servicebus, che non sono conformi alle linee guida di Azure SDK. Verrà terminato anche il supporto del protocollo SBMP, quindi non sarà più possibile usare questo protocollo dopo il 30 settembre 2026. Eseguire la migrazione alle librerie più recenti di Azure SDK, che offrono aggiornamenti critici della sicurezza e funzionalità migliorate, prima di tale data.

Anche se le librerie precedenti possono ancora essere usate oltre il 30 settembre 2026, non riceveranno più il supporto e gli aggiornamenti ufficiali da Microsoft. Per altre informazioni, vedere l'annuncio del ritiro del supporto.

Proprietà	Type	Descrizione
`ContentType`	`string`	Identificatore del tipo di contenuto utilizzato dal mittente e dal destinatario per la logica specifica dell'applicazione.
`CorrelationId`	`string`	L'ID di correlazione.
`DeliveryCount`	`Int32`	Il numero di recapiti.
`ScheduledEnqueueTimeUtc`	`DateTime`	Ora di accodamento pianificata in formato UTC.
`ExpiresAtUtc`	`DateTime`	L'ora di scadenza in formato UTC.
`Label`	`string`	Etichetta specifica dell'applicazione.
`MessageId`	`string`	Valore definito dall'utente che il bus di servizio può usare per identificare i messaggi duplicati, se abilitato.
`ReplyTo`	`string`	La risposta all'indirizzo della coda.
`To`	`string`	L'indirizzo di destinazione.
`UserProperties`	`IDictionary<string, object>`	Proprietà impostate dal mittente.

Queste proprietà sono membri delle classi BrokeredMessage e MessageReceiver .

Il 30 settembre 2026 verranno ritirate le librerie dell'SDK del bus di servizio di Azure WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus e com.microsoft.azure.servicebus, che non sono conformi alle linee guida di Azure SDK. Verrà terminato anche il supporto del protocollo SBMP, quindi non sarà più possibile usare questo protocollo dopo il 30 settembre 2026. Eseguire la migrazione alle librerie più recenti di Azure SDK, che offrono aggiornamenti critici della sicurezza e funzionalità migliorate, prima di tale data.

Anche se le librerie precedenti possono ancora essere usate oltre il 30 settembre 2026, non riceveranno più il supporto e gli aggiornamenti ufficiali da Microsoft. Per altre informazioni, vedere l'annuncio del ritiro del supporto.

Proprietà	Type	Descrizione
`ContentType`	`string`	Identificatore del tipo di contenuto utilizzato dal mittente e dal destinatario per la logica specifica dell'applicazione.
`CorrelationId`	`string`	L'ID di correlazione.
`DeadLetterSource`	`string`	La coda di messaggi non recapitabili.
`DeliveryCount`	`Int32`	Il numero di recapiti.
`EnqueuedTimeUtc`	`DateTime`	Il tempo di accodamento in formato UTC.
`ExpiresAtUtc`	`DateTime`	L'ora di scadenza in formato UTC.
`Label`	`string`	Etichetta specifica dell'applicazione.
`MessageId`	`string`	Valore definito dall'utente che il bus di servizio può usare per identificare i messaggi duplicati, se abilitato.
`MessageReceiver`	`MessageReceiver`	bus di servizio ricevitore di messaggi. Può essere usato per abbandonare, completare o disattivare il messaggio.
`MessageSession`	`MessageSession`	Ricevitore di messaggi specifico per le code e gli argomenti abilitati per la sessione.
`ReplyTo`	`string`	La risposta all'indirizzo della coda.
`SequenceNumber`	`long`	Il numero univoco assegnato a un messaggio dal bus di servizio.
`To`	`string`	L'indirizzo di destinazione.
`UserProperties`	`IDictionary<string, object>`	Proprietà impostate dal mittente.

Queste proprietà sono membri della classe ServiceBusReceivedMessage .

Proprietà	Type	Descrizione
`ApplicationProperties`	`ApplicationProperties`	Proprietà impostate dal mittente.
`ContentType`	`string`	Identificatore del tipo di contenuto utilizzato dal mittente e dal destinatario per la logica specifica dell'applicazione.
`CorrelationId`	`string`	L'ID di correlazione.
`DeliveryCount`	`Int32`	Il numero di recapiti.
`EnqueuedTime`	`DateTime`	Il tempo di accodamento in formato UTC.
`ScheduledEnqueueTimeUtc`	`DateTime`	Ora di accodamento pianificata in formato UTC.
`ExpiresAt`	`DateTime`	L'ora di scadenza in formato UTC.
`MessageId`	`string`	Valore definito dall'utente che il bus di servizio può usare per identificare i messaggi duplicati, se abilitato.
`ReplyTo`	`string`	La risposta all'indirizzo della coda.
`Subject`	`string`	Etichetta specifica dell'applicazione che può essere usata al posto della `Label` proprietà dei metadati.
`To`	`string`	L'indirizzo di destinazione.

Passaggi successivi

Inviare messaggi di bus di servizio di Azure da Funzioni di Azure (associazione di output)

Condividi tramite

Trigger del bus di servizio di Azure per Funzioni di Azure

Esempio

Attributi

Elementi Decorator

Annotazioni

Impostazione

Utilizzo

Connessioni

Stringa di connessione

Connessioni basate su identità

Concedere l'autorizzazione all'identità

Messaggi non elaborabili

Comportamento di PeekLock

Metadati del messaggio

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive