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

Funzioni di Azure consente di scrivere codice in risposta agli eventi in Azure e in altri servizi, tramite trigger e associazioni.Azure Functions allows you to write code in response to events in Azure and other services, through triggers and bindings. In questo articolo viene fornita una panoramica concettuale di trigger e associazioni per tutti i linguaggi di programmazione supportati.This article is a conceptual overview of triggers and bindings for all supported programming languages. Le funzionalità comuni a tutte le associazioni sono descritte di seguito.Features that are common to all bindings are described here.

PanoramicaOverview

I trigger e le associazioni sono un modo dichiarativo per definire come viene invocata una funzione e con quali dati opera.Triggers and bindings are a declarative way to define how a function is invoked and what data it works with. 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. Analogamente ai trigger, specificare le stringhe di connessione e le altre proprietà nella configurazione della funzione.Similar to triggers, you specify connection strings and other properties in your function configuration. 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.

Usando i trigger e le associazioni, è possibile scrivere codice più generico e non impostare come hardcoded i dettagli dei servizi con cui interagisce.Using triggers and bindings, you can write code that is more generic and does not hardcode the details of the services with which it interacts. I dati provenienti dai servizi diventano semplicemente valori di input per il codice della funzione.Data coming from services simply become input values for your function code. Per restituire i dati a un altro servizio (ad esempio la creazione di una nuova riga nell'archiviazione tabelle di Azure), usare il valore restituito del metodo.To output data to another service (such as creating a new row in Azure Table Storage), use the return value of the method. In alternativa, se è necessario restituire più valori, usare un oggetto di supporto.Or, if you need to output multiple values, use a helper object. I trigger e le associazioni presentano una proprietà nome, che è un identificatore che si usa nel codice per accedere all'associazione.Triggers and bindings have a name property, which is an identifier you use in your code to access the binding.

È possibile configurare i trigger e le associazioni nella scheda Integrazione nel portale delle Funzioni di Azure.You can configure triggers and bindings in the Integrate tab in the Azure Functions portal. Dietro le quinte, l'interfaccia utente modifica un file denominato file function.json nella directory della funzione.Under the covers, the UI modifies a file called function.json file in the function directory. È possibile modificare questo file passando all'Editor avanzato.You can edit this file by changing to the Advanced editor.

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.

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

1 Deve essere registrato come un'estensione di associazione nella versione 2. x.1 Must be registered as a binding extension in 2.x. Vedere Problemi noti nella versione 2.x.See Known issues in 2.x.

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.

Esempio: trigger di coda e tabella di associazione di outputExample: queue trigger and table output 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 della coda di Azure e un'associazione di output di archiviazione tabelle di Azure.This scenario can be implemented using an Azure Queue trigger and an Azure Table Storage output binding.

Un trigger di archiviazione code di Azure richiede le informazioni seguenti nella scheda Integrazione:An Azure Queue Storage trigger requires the following information in the Integrate tab:

  • Il nome dell'impostazione dell'app che contiene la stringa di connessione dell'account di archiviazione di Azure per archiviazione code di AzureThe name of the app setting that contains the Azure Storage account connection string for the Azure Queue Storage
  • Il nome della codaThe queue name
  • L'identificatore nel codice per leggere il contenuto del messaggio in coda, ad esempio order.The identifier in your code to read the contents of the queue message, such as order.

Per scrivere in archiviazione tabelle di Azure, usare un'associazione di output con i dettagli seguenti:To write to Azure Table Storage, use an output binding with the following details:

  • Il nome dell'impostazione dell'app che contiene la stringa di connessione dell'account di archiviazione di Azure per archiviazione tabelle di AzureThe name of the app setting that contains the Azure Storage account connection string for the Azure Table Storage
  • Il nome della tabellaThe table name
  • L'identificatore nel codice per creare elementi di output o il valore restituito dalla funzione.The identifier in your code to create output items, or the return value from the function.

Le associazioni usano valori di stringhe di connessione archiviati nelle impostazioni dell'app per applicare la procedura consigliata in base alla quale function.json non contiene segreti del servizio ma semplicemente i nomi delle impostazioni dell'app.Bindings use connection strings values stored in the app settings to enforce the best practice that function.json does not contain service secrets and instead simply contain the names of the app settings.

Quindi, usare gli identificatori che vengono forniti per l'integrazione con archiviazione di Azure nel codice.Then, use the identifiers you provided to integrate with Azure Storage in your code.

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

Ecco il function.json che corrisponde al codice precedente.Here is the function.json that corresponds to the preceding code. Si noti che si può usare la stessa configurazione, indipendentemente dal linguaggio di implementazione della funzione.Note that the same configuration can be used, regardless of the language of the function implementation.

{
  "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"
    }
  ]
}

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.

Per altri esempi di codice e informazioni dettagliate sull'integrazione con archiviazione di Azure, vedere Associazioni del BLOB del servizio di archiviazione di Funzioni di Azure.For more code examples and details on integrating with Azure Storage, see Azure Functions triggers and bindings for Azure Storage.

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.

Uso del tipo restituito della funzione per restituire un singolo outputUsing the function return type to return a single output

Nell'esempio precedente viene illustrato come usare il valore restituito della funzione per offrire l'output a un'associazione, che si può fare tramite il parametro nome speciale $return.The preceding example shows how to use the function return value to provide output to a binding, which is achieved by using the special name parameter $return. (Questa opzione è supportata solo nei linguaggi che dispongono di un valore restituito, ad esempio C#, JavaScript e F#). Se una funzione dispone di più associazioni di output, usare $return per una sola delle associazioni di output.(This is only supported in languages that have a return value, such as C#, JavaScript, and F#.) If a function has multiple output bindings, use $return for only one of the output bindings.

// excerpt of function.json
{
    "name": "$return",
    "type": "blob",
    "direction": "out",
    "path": "output-container/{id}"
}

Gli esempi seguenti mostrano come i tipi restituiti vengono usati con le associazioni di output in C#, JavaScript e F#.The examples below show how return types are used with output bindings in C#, JavaScript, and F#.

// C# example: use method return value for output binding
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;
}
// C# example: async method, using return value for output binding
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);
}
// JavaScript: return a value in the second parameter to 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);
}
// F# example: use return value for output binding
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

Proprietà Binding dataTypeBinding dataType property

In .NET usare i tipi per definire il tipo di dati per i dati di input.In .NET, use the types 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 le lingue che vengono digitate in modo dinamico, ad esempio JavaScript, usare la proprietà dataType nella definizione di associazione.For languages that are dynamically typed such as JavaScript, use the dataType property in the binding definition. Ad esempio, per leggere il contenuto di una richiesta HTTP in formato binario, usare il tipo binary:For example, to read the content of an HTTP request in binary format, use the type 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.

Risoluzione di impostazioni appResolving 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. Ciò limita l'accesso a questi segreti e rende sicuro archiviare function.json in un repository di controllo sorgente pubblico.This limits access to these secrets and makes it safe to store function.json in a public source control repository.

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 impostazioni dell'app vengono risolte ogni volta che un valore è racchiuso tra simboli di percentuale, ad esempio %MyAppSetting%.App settings are resolved whenever a value is enclosed in percent signs, such as %MyAppSetting%. Si noti che la proprietà connection di trigger e associazioni è un caso speciale e risolve automaticamente i valori come impostazioni dell'app.Note that the connection property of triggers and bindings is a special case and automatically resolves values as app settings.

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"
    }
  ]
}

Proprietà dei metadati di triggerTrigger metadata properties

Oltre al payload dei dati offerto da un trigger (ad esempio, il messaggio di coda che ha attivato una funzione), molti trigger forniscono i valori dei metadati aggiuntivi.In addition to the data payload provided by a trigger (such as 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 Storage Queue 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 dettagli delle proprietà dei metadati per ogni trigger sono descritti nell'argomento di riferimento corrispondente.Details of metadata properties for each trigger are described in the corresponding reference topic. 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.

Poiché ad esempio i trigger BLOB presentano alcuni ritardi, è possibile usare un trigger di coda per l'esecuzione della funzione (vedere Trigger del BLOB del servizio di archiviazione).For example, since blob triggers have some delays, you can use a queue trigger to run your function (see Blob Storage Trigger). Il messaggio della coda contiene il filename del BLOB da attivare.The queue message would contain the blob filename to trigger on. Con l'uso della proprietà dei metadati queueTrigger, è possibile specificareper intero questo comportamento nella configurazione, invece che nel codice.Using the queueTrigger metadata property, you can specify this behavior all in your configuration, rather than your code.

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

Le proprietà dei metadati da un trigger possono anche essere usate in una espressione dell'associazione per un'altra associazione, come descritto nella sezione seguente.Metadata properties from a trigger can also be used in a binding expression for another binding, as described in the following section.

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. All'interno dell'associazione, è possibile definire delle espressioni di modello che possono quindi essere usate in altre associazioni o nel codice.Within your binding, you can define pattern expressions which can then be used in other bindings or your code. I metadati del trigger possono essere usati anche nelle espressioni di associazione, come illustrato nell'esempio nella sezione precedente.Trigger metadata can also be used in binding expressions, as show in the sample in the preceding section.

Ad esempio, si supponga che si desidera ridimensionare le immagini in un contenitore di archiviazione BLOB specifico, simile al modello di ridimensionamento immagine nella pagina Nuova funzione.For example, suppose you want to resize images in particular blob storage container, similar to the Image Resizer template in the New Function page. Passare a Nuova funzione -> Linguaggio C# -> Scenario Esempi -> ImageResizer-CSharp.Go to New Function -> Language C# -> Scenario Samples -> ImageResizer-CSharp.

Ecco la definizione di function.json:Here is the function.json definition:

{
  "bindings": [
    {
      "name": "image",
      "type": "blobTrigger",
      "path": "sample-images/{filename}",
      "direction": "in",
      "connection": "MyStorageConnection"
    },
    {
      "name": "imageSmall",
      "type": "blob",
      "path": "sample-images-sm/{filename}",
      "direction": "out",
      "connection": "MyStorageConnection"
    }
  ],
}

Si noti che il parametro filename viene usato nella definizione del trigger BLOB e anche nell'associazione output di BLOB.Notice that the filename parameter is used in both the blob trigger definition as well as the blob output binding. Questo parametro può essere usato anche nel codice della funzione.This parameter can also be used in function code.

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

GUID casualiRandom GUIDs

Funzioni di Azure fornisce una sintassi utile per la generazione di GUID nelle associazioni, tramite l'espressione dell'associazione {rand-guid}.Azure Functions provides a convenience syntax for generating GUIDs in your bindings, through the {rand-guid} binding expression. Nell'esempio seguente questa operazione viene usata per generare un nome del BLOB univoco:The following example uses this to generate a unique blob name:

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

Ora correnteCurrent time

È possibile usare l'espressione di associazione DateTime, che viene risolta in DateTime.UtcNow.You can use the binding expression DateTime, which resolves to DateTime.UtcNow.

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

Associare le proprietà di input personalizzate in un'espressione di associazioneBind to custom input properties in a binding expression

Le espressioni di associazione possono anche fare riferimento alle proprietà definite nel payload del trigger stesso.Binding expressions can also reference properties that are defined in the trigger payload itself. Ad esempio, si potrebbe voler associare in modo dinamico ad un file di archiviazione BLOB un filename fornito da un webhook.For example, you may want to dynamically bind to a blob storage file from a filename provided in a webhook.

Ad esempio, la seguente function.json usa una proprietà denominata BlobName dal payload del trigger:For example, the following function.json uses a property called BlobName from the trigger payload:

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

A tale scopo in C# e F #, è necessario definire un POCO che definisce i campi che saranno deserializzati nel payload del trigger.To accomplish this in C# and F#, you must define a POCO that defines the fields that will be deserialized in the trigger payload.

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, viene eseguita automaticamente la deserializzazione di JSON ed è possibile usare direttamente le proprietà.In JavaScript, JSON deserialization is automatically performed and you can use the properties directly.

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

Configurazione dell'associazione di dati in fase di runtimeConfiguring binding data at runtime

In C# e altri linguaggi .NET, è possibile usare un metodo di associazione imperativa anziché dichiarativa in function.json.In C# and other .NET languages, you can use an imperative binding pattern, as opposed to the declarative bindings in function.json. 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 Associazione in fase di runtime tramite le associazioni imperative nel riferimento per sviluppatori C#.To learn more, see Binding at runtime via imperative bindings in the C# developer reference.

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: