Condividi tramite

bus di servizio di Azure binding di output per Funzioni di Azure

  • Articolo

Usare l'associazione di output del bus di servizio di Azure per inviare messaggi della coda o dell'argomento.

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

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.

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 messaggio e la scrive in una seconda coda:

[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 usa un trigger HTTP con un OutputType oggetto per inviare una risposta HTTP e scrivere il messaggio di output.

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

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

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

Questo codice definisce il tipo OutputTypedi output multiplo , che include la definizione dell'associazione di output bus di servizio in OutputEvent:

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

   public HttpResponseData HttpResponse { get; set; }
}

L'esempio seguente mostra una funzione Java che invia un messaggio a una coda myqueue bus di servizio quando viene attivata da una richiesta HTTP.

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

Nella libreria di runtime di funzioni Java usare @QueueOutput l'annotazione per i parametri di funzione il cui valore viene scritto in una coda di bus di servizio. Il tipo di parametro deve essere OutputBinding<T>, dove T è qualsiasi tipo Java nativo di un POJO.

Le funzioni Java possono anche scrivere in un argomento bus di servizio. Nell'esempio seguente viene utilizzata l'annotazione @ServiceBusTopicOutput per descrivere la configurazione per l'associazione di output.

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

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

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

    }

L'esempio seguente mostra una funzione TypeScript attivata dal timer che invia un messaggio di coda ogni 5 minuti.

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

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

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

Per restituire più messaggi, restituire una matrice anziché un singolo oggetto. Ad esempio:

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

L'esempio seguente mostra una funzione JavaScript attivata dal timer che invia un messaggio di coda ogni 5 minuti.

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

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

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

Per restituire più messaggi, restituire una matrice anziché un singolo oggetto. Ad esempio:

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

L'esempio seguente illustra un'associazione di output 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": [
    {
      "type": "serviceBus",
      "direction": "out",
      "connection": "AzureServiceBusConnectionString",
      "name": "outputSbMsg",
      "queueName": "outqueue",
      "topicName": "outtopic"
    }
  ]
}

Ecco PowerShell che crea un messaggio come output della funzione.

param($QueueItem, $TriggerMetadata) 

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

L'esempio seguente illustra come scrivere in una coda bus di servizio in Python. 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.route(route="put_message")
@app.service_bus_topic_output(arg_name="message",
                              connection="<CONNECTION_SETTING>",
                              topic_name="<TOPIC_NAME>")
def main(req: func.HttpRequest, message: func.Out[str]) -> func.HttpResponse:
    input_msg = req.params.get('message')
    message.set(input_msg)
    return 'OK'

Attributi

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

Nelle librerie di classi C# usare ServiceBusOutputAttribute per definire la coda o l'argomento scritto nell'output.

La tabella seguente illustra le proprietà che è possibile impostare usando l'attributo :

Proprietà Descrizione
EntityType Imposta il tipo di entità come Queue per l'invio di messaggi a una coda o Topic quando si inviano messaggi a un argomento.
QueueOrTopicName Nome dell'argomento o della coda a cui inviare messaggi. Usare EntityType per impostare il tipo di destinazione.
Connessione Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi a bus di servizio. Vedere Connessioni.

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

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. Impostare questa proprietà solo se si inviano messaggi della coda, non dell'argomento.
topic_name Nome dell'argomento. Impostare questa proprietà solo se si inviano messaggi dell'argomento, non della coda.
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

Le ServiceBusQueueOutput annotazioni e ServiceBusTopicOutput sono disponibili per scrivere un messaggio come output di funzione. Il parametro decorato con queste annotazioni deve essere dichiarato come dove OutputBinding<T> T è il tipo corrispondente al tipo del messaggio.

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

Impostazione

Si applica solo al modello di programmazione Python v1.

Nella tabella seguente vengono illustrate le proprietà che è possibile impostare sull'oggetto options passato al output.serviceBusQueue() metodo .

Proprietà Descrizione
queueName Nome della coda.
connection Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi a bus di servizio. Vedere Connessioni.

Nella tabella seguente vengono illustrate le proprietà che è possibile impostare sull'oggetto options passato al output.serviceBusTopic() metodo .

Proprietà Descrizione
topicName Nome dell'argomento.
connection Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi a bus di servizio. Vedere Connessioni.

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 e nell'attributo ServiceBus.

Proprietà di function.json Descrizione
type Il valore deve essere impostato su "serviceBus". Questa proprietà viene impostata automaticamente quando si crea il trigger nel portale di Azure.
direction Deve essere impostato su "out". 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. Impostare su "$return" per fare riferimento al valore restituito della funzione.
queueName Nome della coda. Impostare questa proprietà solo se si inviano messaggi della coda, non dell'argomento.
topicName Nome dell'argomento. Impostare questa proprietà solo se si inviano messaggi dell'argomento, non della 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 (solo v1) 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.

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 parametri di output seguenti sono supportati da tutte le modalità C# e le versioni dell'estensione:

Tipo Descrizione
System.String Usare quando il messaggio da scrivere è testo semplice. Quando il valore del parametro è Null quando la funzione viene chiusa, Funzioni non crea un messaggio.
byte[] Usare per scrivere messaggi di dati binari. Quando il valore del parametro è Null quando la funzione viene chiusa, Funzioni non crea un messaggio.
Oggetto Quando un messaggio contiene JSON, Funzioni serializza l'oggetto in un payload di messaggio JSON. Quando il valore del parametro è Null quando la funzione viene chiusa, Functions crea un messaggio con un oggetto Null.

I tipi di parametro specifici della messaggistica contengono metadati di messaggio aggiuntivi. I tipi specifici supportati dall'associazione di output dipendono dalla versione del runtime di Funzioni, dalla versione del pacchetto di estensione e dalla modalità C# usata.

Quando si vuole che la funzione scriva un singolo messaggio, l'associazione di output bus di servizio può essere associata ai tipi seguenti:

Tipo Descrizione
string Messaggio come stringa. Usare quando il messaggio è testo semplice.
byte[] Byte del messaggio.
Tipi serializzabili JSON Oggetto che rappresenta il messaggio. Funzioni tenta di serializzare un tipo di oggetto CLR (POCO) normale in dati JSON.

Quando si vuole che la funzione scriva più messaggi, l'associazione di output bus di servizio può essere associata ai tipi seguenti:

Tipo Descrizione
T[] dove T è uno dei singoli tipi di messaggio Matrice contenente più messaggi. Ogni voce rappresenta un messaggio.

Per altri scenari di output, creare e usare direttamente i tipi da Azure.Messaging.ServiceBus .

In Funzioni di Azure 1.x il runtime crea la coda se inesistente e se il parametro accessRights è stato impostato su manage. In Funzioni di Azure versione 2.x e successive, la coda o l'argomento deve esistere già. Se si specifica una coda o un argomento che non esiste, la funzione ha esito negativo.

Usare bus di servizio di Azure SDK anziché l'associazione di output predefinita.

Accedere al messaggio di output restituendo direttamente il valore o usando context.extraOutputs.set().

L'output del bus di servizio è disponibile tramite il Push-OutputBinding cmdlet in cui si passano argomenti che corrispondono al nome designato dal parametro name dell'associazione nel file function.json.

Usare bus di servizio di Azure SDK anziché l'associazione di output predefinita.

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

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

Eccezioni e codici restituiti

Binding Riferimento
Bus di servizio Codici di errore del bus di servizio
Bus di servizio Limiti del bus di servizio

Passaggi successivi