Condividi tramite

trigger bus di servizio di Azure per Funzioni di Azure

Usare il trigger bus di servizio per rispondere ai messaggi di una coda o di un argomento 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 su 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 sviluppatori Funzioni di Azure Node.js. 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 versioni LTS e non LTS .NET e .NET Framework. Le estensioni per le funzioni del processo di lavoro isolato usano spazi dei nomi Microsoft.Azure.Functions.Worker.Extensions.*.
  • 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 spazi dei nomi Microsoft.Azure.WebJobs.Extensions.*.

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.

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

La funzione di Java seguente usa l'annotazione @ServiceBusQueueTrigger della libreria di runtime delle funzioni Java funzioni 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);
 }

Java funzioni 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);
    }

Questo esempio usa il tipo SDK ServiceBusReceivedMessage ottenuto da ServiceBusMessageContext fornito dal trigger bus di servizio:

import '@azure/functions-extensions-servicebus'; // Ensure the Service Bus extension is imported
import { app, type InvocationContext } from '@azure/functions';
import { type ServiceBusMessageContext, messageBodyAsJson } from '@azure/functions-extensions-servicebus';

// This sample uses sdkBinding = true with manual message completion.
// With v0.4.0, message.body is returned as a raw Buffer instead of auto-parsed object.
export async function serviceBusQueueTrigger(
    serviceBusMessageContext: ServiceBusMessageContext,
    context: InvocationContext
): Promise<void> {
    const message = serviceBusMessageContext.messages[0];

    // v0.4.0: message.body is a Buffer — use messageBodyAsJson<T>() from the extension for one-line parsing
    const bodyData = messageBodyAsJson(message);
    context.log('Parsed message body:', bodyData);

    // Get current retry count from custom properties, default to 0
    const currentRetryCount = message.applicationProperties?.retryCnt
        ? parseInt(message.applicationProperties.retryCnt as string)
        : 0;
    context.log(`Current retry count: ${currentRetryCount}`);

    if (currentRetryCount >= 3) {
        // After 3 retries, complete the message to remove it from the queue
        context.log(`Maximum retry count (3) reached. Completing message to prevent infinite loop.`);
        await serviceBusMessageContext.actions.complete(message);
        context.log('Message completed after maximum retries');
    } else {
        // Abandon with updated retry count
        const newRetryCount = currentRetryCount + 1;
        const propertiesToModify = {
            retryCnt: newRetryCount.toString(),
            lastRetryTime: new Date().toISOString(),
            errorMessage: 'Processing failed',
        };

        context.log(`Abandoning message with retry count: ${newRetryCount}`);
        await serviceBusMessageContext.actions.abandon(message, propertiesToModify);
    }

    context.log('triggerMetadata: ', context.triggerMetadata);
}

app.serviceBusQueue('serviceBusQueueTrigger1', {
    connection: 'ServiceBusConnection',
    queueName: 'testqueue',
    sdkBinding: true,

Per un altro esempio di uso dei tipi SDK, vedere l'esempio di strategia di backoff esponziale.

Per altre informazioni, vedere Tipi di SDK nell'articolo di riferimento Node.js.

Nell'esempio seguente viene illustrato un trigger bus di servizio TypeScript. La funzione legge i metadati message e registra un messaggio della coda 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,
});

Nell'esempio seguente viene illustrato un trigger bus di servizio FunzioneJavaScript. La funzione legge i metadati message e registra un messaggio della coda 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 illustra un'associazione di trigger bus di servizio in un file function.json e una funzione 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"

Questo esempio usa i tipi SDK per accedere direttamente all'oggetto ServiceBusReceivedMessage sottostante fornito dal trigger bus di servizio:

import logging

import azure.functions as func
import azurefunctions.extensions.bindings.servicebus as servicebus

app = func.FunctionApp(http_auth_level=func.AuthLevel.FUNCTION)

@app.service_bus_queue_trigger(arg_name="receivedmessage",
                               queue_name="QUEUE_NAME",
                               connection="SERVICEBUS_CONNECTION")
def servicebus_queue_trigger(receivedmessage: servicebus.ServiceBusReceivedMessage):
    logging.info("Python ServiceBus queue trigger processed message.")
    logging.info("Receiving: %s\n"
                 "Body: %s\n"
                 "Enqueued time: %s\n"
                 "Lock Token: %s\n"
                 "Message ID: %s\n"
                 "Sequence number: %s\n",
                 receivedmessage,
                 receivedmessage.body,
                 receivedmessage.enqueued_time_utc,
                 receivedmessage.lock_token,
                 receivedmessage.message_id,
                 receivedmessage.sequence_number)

La funzione legge varie proprietà del ServiceBusReceivedMessage tipo e le registra.

Per altri esempi che usano bus di servizio tipi sdk, vedere gli esempi di ServiceBusReceivedMessage. Per un'esercitazione dettagliata su come includere associazioni di tipo SDK nell'app per le funzioni, seguire i binding Python SDK per bus di servizio Sample.

Nota

Le limitazioni note includono:

  • La message proprietà non è supportata.
  • Il supporto dei messaggi batch richiede la versione 4.1039 o successiva del runtime di Funzioni.

Per altre informazioni, inclusi gli altri binding dei tipi di SDK supportati, vedere Associazioni dei tipi di SDK.

Questo esempio illustra 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 v1 o v2 Python.

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'))

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)

Attributi

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

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

Proprietà Descrizione
Nome coda 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 sottoscrizione session-aware. 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 si basa sulla autoCompleteMessages configurazione in host.json.

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

Elementi Decorator

Applica solo per il modello di programmazione Python v2.

Per Python funzioni v2 definite usando un elemento Decorator, le proprietà seguenti nella 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 Configuration.

Annotazioni

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

Proprietà Descrizione
nome 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.
nomeAbbonamento 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.

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

Applica solo al modello di programmazione Python v1.

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.
nomeAbbonamento 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.
accessRights Diritti di accesso per il 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 un stringa di connessione che non dispone dell'autorizzazione Manage, 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 sottoscrizione session-aware. 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 la chiamata 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
tipo Deve essere impostato su serviceBusTrigger. Questa proprietà viene impostata automaticamente quando si crea il trigger nel portale di Azure.
direzione Il valore deve essere impostato su "in". Questa proprietà viene impostata automaticamente quando si crea il trigger nel portale di Azure.
nome 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.
nomeAbbonamento 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.
accessRights Diritti di accesso per il 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 un stringa di connessione che non dispone dell'autorizzazione Manage, 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 sottoscrizione session-aware. 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 la chiamata 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.

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).
ServiceBusReceivedMessage1 Oggetto messaggio.

Quando si esegue l'associazione a ServiceBusReceivedMessage, è anche possibile includere un parametro di tipo ServiceBusMessageActions1 per eseguire message settlement.

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 per eseguire message settlement.

1 Per usare questi tipi, è necessario fare riferimento a Microsoft.Azure. Functions.Worker.Extensions.ServiceBus 5.14.1 o versione successiva e le dipendenze common per le associazioni di tipi SDK.

2 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 proprietà Connection 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 proprietà Connection per specificare il nome di un'impostazione dell'applicazione contenente il bus di servizio stringa di connessione da usare.

Il messaggio di bus di servizio in arrivo è disponibile tramite un parametro /> .

Accedere alla coda o al messaggio dell'argomento come primo argomento per la funzione. Il messaggio 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 bus di servizio viene passato alla funzione come stringa o oggetto JSON.

Le funzioni supportano anche Python associazioni di tipi SDK per bus di servizio di Azure, che consente di usare i dati usando questi tipi di SDK sottostanti:

Importante

Il supporto per i tipi bus di servizio SDK in Python è disponibile in anteprima ed è supportato solo per il modello di programmazione Python v2. Per altre informazioni, vedere tipi SDK in Python.

Per un esempio completo, vedere la sezione degli esempi.

Connessioni

La configurazione della proprietà connection fa riferimento alla configurazione dell'ambiente che specifica la modalità di connessione dell'app 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 che definiscono insieme una connessione di identità gestita.

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

Suggerimento

Usare le connessioni di identità gestite anziché le stringhe di connessione per una maggiore sicurezza. Le stringhe di connessione includono credenziali che possono essere esposte, mentre le identità gestite eliminano la necessità di gestire i segreti.

Se si usa version 5.x o versione successiva dell'estensione, anziché usare un stringa di connessione con un segreto, è possibile che l'app usi un'identità Microsoft Entra. Per usare le identità gestite, 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 impostazioni dell'applicazione seguenti:

Impostazione basata su modello Descrizione Tipo di identità
<CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace Spazio dei nomi completo bus di servizio. Assegnata dal sistema o assegnata dall'utente
<CONNECTION_NAME_PREFIX>__credential Deve essere impostato su managedidentity. Assegnata dall'utente
<CONNECTION_NAME_PREFIX>__clientId ID cliente dell'identità gestita assegnata dall'utente. Assegnata dall'utente

Il valore sostituito <CONNECTION_NAME_PREFIX> con viene considerato dall'estensione dell'associazione come nome dell'impostazione di connessione.

Ad esempio, se la configurazione dell'associazione specifica connection = "ServiceBusConnection" con un'identità gestita assegnata dall'utente, configurare le impostazioni dell'applicazione seguenti:

{
    "ServiceBusConnection__fullyQualifiedNamespace": "myservicebus.servicebus.windows.net",
    "ServiceBusConnection__credential": "managedidentity",
    "ServiceBusConnection__clientId": "00000000-0000-0000-0000-000000000000"
}

Suggerimento

Usare le identità gestite assegnate dall'utente per scenari di produzione in cui è necessario un controllo granulare sulle autorizzazioni di identità tra più risorse.

È possibile usare altre impostazioni nel modello per personalizzare ulteriormente la connessione. Vedere Proprietà comuni per le connessioni basate su identità.

Nota

Quando si usa Configurazione app di Azure o Key Vault per fornire le impostazioni per le connessioni identità gestite, i nomi delle impostazioni devono usare un separatore di chiavi valido, ad esempio : o / al posto del __ per assicurarsi che i nomi vengano risolti correttamente.

Ad esempio: ServiceBusConnection:fullyQualifiedNamespace

Se ospitata nel servizio Funzioni di Azure, le connessioni basate su identità usano un'identità managed identity. 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, è necessario assegnare un ruolo in Azure controllo degli accessi in base al ruolo, 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 bus di servizio nel normale funzionamento. L'applicazione potrebbe richiedere autorizzazioni aggiuntive in base al codice scritto.

Tipo di associazione Ruoli predefiniti di esempio
Trigger1 bus di servizio di Azure Data Receiver, bus di servizio di Azure Data Owner
Associazione di output bus di servizio di Azure Mittente dati

1 Per l'attivazione da argomenti bus di servizio, l'assegnazione di ruolo deve avere un ambito efficace sulla risorsa di sottoscrizione 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 di sottoscrizione bus di servizio come ambito per l'assegnazione di ruolo. In questi casi, il interfaccia della riga di comando di Azure può essere invece usato. Per altre informazioni, vedere Azure ruoli predefiniti per bus di servizio di Azure.

Messaggi non elaborabili

La gestione dei messaggi non elaborabili non può essere controllata o configurata in Funzioni di Azure. bus di servizio gestisce i messaggi non elaborabili.

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 con la autoCompleteMessages.host.json

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 autoCompleteMessageshost.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à Tipo 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 bus di servizio possibile usare per identificare i messaggi duplicati, se abilitati.
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

  • Last updated on