Trigger di archiviazione code di Azure per Funzioni di Azure
Il trigger di archiviazione code esegue una funzione come messaggi vengono aggiunti all'archiviazione code di Azure.
Le decisioni di ridimensionamento dell'archiviazione code di Azure per i piani a consumo e Premium vengono eseguite tramite il ridimensionamento basato su destinazione. Per altre informazioni, vedere Scalabilità basata su destinazione.
Importante
Questo articolo usa schede per supportare più versioni 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 di Funzioni di Azure Node.js. Per altre informazioni sulle differenze tra v3 e v4, vedere la 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
Usare il trigger della coda per avviare una funzione quando viene ricevuto un nuovo elemento in una coda. Il messaggio in coda viene inviato come input alla funzione.
È 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.
L'esempio seguente mostra una funzione C# che esegue il polling della input-queue coda e scrive diversi messaggi in una coda di output ogni volta che viene elaborato un elemento della coda.
[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;
}
L'esempio Java seguente mostra una funzione trigger della coda di archiviazione, che registra il messaggio attivato inserito nella coda myqueuename.
@FunctionName("queueprocessor")
public void run(
@QueueTrigger(name = "msg",
queueName = "myqueuename",
connection = "myconnvarname") String message,
final ExecutionContext context
) {
context.getLogger().info(message);
}
L'esempio seguente mostra una funzione TypeScript trigger della coda. La funzione esegue il polling della coda myqueue-items e scrive un log a ogni elaborazione di un elemento della coda.
import { app, InvocationContext } from '@azure/functions';
export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<void> {
context.log('Storage queue function processed work item:', queueItem);
context.log('expirationTime =', context.triggerMetadata.expirationTime);
context.log('insertionTime =', context.triggerMetadata.insertionTime);
context.log('nextVisibleTime =', context.triggerMetadata.nextVisibleTime);
context.log('id =', context.triggerMetadata.id);
context.log('popReceipt =', context.triggerMetadata.popReceipt);
context.log('dequeueCount =', context.triggerMetadata.dequeueCount);
}
app.storageQueue('storageQueueTrigger1', {
queueName: 'myqueue-items',
connection: 'MyStorageConnectionAppSetting',
handler: storageQueueTrigger1,
});
La sezione relativa all'utilizzo illustra queueItem. Nella sezione message metadata sono illustrate tutte le altre variabili indicate.
L'esempio seguente mostra una funzione JavaScript trigger della coda. La funzione esegue il polling della coda myqueue-items e scrive un log a ogni elaborazione di un elemento della coda.
const { app } = require('@azure/functions');
app.storageQueue('storageQueueTrigger1', {
queueName: 'myqueue-items',
connection: 'MyStorageConnectionAppSetting',
handler: (queueItem, context) => {
context.log('Storage queue function processed work item:', queueItem);
context.log('expirationTime =', context.triggerMetadata.expirationTime);
context.log('insertionTime =', context.triggerMetadata.insertionTime);
context.log('nextVisibleTime =', context.triggerMetadata.nextVisibleTime);
context.log('id =', context.triggerMetadata.id);
context.log('popReceipt =', context.triggerMetadata.popReceipt);
context.log('dequeueCount =', context.triggerMetadata.dequeueCount);
},
});
La sezione relativa all'utilizzo illustra queueItem. Nella sezione message metadata sono illustrate tutte le altre variabili indicate.
Nell'esempio seguente viene illustrato come leggere un messaggio della coda passato a una funzione tramite un trigger.
Un trigger della coda Archiviazione viene definito nel file function.json in cui type è impostato su queueTrigger.
{
"bindings": [
{
"name": "QueueItem",
"type": "queueTrigger",
"direction": "in",
"queueName": "messages",
"connection": "MyStorageConnectionAppSetting"
}
]
}
Il codice nel file Run.ps1 dichiara un parametro come $QueueItem, che consente di leggere il messaggio della coda nella funzione.
# Input bindings are passed in via param block.
param([string] $QueueItem, $TriggerMetadata)
# Write out the queue message and metadata to the information log.
Write-Host "PowerShell queue trigger function processed work item: $QueueItem"
Write-Host "Queue item expiration time: $($TriggerMetadata.ExpirationTime)"
Write-Host "Queue item insertion time: $($TriggerMetadata.InsertionTime)"
Write-Host "Queue item next visible time: $($TriggerMetadata.NextVisibleTime)"
Write-Host "ID: $($TriggerMetadata.Id)"
Write-Host "Pop receipt: $($TriggerMetadata.PopReceipt)"
Write-Host "Dequeue count: $($TriggerMetadata.DequeueCount)"
Nell'esempio seguente viene illustrato come leggere un messaggio della coda passato a una funzione 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="QueueFunc")
@app.queue_trigger(arg_name="msg", queue_name="inputqueue",
connection="storageAccountConnectionString") # Queue trigger
@app.queue_output(arg_name="outputQueueItem", queue_name="outqueue",
connection="storageAccountConnectionString") # Queue output binding
def test_function(msg: func.QueueMessage,
outputQueueItem: func.Out[str]) -> None:
logging.info('Python queue trigger function processed a queue item: %s',
msg.get_body().decode('utf-8'))
outputQueueItem.set('hello')
Attributi
Sia le librerie in-process che il processo di lavoro isolato C# usano QueueTriggerAttribute per definire la funzione. Lo script C# usa invece un file di configurazione function.json come descritto nella guida per gli script C#.
Nelle librerie di classi C# il costruttore dell'attributo prende il nome della coda da monitorare, come illustrato nell'esempio seguente:
[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)
In questo esempio viene illustrata anche l'impostazione del stringa di connessione nell'attributo stesso.
Annotazioni
L'annotazione QueueTrigger consente di accedere alla coda che attiva la funzione. Nell'esempio seguente il messaggio della coda viene reso disponibile per la funzione tramite il message parametro .
package com.function;
import com.microsoft.azure.functions.annotation.*;
import java.util.Queue;
import com.microsoft.azure.functions.*;
public class QueueTriggerDemo {
@FunctionName("QueueTriggerDemo")
public void run(
@QueueTrigger(name = "message", queueName = "messages", connection = "MyStorageConnectionAppSetting") String message,
final ExecutionContext context
) {
context.getLogger().info("Queue message: " + message);
}
}
| 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. |
Elementi Decorator
Si applica solo al modello di programmazione Python v2.
Per le funzioni Python v2 definite tramite decorator, le proprietà seguenti nell'elemento queue_trigger Decorator definiscono il trigger Queue Archiviazione:
| Proprietà | Descrizione |
|---|---|
arg_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. |
queue_name |
Dichiara il nome della coda nell'account di archiviazione. |
connection |
Punta all'account di archiviazione stringa di connessione. |
Per le funzioni Python definite tramite function.json, vedere la sezione Configurazione.
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 app.storageQueue() metodo .
| Proprietà | Descrizione |
|---|---|
| queueName | Nome della coda sulla quale eseguire il polling. |
| connection | Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi alle code di Azure. Vedere Connessione ions. |
Nella tabella seguente sono illustrate le proprietà di configurazione dell'associazione impostate nel file function.json e nell'attributo QueueTrigger.
| Proprietà di function.json | Descrizione |
|---|---|
| type | Deve essere impostato su queueTrigger. Questa proprietà viene impostata automaticamente quando si crea il trigger nel portale di Azure. |
| direction | Solo nel file function.json. Deve essere impostato su in. Questa proprietà viene impostata automaticamente quando si crea il trigger nel portale di Azure. |
| name | Nome della variabile che contiene il payload dell'elemento della coda nel codice della funzione. |
| queueName | Nome della coda sulla quale eseguire il polling. |
| connection | Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi alle code di Azure. Vedere Connessione ions. |
Per esempi completi, vedere la sezione Esempio.
Quando si sviluppa in locale, aggiungere le impostazioni dell'applicazione nel file local.settings.json nella Values raccolta.
Utilizzo
Nota
Le funzioni richiedono una stringa codificata base64. Le modifiche al tipo di codifica, per preparare i dati come una stringa con codifica base64, devono essere implementate nel servizio di chiamata.
L'utilizzo del trigger queue dipende dalla versione del pacchetto di estensione e dalla modalità C# usata nell'app per le funzioni, che può essere una di queste modalità:
Una libreria di classi di processo di lavoro isolata compilata C# viene eseguita in un processo isolato dal runtime.
Scegliere una versione per visualizzare i dettagli di utilizzo per la modalità e la versione.
Il trigger della coda può essere associato ai tipi seguenti:
| Tipo | Descrizione |
|---|---|
string |
Contenuto del messaggio come stringa. Usare quando il messaggio è testo semplice. |
byte[] |
Byte del messaggio. |
| Tipi serializzabili JSON | Quando un messaggio della coda contiene dati JSON, Funzioni tenta di deserializzare i dati JSON in un tipo POCO (Plain-Old CLR Object). |
| QueueMessage1 | Messaggio. |
| BinaryData1 | Byte del messaggio. |
1 Per usare questi tipi, è necessario fare riferimento a Microsoft.Azure.Functions.Worker.Extensions.Archiviazione. Accoda la versione 5.2.0 o successiva e le dipendenze comuni per le associazioni dei tipi di SDK.
L'annotazione QueueTrigger consente di accedere al messaggio della coda che ha attivato la funzione.
Accedere all'elemento della coda come primo argomento alla funzione. Se il payload è JSON, il valore viene deserializzato in un oggetto .
Accedere al messaggio della coda tramite un parametro stringa corrispondente al nome designato dal parametro dell'associazione name nel file function.json .
Accedere al messaggio della coda tramite il parametro digitato come QueueMessage.
Metadati UFX
Il trigger della coda fornisce diverse proprietà di metadati. Queste proprietà possono essere usate come parte delle espressioni di associazione in altre associazioni o come parametri nel codice, per i ruoli di lavoro del linguaggio che forniscono questo accesso ai metadati del messaggio.
Le proprietà dei metadati del messaggio sono membri della classe CloudQueueMessage .
È possibile accedere alle proprietà dei metadati del messaggio da context.triggerMetadata.
È possibile accedere alle proprietà dei metadati del messaggio dal parametro passato $TriggerMetadata .
| Proprietà | Type | Descrizione |
|---|---|---|
QueueTrigger |
string |
Payload della coda, se si tratta di una stringa valida. Se il payload del messaggio della coda è una stringa, QueueTrigger ha lo stesso valore della variabile denominata dalla name proprietà in function.json. |
DequeueCount |
long |
Il numero di volte in cui questo messaggio è stato rimosso dalla coda. |
ExpirationTime |
DateTimeOffset |
Ora di scadenza del messaggio. |
Id |
string |
ID del messaggio in coda. |
InsertionTime |
DateTimeOffset |
L'ora in cui il messaggio è stato aggiunto alla coda. |
NextVisibleTime |
DateTimeOffset |
Ora in cui il messaggio sarà visibile. |
PopReceipt |
string |
Ricezione del messaggio. |
È possibile accedere alle proprietà dei metadati del messaggio seguenti dal parametro di associazione passato (msg negli esempi precedenti).
| Proprietà | Descrizione |
|---|---|
body |
Payload della coda come stringa. |
dequeue_count |
Il numero di volte in cui questo messaggio è stato rimosso dalla coda. |
expiration_time |
Ora di scadenza del messaggio. |
id |
ID del messaggio in coda. |
insertion_time |
L'ora in cui il messaggio è stato aggiunto alla coda. |
time_next_visible |
Ora in cui il messaggio sarà visibile. |
pop_receipt |
Ricezione del messaggio. |
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.
Connection string
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 "My Archiviazione", il runtime di Funzioni cerca un'impostazione dell'app denominata "AzureWebJobsMy Archiviazione". Se si lascia connection vuoto, il runtime di Funzioni usa il Archiviazione stringa di connessione 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 "AzureWebJobs Archiviazione", vedere Connessione ing per ospitare l'archiviazione 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 fornisce l'accesso alla coda 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 Queue Archiviazione nel normale funzionamento. L'applicazione potrebbe richiedere autorizzazioni aggiuntive in base al codice scritto.
| Tipo di associazione | Ruoli predefiniti di esempio |
|---|---|
| Trigger | Lettore dati coda Archiviazione, responsabile del messaggio di dati della coda Archiviazione coda |
| Associazione di output | collaboratore ai dati della coda Archiviazione, Archiviazione mittente del messaggio di dati della coda |
Messaggi non elaborabili
Quando una funzione di trigger della coda ha esito negativo, Funzioni di Azure ritenta l'esecuzione fino a cinque volte per un dato messaggio della coda, incluso il primo tentativo. Se tutti e cinque i tentativi hanno esito negativo, il runtime delle funzioni aggiunge un messaggio a una coda denominata <originalqueuename-poison>. È possibile scrivere una funzione per elaborare i messaggi dalla coda non elaborabile archiviandoli o inviando una notifica della necessità di un intervento manuale.
Per gestire manualmente i messaggi non elaborabili, controllare dequeueCount nel messaggio della coda.
Blocco di visualizzazione
Il modello peek-lock viene eseguito automaticamente per i trigger della coda, usando i meccanismi di visibilità forniti dal servizio di archiviazione. Poiché i messaggi vengono dequeuati dalla funzione attivata, vengono contrassegnati come invisibili. L'esecuzione di una funzione attivata da una coda può avere uno di questi risultati nel messaggio nella coda:
- L'esecuzione della funzione viene completata correttamente e il messaggio viene eliminato dalla coda.
- L'esecuzione della funzione ha esito negativo e l'host di Funzioni aggiorna la visibilità del messaggio in base all'impostazione
visibilityTimeoutnel file host.json. Il timeout di visibilità predefinito è zero, il che significa che il messaggio viene nuovamente visualizzato nella coda per la rielaborazione. Usare l'impostazionevisibilityTimeoutper ritardare la rielaborazione dei messaggi che non riescono a elaborare. Questa impostazione di timeout si applica a tutte le funzioni attivate dalla coda nell'app per le funzioni. - L'host funzioni si arresta in modo anomalo durante l'esecuzione della funzione. Quando si verifica questo evento non comune, l'host non può applicare l'oggetto
visibilityTimeoutal messaggio in fase di elaborazione. Al contrario, il messaggio viene lasciato con il timeout predefinito di 10 minuti impostato dal servizio di archiviazione. Dopo 10 minuti, il messaggio viene visualizzato nuovamente nella coda per la rielaborazione. Questo timeout predefinito definito dal servizio non può essere modificato.
Algoritmo di polling
Il trigger della coda implementa un algoritmo di backoff esponenziale casuale per ridurre l'effetto del polling delle code inattive sui costi delle transazioni di archiviazione.
L'algoritmo usa la logica seguente:
- Quando viene trovato un messaggio, il runtime attende 100 millisecondi e quindi verifica la presenza di un altro messaggio.
- Quando non viene trovato alcun messaggio, attende circa 200 millisecondi prima di riprovare.
- Dopo alcuni tentativi non riusciti per ottenere un messaggio nella coda, il tempo di attesa continua ad aumentare finché non raggiunge il tempo massimo di attesa, che per impostazione predefinita è di un minuto.
- Il tempo di attesa massimo può essere configurato tramite la proprietà
maxPollingIntervalnel file host.json.
Durante lo sviluppo locale, per impostazione predefinita l'intervallo di polling massimo è di due secondi.
Nota
Per quanto riguarda la fatturazione quando si ospitano le app per le funzioni nel piano a consumo, non vengono addebitati costi per il tempo impiegato dal runtime.
Concorrenza
Quando sono in attesa più messaggi della coda, il trigger della coda recupera un batch di messaggi e richiama le istanze della funzione in modo simultaneo per l'elaborazione. Per impostazione predefinita, la dimensione del batch è pari a 16. Quando il numero elaborato scende a 8, il runtime ottiene un altro batch e inizia l'elaborazione dei messaggi. Di conseguenza, il numero massimo di messaggi simultanei elaborati per ogni funzione in una singola macchina virtuale è pari a 24. Questo limite si applica separatamente a ogni funzione attivata dalla coda in ogni macchina virtuale. Se l'app per le funzioni viene ridimensionata in più macchine virtuali, ogni macchina virtuale attende i trigger e tenta di eseguire le funzioni. Se ad esempio il numero di istanze di un'app per le funzioni aumento includendo 3 macchine virtuali, il numero massimo predefinito di istanze simultanee di una funzione attivata dalla coda è pari a 72.
La dimensione del batch e la soglia ottenere un nuovo batch possono essere configurate nel file host.json. Se si desidera ridurre al minimo l'esecuzione parallela per le funzioni attivate dalla coda in un'app per le funzioni, è possibile impostare la dimensione del batch su 1. Questa impostazione elimina la concorrenza solo fino a quando l'app per le funzioni viene eseguita in una singola macchina virtuale.
Il trigger della coda impedisce automaticamente a una funzione di elaborare un messaggio di coda più volte contemporaneamente.
Proprietà di host.json
Il file host.json contiene le impostazioni che controllano il comportamento del trigger della coda. Per informazioni dettagliate sulle impostazioni disponibili, vedere la sezione impostazioni host.json .