Associazioni di Archiviazione code di Azure per Funzioni di AzureAzure Queue storage bindings for Azure Functions

Questo articolo illustra come operare con le associazioni dell'archiviazione code di Azure in Funzioni di Azure.This article explains how to work with Azure Queue storage bindings in Azure Functions. Funzioni di Azure supporta il trigger e le associazioni di output per le code.Azure Functions supports trigger and output bindings for queues.

Informazioni di riferimento per gli sviluppatori delle Funzioni di Azure.This is reference information for Azure Functions developers. Se non si ha familiarità con le Funzioni di Azure, iniziare con le seguenti risorse:If you're new to Azure Functions, start with the following resources:

TriggerTrigger

Usare il trigger della coda per avviare una funzione quando viene ricevuto un nuovo elemento in una coda.Use the queue trigger to start a function when a new item is received on a queue. Il messaggio in coda viene fornito come input alla funzione.The queue message is provided as input to the function.

Trigger - esempioTrigger - example

Vedere l'esempio specifico per ciascun linguaggio:See the language-specific example:

Trigger - esempio in C#Trigger - C# example

L'esempio seguente illustra codice C# precompilato che esegue il polling della coda myqueue-items e scrive un log a ogni elaborazione di un elemento della coda.The following example shows precompiled C# code that polls the myqueue-items queue and writes a log each time a queue item is processed.

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

Trigger - esempio di script C#Trigger - C# script example

L'esempio seguente illustra un'associazione di trigger di BLOB in un file function.json e codice script C# che usa l'associazione.The following example shows a blob trigger binding in a function.json file and C# script code that uses the binding. La funzione esegue il polling della coda myqueue-items e scrive un log a ogni elaborazione di un elemento della coda.The function polls the myqueue-items queue and writes a log each time a queue item is processed.

Ecco il file function.json:Here's the function.json file:

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

Queste proprietà sono descritte nella sezione configuration.The configuration section explains these properties.

Ecco il codice script C#:Here's the C# script code:

#r "Microsoft.WindowsAzure.Storage"

using Microsoft.WindowsAzure.Storage.Queue;
using System;

public static void Run(CloudQueueMessage myQueueItem, 
    DateTimeOffset expirationTime, 
    DateTimeOffset insertionTime, 
    DateTimeOffset nextVisibleTime,
    string queueTrigger,
    string id,
    string popReceipt,
    int dequeueCount,
    TraceWriter log)
{
    log.Info($"C# Queue trigger function processed: {myQueueItem.AsString}\n" +
        $"queueTrigger={queueTrigger}\n" +
        $"expirationTime={expirationTime}\n" +
        $"insertionTime={insertionTime}\n" +
        $"nextVisibleTime={nextVisibleTime}\n" +
        $"id={id}\n" +
        $"popReceipt={popReceipt}\n" + 
        $"dequeueCount={dequeueCount}");
}

Nella sezione usage è illustrato myQueueItem, denominato dalla proprietà name in function.json.The usage section explains myQueueItem, which is named by the name property in function.json. Nella sezione message metadata sono illustrate tutte le altre variabili indicate.The message metadata section explains all of the other variables shown.

Trigger - esempio JavaScriptTrigger - JavaScript example

L'esempio seguente illustra un'associazione di trigger di BLOB in un file function.json e una funzione JavaScript che usa l'associazione.The following example shows a blob trigger binding in a function.json file and a JavaScript function that uses the binding. La funzione esegue il polling della coda myqueue-items e scrive un log a ogni elaborazione di un elemento della coda.The function polls the myqueue-items queue and writes a log each time a queue item is processed.

Ecco il file function.json:Here's the function.json file:

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

Queste proprietà sono descritte nella sezione configuration.The configuration section explains these properties.

Ecco il codice JavaScript:Here's the JavaScript code:

module.exports = function (context) {
    context.log('Node.js queue trigger function processed work item', context.bindings.myQueueItem);
    context.log('queueTrigger =', context.bindingData.queueTrigger);
    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);
    context.done();
};

Nella sezione usage è illustrato myQueueItem, denominato dalla proprietà name in function.json.The usage section explains myQueueItem, which is named by the name property in function.json. Nella sezione message metadata sono illustrate tutte le altre variabili indicate.The message metadata section explains all of the other variables shown.

Trigger - attributiTrigger - attributes

Per le funzioni di C# precompilato, usare i seguenti attributi per configurare un trigger della coda:For precompiled C# functions, use the following attributes to configure a queue trigger:

  • QueueTriggerAttribute, definito nel pacchetto NuGet Microsoft.Azure.WebJobsQueueTriggerAttribute, defined in NuGet package Microsoft.Azure.WebJobs

    Il costruttore dell'attributo accetta il nome della coda da monitorare, come illustrato nell'esempio seguente:The attribute's constructor takes the name of the queue to monitor, as shown in the following example:

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

    È possibile impostare la proprietà Connection per specificare l'account di archiviazione da usare, come illustrato nell'esempio seguente:You can set the Connection property to specify the storage account to use, as shown in the following example:

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

    Per un esempio completo, vedere Trigger - esempio in C# precompilato.For a complete example, see Trigger - precompiled C# example.

  • StorageAccountAttribute, definito nel pacchetto NuGet Microsoft.Azure.WebJobsStorageAccountAttribute, defined in NuGet package Microsoft.Azure.WebJobs

    Offre un altro modo per specificare l'account di archiviazione da usare.Provides another way to specify the storage account to use. Il costruttore accetta il nome di un'impostazione dell'app che contiene una stringa di connessione di archiviazione.The constructor takes the name of an app setting that contains a storage connection string. L'attributo può essere applicato a livello di parametro, metodo o classe.The attribute can be applied at the parameter, method, or class level. L'esempio seguente illustra il livello classe e il livello metodo:The following example shows class level and method level:

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

L'account di archiviazione da usare è determinato nell'ordine seguente:The storage account to use is determined in the following order:

  • La proprietà Connection dell'attributo QueueTrigger.The QueueTrigger attribute's Connection property.
  • L'attributo StorageAccount applicato allo stesso parametro dell'attributo QueueTrigger.The StorageAccount attribute applied to the same parameter as the QueueTrigger attribute.
  • L'attributo StorageAccount applicato alla funzione.The StorageAccount attribute applied to the function.
  • L'attributo StorageAccount applicato alla classe.The StorageAccount attribute applied to the class.
  • L'impostazione dell'app "AzureWebJobsStorage".The "AzureWebJobsStorage" app setting.

Trigger - configurazioneTrigger - configuration

Nella tabella seguente sono illustrate le proprietà di configurazione dell'associazione impostate nel file function.json e nell'attributo QueueTrigger.The following table explains the binding configuration properties that you set in the function.json file and the QueueTrigger attribute.

Proprietà di function.jsonfunction.json property Proprietà dell'attributoAttribute property DescrizioneDescription
typetype n/dn/a Il valore deve essere impostato su queueTrigger.Must be set to queueTrigger. Questa proprietà viene impostata automaticamente quando si crea il trigger nel portale di Azure.This property is set automatically when you create the trigger in the Azure portal.
directiondirection n/dn/a Solo nel file function.json.In the function.json file only. Il valore deve essere impostato su in.Must be set to in. Questa proprietà viene impostata automaticamente quando si crea il trigger nel portale di Azure.This property is set automatically when you create the trigger in the Azure portal.
nomename n/dn/a Nome della variabile che rappresenta la coda nel codice della funzione.The name of the variable that represents the queue in function code.
queueNamequeueName QueueNameQueueName Nome della coda sulla quale eseguire il polling.The name of the queue to poll.
connessioneconnection ConnectionConnection Nome di un'impostazione dell'app che contiene la stringa di connessione di archiviazione da usare per questa associazione.The name of an app setting that contains the Storage connection string to use for this binding. Se il nome dell'impostazione dell'app inizia con "AzureWebJobs", è possibile specificare solo il resto del nome.If the app setting name begins with "AzureWebJobs", you can specify only the remainder of the name here. Ad esempio, se si imposta connection su "MyStorage", il runtime di Funzioni di Azure cerca un'impostazione dell'app denominata "AzureWebJobsMyStorage".For example, if you set connection to "MyStorage", the Functions runtime looks for an app setting that is named "AzureWebJobsMyStorage." Se si lascia vuoto connection, il runtime di Funzioni di Azure usa la stringa di connessione di archiviazione predefinita nell'impostazione dell'app denominata AzureWebJobsStorage.If you leave connection empty, the Functions runtime uses the default Storage connection string in the app setting that is named AzureWebJobsStorage.

Quando si sviluppa in locale, le impostazioni dell'app vengono inserite nel file local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Trigger - usoTrigger - usage

In C# e negli script C# è possibile accedere ai dati del BLOB con un parametro del metodo, ad esempio Stream paramName.In C# and C# script, access the blob data by using a method parameter such as Stream paramName. Negli script C#, paramName è il valore specificato nella proprietà name di function.json.In C# script, paramName is the value specified in the name property of function.json. È possibile definire associazioni con uno dei seguenti tipi:You can bind to any of the following types:

  • Oggetto POCO - Il runtime di Funzioni deserializza un payload JSON in un oggetto POCO.POCO object - The Functions runtime deserializes a JSON payload into a POCO object.
  • string
  • byte[]
  • CloudQueueMessageCloudQueueMessage

In JavaScript, usare context.bindings.<name> per accedere al payload dell'elemento della coda.In JavaScript, use context.bindings.<name> to access the queue item payload. Se il payload è JSON, viene deserializzato in un oggetto.If the payload is JSON, it's deserialized into an object.

Trigger - metadati del messaggioTrigger - message metadata

Il trigger della coda contiene diverse proprietà di metadati.The queue trigger provides several metadata properties. Queste proprietà possono essere usate come parte delle espressioni di associazione in altre associazioni o come parametri nel codice.These properties can be used as part of binding expressions in other bindings or as parameters in your code. I valori hanno la stessa semantica di CloudQueueMessage.The values have the same semantics as CloudQueueMessage.

ProprietàProperty TipoType DescrizioneDescription
QueueTrigger string Payload della coda, se si tratta di una stringa valida.Queue payload (if a valid string). Se il payload della coda di messaggi è una stringa, QueueTrigger ha lo stesso valore della variabile denominata dalla proprietà name in function.json.If the queue message payload as a string, QueueTrigger has the same value as the variable named by the name property in function.json.
DequeueCount int Il numero di volte in cui questo messaggio è stato rimosso dalla coda.The number of times this message has been dequeued.
ExpirationTime DateTimeOffset? Ora di scadenza del messaggio.The time that the message expires.
Id string ID del messaggio in coda.Queue message ID.
InsertionTime DateTimeOffset? L'ora in cui il messaggio è stato aggiunto alla coda.The time that the message was added to the queue.
NextVisibleTime DateTimeOffset? Ora in cui il messaggio sarà visibile.The time that the message will next be visible.
PopReceipt string Ricezione del messaggio.The message's pop receipt.

Trigger - messaggi non elaborabiliTrigger - poison messages

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.When a queue trigger function fails, Azure Functions retries the function up to five times for a given queue message, including the first try. Se tutti i cinque tentativi hanno esito negativo, il runtime di Funzioni aggiunge un messaggio a una coda denominata <originalqueuename>-poison.If all five attempts fail, the functions runtime adds a message to a queue named <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.You can write a function to process messages from the poison queue by logging them or sending a notification that manual attention is needed.

Per gestire manualmente i messaggi non elaborabili, controllare dequeueCount nel messaggio della coda.To handle poison messages manually, check the dequeueCount of the queue message.

Trigger - proprietà di host.jsonTrigger - host.json properties

Il file host.json contiene le impostazioni che controllano il comportamento del trigger della coda.The host.json file contains settings that control queue trigger behavior.

{
    "queues": {
      "maxPollingInterval": 2000,
      "visibilityTimeout" : "00:00:30",
      "batchSize": 16,
      "maxDequeueCount": 5,
      "newBatchThreshold": 8
    }
}
ProprietàProperty DefaultDefault DescrizioneDescription
maxPollingIntervalmaxPollingInterval 6000060000 L'intervallo massimo, in millisecondi, tra i polling di coda.The maximum interval in milliseconds between queue polls.
visibilityTimeoutvisibilityTimeout 00 L'intervallo di tempo tra i tentativi se l'elaborazione di un messaggio ha esito negativo.The time interval between retries when processing of a message fails.
batchSizebatchSize 1616 Il numero di messaggi in coda da recuperare ed elaborare in parallelo.The number of queue messages to retrieve and process in parallel. Il valore massimo è 32.The maximum is 32.
maxDequeueCountmaxDequeueCount 55 Il numero di volte per provare l'elaborazione di un messaggio prima di essere spostato nella coda non elaborabile.The number of times to try processing a message before moving it to the poison queue.
newBatchThresholdnewBatchThreshold batchSize/2batchSize/2 La soglia in corrispondenza della quale viene recuperato un nuovo batch di messaggi.The threshold at which a new batch of messages are fetched.

OutputOutput

Usare l'associazione di output dell'archiviazione code di Azure per scrivere i messaggi in una coda.Use the Azure Queue storage output binding to write messages to a queue.

Output - esempioOutput - example

Vedere l'esempio specifico per ciascun linguaggio:See the language-specific example:

Output - esempio in C#Output - C# example

L'esempio seguente illustra un codice C# precompilato che crea un messaggio nella coda per ogni richiesta HTTP ricevuta.The following example shows precompiled C# code that creates a queue message for each HTTP request received.

[StorageAccount("AzureWebJobsStorage")]
public static class QueueFunctions
{
    [FunctionName("QueueOutput")]
    [return: Queue("myqueue-items")]
    public static string QueueOutput([HttpTrigger] dynamic input,  TraceWriter log)
    {
        log.Info($"C# function processed: {input.Text}");
        return input.Text;
    }
}

Output - esempio di script C#Output - C# script example

L'esempio seguente illustra un'associazione di trigger di BLOB in un file function.json e codice script C# che usa l'associazione.The following example shows a blob trigger binding in a function.json file and C# script code that uses the binding. La funzione crea un elemento della coda con un payload POCO per ogni richiesta HTTP ricevuta.The function creates a queue item with a POCO payload for each HTTP request received.

Ecco il file function.json:Here's the function.json file:

{
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "authLevel": "function",
      "name": "input"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "return"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "$return",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting",
    }
  ]
}

Queste proprietà sono descritte nella sezione configuration.The configuration section explains these properties.

Ecco il codice script C# che crea un singolo messaggio nella coda:Here's C# script code that creates a single queue message:

public class CustomQueueMessage
{
    public string PersonName { get; set; }
    public string Title { get; set; }
}

public static CustomQueueMessage Run(CustomQueueMessage input, TraceWriter log)
{
    return input;
}

È possibile inviare più messaggi contemporaneamente usando ICollector o il parametro IAsyncCollector.You can send multiple messages at once by using an ICollector or IAsyncCollector parameter. Ecco il codice script C# che invia più messaggi, uno con i dati della richiesta HTTP e uno con i valori hardcoded:Here's C# script code that sends multiple messages, one with the HTTP request data and one with hard-coded values:

public static void Run(
    CustomQueueMessage input, 
    ICollector<CustomQueueMessage> myQueueItem, 
    TraceWriter log)
{
    myQueueItem.Add(input);
    myQueueItem.Add(new CustomQueueMessage { PersonName = "You", Title = "None" });
}

Output - esempio JavaScriptOutput - JavaScript example

L'esempio seguente illustra un'associazione di trigger di BLOB in un file function.json e una funzione JavaScript che usa l'associazione.The following example shows a blob trigger binding in a function.json file and a JavaScript function that uses the binding. La funzione crea un elemento della coda per ogni richiesta HTTP ricevuta.The function creates a queue item for each HTTP request received.

Ecco il file function.json:Here's the function.json file:

{
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "authLevel": "function",
      "name": "input"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "return"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "$return",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting",
    }
  ]
}

Queste proprietà sono descritte nella sezione configuration.The configuration section explains these properties.

Ecco il codice JavaScript:Here's the JavaScript code:

module.exports = function (context, input) {
    context.done(null, input.body);
};

È possibile inviare più messaggi contemporaneamente definendo un array di messaggio per l'associazione di output myQueueItem.You can send multiple messages at once by defining a message array for the myQueueItem output binding. Il codice JavaScript seguente invia due messaggi della coda con valori hardcoded per ogni richiesta HTTP ricevuta.The following JavaScript code sends two queue messages with hard-coded values for each HTTP request received.

module.exports = function(context) {
    context.bindings.myQueueItem = ["message 1","message 2"];
    context.done();
};

Output - attributiOutput - attributes

Per C# precompilato usare QueueAttribute, che è definito nel pacchetto NuGet Microsoft.Azure.WebJobs.For precompiled C# functions, use the QueueAttribute, which is defined in NuGet package Microsoft.Azure.WebJobs.

L'attributo si applica a un parametro out o al valore restituito della funzione.The attribute applies to an out parameter or the return value of the function. Il costruttore dell'attributo accetta il nome della coda, come illustrato nell'esempio seguente:The attribute's constructor takes the name of the queue, as shown in the following example:

[FunctionName("QueueOutput")]
[return: Queue("myqueue-items")]
public static string Run([HttpTrigger] dynamic input,  TraceWriter log)
{
    ...
}

È possibile impostare la proprietà Connection per specificare l'account di archiviazione da usare, come illustrato nell'esempio seguente:You can set the Connection property to specify the storage account to use, as shown in the following example:

[FunctionName("QueueOutput")]
[return: Queue("myqueue-items, Connection = "StorageConnectionAppSetting")]
public static string Run([HttpTrigger] dynamic input,  TraceWriter log)
{
    ...
}

Per un esempio completo, vedere Output - esempio in C# precompilato.For a complete example, see Output - precompiled C# example.

È possibile usare l'attributo StorageAccount per specificare l'account di archiviazione a livello di classe, metodo o parametro.You can use the StorageAccount attribute to specify the storage account at class, method, or parameter level. Per altre informazioni, vedere Trigger - attributi.For more information, see Trigger - attributes.

Output - configurazioneOutput - configuration

Nella tabella seguente sono illustrate le proprietà di configurazione dell'associazione impostate nel file function.json e nell'attributo Queue.The following table explains the binding configuration properties that you set in the function.json file and the Queue attribute.

Proprietà di function.jsonfunction.json property Proprietà dell'attributoAttribute property DescrizioneDescription
typetype n/dn/a Il valore deve essere impostato su queue.Must be set to queue. Questa proprietà viene impostata automaticamente quando si crea il trigger nel portale di Azure.This property is set automatically when you create the trigger in the Azure portal.
directiondirection n/dn/a Il valore deve essere impostato su out.Must be set to out. Questa proprietà viene impostata automaticamente quando si crea il trigger nel portale di Azure.This property is set automatically when you create the trigger in the Azure portal.
nomename n/dn/a Nome della variabile che rappresenta la coda nel codice della funzione.The name of the variable that represents the queue in function code. Impostare su $return per fare riferimento al valore restituito della funzione.Set to $return to reference the function return value.
queueNamequeueName QueueNameQueueName Nome della coda.The name of the queue.
connessioneconnection ConnectionConnection Nome di un'impostazione dell'app che contiene la stringa di connessione di archiviazione da usare per questa associazione.The name of an app setting that contains the Storage connection string to use for this binding. Se il nome dell'impostazione dell'app inizia con "AzureWebJobs", è possibile specificare solo il resto del nome.If the app setting name begins with "AzureWebJobs", you can specify only the remainder of the name here. Ad esempio, se si imposta connection su "MyStorage", il runtime di Funzioni di Azure cerca un'impostazione dell'app denominata "AzureWebJobsMyStorage".For example, if you set connection to "MyStorage", the Functions runtime looks for an app setting that is named "AzureWebJobsMyStorage." Se si lascia vuoto connection, il runtime di Funzioni di Azure usa la stringa di connessione di archiviazione predefinita nell'impostazione dell'app denominata AzureWebJobsStorage.If you leave connection empty, the Functions runtime uses the default Storage connection string in the app setting that is named AzureWebJobsStorage.

Quando si sviluppa in locale, le impostazioni dell'app vengono inserite nel file local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Output - usoOutput - usage

In C# e negli script C# scrivere un singolo messaggio nella coda tramite un parametro di metodo, ad esempio out T paramName.In C# and C# script, write a single queue message by using a method parameter such as out T paramName. Negli script C#, paramName è il valore specificato nella proprietà name di function.json.In C# script, paramName is the value specified in the name property of function.json. È possibile usare il tipo restituito del metodo anziché un parametro out e T può essere uno dei seguenti tipi:You can use the method return type instead of an out parameter, and T can be any of the following types:

In C# e negli script C# scrivere più messaggi nella coda usando uno dei seguenti tipi:In C# and C# script, write multiple queue messages by using one of the following types:

Nelle funzioni JavaScript usare context.bindings.<name> per accedere al messaggio nella coda di output.In JavaScript functions, use context.bindings.<name> to access the output queue message. È possibile usare una stringa o un oggetto serializzabile in JSON per il payload dell'elemento della coda.You can use a string or a JSON-serializable object for the queue item payload.

Passaggi successiviNext steps