Guida per gli sviluppatori JavaScript di Funzioni di AzureAzure Functions JavaScript developer guide

L'esperienza JavaScript per Funzioni di Azure semplifica l'esportazione di una funzione, che viene passata come oggetto context per la comunicazione con il runtime e per la ricezione e l'invio di dati tramite associazioni.The JavaScript experience for Azure Functions makes it easy to export a function, which is passed as a context object for communicating with the runtime and for receiving and sending data via bindings.

Questo articolo presuppone che l'utente abbia già letto Guida di riferimento per gli sviluppatori di Funzioni di Azure.This article assumes that you've already read the Azure Functions developer reference.

Esportazione di una funzioneExporting a function

Tutte le funzioni JavaScript devono esportare una singola function tramite module.exports per consentire al runtime di trovare la funzione ed eseguirla.All JavaScript functions must export a single function via module.exports for the runtime to find the function and run it. Questa funzione deve sempre includere un oggetto context .This function must always include a context object.

// You must include a context, but other arguments are optional
module.exports = function(context) {
    // Additional inputs can be accessed by the arguments property
    if(arguments.length === 4) {
        context.log('This function has 4 inputs');
    }
};
// or you can include additional inputs in your arguments
module.exports = function(context, myTrigger, myInput, myOtherInput) {
    // function logic goes here :)
};

Le associazioni di direction === "in" vengono passate come argomenti della funzione, pertanto è possibile usare arguments per gestire in modo dinamico nuovi input, ad esempio usando arguments.length per l'iterazione di tutti gli input.Bindings of direction === "in" are passed along as function arguments, which means that you can use arguments to dynamically handle new inputs (for example, by using arguments.length to iterate over all your inputs). Questa funzionalità è utile se si ha solo un trigger e nessun input aggiuntivo, in quanto consente di accedere ai dati del trigger in modo prevedibile senza fare riferimento all'oggetto context.This functionality is convenient when you have only a trigger and no additional inputs, because you can predictably access your trigger data without referencing your context object.

Gli argomenti vengono sempre passati insieme alla funzione nell'ordine in cui sono indicati nel file function.json, anche se non vengono specificati nell'istruzione exports.The arguments are always passed along to the function in the order in which they occur in function.json, even if you don't specify them in your exports statement. Se ad esempio si ha function(context, a, b) e viene modificato in function(context, a), è comunque possibile ottenere il valore di b nel codice della funzione facendo riferimento a arguments[2].For example, if you have function(context, a, b) and change it to function(context, a), you can still get the value of b in function code by referring to arguments[2].

Anche tutte le associazioni, indipendentemente dalla direzione, vengono passate sull'oggetto context (vedere lo script seguente).All bindings, regardless of direction, are also passed along on the context object (see the following script).

Oggetto contextcontext object

Il runtime usa un oggetto context per passare dati dalla e alla funzione e consentire la comunicazione con il runtime.The runtime uses a context object to pass data to and from your function and to let you communicate with the runtime.

L'oggetto context è sempre il primo parametro di una funzione e deve essere incluso, in quanto contiene i metodi necessari per usare correttamente il runtime, ad esempio context.done e context.log.The context object is always the first parameter to a function and must be included because it has methods such as context.done and context.log, which are required to use the runtime correctly. È possibile assegnare all'oggetto un nome qualsiasi, ad esempio ctx o c.You can name the object whatever you would like (for example, ctx or c).

// You must include a context, but other arguments are optional
module.exports = function(context) {
    // function logic goes here :)
};

Proprietà context.bindingscontext.bindings property

context.bindings

Restituisce un oggetto denominato che contiene tutti i dati di input e output.Returns a named object that contains all your input and output data. Data la seguente definizione di associazione in function.json, è ad esempio possibile accedere al contenuto della coda tramite l'oggetto context.bindings.myInput.For example, the following binding definition in your function.json lets you access the contents of the queue from the context.bindings.myInput object.

{
    "type":"queue",
    "direction":"in",
    "name":"myInput"
    ...
}
// myInput contains the input data, which may have properties such as "name"
var author = context.bindings.myInput.name;
// Similarly, you can set your output data
context.bindings.myOutput = { 
        some_text: 'hello world', 
        a_number: 1 };

Metodo context.donecontext.done method

context.done([err],[propertyBag])

Comunica al runtime che l'esecuzione è stata completata.Informs the runtime that your code has finished. La chiamata a context.done è necessaria. In caso contrario, il runtime non saprà mai che la funzione è stata completata e l'esecuzione raggiungerà il timeout.You must call context.done, or else the runtime never knows that your function is complete, and the execution will time out.

Il metodo context.done consente di passare di nuovo al runtime sia un errore definito dall'utente sia un contenitore delle proprietà con proprietà che sovrascriveranno quelle presenti nell'oggetto context.bindings.The context.done method allows you to pass back both a user-defined error to the runtime and a property bag of properties that overwrite the properties on the context.bindings object.

// Even though we set myOutput to have:
//  -> text: hello world, number: 123
context.bindings.myOutput = { text: 'hello world', number: 123 };
// If we pass an object to the done function...
context.done(null, { myOutput: { text: 'hello there, world', noNumber: true }});
// the done method will overwrite the myOutput binding to be: 
//  -> text: hello there, world, noNumber: true

Metodo context.logcontext.log method

context.log(message)

Consente di scrivere nei log della console in streaming a livello di traccia predefinito.Allows you to write to the streaming console logs at the default trace level. In context.log sono disponibili altri metodi di registrazione che consentono di scrivere nel log della console ad altri livelli di traccia:On context.log, additional logging methods are available that let you write to the console log at other trace levels:

MetodoMethod DescrizioneDescription
error(messaggio)error(message) Scrive nella registrazione a livello di errore o inferiore.Writes to error level logging, or lower.
warn(messaggio)warn(message) Scrive nella registrazione a livello di avviso o inferiore.Writes to warning level logging, or lower.
info(messaggio)info(message) Scrive nella registrazione a livello di informazioni o inferiore.Writes to info level logging, or lower.
verbose(messaggio)verbose(message) Scrive nella registrazione a livello dettagliato.Writes to verbose level logging.

L'esempio seguente scrive nella console a livello di traccia di avviso:The following example writes to the console at the warning trace level:

context.log.warn("Something has happened."); 

È possibile impostare la soglia del livello di traccia per la registrazione nel file host.json o disattivarla.You can set the trace-level threshold for logging in the host.json file, or turn it off. Per altre informazioni su come scrivere nei log, vedere la sezione successiva.For more information about how to write to the logs, see the next section.

Associazione del tipo di datiBinding data type

Per definire il tipo di dati per un'associazione di input, usare la proprietà dataType nella definizione dell'associazione.To define the data type for an input binding, 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.

Scrittura dell'output di traccia nella consoleWriting trace output to the console

In Funzioni usare i metodi context.log per scrivere l'output di traccia nella console.In Functions, you use the context.log methods to write trace output to the console. A questo punto, non è possibile usare console.log per scrivere nella console.At this point, you cannot use console.log to write to the console.

Quando si chiama context.log(), il messaggio viene scritto nella console a livello di traccia predefinito, ovvero il livello di traccia info.When you call context.log(), your message is written to the console at the default trace level, which is the info trace level. Il codice seguente scrive nella console a livello di traccia informazioni:The following code writes to the console at the info trace level:

context.log({hello: 'world'});  

Il codice precedente equivale al seguente:The preceding code is equivalent to the following code:

context.log.info({hello: 'world'});  

Il codice seguente scrive nella console a livello di errore:The following code writes to the console at the error level:

context.log.error("An error has occurred.");  

Poiché error è il livello di traccia più alto, questa traccia viene scritta nell'output a tutti i livelli di traccia, fintantoché la registrazione è abilitata.Because error is the highest trace level, this trace is written to the output at all trace levels as long as logging is enabled.

Tutti i metodi context.log supportano lo stesso formato di parametri supportato dal metodo Node.js util.format.All context.log methods support the same parameter format that's supported by the Node.js util.format method. Si consideri il codice seguente, che scrive nella console usando il livello di traccia predefinito:Consider the following code, which writes to the console by using the default trace level:

context.log('Node.js HTTP trigger function processed a request. RequestUri=' + req.originalUrl);
context.log('Request Headers = ' + JSON.stringify(req.headers));

È possibile scrivere lo stesso codice anche nel formato seguente:You can also write the same code in the following format:

context.log('Node.js HTTP trigger function processed a request. RequestUri=%s', req.originalUrl);
context.log('Request Headers = ', JSON.stringify(req.headers));

Configurare il livello di traccia per la registrazione della consoleConfigure the trace level for console logging

Funzioni consente di definire la soglia del livello di traccia per la scrittura nella console; questo consente di controllare più facilmente il modo in cui le tracce vengono scritte nella console dalle funzioni.Functions lets you define the threshold trace level for writing to the console, which makes it easy to control the way traces are written to the console from your functions. Per impostare la soglia per tutte le tracce scritte nella console, usare la proprietà tracing.consoleLevel nel file host.json.To set the threshold for all traces written to the console, use the tracing.consoleLevel property in the host.json file. Questa impostazione si applica a tutte le funzioni dell'app per le funzioni.This setting applies to all functions in your function app. L'esempio seguente imposta la soglia di traccia per abilitare la registrazione dettagliata:The following example sets the trace threshold to enable verbose logging:

{ 
    "tracing": {      
        "consoleLevel": "verbose"     
    }
}  

I valori di consoleLevel corrispondono ai nomi dei metodi context.log.Values of consoleLevel correspond to the names of the context.log methods. Per disabilitare tutta la registrazione traccia nella console, impostare consoleLevel su off.To disable all trace logging to the console, set consoleLevel to off. Per altre informazioni, vedere il riferimento su host.json.For more information, see host.json reference.

Trigger e associazioni HTTPHTTP triggers and bindings

I trigger e i webhook HTTP e le associazioni di output HTTP usano oggetti di richiesta e risposta per rappresentare la messaggistica HTTP.HTTP and webhook triggers and HTTP output bindings use request and response objects to represent the HTTP messaging.

Oggetto della richiestaRequest object

Di seguito sono elencate le proprietà dell'oggetto request:The request object has the following properties:

ProprietàProperty DescrizioneDescription
bodybody Oggetto che contiene il corpo della richiesta.An object that contains the body of the request.
headersheaders Oggetto che contiene le intestazioni della richiesta.An object that contains the request headers.
methodmethod Metodo HTTP della richiesta.The HTTP method of the request.
originalUrloriginalUrl URL della richiesta.The URL of the request.
paramsparams Oggetto che contiene i parametri di routing della richiesta.An object that contains the routing parameters of the request.
queryquery Oggetto che contiene i parametri di query della richiesta.An object that contains the query parameters.
rawBodyrawBody Il corpo del messaggio sotto forma di stringa.The body of the message as a string.

Oggetto della rispostaResponse object

Di seguito sono elencate le proprietà dell'oggetto response:The response object has the following properties:

ProprietàProperty DescrizioneDescription
bodybody Oggetto che contiene il corpo della risposta.An object that contains the body of the response.
headersheaders Oggetto che contiene le intestazioni della risposta.An object that contains the response headers.
isRawisRaw Indica che la formattazione viene ignorata per la risposta.Indicates that formatting is skipped for the response.
Statostatus Codice di stato HTTP della risposta.The HTTP status code of the response.

Accesso a richiesta e rispostaAccessing the request and response

Quando si lavora con i trigger HTTP, è possibile accedere agli oggetti richiesta e risposta HTTP in uno qualsiasi dei tre modi seguenti:When you work with HTTP triggers, you can access the HTTP request and response objects in any of three ways:

  • Dalle associazioni di input e di output denominate.From the named input and output bindings. In questo modo, il trigger e le associazioni HTTP funzionano come qualsiasi altra associazione.In this way, the HTTP trigger and bindings work the same as any other binding. L'esempio seguente imposta l'oggetto risposta usando un'associazione response denominata.The following example sets the response object by using a named response binding:

    context.bindings.response = { status: 201, body: "Insert succeeded." };
    
  • Dalle proprietà req e res sull'oggetto context.From req and res properties on the context object. In questo modo per accedere ai dati HTTP dall'oggetto di contesto è possibile usare il modello convenzionale anziché il modello context.bindings.name completo.In this way, you can use the conventional pattern to access HTTP data from the context object, instead of having to use the full context.bindings.name pattern. L'esempio seguente illustra come accedere agli oggetti req e res nell'oggetto context:The following example shows how to access the req and res objects on the context:

    // You can access your http request off the context ...
    if(context.req.body.emoji === ':pizza:') context.log('Yay!');
    // and also set your http response
    context.res = { status: 202, body: 'You successfully ordered more coffee!' }; 
    
  • Oppure chiamando context.done().By calling context.done(). Un tipo speciale di associazione HTTP restituisce la risposta che viene passata al metodo context.done().A special kind of HTTP binding returns the response that is passed to the context.done() method. L'associazione di output HTTP seguente definisce un parametro di output $return:The following HTTP output binding defines a $return output parameter:

    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    }
    

    Questa associazione di output prevede che l'utente dia la risposta quando chiama done(), come indicato di seguito:This output binding expects you to supply the response when you call done(), as follows:

     // Define a valid response object.
    res = { status: 201, body: "Insert succeeded." };
    context.done(null, res);   
    

Versione di Node e gestione dei pacchettiNode version and package management

La versione di Node è attualmente bloccata alla 6.5.0.The node version is currently locked at 6.5.0. Si sta analizzando la possibilità di aggiungere il supporto per altre versioni e renderle configurabili.We're investigating adding support for more versions and making it configurable.

I passaggi seguenti consentono di includere i pacchetti nell'app per le funzioni:The following steps let you include packages in your function app:

  1. Passare a https://<function_app_name>.scm.azurewebsites.net.Go to https://<function_app_name>.scm.azurewebsites.net.

  2. Fare clic su Debug Console > CMD (Console di debug > CMD).Click Debug Console > CMD.

  3. Passare a D:\home\site\wwwroot, quindi trascinare il file package.json nella cartella wwwroot nella metà superiore della pagina.Go to D:\home\site\wwwroot, and then drag your package.json file to the wwwroot folder at the top half of the page.
    È possibile caricare i file nell'app per le funzioni anche in altri modi.You can upload files to your function app in other ways also. Per altre informazioni, vedere Come aggiornare i file delle app per le funzioni.For more information, see How to update function app files.

  4. Dopo aver caricato il file package.json, eseguire il comando npm install nella console di esecuzione remota Kudu.After the package.json file is uploaded, run the npm install command in the Kudu remote execution console.
    Questa azione scarica i pacchetti indicati nel file package.json e riavvia l'app per le funzioni.This action downloads the packages indicated in the package.json file and restarts the function app.

Una volta che i pacchetti necessari sono installati, è possibile importarli nella funzione chiamando il metodo require('packagename'), come nell'esempio seguente:After the packages you need are installed, you import them to your function by calling require('packagename'), as in the following example:

// Import the underscore.js library
var _ = require('underscore');
var version = process.version; // version === 'v6.5.0'

module.exports = function(context) {
    // Using our imported underscore.js library
    var matched_names = _
        .where(context.bindings.myInput.names, {first: 'Carla'});

È necessario definire un file package.json nella directory principale dell'app per le funzioni.You should define a package.json file at the root of your function app. La definizione del file consente a tutte le funzioni dell'app di condividere gli stessi pacchetti memorizzati nella cache garantendo prestazioni migliori.Defining the file lets all functions in the app share the same cached packages, which gives the best performance. In caso di conflitto di versione, è possibile risolverlo aggiungendo un file package.json nella cartella di una funzione specifica.If a version conflict arises, you can resolve it by adding a package.json file in the folder of a specific function.

Variabili di ambienteEnvironment variables

Per ottenere una variabile di ambiente o un valore di impostazione dell'app, usare process.envcome illustrato nell'esempio di codice seguente:To get an environment variable or an app setting value, use process.env, as shown in the following code example:

module.exports = function (context, myTimer) {
    var timeStamp = new Date().toISOString();

    context.log('Node.js timer trigger function ran!', timeStamp);   
    context.log(GetEnvironmentVariable("AzureWebJobsStorage"));
    context.log(GetEnvironmentVariable("WEBSITE_SITE_NAME"));

    context.done();
};

function GetEnvironmentVariable(name)
{
    return name + ": " + process.env[name];
}

Considerazioni per le funzioni JavaScriptConsiderations for JavaScript functions

Quando si usano le funzioni JavaScript, tenere presente le considerazioni nelle due sezioni che seguono.When you work with JavaScript functions, be aware of the considerations in the following two sections.

Scegliere i piani di servizio app con una singola vCPUChoose single-vCPU App Service plans

Quando si crea un'app per le funzioni che usa il piano di servizio app, è consigliabile selezionare un piano con una singola vCPU anziché uno con più vCPU.When you create a function app that uses the App Service plan, we recommend that you select a single-vCPU plan rather than a plan with multiple vCPUs. Oggi Funzioni esegue funzioni JavaScript in modo più efficiente in macchine virtuali con una singola vCPU e l'uso di macchine virtuali di dimensioni maggiori non produce i miglioramenti delle prestazioni previsti.Today, Functions runs JavaScript functions more efficiently on single-vCPU VMs, and using larger VMs does not produce the expected performance improvements. Se necessario, è possibile scalare orizzontalmente manualmente aggiungendo altre istanze di macchine virtuali con una singola vCPU oppure abilitare la scalabilità automatica.When necessary, you can manually scale out by adding more single-vCPU VM instances, or you can enable auto-scale. Per altre informazioni, vedere Scalare il conteggio delle istanze manualmente o automaticamente.For more information, see Scale instance count manually or automatically.

Supporto TypeScript e CoffeeScriptTypeScript and CoffeeScript support

Dal momento che non è ancora disponibile il supporto diretto per la compilazione automatica di TypeScript o CoffeeScript tramite il runtime, il supporto deve essere gestito all'esterno del runtime al momento della distribuzione.Because direct support does not yet exist for auto-compiling TypeScript or CoffeeScript via the runtime, such support needs to be handled outside the runtime, at deployment time.

Passaggi successiviNext steps

Per altre informazioni, vedere le seguenti risorse:For more information, see the following resources: