Concetti di Trigger e associazioni di Funzioni di AzureAzure Functions triggers and bindings concepts

In questo articolo viene fornita una panoramica concettuale di trigger e associazioni in Funzioni di Azure.This article is a conceptual overview of triggers and bindings in Azure Functions. Le funzionalità comuni a tutte le associazioni e a tutti i linguaggi supportati sono descritte di seguito.Features that are common to all bindings and all supported languages are described here.

PanoramicaOverview

Un trigger definisce come viene richiamata una funzione.A trigger defines how a function is invoked. Una funzione deve avere esattamente un trigger.A function must have exactly one trigger. I trigger hanno dei dati associati, ovvero in genere il payload che ha attivato la funzione.Triggers have associated data, which is usually the payload that triggered the function.

Le associazioni di input e output forniscono una modalità dichiarativa per connettersi ai dati dall'interno del codice.Input and output bindings provide a declarative way to connect to data from within your code. Le associazioni sono facoltative e una funzione può avere più associazioni di input e output.Bindings are optional and a function can have multiple input and output bindings.

I trigger e le associazioni permettono di evitare di inserire dettagli hardcoded dei servizi usati.Triggers and bindings let you avoid hardcoding the details of the services that you're working with. La funzione riceve i dati, ad esempio il contenuto di un messaggio della coda, nei parametri della funzione.Your function receives data (for example, the content of a queue message) in function parameters. I dati vengono inviati, ad esempio per creare un messaggio della coda, usando il valore restituito della funzione, un parametro out o un oggetto agente di raccolta.You send data (for example, to create a queue message) by using the return value of the function, an out parameter, or a collector object.

Quando si sviluppano funzioni tramite il portale di Azure, i trigger e le associazioni sono configurati in un file function.json.When you develop functions by using the Azure portal, triggers and bindings are configured in a function.json file. Il portale fornisce un'interfaccia utente per questa configurazione, ma è possibile modificare direttamente il file passando all'editor avanzato.The portal provides a UI for this configuration but you can edit the file directly by changing to the Advanced editor.

Se le funzioni vengono sviluppate in Visual Studio per creare una libreria di classi, i trigger e le associazioni vengono configurati tramite la decorazione di metodi e parametri con attributi.When you develop functions by using Visual Studio to create a class library, you configure triggers and bindings by decorating methods and parameters with attributes.

Binding supportatiSupported bindings

La tabella seguente mostra le associazioni supportate nelle due principali versioni del runtime di Funzioni di Azure.The following table shows the bindings that are supported in the two major versions of the Azure Functions runtime.

typeType 1.x1.x 2.x2.x TriggerTrigger InputInput OutputOutput
Archiviazione BLOBBlob Storage 11
Cosmos DBCosmos DB
Griglia di eventiEvent Grid
Hub eventiEvent Hubs
File esterno2External File2
Tabella esterna2External Table2
HTTPHTTP 11
Microsoft Graph
Tabelle di Excel
Microsoft Graph
Excel tables
Microsoft Graph
File di OneDrive
Microsoft Graph
OneDrive files
Microsoft Graph
Indirizzo e-mail Outlook
Microsoft Graph
Outlook email
Microsoft Graph
Eventi
Microsoft Graph
Events
Microsoft Graph
Token di autenticazione
Microsoft Graph
Auth tokens
App per dispositivi mobiliMobile Apps
Hub di notifica di AzureNotification Hubs
Archiviazione codeQueue storage 11
SendGridSendGrid
Bus di servizioService Bus
Archiviazione tabelleTable storage 11
TimerTimer
TwilioTwilio
WebhookWebhooks

1 In 2.x tutte le associazioni tranne HTTP, Timer e Archiviazione di Azure devono essere registrate.1 In 2.x, all bindings except HTTP, Timer, and Azure Storage must be registered. Vedere Registrare le estensioni delle associazioni.See Register binding extensions.

2 Sperimentale — Non supportato e potrebbe venire abbandonato in futuro.2 Experimental — not supported and might be abandoned in the future.

Per informazioni sulle associazioni in anteprima o approvate per l'uso in ambiente di produzione, vedere Linguaggi supportati .For information about which bindings are in preview or are approved for production use, see Supported languages.

Registrare le estensioni delle associazioniRegister binding extensions

In alcuni ambienti di sviluppo è necessario registrare in modo esplicito un'associazione che si desidera usare.In some development environments, you have to explicitly register a binding that you want to use. Le estensioni di associazione sono incluse nei pacchetti NuGet e per registrare un'estensione si installa un pacchetto.Binding extensions are provided in NuGet packages, and to register an extension you install a package. La tabella seguente indica come e quando registrare le estensioni di associazione.The following table indicates when and how you register binding extensions.

Ambiente di sviluppoDevelopment environment RegistrazioneRegistration
in Funzioni 1.xin Functions 1.x
RegistrazioneRegistration
in Funzioni 2.xin Functions 2.x
Portale di AzureAzure portal AutomaticoAutomatic Automatico con promptAutomatic with prompt
A livello locale con gli strumenti di base di Funzioni di AzureLocal using Azure Functions Core Tools AutomaticoAutomatic Usare i comandi CLI degli strumenti di baseUse Core Tools CLI commands
Libreria di classi C# usando Visual Studio 2017C# class library using Visual Studio 2017 Usare gli strumenti di NuGetUse NuGet tools Usare gli strumenti di NuGetUse NuGet tools
Libreria di classi C# usando Visual Studio CodeC# class library using Visual Studio Code N/DN/A Usare l'interfaccia della riga di comando di .NET CoreUse .NET Core CLI

I tipi di associazione seguenti sono eccezioni che non richiedono la registrazione esplicita perché sono registrati automaticamente in tutte le versioni e gli ambienti: HTTP, timer e Archiviazione di Azure (BLOB, code e tabelle).The following binding types are exceptions that don't require explicit registration because they are automatically registered in all versions and environments: HTTP, timer, and Azure Storage (blobs, queues, and tables).

Sviluppo con il portale di AzureAzure portal development

Quando si crea una funzione o si aggiunge un'associazione, compare un avviso quando è necessario registrare l'estensione dell'associazione o del trigger.When you create a function or add a binding, you are prompted when the extension for the trigger or binding requires registration. Rispondere all'avviso facendo clic Installa per registrare l'estensione.Respond to the prompt by clicking Install to register the extension. L'installazione può richiedere fino a 10 minuti in un piano a consumo.Installation can take up to 10 minutes on a consumption plan.

È necessario installare ogni estensione una sola volta per una determinata app per le funzioni.You need only install each extension one time for a given function app.

Sviluppo a livello locale con gli strumenti di base di Funzioni di AzureLocal development Azure Functions Core Tools

Quando si sviluppano funzioni in locale, è possibile installare le estensioni necessarie tramite Strumenti di base di Funzioni di Azure dal terminale o da un prompt dei comandi.When you develop functions locally, you can install the extensions you need by using the Azure Functions Core Tools from the Terminal or from a command prompt.

Dopo avere aggiornato il file function.json per includere tutte le associazioni necessarie per la funzione, eseguire il comando func extensions install nella cartella del progetto.After you have updated your function.json file to include all the bindings that your function needs, run the func extensions install command in the project folder. Il comando legge il file function.json per scoprire quali pacchetti sono necessari e li installa.The command reads the function.json file to see which packages you need and then installs them.

Se si vuole installare una versione specifica di un pacchetto o si vogliono installare i pacchetti prima di modificare il file function.json, usare il comando func extensions install con il nome del pacchetto, come illustrato nell'esempio seguente:If you want to install a particular version of a package or you want to install packages before editing the function.json file, use the func extensions install command with the name of the package, as shown in the following example:

func extensions install --package Microsoft.Azure.WebJobs.ServiceBus --version <target_version>

Sostituire <target_version> con una specifica versione del pacchetto, come 3.0.0-beta5.Replace <target_version> with a specific version of the package, such as 3.0.0-beta5. Le versioni valide sono elencate nelle pagine dei singoli pacchetti in NuGet.org.Valid versions are listed on the individual package pages at NuGet.org.

Libreria di classi C# con Visual Studio 2017C# class library with Visual Studio 2017

In Visual Studio 2017 è possibile installare pacchetti dalla Console di Gestione pacchetti usando il comando Install-Package, come illustrato nell'esempio seguente:In Visual Studio 2017, you can install packages from the Package Manager Console using the Install-Package command, as shown in the following example:

Install-Package Microsoft.Azure.WebJobs.ServiceBus --Version <target_version>

Il nome del pacchetto da usare per una determinata associazione è fornito nell'articolo di riferimento per quell'associazione.The name of the package to use for a given binding is provided in the reference article for that binding. Per un esempio, vedere la sezione sui pacchetti dell'articolo di riferimento sull'associazione del bus di servizio.For an example, see the Packages section of the Service Bus binding reference article.

Sostituire <target_version> nell'esempio con una specifica versione del pacchetto, come 3.0.0-beta5.Replace <target_version> in the example with a specific version of the package, such as 3.0.0-beta5. Le versioni valide sono elencate nelle pagine dei singoli pacchetti in NuGet.org. Le versioni principali che corrispondono al runtime di Funzioni 1.x o 2.x sono specificate nell'articolo di riferimento per l'associazione.Valid versions are listed on the individual package pages at NuGet.org. The major versions that correspond to Functions runtime 1.x or 2.x are specified in the reference article for the binding.

Libreria di classi C# con Visual Studio CodeC# class library with Visual Studio Code

In Visual Studio Code è possibile installare i pacchetti dal prompt dei comandi usando il comando dotnet add package nell'interfaccia della riga di comando di .NET Core, come indicato nell'esempio seguente:In Visual Studio Code, you can install packages from the command prompt using the dotnet add package command in the .NET Core CLI, as shown in the following example:

dotnet add package Microsoft.Azure.WebJobs.ServiceBus --version <target_version>

L'interfaccia della riga di comando di .NET Core può essere usata solo per lo sviluppo di Funzioni di Azure 2.x.The .NET Core CLI can only be used for Azure Functions 2.x development.

Il nome del pacchetto da usare per una determinata associazione è fornito nell'articolo di riferimento per quell'associazione.The name of the package to use for a given binding is provided in the reference article for that binding. Per un esempio, vedere la sezione sui pacchetti dell'articolo di riferimento sull'associazione del bus di servizio.For an example, see the Packages section of the Service Bus binding reference article.

Sostituire <target_version> nell'esempio con una specifica versione del pacchetto, come 3.0.0-beta5.Replace <target_version> in the example with a specific version of the package, such as 3.0.0-beta5. Le versioni valide sono elencate nelle pagine dei singoli pacchetti in NuGet.org. Le versioni principali che corrispondono al runtime di Funzioni 1.x o 2.x sono specificate nell'articolo di riferimento per l'associazione.Valid versions are listed on the individual package pages at NuGet.org. The major versions that correspond to Functions runtime 1.x or 2.x are specified in the reference article for the binding.

Trigger e associazione di esempioExample trigger and binding

Si supponga di voler scrivere una nuova riga in archiviazione tabelle di Azure ogni volta che viene visualizzato un messaggio nuovo in archiviazione code di Azure.Suppose you want to write a new row to Azure Table storage whenever a new message appears in Azure Queue storage. Questo scenario può essere implementato tramite un trigger di archiviazione code di Azure e un'associazione di output di archiviazione tabelle di Azure.This scenario can be implemented using an Azure Queue storage trigger and an Azure Table storage output binding.

Ecco un file function.json per questo scenario.Here's a function.json file for this scenario.

{
  "bindings": [
    {
      "name": "order",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "myqueue-items",
      "connection": "MY_STORAGE_ACCT_APP_SETTING"
    },
    {
      "name": "$return",
      "type": "table",
      "direction": "out",
      "tableName": "outTable",
      "connection": "MY_TABLE_STORAGE_ACCT_APP_SETTING"
    }
  ]
}

Il primo elemento nella matrice bindings è il trigger di archiviazione code.The first element in the bindings array is the Queue storage trigger. Le proprietà type e direction identificano il trigger.The type and direction properties identify the trigger. La proprietà name identifica il parametro della funzione che riceve il contenuto del messaggio della coda.The name property identifies the function parameter that receives the queue message content. Il nome della coda da monitorare si trova in queueName e la stringa di connessione si trova nell'impostazione app identificata da connection.The name of the queue to monitor is in queueName, and the connection string is in the app setting identified by connection.

Il secondo elemento nella matrice bindings è l'associazione di output dell'archiviazione tabelle di Azure.The second element in the bindings array is the Azure Table Storage output binding. Le proprietà type e direction identificano l'associazione.The type and direction properties identify the binding. La proprietà name specifica in che modo la funzione fornisce la nuova riga di tabella, in questo caso usando il valore restituito della funzione.The name property specifies how the function provides the new table row, in this case by using the function return value. Il nome della tabella si trova in tableName e la stringa di connessione si trova nell'impostazione app identificata da connection.The name of the table is in tableName, and the connection string is in the app setting identified by connection.

Per visualizzare e modificare i contenuti della funzione .json nel portale di Azure, fare clic sull'opzione Editor avanzato nella scheda Integrazione della funzione.To view and edit the contents of function.json in the Azure portal, click the Advanced editor option on the Integrate tab of your function.

Nota

Il valore di connection corrisponde al nome di un'impostazione app che contiene la stringa di connessione e non alla stringa di connessione stessa.The value of connection is the name of an app setting that contains the connection string, not the connection string itself. Le associazioni usano stringhe di connessione archiviate nelle impostazioni app per imporre la procedura consigliata che prevede che il file function.json non contenga i segreti del servizio.Bindings use connection strings stored in app settings to enforce the best practice that function.json does not contain service secrets.

Ecco il codice dello script C# per questo trigger e questa associazione.Here's C# script code that works with this trigger and binding. Si noti che il nome del parametro che fornisce il contenuto del messaggio della coda è order. Questo nome è obbligatorio perché il valore della proprietà name nel file function.json è orderNotice that the name of the parameter that provides the queue message content is order; this name is required because the name property value in function.json is order

#r "Newtonsoft.Json"

using Newtonsoft.Json.Linq;

// From an incoming queue message that is a JSON object, add fields and write to Table storage
// The method return value creates a new row in Table Storage
public static Person Run(JObject order, TraceWriter log)
{
    return new Person() { 
            PartitionKey = "Orders", 
            RowKey = Guid.NewGuid().ToString(),  
            Name = order["Name"].ToString(),
            MobileNumber = order["MobileNumber"].ToString() };  
}

public class Person
{
    public string PartitionKey { get; set; }
    public string RowKey { get; set; }
    public string Name { get; set; }
    public string MobileNumber { get; set; }
}

Lo stesso file function.json può essere usato con una funzione JavaScript:The same function.json file can be used with a JavaScript function:

// From an incoming queue message that is a JSON object, add fields and write to Table Storage
// The second parameter to context.done is used as the value for the new row
module.exports = function (context, order) {
    order.PartitionKey = "Orders";
    order.RowKey = generateRandomId(); 

    context.done(null, order);
};

function generateRandomId() {
    return Math.random().toString(36).substring(2, 15) +
        Math.random().toString(36).substring(2, 15);
}

In una libreria di classi le stesse informazioni sui trigger e sulle associazioni, ovvero i nomi di coda e tabella, gli account di archiviazione, i parametri di funzione per l'input e l'output, vengono fornite dagli attributi anziché da un file function.json.In a class library, the same trigger and binding information — queue and table names, storage accounts, function parameters for input and output — is provided by attributes instead of a function.json file. Ad esempio:Here's an example:

 public static class QueueTriggerTableOutput
 {
     [FunctionName("QueueTriggerTableOutput")]
     [return: Table("outTable", Connection = "MY_TABLE_STORAGE_ACCT_APP_SETTING")]
     public static Person Run(
         [QueueTrigger("myqueue-items", Connection = "MY_STORAGE_ACCT_APP_SETTING")]JObject order, 
         TraceWriter log)
     {
         return new Person() {
                 PartitionKey = "Orders",
                 RowKey = Guid.NewGuid().ToString(),
                 Name = order["Name"].ToString(),
                 MobileNumber = order["MobileNumber"].ToString() };
     }
 }

 public class Person
 {
     public string PartitionKey { get; set; }
     public string RowKey { get; set; }
     public string Name { get; set; }
     public string MobileNumber { get; set; }
 }

Direzione dell'associazioneBinding direction

Tutti i trigger e le associazioni hanno una proprietà direction nel file function.json:All triggers and bindings have a direction property in the function.json file:

  • Per i trigger, la direzione è sempre inFor triggers, the direction is always in
  • Le associazioni di input e di output usano in e outInput and output bindings use in and out
  • Alcune associazioni supportano una direzione speciale inout.Some bindings support a special direction inout. Se si usa inout, solo l'Editor avanzato è disponibile nelle scheda Integrazione.If you use inout, only the Advanced editor is available in the Integrate tab.

Quando si usano gli attributi in una libreria di classi per configurare i trigger e le associazioni, la direzione viene specificata in un costruttore di attributo o dedotta dal tipo di parametro.When you use attributes in a class library to configure triggers and bindings, the direction is provided in an attribute constructor or inferred from the parameter type.

Uso del valore restituito della funzioneUsing the function return value

Nei linguaggi che hanno un valore restituito è possibile associare a tale valore un'associazione di output:In languages that have a return value, you can bind an output binding to the return value:

  • In una libreria di classi C# applicare l'attributo dell'associazione di output al valore restituito del metodo.In a C# class library, apply the output binding attribute to the method return value.
  • In altri linguaggi impostare la proprietà name in function.json su $return.In other languages, set the name property in function.json to $return.

Se è necessario scrivere più elementi, usare un oggetto agente di raccolta anziché il valore restituito.If you need to write more than one item, use a collector object instead of the return value. Se sono presenti più associazioni di output, usare il valore restituito per una sola di tali associazioni.If there are multiple output bindings, use the return value for only one of them.

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

Esempio in C#C# example

Di seguito è riportato il codice C# che usa il valore restituito per un'associazione di output, seguito da un esempio asincrono:Here's C# code that uses the return value for an output binding, followed by an async example:

[FunctionName("QueueTrigger")]
[return: Blob("output-container/{id}")]
public static string Run([QueueTrigger("inputqueue")]WorkItem input, TraceWriter log)
{
    string json = string.Format("{{ \"id\": \"{0}\" }}", input.Id);
    log.Info($"C# script processed queue message. Item={json}");
    return json;
}
[FunctionName("QueueTrigger")]
[return: Blob("output-container/{id}")]
public static Task<string> Run([QueueTrigger("inputqueue")]WorkItem input, TraceWriter log)
{
    string json = string.Format("{{ \"id\": \"{0}\" }}", input.Id);
    log.Info($"C# script processed queue message. Item={json}");
    return Task.FromResult(json);
}

Esempio di script C#C# script example

Di seguito è riportata l'associazione di output nel file function.json:Here's the output binding in the function.json file:

{
    "name": "$return",
    "type": "blob",
    "direction": "out",
    "path": "output-container/{id}"
}

Di seguito è riportato il codice di script C#, seguito da un esempio asincrono:Here's the C# script code, followed by an async example:

public static string Run(WorkItem input, TraceWriter log)
{
    string json = string.Format("{{ \"id\": \"{0}\" }}", input.Id);
    log.Info($"C# script processed queue message. Item={json}");
    return json;
}
public static Task<string> Run(WorkItem input, TraceWriter log)
{
    string json = string.Format("{{ \"id\": \"{0}\" }}", input.Id);
    log.Info($"C# script processed queue message. Item={json}");
    return Task.FromResult(json);
}

Esempio F#F# example

Di seguito è riportata l'associazione di output nel file function.json:Here's the output binding in the function.json file:

{
    "name": "$return",
    "type": "blob",
    "direction": "out",
    "path": "output-container/{id}"
}

Ecco il codice F#:Here's the F# code:

let Run(input: WorkItem, log: TraceWriter) =
    let json = String.Format("{{ \"id\": \"{0}\" }}", input.Id)   
    log.Info(sprintf "F# script processed queue message '%s'" json)
    json

Esempio JavaScriptJavaScript example

Di seguito è riportata l'associazione di output nel file function.json:Here's the output binding in the function.json file:

{
    "name": "$return",
    "type": "blob",
    "direction": "out",
    "path": "output-container/{id}"
}

In JavaScript il valore restituito viene inserito nel secondo parametro per context.done:In JavaScript, the return value goes in the second parameter for context.done:

module.exports = function (context, input) {
    var json = JSON.stringify(input);
    context.log('Node.js script processed queue message', json);
    context.done(null, json);
}

Proprietà Binding dataTypeBinding dataType property

In .NET usare il tipo di parametro per definire il tipo di dati per i dati di input.In .NET, use the parameter type to define the data type for input data. Usare ad esempio string da associare al testo di un trigger di coda, una matrice di byte da leggere in formato binario e un tipo personalizzato per deserializzare un oggetto POCO.For instance, use string to bind to the text of a queue trigger, a byte array to read as binary and a custom type to deserialize to a POCO object.

Per i linguaggi tipizzati in modo dinamico, ad esempio JavaScript, usare la proprietà dataType nel file function.json.For languages that are dynamically typed such as JavaScript, use the dataType property in the function.json file. Ad esempio, per eseguire la lettura del contenuto di una richiesta HTTP in formato binario, impostare dataType su binary:For example, to read the content of an HTTP request in binary format, set dataType to binary:

{
    "type": "httpTrigger",
    "name": "req",
    "direction": "in",
    "dataType": "binary"
}

Altre opzioni per dataType sono stream e string.Other options for dataType are stream and string.

Modelli ed espressioni di associazioneBinding expressions and patterns

Una delle funzionalità più potenti di trigger e associazioni sono le espressioni di associazione.One of the most powerful features of triggers and bindings is binding expressions. Nel file function.json e nel codice e nei parametri della funzione è possibile usare espressioni risolvibili in valori di varie origini.In the function.json file and in function parameters and code, you can use expressions that resolve to values from various sources.

Quasi tutte le espressioni sono identificate tramite la disposizione del testo tra parentesi graffe.Most expressions are identified by wrapping them in curly braces. Ad esempio, in una funzione di trigger della coda {queueTrigger} viene risolto nel testo dei messaggi della coda.For example, in a queue trigger function, {queueTrigger} resolves to the queue message text. Se la proprietà path dell'associazione di output di un BLOB è container/{queueTrigger} e la funzione viene attivata da un messaggio della coda HelloWorld, viene creato un BLOB denominato HelloWorld.If the path property for a blob output binding is container/{queueTrigger} and the function is triggered by a queue message HelloWorld, a blob named HelloWorld is created.

Tipi di espressioni di associazioneTypes of binding expressions

Espressioni di associazione - impostazioni dell'appBinding expressions - app settings

Come procedura consigliata, i segreti e le stringhe di connessione devono essere gestiti tramite le impostazioni dell'app, invece dei file di configurazione.As a best practice, secrets and connection strings should be managed using app settings, rather than configuration files. Questo limita l'accesso ai segreti e rende sicuro archiviare i file, ad esempio function.json, nei repository pubblici di controllo del codice sorgente.This limits access to these secrets and makes it safe to store files such as function.json in public source control repositories.

Le impostazioni dell'app sono utili anche ogni volta che si desidera modificare la configurazione in base all'ambiente.App settings are also useful whenever you want to change configuration based on the environment. Ad esempio, in un ambiente di test, si potrebbe voler monitorare un contenitore di archiviazione BLOB o di coda diverso.For example, in a test environment, you may want to monitor a different queue or blob storage container.

Le espressioni di associazione gestite tramite le impostazioni dell'app vengono identificate in modo diverso rispetto ad altre espressioni di associazione. Vengono infatti racchiuse tra segni di percentuale anziché tra parentesi graffe.App setting binding expressions are identified differently from other binding expressions: they are wrapped in percent signs rather than curly braces. Ad esempio, se è il percorso dell'associazione di output del BLOB è %Environment%/newblob.txt e il valore dell'impostazione dell'app Environment è Development, verrà creato un BLOB nel contenitore Development.For example if the blob output binding path is %Environment%/newblob.txt and the Environment app setting value is Development, a blob will be created in the Development container.

Quando una funzione è in esecuzione a livello locale, i valori delle impostazioni dell'app vengono ricavati dal file local.settings.json.When a function is running locally, app setting values come from the local.settings.json file.

Si noti che la proprietà connection dei trigger e delle associazioni è un caso speciale e risolve automaticamente i valori come impostazioni dell'app senza segni di percentuale.Note that the connection property of triggers and bindings is a special case and automatically resolves values as app settings, without percent signs.

L'esempio seguente è un trigger di archiviazione code di Azure che usa un'impostazione dell'app %input-queue-name% per definire la coda di trigger.The following example is an Azure Queue Storage trigger that uses an app setting %input-queue-name% to define the queue to trigger on.

{
  "bindings": [
    {
      "name": "order",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "%input-queue-name%",
      "connection": "MY_STORAGE_ACCT_APP_SETTING"
    }
  ]
}

È possibile usare lo stesso approccio nelle librerie di classi:You can use the same approach in class libraries:

[FunctionName("QueueTrigger")]
public static void Run(
    [QueueTrigger("%input-queue-name%")]string myQueueItem, 
    TraceWriter log)
{
    log.Info($"C# Queue trigger function processed: {myQueueItem}");
}

Espressioni di associazione - nome file del triggerBinding expressions - trigger file name

La proprietà path di un trigger BLOB può essere un modello che consente di fare riferimento al nome del BLOB di attivazione in altre associazioni e in altro codice della funzione.The path for a Blob trigger can be a pattern that lets you refer to the name of the triggering blob in other bindings and function code. Il modello può anche includere criteri di filtro che specificano quali BLOB può attivare una chiamata di funzione.The pattern can also include filtering criteria that specify which blobs can trigger a function invocation.

Ad esempio, nell'associazione del trigger BLOB seguente il modello path è sample-images/{filename} e crea un'espressione di associazione denominata filename:For example, in the following Blob trigger binding, the path pattern is sample-images/{filename}, which creates a binding expression named filename:

{
  "bindings": [
    {
      "name": "image",
      "type": "blobTrigger",
      "path": "sample-images/{filename}",
      "direction": "in",
      "connection": "MyStorageConnection"
    },
    ...

L'espressione filename può quindi essere usata in un'associazione di output per specificare il nome del BLOB da creare:The expression filename can then be used in an output binding to specify the name of the blob being created:

    ...
    {
      "name": "imageSmall",
      "type": "blob",
      "path": "sample-images-sm/{filename}",
      "direction": "out",
      "connection": "MyStorageConnection"
    }
  ],
}

Il codice della funzione ha accesso a questo stesso valore usando filename come nome di parametro:Function code has access to this same value by using filename as a parameter name:

// C# example of binding to {filename}
public static void Run(Stream image, string filename, Stream imageSmall, TraceWriter log)  
{
    log.Info($"Blob trigger processing: {filename}");
    // ...
} 

La stessa possibilità di usare criteri ed espressioni di associazione si applica agli attributi nelle librerie di classi.The same ability to use binding expressions and patterns applies to attributes in class libraries. Nell'esempio seguente i parametri del costruttore di attributo corrispondono ai valori di path nei precedenti esempi di function.json:In the following example, the attribute constructor parameters are the same path values as the preceding function.json examples:

[FunctionName("ResizeImage")]
public static void Run(
    [BlobTrigger("sample-images/{filename}")] Stream image,
    [Blob("sample-images-sm/{filename}", FileAccess.Write)] Stream imageSmall,
    string filename,
    TraceWriter log)
{
    log.Info($"Blob trigger processing: {filename}");
    // ...
}

È anche possibile creare espressioni per parti del nome file, ad esempio per l'estensione.You can also create expressions for parts of the file name such as the extension. Per altre informazioni su come usare le espressioni e i modelli nella stringa del percorso del BLOB, vedere la documentazione di riferimento sulle associazioni dell'archiviazione BLOB.For more information on how to use expressions and patterns in the Blob path string, see the Storage blob binding reference.

Espressioni di associazione - metadati dei triggerBinding expressions - trigger metadata

Oltre al payload dei dati fornito da un trigger, ad esempio il contenuto del messaggio della coda che ha attivato una funzione, molti trigger forniscono altri valori di metadati.In addition to the data payload provided by a trigger (such as the content of the queue message that triggered a function), many triggers provide additional metadata values. Questi valori possono essere usati come parametri di input in C# e F# o come proprietà nell'oggetto context.bindings in JavaScript.These values can be used as input parameters in C# and F# or properties on the context.bindings object in JavaScript.

Un trigger di archiviazione code di Azure, ad esempio, supporta le proprietà seguenti:For example, an Azure Queue storage trigger supports the following properties:

  • QueueTrigge: attivazione del contenuto del messaggio, se una stringa validaQueueTrigger - triggering message content if a valid string
  • DequeueCountDequeueCount
  • ExpirationTimeExpirationTime
  • IDId
  • InsertionTimeInsertionTime
  • NextVisibleTimeNextVisibleTime
  • PopReceiptPopReceipt

I valori di questi metadati sono accessibili nelle proprietà del file function.json.These metadata values are accessible in function.json file properties. Si supponga, ad esempio, di usare un trigger di accodamento e che il messaggio della coda contenga il nome di un BLOB di cui si vuole eseguire la lettura.For example, suppose you use a queue trigger and the queue message contains the name of a blob you want to read. Nel file function.json è possibile usare la proprietà dei metadati queueTrigger nella proprietà path del BLOB come mostrato nell'esempio seguente:In the function.json file, you can use queueTrigger metadata property in the blob path property, as shown in the following example:

  "bindings": [
    {
      "name": "myQueueItem",
      "type": "queueTrigger",
      "queueName": "myqueue-items",
      "connection": "MyStorageConnection",
    },
    {
      "name": "myInputBlob",
      "type": "blob",
      "path": "samples-workitems/{queueTrigger}",
      "direction": "in",
      "connection": "MyStorageConnection"
    }
  ]

I dettagli delle proprietà dei metadati per ogni trigger sono descritti nell'articolo di riferimento corrispondente.Details of metadata properties for each trigger are described in the corresponding reference article. Per un esempio, vedere metadati dei trigger per le code.For an example, see queue trigger metadata. La documentazione è disponibile anche nella scheda Integrazione del portale nella sezione Documentazione sotto l'area di configurazione dell'associazione.Documentation is also available in the Integrate tab of the portal, in the Documentation section below the binding configuration area.

Espressioni di associazione - payload JSONBinding expressions - JSON payloads

Quando il payload di un trigger è JSON, è possibile fare riferimento alle relative proprietà nella configurazione di altre associazioni nella stessa funzione e nel codice della funzione.When a trigger payload is JSON, you can refer to its properties in configuration for other bindings in the same function and in function code.

L'esempio seguente mostra il file function.json di una funzione webhook che riceve un nome di BLOB in JSON: {"BlobName":"HelloWorld.txt"}.The following example shows the function.json file for a webhook function that receives a blob name in JSON: {"BlobName":"HelloWorld.txt"}. Un'associazione di input del BLOB legge il BLOB e l'associazione di output HTTP restituisce i contenuti del BLOB nella risposta HTTP.A Blob input binding reads the blob, and the HTTP output binding returns the blob contents in the HTTP response. Si noti che l'associazione di input del BLOB ottiene il nome del BLOB facendo riferimento direttamente alla proprietà BlobName ("path": "strings/{BlobName}").Notice that the Blob input binding gets the blob name by referring directly to the BlobName property ("path": "strings/{BlobName}")

{
  "bindings": [
    {
      "name": "info",
      "type": "httpTrigger",
      "direction": "in",
      "webHookType": "genericJson"
    },
    {
      "name": "blobContents",
      "type": "blob",
      "direction": "in",
      "path": "strings/{BlobName.FileName}.{BlobName.Extension}",
      "connection": "AzureWebJobsStorage"
    },
    {
      "name": "res",
      "type": "http",
      "direction": "out"
    }
  ]
}

Per il corretto funzionamento di questo meccanismo in C# e F#, è necessaria una classe che definisca i campi da deserializzare, come nell'esempio seguente:For this to work in C# and F#, you need a class that defines the fields to be deserialized, as in the following example:

using System.Net;

public class BlobInfo
{
    public string BlobName { get; set; }
}

public static HttpResponseMessage Run(HttpRequestMessage req, BlobInfo info, string blobContents)
{
    if (blobContents == null) {
        return req.CreateResponse(HttpStatusCode.NotFound);
    } 

    return req.CreateResponse(HttpStatusCode.OK, new {
        data = $"{blobContents}"
    });
}

In JavaScript la deserializzazione JSON viene eseguita automaticamente.In JavaScript, JSON deserialization is automatically performed.

module.exports = function (context, info) {
    if ('BlobName' in info) {
        context.res = {
            body: { 'data': context.bindings.blobContents }
        }
    }
    else {
        context.res = {
            status: 404
        };
    }
    context.done();
}

Notazione con il puntoDot notation

Se alcune proprietà nel payload JSON sono oggetti con proprietà, è possibile fare riferimento direttamente a tali oggetti tramite la notazione con il punto.If some of the properties in your JSON payload are objects with properties, you can refer to those directly by using dot notation. Ad esempio, si supponga che il file JSON sia simile al seguente:For example, suppose your JSON looks like this:

{"BlobName": {
  "FileName":"HelloWorld",
  "Extension":"txt"
  }
}

È possibile fare riferimento direttamente a FileName come BlobName.FileName.You can refer directly to FileName as BlobName.FileName. Con questo formato JSON, la proprietà path dell'esempio precedente avrà l'aspetto seguente:With this JSON format, here's what the path property in the preceding example would look like:

"path": "strings/{BlobName.FileName}.{BlobName.Extension}",

In C# sono necessarie due classi:In C#, you would need two classes:

public class BlobInfo
{
    public BlobName BlobName { get; set; }
}
public class BlobName
{
    public string FileName { get; set; }
    public string Extension { get; set; }
}

Espressioni di associazione - creare GUIDBinding expressions - create GUIDs

L'espressione di associazione {rand-guid} crea un GUID.The {rand-guid} binding expression creates a GUID. Il percorso del BLOB seguente in un file function.json crea un BLOB con un nome, ad esempio 50710cb5 84b9 - 4d 87-9d 83-a03d6976a682.txt.The following blob path in a function.json file creates a blob with a name like 50710cb5-84b9-4d87-9d83-a03d6976a682.txt.

{
  "type": "blob",
  "name": "blobOutput",
  "direction": "out",
  "path": "my-output-container/{rand-guid}"
}

Espressioni di associazione - data e ora correntiBinding expressions - current time

L'espressione di associazione DateTime viene risolta in DateTime.UtcNow.The binding expression DateTime resolves to DateTime.UtcNow. Il percorso del BLOB seguente in un file function.json crea un BLOB con un nome, ad esempio 2018-02-16T17-59-55Z.txt.The following blob path in a function.json file creates a blob with a name like 2018-02-16T17-59-55Z.txt.

{
  "type": "blob",
  "name": "blobOutput",
  "direction": "out",
  "path": "my-output-container/{DateTime}"
}

Associazione in fase di esecuzioneBinding at runtime

In C# e altri linguaggi .NET, è possibile usare criteri di associazione imperativa, rispetto alle associazioni dichiarative nel file function.json e negli attributi.In C# and other .NET languages, you can use an imperative binding pattern, as opposed to the declarative bindings in function.json and attributes. L'associazione imperativa è utile quando i parametri di associazione devono essere calcolati in fase di runtime invece che in fase di progettazione.Imperative binding is useful when binding parameters need to be computed at runtime rather than design time. Per altre informazioni, vedere la documentazione di riferimento per sviluppatori C# o la documentazione di riferimento per sviluppatori di script C#.To learn more, see the C# developer reference or the C# script developer reference.

Schema del file function.jsonfunction.json file schema

Lo schema del file function.json è disponibile all'indirizzo http://json.schemastore.org/function.The function.json file schema is available at http://json.schemastore.org/function.

Gestione degli errori di associazioneHandling binding errors

Trigger e associazioni di Funzioni di Azure comunicano con diversi servizi di Azure.Azure Functions triggers and bindings communicate with various Azure services. In caso di integrazione con questi servizi, possono venire generati errori originati dalle API dei servizi di Azure sottostanti.When integrating with these services, you may have errors raised that originate from the APIs of the underlying Azure services. Possono verificarsi errori anche quando si prova a comunicare con altri servizi dal codice della funzione usando librerie client o REST.Errors can also occur when you try to communicate with other services from your function code by using REST or client libraries. Per evitare la perdita di dati e garantire un comportamento corretto delle funzioni, è importante gestire gli errori da entrambe le origini.To avoid loss of data and ensure good behavior of your functions, it is important to handle errors from either source.

Per la maggior parte dei trigger, non è disponibile un meccanismo predefinito di ripetizione dei tentativi quando si verificano errori durante l'esecuzione della funzione.For most triggers, there is no built-in retry when errors occur during function execution. I due trigger che offrono supporto per la ripetizione dei tentativi sono Archiviazione code di Azure e Archiviazione BLOB di Azure.The two triggers that have retry support are Azure Queue storage and Azure Blob storage. Per impostazione predefinita, per questi trigger vengono eseguiti fino a cinque nuovi tentativi.By default, these triggers are retried up to five times. Dopo il quinto tentativo, entrambi i trigger scrivono un messaggio in una speciale coda non elaborabile.After the fifth retry, both triggers write a message to a special poison queue.

Per evitare perdite di informazioni dei trigger in caso di errore nella funzione, è consigliabile usare blocchi Try-Catch nel codice della funzione per intercettare gli errori.To prevent loss of trigger information should an error occur in your function, we recommend that you use try-catch blocks in your function code to catch any errors. Quando si verifica un errore, scrivere le informazioni passate alla funzione dal trigger in una speciale coda "non elaborabile".When an error occurs, write the information passed into the function by the trigger to a special "poison" message queue. Questo approccio corrisponde a quello usato dal trigger di archiviazione BLOB.This approach is the same one used by the Blob storage trigger.

In questo modo, è possibile acquisire gli eventi di trigger che potrebbero andare persi a causa di errori ed eseguire un nuovo tentativo in un secondo momento usando un'altra funzione per elaborare i messaggi dalla coda non elaborabile usando le informazioni archiviate.In this way, you can capture trigger events that could be lost due to errors and retry them at a later time using another function to process messages from the poison queue using the stored information.

Per i collegamenti a tutti gli argomenti relativi agli errori pertinenti per i diversi servizi supportati da Funzioni, vedere la sezione Binding error codes (Codici degli errori di associazione) dell'argomento introduttivo Azure Functions error handling (Gestione degli errori di Funzioni di Azure).For links to all relevant error topics for the various services supported by Functions, see the Binding error codes section of the Azure Functions error handling overview topic.

Passaggi successiviNext steps

Per altre informazioni su questi elementi, vedere gli articoli indicati di seguito:For more information on a specific binding, see the following articles: