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.

v2

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.

v1

Il modello di programmazione Python v1 richiede di definire associazioni in un file di function.json separato nella cartella della funzione. 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.

Modello di lavoro isolato

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

Modello di processo

L'esempio seguente illustra una funzione C# che esegue il polling della coda myqueue-items e scrive un log a ogni elaborazione di un elemento della coda.

public static class QueueFunctions
{
    [FunctionName("QueueTrigger")]
    public static void QueueTrigger(
        [QueueTrigger("myqueue-items")] string myQueueItem, 
        ILogger log)
    {
        log.LogInformation($"C# function processed: {myQueueItem}");
    }
}

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

Modello v4

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.

Modello v3

Gli esempi typeScript non sono documentati per il modello v3.

Modello v4

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.

Modello v3

L'esempio seguente illustra un'associazione di trigger della coda in un file function.json e una funzione JavaScript che usa l'associazione. La funzione esegue il polling della coda myqueue-items e scrive un log a ogni elaborazione di un elemento della coda.

Ecco il file function.json:

{
    "disabled": false,
    "bindings": [
        {
            "type": "queueTrigger",
            "direction": "in",
            "name": "myQueueItem",
            "queueName": "myqueue-items",
            "connection":"MyStorageConnectionAppSetting"
        }
    ]
}

Queste proprietà sono descritte nella sezione configuration.

Nota

Il parametro Name viene visualizzato come context.bindings.<name> nel codice JavaScript che contiene il payload dell'elemento della coda. Il payload viene anche passato come secondo parametro alla funzione.

Ecco il codice JavaScript:

module.exports = async function (context, message) {
    context.log('Node.js queue trigger function processed work item', message);
    // OR access using context.bindings.<name>
    // context.log('Node.js queue trigger function processed work item', context.bindings.myQueueItem);
    context.log('expirationTime =', context.bindingData.expirationTime);
    context.log('insertionTime =', context.bindingData.insertionTime);
    context.log('nextVisibleTime =', context.bindingData.nextVisibleTime);
    context.log('id =', context.bindingData.id);
    context.log('popReceipt =', context.bindingData.popReceipt);
    context.log('dequeueCount =', context.bindingData.dequeueCount);
};

Nella sezione usage è illustrato myQueueItem, denominato dalla proprietà name in function.json. 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 di 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.

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

v1

Un trigger della coda di archiviazione viene definito in function.json dove il tipo è impostato su queueTrigger.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "name": "msg",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "messages",
      "connection": "AzureStorageQueuesConnectionString"
    }
  ]
}

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

import logging
import json

import azure.functions as func

def main(msg: func.QueueMessage):
    logging.info('Python queue trigger function processed a queue item.')

    result = json.dumps({
        'id': msg.id,
        'body': msg.get_body().decode('utf-8'),
        'expiration_time': (msg.expiration_time.isoformat()
                            if msg.expiration_time else None),
        'insertion_time': (msg.insertion_time.isoformat()
                           if msg.insertion_time else None),
        'time_next_visible': (msg.time_next_visible.isoformat()
                              if msg.time_next_visible else None),
        'pop_receipt': msg.pop_receipt,
        'dequeue_count': msg.dequeue_count
    })

    logging.info(result)

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

Modello di lavoro isolato

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.

Modello di processo

Nelle librerie di classi C# il costruttore dell'attributo prende il nome della coda da monitorare, come illustrato nell'esempio seguente:

[FunctionName("QueueTrigger")]
public static void Run(
    [QueueTrigger("myqueue-items")] string myQueueItem, 
    ILogger log)
{
    ...
}

È possibile impostare la Connection proprietà per specificare l'impostazione dell'app che contiene l'account di archiviazione stringa di connessione da usare, come illustrato nell'esempio seguente:

[FunctionName("QueueTrigger")]
public static void Run(
    [QueueTrigger("myqueue-items", Connection = "StorageConnectionAppSetting")] string myQueueItem, 
    ILogger log)
{
    ....
}

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 di archiviazione code:

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.

Modello v4

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

Modello v3

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

Proprietà	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 Connessioni.

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

Per esempi completi, vedere la sezione di 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à:

Modello di lavoro isolato

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

Libreria di classi in-process

Una libreria di classi in-process è una funzione C# compilata eseguita nello stesso processo del runtime di Funzioni.

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

Estensione 5.x+

Accedere ai dati del messaggio usando un parametro del metodo, string paramNamead esempio . paramName è il valore specificato in QueueTriggerAttribute. È possibile definire associazioni con uno dei seguenti tipi:

• Oggetto CLR .NET precedente (POCO)
• string
• byte[]
• QueueMessage

Quando si esegue l'associazione a un oggetto, il runtime di Funzioni tenta di deserializzare il payload JSON in un'istanza di una classe arbitraria definita nel codice. Per esempi relativi all'uso di QueueMessage, vedere il repository GitHub per l'estensione.

Mentre l'attributo accetta una Connection proprietà, è anche possibile usare StorageAccountAttribute per specificare una connessione all'account di archiviazione. Questa operazione può essere eseguita quando è necessario usare un account di archiviazione diverso da altre funzioni della libreria. Il costruttore accetta il nome di un'impostazione dell'app che contiene una stringa di connessione di archiviazione. L'attributo può essere applicato a livello di parametro, metodo o classe. L'esempio seguente illustra il livello classe e il livello metodo:

[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
    [FunctionName("StorageTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ...
}

L'account di archiviazione da usare è determinato nell'ordine seguente:

• Proprietà dell'attributo trigger o binding Connection .
• Attributo StorageAccount applicato allo stesso parametro dell'attributo trigger o binding.
• L'attributo StorageAccount applicato alla funzione.
• L'attributo StorageAccount applicato alla classe.
• L'account di archiviazione predefinito per l'app per le funzioni, definito nell'impostazione dell'applicazione AzureWebJobsStorage .

Estensione 2.x+

Accedere ai dati del messaggio usando un parametro del metodo, string paramNamead esempio . paramName è il valore specificato in QueueTriggerAttribute. È possibile definire associazioni con uno dei seguenti tipi:

• Oggetto CLR normale (POCO)
• string
• byte[]
• CloudQueueMessage

Quando si esegue l'associazione a un oggetto, il runtime di Funzioni tenta di deserializzare il payload JSON in un'istanza di una classe arbitraria definita nel codice. Se si tenta di eseguire l'associazione a CloudQueueMessage e viene visualizzato un messaggio di errore, assicurarsi di avere un riferimento alla versione corretta di Storage SDK.

Mentre l'attributo accetta una Connection proprietà, è anche possibile usare StorageAccountAttribute per specificare una connessione all'account di archiviazione. Questa operazione può essere eseguita quando è necessario usare un account di archiviazione diverso da altre funzioni della libreria. Il costruttore accetta il nome di un'impostazione dell'app che contiene una stringa di connessione di archiviazione. L'attributo può essere applicato a livello di parametro, metodo o classe. L'esempio seguente illustra il livello classe e il livello metodo:

[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
    [FunctionName("StorageTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ...
}

L'account di archiviazione da usare è determinato nell'ordine seguente:

• Proprietà dell'attributo trigger o binding Connection .
• Attributo StorageAccount applicato allo stesso parametro dell'attributo trigger o binding.
• L'attributo StorageAccount applicato alla funzione.
• L'attributo StorageAccount applicato alla classe.
• L'account di archiviazione predefinito per l'app per le funzioni, definito nell'impostazione dell'applicazione AzureWebJobsStorage .

Estensione 5.x+

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.

¹ Per usare questi tipi, è necessario fare riferimento a Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues 5.2.0 o versione successiva e alle dipendenze comuni per le associazioni di tipi SDK.

Estensione 2.x+

Le versioni precedenti di questa estensione nel processo di lavoro isolato supportano solo l'associazione alle stringhe. Sono disponibili altre opzioni per l'estensione 5.x+.

L'annotazione QueueTrigger consente di accedere al messaggio della coda che ha attivato la funzione.

Modello v4

Accedere all'elemento della coda come primo argomento alla funzione. Se il payload è JSON, il valore viene deserializzato in un oggetto .

Modello v3

Accedere all'elemento della coda usando context.bindings.<NAME> dove <NAME> corrisponde al valore definito in function.json. 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.

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>

¹ <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 mostra i ruoli predefiniti consigliati quando si usa l'estensione archiviazione code 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 di archiviazione, responsabile dei messaggi dei dati della coda di archiviazione
Associazione di output	Collaboratore ai dati della coda di archiviazione, mittente del messaggio di dati della coda di archiviazione

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 funzioni aggiorna la visibilità del messaggio in base all'impostazione visibilityTimeout nel 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'impostazione visibilityTimeout per 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 visibilityTimeout al 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à maxPollingInterval nel 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 .

Passaggi successivi

• Scrivere messaggi di archiviazione code (associazione di output)