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

Questa guida contiene informazioni sulle complessità correlate alla scrittura di funzioni di Azure con JavaScript.This guide contains information about the intricacies of writing Azure Functions with JavaScript.

Una funzione JavaScript è un oggetto function esportato che viene eseguito quando viene attivato (i trigger vengono configurati in function.json).A JavaScript function is an exported function that executes when triggered (triggers are configured in function.json). Il primo argomento passato a ogni funzione è un oggetto context, che viene usato per la ricezione e l'invio di dati di binding, la registrazione e la comunicazione con il Runtime.The first argument passed to every function is a context object, which is used for receiving and sending binding data, logging, and communicating with the runtime.

Questo articolo presuppone che siano già state lette le informazioni di riferimento per sviluppatori su Funzioni di Azure.This article assumes that you have already read the Azure Functions developer reference. Completare la Guida introduttiva funzioni per creare la prima funzione usando Visual Studio Code o nel portale.Complete the Functions quickstart to create your first function, using Visual Studio Code or in the portal.

Questo articolo supporta anche lo sviluppo di app typescript.This article also supports TypeScript app development.

Struttura di cartelleFolder structure

La struttura di cartelle di output per un progetto JavaScript ha un aspetto simile alla seguente.The required folder structure for a JavaScript project looks like the following. Questa impostazione predefinita non può essere modificata.This default can be changed. Per altre informazioni, vedere la sezione scriptFile di seguito.For more information, see the scriptFile section below.

FunctionsProject
 | - MyFirstFunction
 | | - index.js
 | | - function.json
 | - MySecondFunction
 | | - index.js
 | | - function.json
 | - SharedCode
 | | - myFirstHelperFunction.js
 | | - mySecondHelperFunction.js
 | - node_modules
 | - host.json
 | - package.json
 | - extensions.csproj

Nella radice del progetto è presente un file host.json condiviso che può essere usato per configurare l'app per le funzioni.At the root of the project, there's a shared host.json file that can be used to configure the function app. Per ogni funzione è presente una cartella con il file di codice (JS) e il file di configurazione delle associazioni (function.json) correlati.Each function has a folder with its own code file (.js) and binding configuration file (function.json). Il nome della directory padre di function.json è sempre il nome della funzione.The name of function.json's parent directory is always the name of your function.

Le estensioni di associazione richieste nella versione 2.x del runtime di Funzioni sono definite nel file extensions.csproj, con gli effettivi file di libreria inclusi nella cartella bin.The binding extensions required in version 2.x of the Functions runtime are defined in the extensions.csproj file, with the actual library files in the bin folder. Quando si sviluppa una funzione in locale, è necessario registrare le estensioni di associazione.When developing locally, you must register binding extensions. Quando si sviluppano funzioni nel portale di Azure, la registrazione viene eseguita automaticamente.When developing functions in the Azure portal, this registration is done for you.

Esportazione di una funzioneExporting a function

Le funzioni JavaScript devono essere esportate tramite module.exports (o exports).JavaScript functions must be exported via module.exports (or exports). La funzione esportata deve essere una funzione JavaScript che viene eseguita quando attivata.Your exported function should be a JavaScript function that executes when triggered.

Per impostazione predefinita, il runtime di Funzioni cerca la funzione in index.js, dove index.js condivide la stessa directory padre del file function.json corrispondente.By default, the Functions runtime looks for your function in index.js, where index.js shares the same parent directory as its corresponding function.json. Nel caso predefinito la funzione esportata deve essere l'unica esportazione dal relativo file, ovvero l'esportazione denominata run o index.In the default case, your exported function should be the only export from its file or the export named run or index. Per configurare il percorso del file e il nome di esportazione della funzione, vedere Configurare il punto di ingresso della funzione più avanti.To configure the file location and export name of your function, read about configuring your function's entry point below.

Alla funzione esportata vengono passati vari di argomenti per l'esecuzione.Your exported function is passed a number of arguments on execution. Il primo argomento accettato è sempre un oggetto context.The first argument it takes is always a context object. Se la funzione è sincrona (non restituisce un suggerimento), è necessario passare l'oggetto context, perché la chiamata context.done è necessaria per l'uso corretto.If your function is synchronous (doesn't return a Promise), you must pass the context object, as calling context.done is required for correct use.

// You should include context, other arguments are optional
module.exports = function(context, myTrigger, myInput, myOtherInput) {
    // function logic goes here :)
    context.done();
};

Esportazione di una funzione asincronaExporting an async function

Quando si usano la dichiarazione async function o semplici oggetti Promise JavaScript nella versione 2.x del runtime di Funzioni, non è necessario chiamare in modo esplicito il callback context.done per segnalare che la funzione è stata completata.When using the async function declaration or plain JavaScript Promises in version 2.x of the Functions runtime, you do not need to explicitly call the context.done callback to signal that your function has completed. La funzione viene completata al termine della funzione asincrona esportata o di Promise.Your function completes when the exported async function/Promise completes. Per le funzioni destinate alla versione 1.x del runtime, è necessario chiamare comunque context.done al termine dell'esecuzione del codice.For functions targeting the version 1.x runtime, you must still call context.done when your code is done executing.

L'esempio seguente è una semplice funzione che registra che è stata attivata e termina immediatamente l'esecuzione.The following example is a simple function that logs that it was triggered and immediately completes execution.

module.exports = async function (context) {
    context.log('JavaScript trigger function processed a request.');
};

Quando si esporta una funzione asincrona, è possibile anche configurare il valore return per un'associazione di output.When exporting an async function, you can also configure an output binding to take the return value. Questa procedura è consigliata in presenza di una sola associazione di output.This is recommended if you only have one output binding.

Per assegnare un output usando return, modificare la proprietà name in $return nel file function.json.To assign an output using return, change the name property to $return in function.json.

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

In questo caso, la funzione dovrebbe essere simile all'esempio seguente:In this case, your function should look like the following example:

module.exports = async function (context, req) {
    context.log('JavaScript HTTP trigger function processed a request.');
    // You can call and await an async method here
    return {
        body: "Hello, world!"
    };
}

AssociazioniBindings

In JavaScript le associazioni vengono configurate e definite nel file function.json di una funzione.In JavaScript, bindings are configured and defined in a function's function.json. Le funzioni interagiscono con le associazioni in molti modi.Functions interact with bindings a number of ways.

InputInputs

In Funzioni di Azure, gli input vengono suddivisi in due categorie, ovvero l'input del trigger e un input aggiuntivo.Input are divided into two categories in Azure Functions: one is the trigger input and the other is the additional input. Le associazioni di trigger e di altri input (associazioni di direction === "in") possono essere lette da una funzione in tre modi:Trigger and other input bindings (bindings of direction === "in") can be read by a function in three ways:

  • [Consigliato] Come parametri passati alla funzione.[Recommended] As parameters passed to your function. Vengono passati alla funzione nell'ordine in cui sono definiti in function.json.They are passed to the function in the same order that they are defined in function.json. La proprietà name definita in Function. JSON non deve necessariamente corrispondere al nome del parametro, anche se deve essere.The name property defined in function.json does not need to match the name of your parameter, although it should.

    module.exports = async function(context, myTrigger, myInput, myOtherInput) { ... };
    
  • Come membri dell'oggetto context.bindings.As members of the context.bindings object. Ogni membro è denominato in base alla proprietà name definita in function.json.Each member is named by the name property defined in function.json.

    module.exports = async function(context) { 
        context.log("This is myTrigger: " + context.bindings.myTrigger);
        context.log("This is myInput: " + context.bindings.myInput);
        context.log("This is myOtherInput: " + context.bindings.myOtherInput);
    };
    
  • Come input tramite l'oggetto JavaScript arguments.As inputs using the JavaScript arguments object. Ciò equivale essenzialmente a passare gli input come parametri, ma consente di gestire in modo dinamico gli input.This is essentially the same as passing inputs as parameters, but allows you to dynamically handle inputs.

    module.exports = async function(context) { 
        context.log("This is myTrigger: " + arguments[1]);
        context.log("This is myInput: " + arguments[2]);
        context.log("This is myOtherInput: " + arguments[3]);
    };
    

OutputOutputs

Gli output (associazioni di direction === "out") possono essere scritti da una funzione in diversi modi.Outputs (bindings of direction === "out") can be written to by a function in a number of ways. In tutti i casi, la proprietà name dell'associazione come definita in function.json corrisponde al nome del membro dell'oggetto scritto nella funzione.In all cases, the name property of the binding as defined in function.json corresponds to the name of the object member written to in your function.

È possibile assegnare i dati alle associazioni di output in uno dei modi seguenti (non combinare questi metodi):You can assign data to output bindings in one of the following ways (don't combine these methods):

  • [Consigliato per più output] Restituzione di un oggetto.[Recommended for multiple outputs] Returning an object. Se si usa una funzione di restituzione asincrona/Promise, è possibile restituire un oggetto con i dati di output assegnati.If you are using an async/Promise returning function, you can return an object with assigned output data. Nell'esempio seguente, le associazioni di output sono denominate "httpResponse" e "queueOutput" in function.json.In the example below, the output bindings are named "httpResponse" and "queueOutput" in function.json.

    module.exports = async function(context) {
        let retMsg = 'Hello, world!';
        return {
            httpResponse: {
                body: retMsg
            },
            queueOutput: retMsg
        };
    };
    

    Se si usa una funzione sincrona, è possibile restituire questo oggetto usando context.done (vedere l'esempio).If you are using a synchronous function, you can return this object using context.done (see example).

  • [Consigliato per singolo output] Restituzione diretta di un valore e uso del nome di associazione $return.[Recommended for single output] Returning a value directly and using the $return binding name. Questo approccio vale solo per le funzioni asincrone o che restituiscono oggetti Promise.This only works for async/Promise returning functions. Vedere l'esempio in Esportazione di una funzione asincrona.See example in exporting an async function.

  • Assegnazione di valori a context.bindings È possibile assegnare valori direttamente a context.bindings.Assigning values to context.bindings You can assign values directly to context.bindings.

    module.exports = async function(context) {
        let retMsg = 'Hello, world!';
        context.bindings.httpResponse = {
            body: retMsg
        };
        context.bindings.queueOutput = retMsg;
        return;
    };
    

Tipo di dati delle associazioniBindings 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"
}

Le opzioni per dataType sono: binary, stream e string.Options for dataType are: binary, stream, and string.

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 può essere usato per la lettura e l'impostazione dei dati dalle associazioni, la scrittura di log e l'uso del callback context.done quando la funzione esportata è sincrona.The context object can be used for reading and setting data from bindings, writing logs, and using the context.done callback when your exported function is synchronous.

L'oggetto context è sempre il primo parametro per una funzione.The context object is always the first parameter to a function. Deve essere incluso perché contiene metodi importanti, come context.done e context.log.It should be included because it has important methods such as context.done and context.log. È 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(ctx) {
    // function logic goes here :)
    ctx.done();
};

Proprietà context.bindingscontext.bindings property

context.bindings

Restituisce un oggetto denominato utilizzato per leggere o assegnare dati di associazione.Returns a named object that is used to read or assign binding data. È possibile accedere ai dati di binding di input e trigger leggendo le proprietà in context.bindings.Input and trigger binding data can be accessed by reading properties on context.bindings. I dati dell'associazione di output possono essere assegnati aggiungendo dati a context.bindingsOutput binding data can be assigned by adding data to context.bindings

Ad esempio, le definizioni di associazione seguenti in function.json consentono di accedere al contenuto di una coda da context.bindings.myInput e di assegnare output a una coda tramite context.bindings.myOutput.For example, the following binding definitions in your function.json let you access the contents of a queue from context.bindings.myInput and assign outputs to a queue using context.bindings.myOutput.

{
    "type":"queue",
    "direction":"in",
    "name":"myInput"
    ...
},
{
    "type":"queue",
    "direction":"out",
    "name":"myOutput"
    ...
}
// 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 };

È possibile scegliere di definire i dati di associazione di output usando il metodo context.done invece dell'oggetto context.binding (vedere di seguito).You can choose to define output binding data using the context.done method instead of the context.binding object (see below).

Proprietà context.bindingDatacontext.bindingData property

context.bindingData

Restituisce un oggetto denominato che contiene i metadati del trigger e i dati di chiamata della funzione (invocationId, sys.methodName, sys.utcNow, sys.randGuid).Returns a named object that contains trigger metadata and function invocation data (invocationId, sys.methodName, sys.utcNow, sys.randGuid). Per un esempio dei metadati del trigger, vedere questo esempio di hub eventi.For an example of trigger metadata, see this event hubs example.

Metodo context.donecontext.done method

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

Segnala al runtime che il codice è stato completato.Lets the runtime know that your code has completed. Quando la funzione usa la dichiarazione async function, non è necessario usare context.done().When your function uses the async function declaration, you do not need to use context.done(). Il callback context.done viene chiamato in modo implicito.The context.done callback is implicitly called. Le funzioni asincrone sono disponibili in Node 8 o versione successiva, che richiede la versione 2.x del runtime di Funzioni.Async functions are available in Node 8 or a later version, which requires version 2.x of the Functions runtime.

Se la funzione non è asincrona, è necessario chiamare context.done per informare il runtime che la funzione è completa.If your function is not an async function, you must call context.done to inform the runtime that your function is complete. Si verifica il timeout dell'esecuzione se manca.The execution times out if it is missing.

Il metodo context.done permette di restituire un errore definito dall'utente al runtime e un oggetto JSON contenente i dati di associazione di output.The context.done method allows you to pass back both a user-defined error to the runtime and a JSON object containing output binding data. Le proprietà passate a context.done sovrascrivono qualsiasi impostazione nell'oggetto context.bindings.Properties passed to context.done overwrite anything set 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 overwrites the myOutput binding to be: 
//  -> text: 'hello there, world', noNumber: true

Metodo context.logcontext.log method

context.log(message)

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

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

L'esempio seguente scrive un log nel livello di traccia di avviso:The following example writes a log at the warning trace level:

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

È possibile configurare la soglia del livello di traccia per la registrazione nel file host.json.You can configure the trace-level threshold for logging in the host.json file. Per altre informazioni sulla scrittura di log, vedere Scrittura dell'output di traccia nella console più avanti.For more information on writing logs, see writing trace outputs below.

Vedere Monitoraggio di Funzioni di Azure per altre informazioni sulla visualizzazione e sull'esecuzione di query su log di funzioni.Read monitoring Azure Functions to learn more about viewing and querying function logs.

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. In Funzioni di Azure v2.x gli output di traccia tramite console.log vengono acquisiti a livello di app per le funzioni.In Functions v2.x, trace outputs using console.log are captured at the Function App level. Questo significa che gli output di console.log non sono associati a una chiamata di funzione specifica e non vengono visualizzati nei log di una funzione specifica.This means that outputs from console.log are not tied to a specific function invocation and aren't displayed in a specific function's logs. Vengono tuttavia propagati in Application Insights.They do, however, propagate to Application Insights. In Funzioni di Azure v1.x non è possibile usare console.log per scrivere nella console.In Functions v1.x, 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'});  

Questo codice equivale al codice mostrato sopra:This code is equivalent to the code above:

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

Questo codice scrive nella console a livello di errore:This 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 log di funzioni usando il livello di traccia predefinito:Consider the following code, which writes function logs 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

Con Funzioni 1.x è possibile definire la soglia del livello di traccia per la scrittura nella console. Ciò consente di controllare più facilmente il modo in cui le tracce vengono scritte nella console dalla funzione.Functions 1.x 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 function. 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

L'oggetto (richiesta) context.req ha le proprietà seguenti:The context.req (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

L'oggetto (risposta) context.res ha le proprietà seguenti:The context.res (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.
statusstatus Codice di stato HTTP della risposta.The HTTP status code of the response.

Accesso a richiesta e rispostaAccessing the request and response

Quando si usano trigger HTTP, è possibile accedere agli oggetti richiesta e risposta HTTP in diversi modi:When you work with HTTP triggers, you can access the HTTP request and response objects in a number of ways:

  • Dalle proprietà req e res per l'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!' }; 
    
  • 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:

    {
        "type": "http",
        "direction": "out",
        "name": "response"
    }
    
    context.bindings.response = { status: 201, body: "Insert succeeded." };
    
  • [Solo risposta] Chiamando context.res.send(body?: any).[Response only] By calling context.res.send(body?: any). Viene creata una risposta HTTP con input body come corpo della risposta.An HTTP response is created with input body as the response body. Viene chiamato context.done() in modo implicito.context.done() is implicitly called.

  • [Solo risposta] Chiamando context.done().[Response only] By calling context.done(). Un tipo speciale di binding HTTP restituisce la risposta che viene passata al metodo context.done().A special type 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"
    }
    
     // Define a valid response object.
    res = { status: 201, body: "Insert succeeded." };
    context.done(null, res);   
    

Versione del nodoNode version

La tabella seguente mostra la versione di Node.js usata da ogni versione principale del runtime di Funzioni:The following table shows the Node.js version used by each major version of the Functions runtime:

Versione di FunzioniFunctions version Versione di Node.jsNode.js version
1.x1.x 6.11.2 (bloccata dal runtime)6.11.2 (locked by the runtime)
2.x2.x Versioni di node. js attiva e di manutenzione LTS (~ 10 consigliate).Active LTS and Maintenance LTS Node.js versions (~10 recommended). Specificare come destinazione la versione in Azure impostando l' impostazione dell'app WEBSITE_NODE_DEFAULT_VERSION su ~10.Target the version in Azure by setting the WEBSITE_NODE_DEFAULT_VERSION app setting to ~10.

È possibile visualizzare la versione corrente usata dal runtime controllando l'impostazione dell'app seguente o stampando process.version da qualsiasi funzione.You can see the current version that the runtime is using by checking the above app setting or by printing process.version from any function.

Gestione delle dipendenzeDependency management

Per poter usare librerie della community nel codice JavaScript, come mostrato nell'esempio seguente, è necessario assicurarsi che tutte le dipendenze siano installate nell'app per le funzioni in Azure.In order to use community libraries in your JavaScript code, as is shown in the below example, you need to ensure that all dependencies are installed on your Function App in Azure.

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

Nota

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

Quando si distribuiscono le app per le funzioni dal controllo del codice sorgente, durante la distribuzione qualsiasi file package.json presente nel repository attiverà un comando npm install nella cartella in cui si trova.When deploying Function Apps from source control, any package.json file present in your repo, will trigger an npm install in its folder during deployment. Ma quando si esegue una distribuzione tramite il portale o l'interfaccia della riga di comando, è necessario installare il pacchetto manualmente.But when deploying via the Portal or CLI, you will have to manually install the packages.

Esistono due modi per installare pacchetti nell'app per le funzioni:There are two ways to install packages on your Function App:

Distribuzione con le dipendenzeDeploying with Dependencies

  1. Installare tutti i pacchetti necessari in locale eseguendo npm install.Install all requisite packages locally by running npm install.

  2. Distribuire il codice e assicurarsi che la cartella node_modules sia inclusa nella distribuzione.Deploy your code, and ensure that the node_modules folder is included in the deployment.

Tramite KuduUsing Kudu

  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.

Variabili di ambienteEnvironment variables

In Funzioni, le impostazioni dell'app, come le stringhe di connessione al servizio, vengono esposte come variabili di ambiente durante l'esecuzione.In Functions, app settings, such as service connection strings, are exposed as environment variables during execution. È possibile accedere a queste impostazioni usando process.env, come illustrato nella seconda e terza chiamata a context.log() in cui si registrano le variabili di ambiente AzureWebJobsStorage e WEBSITE_SITE_NAME:You can access these settings using process.env, as shown here in the second and third calls to context.log() where we log the AzureWebJobsStorage and WEBSITE_SITE_NAME environment variables:

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

    context.log('Node.js timer trigger function ran!', timeStamp);
    context.log("AzureWebJobsStorage: " + process.env["AzureWebJobsStorage"]);
    context.log("WEBSITE_SITE_NAME: " + process.env["WEBSITE_SITE_NAME"]);
};

Esistono diversi modi per aggiungere, aggiornare ed eliminare le impostazioni dell'app per le funzioni:There are several ways that you can add, update, and delete function app settings:

Per l'esecuzione in locale, le impostazioni dell'app vengono lette dal file di progetto local.settings.json.When running locally, app settings are read from the local.settings.json project file.

Configurare il punto di ingresso della funzioneConfigure function entry point

È possibile usare le proprietà scriptFile e entryPoint di function.json per configurare il percorso e il nome della funzione esportata.The function.json properties scriptFile and entryPoint can be used to configure the location and name of your exported function. Queste proprietà possono essere importanti quando JavaScript viene sottoposto a transpile.These properties can be important when your JavaScript is transpiled.

Usando scriptFileUsing scriptFile

Per impostazione predefinita, viene eseguita una funzione JavaScript da index.js, un file che condivide la stessa directory padre del file function.json corrispondente.By default, a JavaScript function is executed from index.js, a file that shares the same parent directory as its corresponding function.json.

È possibile usare scriptFile per ottenere una struttura di cartelle simile a quella nell'esempio seguente:scriptFile can be used to get a folder structure that looks like the following example:

FunctionApp
 | - host.json
 | - myNodeFunction
 | | - function.json
 | - lib
 | | - sayHello.js
 | - node_modules
 | | - ... packages ...
 | - package.json

Il file function.json per myNodeFunction deve includere una proprietà scriptFile che punta al file con la funzione esportata da eseguire.The function.json for myNodeFunction should include a scriptFile property pointing to the file with the exported function to run.

{
  "scriptFile": "../lib/sayHello.js",
  "bindings": [
    ...
  ]
}

Usando entryPointUsing entryPoint

In scriptFile (o index.js) una funzione deve essere esportata tramite module.exports per poter essere trovata ed eseguita.In scriptFile (or index.js), a function must be exported using module.exports in order to be found and run. Per impostazione predefinita, la funzione eseguita quando viene attivata è l'unica esportazione dal file, ovvero l'esportazione denominata run o quella denominata index.By default, the function that executes when triggered is the only export from that file, the export named run, or the export named index.

Questo aspetto può essere configurato tramite entryPoint in function.json, come illustrato nell'esempio seguente:This can be configured using entryPoint in function.json, as in the following example:

{
  "entryPoint": "logFoo",
  "bindings": [
    ...
  ]
}

In Funzioni v2.x, che supporta il parametro this nelle funzioni utente, il codice della funzione può quindi essere simile all'esempio seguente:In Functions v2.x, which supports the this parameter in user functions, the function code could then be as in the following example:

class MyObj {
    constructor() {
        this.foo = 1;
    };

    logFoo(context) { 
        context.log("Foo is " + this.foo); 
        context.done(); 
    }
}

const myObj = new MyObj();
module.exports = myObj;

In questo esempio, è importante notare che, anche se è in corso l'esportazione di un oggetto, non vi sono garanzie per mantenere lo stato tra le esecuzioni.In this example, it is important to note that although an object is being exported, there are no guarantees for preserving state between executions.

Debug localeLocal Debugging

Quando viene avviato con il parametro --inspect, un processo node. js è in ascolto di un client di debug sulla porta specificata.When started with the --inspect parameter, a Node.js process listens for a debugging client on the specified port. In funzioni di Azure 2. x è possibile specificare gli argomenti da passare al processo node. js che esegue il codice aggiungendo la variabile di ambiente o l'impostazione dell'app languageWorkers:node:arguments = <args>.In Azure Functions 2.x, you can specify arguments to pass into the Node.js process that runs your code by adding the environment variable or App Setting languageWorkers:node:arguments = <args>.

Per eseguire il debug in locale, aggiungere "languageWorkers:node:arguments": "--inspect=5858" in Values nel file local. Settings. JSON e aggiungere un debugger alla porta 5858.To debug locally, add "languageWorkers:node:arguments": "--inspect=5858" under Values in your local.settings.json file and attach a debugger to port 5858.

Quando si esegue il debug con VS Code, il parametro --inspect viene aggiunto automaticamente usando il valore port nel file Launch. JSON del progetto.When debugging using VS Code, the --inspect parameter is automatically added using the port value in the project's launch.json file.

Nella versione 1. x, l'impostazione languageWorkers:node:arguments non funzionerà.In version 1.x, setting languageWorkers:node:arguments will not work. È possibile selezionare la porta di debug con il parametro --nodeDebugPort Azure Functions Core Tools.The debug port can be selected with the --nodeDebugPort parameter on Azure Functions Core Tools.

TypeScriptTypeScript

Quando la versione 2. x del runtime di funzioni è la destinazione, entrambe le funzioni di Azure per Visual Studio Code e il Azure Functions Core Tools consentono di creare app per le funzioni usando un modello che supporta i progetti di app per le funzioni typescript.When you target version 2.x of the Functions runtime, both Azure Functions for Visual Studio Code and the Azure Functions Core Tools let you create function apps using a template that support TypeScript function app projects. Il modello genera file di progetto package.json e tsconfig.json che semplificano il transpile, l'esecuzione e la pubblicazione di funzioni JavaScript dal codice TypeScript con questi strumenti.The template generates package.json and tsconfig.json project files that make it easier to transpile, run, and publish JavaScript functions from TypeScript code with these tools.

Viene usato un file .funcignore generato per indicare quali file vengono esclusi quando un progetto viene pubblicato in Azure.A generated .funcignore file is used to indicate which files are excluded when a project is published to Azure.

I file TypeScript (. TS) vengono traspilati in file JavaScript (con estensione js) nella directory di output dist.TypeScript files (.ts) are transpiled into JavaScript files (.js) in the dist output directory. I modelli TypeScript usano il parametro scriptFile in function.json per indicare la posizione del file con estensione js corrispondente nella cartella dist.TypeScript templates use the scriptFile parameter in function.json to indicate the location of the corresponding .js file in the dist folder. Il percorso di output viene impostato dal modello utilizzando il parametro outDir nel file tsconfig.json.The output location is set by the template by using outDir parameter in the tsconfig.json file. Se si modifica questa impostazione o il nome della cartella, il runtime non è in grado di trovare il codice da eseguire.If you change this setting or the name of the folder, the runtime is not able to find the code to run.

Nota

Il supporto sperimentale per TypeScript esiste la versione 1. x del runtime di funzioni.Experimental support for TypeScript exists version 1.x of the Functions runtime. La versione sperimentale esegue il transpile dei file TypeScript in file JavaScript quando viene richiamata la funzione.The experimental version transpiles TypeScript files into JavaScript files when the function is invoked. Nella versione 2. x questo supporto sperimentale è stato sostituito dal metodo basato su strumenti che transpilazione prima dell'inizializzazione dell'host e durante il processo di distribuzione.In version 2.x, this experimental support has been superseded by the tool-driven method that does transpilation before the host is initialized and during the deployment process.

Il modo in cui si sviluppa e distribuisce localmente da un progetto TypeScript dipende dallo strumento di sviluppo.The way that you locally develop and deploy from a TypeScript project depends on your development tool.

Visual Studio CodeVisual Studio Code

Funzioni di Azure per Visual Studio Code estensione consente di sviluppare le funzioni usando typescript.The Azure Functions for Visual Studio Code extension lets you develop your functions using TypeScript. Gli strumenti di base sono un requisito dell'estensione funzioni di Azure.The Core Tools is a requirement of the Azure Functions extension.

Per creare un'app per le funzioni TypeScript in Visual Studio Code, scegliere TypeScript come lingua quando si crea un'app per le funzioni.To create a TypeScript function app in Visual Studio Code, choose TypeScript as your language when you create a function app.

Quando si preme F5 per eseguire l'app in locale, transpilazione viene eseguita prima che l'host (Func. exe) venga inizializzato.When you press F5 to run the app locally, transpilation is done before the host (func.exe) is initialized.

Quando si distribuisce l'app per le funzioni in Azure usando il pulsante Distribuisci in app per le funzioni, l'estensione di funzioni di Azure genera prima di tutto una compilazione di file JavaScript pronta per la produzione dai file di origine typescript.When you deploy your function app to Azure using the Deploy to function app... button, the Azure Functions extension first generates a production-ready build of JavaScript files from the TypeScript source files.

Azure Functions Core ToolsAzure Functions Core Tools

Esistono diversi modi in cui un progetto TypeScript differisce da un progetto JavaScript quando si usano gli strumenti di base.There are several ways in which a TypeScript project differs from a JavaScript project when using the Core Tools.

Crea progettoCreate project

Per creare un progetto di app per le funzioni TypeScript usando gli strumenti di base, è necessario specificare l'opzione di lingua TypeScript quando si crea l'app per le funzioni.To create a TypeScript function app project using Core Tools, you must specify the TypeScript language option when you create your function app. Questa operazione può essere eseguita in uno dei modi seguenti:You can do this in one of the following ways:

  • Eseguire il comando func init, selezionare node come Language stack, quindi selezionare typescript.Run the func init command, select node as your language stack, and then select typescript.

  • Eseguire il comando func init --worker-runtime typescript.Run the func init --worker-runtime typescript command.

Esegui localeRun local

Per eseguire localmente il codice dell'app per le funzioni usando gli strumenti di base, usare i comandi seguenti anziché func host start:To run your function app code locally using Core Tools, use the following commands instead of func host start:

npm install
npm start

Il comando npm start equivale ai comandi seguenti:The npm start command is equivalent to the following commands:

  • npm run build
  • func extensions install
  • tsc
  • func start

Pubblicazione in AzurePublish to Azure

Prima di usare il comando func azure functionapp publish per eseguire la distribuzione in Azure, creare una compilazione di file JavaScript pronta per la produzione dai file di origine typescript.Before you use the func azure functionapp publish command to deploy to Azure, you create a production-ready build of JavaScript files from the TypeScript source files.

I comandi seguenti preparano e pubblicano il progetto TypeScript usando gli strumenti principali:The following commands prepare and publish your TypeScript project using Core Tools:

npm run build:production 
func azure functionapp publish <APP_NAME>

In questo comando sostituire <APP_NAME> con il nome dell'app per le funzioni.In this command, replace <APP_NAME> with the name of your function app.

Considerazioni per le funzioni JavaScriptConsiderations for JavaScript functions

Quando si usano funzioni JavaScript, tenere presente le considerazioni indicate nelle due sezioni seguenti.When you work with JavaScript functions, be aware of the considerations in the following 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. Quando necessario, è possibile aumentare manualmente il numero di istanze aggiungendo altre istanze di macchine virtuali vCPU. in alternativa, è possibile abilitare la scalabilità automatica.When necessary, you can manually scale out by adding more single-vCPU VM instances, or you can enable autoscale. Per altre informazioni, vedere Scalare il conteggio delle istanze manualmente o automaticamente.For more information, see Scale instance count manually or automatically.

Avvio a freddoCold Start

Quando si sviluppano funzioni di Azure in un modello di hosting serverless, gli avvii a freddo sono una realtà.When developing Azure Functions in the serverless hosting model, cold starts are a reality. Il termine avvio a freddo si riferisce al fatto che quando viene avviata per la prima volta dopo un periodo di inattività, l'app per le funzioni richiede più tempo per l'avvio.Cold start refers to the fact that when your function app starts for the first time after a period of inactivity, it takes longer to start up. Per le funzioni di JavaScript con alberi delle dipendenze estesi, in particolare, l'avvio a freddo può essere significativo.For JavaScript functions with large dependency trees in particular, cold start can be significant. Per velocizzare il processo di avvio a freddo eseguire le funzioni come un file di pacchetto quando possibile.To speed up the cold start process, run your functions as a package file when possible. Molti metodi di distribuzione usano il modello di esecuzione dal pacchetto per impostazione predefinita, ma in presenza di numerosi avvii a freddo e se questo non è il modello di esecuzione in uso, questa modifica può offrire miglioramenti significativi.Many deployment methods use the run from package model by default, but if you're experiencing large cold starts and are not running this way, this change can offer a significant improvement.

Limiti di connessioneConnection Limits

Quando si usa un client specifico del servizio in un'applicazione di funzioni di Azure, non creare un nuovo client con ogni chiamata di funzione.When you use a service-specific client in an Azure Functions application, don't create a new client with every function invocation. In alternativa, creare un singolo client statico nell'ambito globale.Instead, create a single, static client in the global scope. Per altre informazioni, vedere gestione delle connessioni in funzioni di Azure.For more information, see managing connections in Azure Functions.

Usare async e awaitUse async and await

Quando si scrivono funzioni di Azure in JavaScript, è necessario scrivere codice usando le parole chiave async e await.When writing Azure Functions in JavaScript, you should write code using the async and await keywords. La scrittura di codice utilizzando async e await anziché i callback o .then e .catch con le promesse consente di evitare due problemi comuni:Writing code using async and await instead of callbacks or .then and .catch with Promises helps avoid two common problems:

  • Generazione di eccezioni non rilevate che arrestano in modo anomalo il processo node. js, che potenzialmente influisce sull'esecuzione di altre funzioni.Throwing uncaught exceptions that crash the Node.js process, potentially affecting the execution of other functions.
  • Comportamento imprevisto, ad esempio log mancanti da context. log, causato da chiamate asincrone non correttamente attese.Unexpected behavior, such as missing logs from context.log, caused by asynchronous calls that are not properly awaited.

Nell'esempio seguente viene richiamato il metodo asincrono fs.readFile con una funzione di callback di errore-prima come secondo parametro.In the example below, the asynchronous method fs.readFile is invoked with an error-first callback function as its second parameter. Questo codice causa entrambi i problemi menzionati in precedenza.This code causes both of the issues mentioned above. Un'eccezione non rilevata in modo esplicito nell'ambito corretto è stata arrestata in modo anomalo nell'intero processo (problema #1).An exception that is not explicitly caught in the correct scope crashed the entire process (issue #1). La chiamata di context.done() al di fuori dell'ambito della funzione di callback significa che la chiamata della funzione può terminare prima che il file venga letto (problema #2).Calling context.done() outside of the scope of the callback function means that the function invocation may end before the file is read (issue #2). In questo esempio, la chiamata di context.done() è troppo precoce per le voci di log mancanti che iniziano con Data from file:.In this example, calling context.done() too early results in missing log entries starting with Data from file:.

// NOT RECOMMENDED PATTERN
const fs = require('fs');

module.exports = function (context) {
    fs.readFile('./hello.txt', (err, data) => {
        if (err) {
            context.log.error('ERROR', err);
            // BUG #1: This will result in an uncaught exception that crashes the entire process
            throw err;
        }
        context.log(`Data from file: ${data}`);
        // context.done() should be called here
    });
    // BUG #2: Data is not guaranteed to be read before the Azure Function's invocation ends
    context.done();
}

L'utilizzo delle parole chiave async e await consente di evitare entrambi questi errori.Using the async and await keywords helps avoid both of these errors. È consigliabile usare la funzione di utilità node. js util.promisify per trasformare le funzioni di tipo callback con errori prima in funzioni awaitable.You should use the Node.js utility function util.promisify to turn error-first callback-style functions into awaitable functions.

Nell'esempio seguente, le eccezioni non gestite generate durante l'esecuzione della funzione hanno esito negativo solo sulla chiamata che ha generato un'eccezione.In the example below, any unhandled exceptions thrown during the function execution only fail the individual invocation that raised an exception. La parola chiave await indica che i passaggi che seguono readFileAsync vengono eseguiti solo dopo il completamento di readFile.The await keyword means that steps following readFileAsync only execute after readFile is complete. Con async e await, non è necessario chiamare anche il callback di context.done().With async and await, you also don't need to call the context.done() callback.

// Recommended pattern
const fs = require('fs');
const util = require('util');
const readFileAsync = util.promisify(fs.readFile);

module.exports = async function (context) {
    try {
        const data = await readFileAsync('./hello.txt');
    } catch (err) {
        context.log.error('ERROR', err);
        // This rethrown exception will be handled by the Functions Runtime and will only fail the individual invocation
        throw err;
    }
    context.log(`Data from file: ${data}`);
}

Passaggi successiviNext steps

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