Condividi tramite

Associazioni di output di Archiviazione code di Azure per Funzioni di Azure

  • Articolo

Funzioni di Azure possibile creare nuovi messaggi di archiviazione code di Azure configurando un'associazione di output.

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.

[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)
{
    // Use a string array to return more than one message.
    string[] messages = {
        $"Album name = {myQueueItem.Name}",
        $"Album songs = {myQueueItem.Songs.ToString()}"};

    _logger.LogInformation("{msg1},{msg2}", messages[0], messages[1]);

    // Queue Output messages
    return messages;
}

Per un esempio end-to-end di come configurare un'associazione di output all'archiviazione code, vedere uno di questi articoli:

L'esempio seguente mostra una funzione Java che crea un messaggio di coda per quando viene attivato da una richiesta HTTP.

@FunctionName("httpToQueue")
@QueueOutput(name = "item", queueName = "myqueue-items", connection = "MyStorageConnectionAppSetting")
 public String pushToQueue(
     @HttpTrigger(name = "request", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
     final String message,
     @HttpOutput(name = "response") final OutputBinding<String> result) {
       result.setValue(message + " has been added.");
       return message;
 }

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

Per un esempio end-to-end di come configurare un'associazione di output all'archiviazione code, vedere uno di questi articoli:

L'esempio seguente mostra una funzione TypeScript attivata da HTTP che crea un elemento della coda per ogni richiesta HTTP ricevuta.

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

const queueOutput = output.storageQueue({
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
});

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const body = await request.text();
    context.extraOutputs.set(queueOutput, body);
    return { body: 'Created queue item.' };
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraOutputs: [queueOutput],
    handler: httpTrigger1,
});

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

context.extraOutputs.set(queueOutput, ['message 1', 'message 2']);

L'esempio seguente mostra una funzione JavaScript attivata da HTTP che crea un elemento della coda per ogni richiesta HTTP ricevuta.

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

const queueOutput = output.storageQueue({
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
});

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraOutputs: [queueOutput],
    handler: async (request, context) => {
        const body = await request.text();
        context.extraOutputs.set(queueOutput, body);
        return { body: 'Created queue item.' };
    },
});

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

context.extraOutputs.set(queueOutput, ['message 1', 'message 2']);

Per un esempio end-to-end di come configurare un'associazione di output all'archiviazione code, vedere uno di questi articoli:

Gli esempi di codice seguenti illustrano come restituire un messaggio di coda da una funzione attivata da HTTP. La sezione di configurazione con l'oggetto type di definisce l'associazione di queue output.

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "Msg",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

Usando questa configurazione di associazione, una funzione di PowerShell può creare un messaggio della coda usando Push-OutputBinding. In questo esempio viene creato un messaggio da una stringa di query o da un parametro del corpo.

using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with query parameters or the body of the request.
$message = $Request.Query.Message
Push-OutputBinding -Name Msg -Value $message
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = 200
    Body = "OK"
})

Per inviare più messaggi contemporaneamente, definire una matrice di messaggi e usare Push-OutputBinding per inviare messaggi all'associazione di output della coda.

using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with query parameters or the body of the request.
$message = @("message1", "message2")
Push-OutputBinding -Name Msg -Value $message
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = 200
    Body = "OK"
})

Per un esempio end-to-end di come configurare un'associazione di output all'archiviazione code, vedere uno di questi articoli:

Nell'esempio seguente viene illustrato come restituire valori singoli e multipli nelle code di archiviazione. La configurazione necessaria per function.json è identica. 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="QueueOutput1")
@app.route(route="message")
@app.queue_output(arg_name="msg", 
                  queue_name="<QUEUE_NAME>", 
                  connection="<CONNECTION_SETTING>")
def main(req: func.HttpRequest, msg: func.Out[str]) -> func.HttpResponse:
    input_msg = req.params.get('name')
    logging.info(input_msg)

    msg.set(input_msg)

    logging.info(f'name: {name}')
    return 'OK'

Per un esempio end-to-end di come configurare un'associazione di output all'archiviazione code, vedere uno di questi articoli:

Attributi

L'attributo che definisce un'associazione di output nelle librerie C# dipende dalla modalità in cui viene eseguita la libreria di classi C#.

Quando si esegue in un processo di lavoro isolato, si usa QueueOutputAttribute, che accetta il nome della coda, come illustrato nell'esempio seguente:

[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)

Durante l'esecuzione in un processo di lavoro isolato sono supportate solo le variabili restituite. Non è possibile usare i parametri di output.

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

Proprietà Descrizione
arg_name Nome della variabile che rappresenta la coda nel codice della funzione.
queue_name Nome della coda.
connection Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi alle code di Azure. Vedere Connessioni.

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

Annotazioni

L'annotazione QueueOutput consente di scrivere un messaggio come output di una funzione. L'esempio seguente mostra una funzione attivata da HTTP che crea un messaggio della coda.

package com.function;
import java.util.*;
import com.microsoft.azure.functions.annotation.*;
import com.microsoft.azure.functions.*;

public class HttpTriggerQueueOutput {
    @FunctionName("HttpTriggerQueueOutput")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.FUNCTION) HttpRequestMessage<Optional<String>> request,
            @QueueOutput(name = "message", queueName = "messages", connection = "MyStorageConnectionAppSetting") OutputBinding<String> message,
            final ExecutionContext context) {

        message.setValue(request.getQueryParameters().get("name"));
        return request.createResponseBuilder(HttpStatus.OK).body("Done").build();
    }
}
Proprietà Descrizione
name Dichiara il nome del parametro nella firma della funzione. Quando la funzione viene attivata, il valore di questo parametro contiene il contenuto del messaggio della coda.
queueName Dichiara il nome della coda nell'account di archiviazione.
connection Punta all'account di archiviazione stringa di connessione.

Il parametro associato all'annotazione QueueOutput viene tipizzato come istanza di OutputBinding<T> .

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.storageQueue() metodo .

Proprietà Descrizione
queueName Nome della coda.
connection Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi alle code di Azure. 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.

Proprietà di function.json Descrizione
type Deve essere impostato su queue. 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 la coda nel codice della funzione. Impostare su $return per fare riferimento al valore restituito della funzione.
queueName Nome della coda.
connection Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi alle code di Azure. Vedere Connessioni.

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

L'utilizzo dell'associazione di output coda dipende dalla versione del pacchetto di estensione e dalla modalità C# usata nell'app per le funzioni, che può essere una delle seguenti:

Una funzione C# compilata di libreria di classi di processo di lavoro viene eseguita in un processo isolato dal runtime.

Scegliere una versione per visualizzare i dettagli di utilizzo per la modalità e la versione.

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

Tipo Descrizione
string Contenuto del messaggio come stringa. Usare quando il messaggio è testo semplice.
byte[] Byte del messaggio.
Tipi serializzabili JSON Oggetto che rappresenta il contenuto di un messaggio JSON. 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 della coda può essere associata ai tipi seguenti:

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

Per altri scenari di output, creare e usare i tipi direttamente da Azure.Storage.Queues .

Sono disponibili due opzioni per scrivere in una coda da una funzione usando l'annotazione QueueOutput :

  • Valore restituito: applicando l'annotazione alla funzione stessa, il valore restituito della funzione viene scritto nella coda.

  • Imperativo: per impostare in modo esplicito il valore del messaggio, applicare l'annotazione a un parametro specifico del tipo OutputBinding<T>, dove T è un POJO o qualsiasi tipo Java nativo. Con questa configurazione, il passaggio di un valore al setValue metodo scrive il valore nella coda.

Accedere all'elemento della coda di output restituendo il valore direttamente o usando context.extraOutputs.set(). È possibile usare una stringa o un oggetto serializzabile in JSON per il payload dell'elemento della coda.

L'output del messaggio della coda è disponibile tramite Push-OutputBinding il quale si passano argomenti che corrispondono al nome designato dal parametro dell'associazione name nel file function.json .

Sono disponibili due opzioni per la scrittura dalla funzione alla coda configurata:

  • Valore restituito: impostare la name proprietà in function.json su $return. Con questa configurazione, il valore restituito della funzione viene salvato in modo permanente come messaggio di archiviazione code.

  • Imperativo: passare un valore al metodo set del parametro dichiarato come tipo Out . Il valore passato a set viene salvato in modo permanente come messaggio di archiviazione code.

Connessioni

La connection proprietà è un riferimento alla configurazione dell'ambiente che specifica come l'app deve connettersi alle code di Azure. 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 un stringa di connessione, seguire la procedura illustrata in Gestire le chiavi di accesso dell'account di archiviazione.

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 il resto del nome. Ad esempio, se si imposta connection su "MyStorage", il runtime di Funzioni cerca un'impostazione dell'app denominata "AzureWebJobsMyStorage". Se si lascia connection vuoto, il runtime di Funzioni usa il stringa di connessione di archiviazione predefinito nell'impostazione dell'app denominata AzureWebJobsStorage.

Connessioni basate su identità

Se si usa la versione 5.x o successiva dell'estensione (bundle 3.x o versione successiva per gli stack di linguaggi non-.NET), anziché usare un stringa di connessione con un segreto, è possibile che l'app usi un'identità di Microsoft Entra. Per usare un'identità, definire le impostazioni con un prefisso comune che esegue il connection mapping alla proprietà nella configurazione del trigger e dell'associazione.

Se si imposta connection su "AzureWebJobsStorage", vedere Connessione all'archiviazione host con un'identità. Per tutte le altre connessioni, l'estensione richiede le proprietà seguenti:

Proprietà Modello di variabile di ambiente Descrizione Valore di esempio
URI del servizio di accodamento <CONNECTION_NAME_PREFIX>__queueServiceUri1 URI del piano dati del servizio di accodamento a cui ci si connette usando lo schema HTTPS. https://<storage_account_name>.queue.core.windows.net

1 <CONNECTION_NAME_PREFIX>__serviceUri può essere usato come alias. Se vengono forniti entrambi i moduli, viene utilizzato il queueServiceUri modulo. Il serviceUri modulo non può essere usato quando la configurazione di connessione complessiva deve essere usata tra BLOB, code e/o tabelle.

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

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.

Sarà necessario creare un'assegnazione di ruolo che fornisca l'accesso alla coda in fase di esecuzione. I ruoli di gestione come Proprietario non sono sufficienti. Nella tabella seguente vengono illustrati i ruoli predefiniti consigliati quando si usa l'estensione Archiviazione code in condizioni di normale funzionamento. L'applicazione potrebbe richiedere autorizzazioni aggiuntive in base al codice scritto.

Tipo di associazione Ruoli predefiniti di esempio
Trigger Lettore dei dati della coda di archiviazione, Processore dei messaggi sui dati della coda di archiviazione
Associazione di output Collaboratore ai dati della coda di archiviazione, Mittente del messaggio dei dati della coda di archiviazione

Eccezioni e codici restituiti

Binding Riferimento
Queue Codici di errore della coda
Blob, Table, Queue Codici di errore di archiviazione
Blob, Table, Queue Risoluzione dei problemi

Passaggi successivi