Eseguire la migrazione alla versione 4 del modello di programmazione Node.js per Funzioni di Azure

Articolo
01/19/2024

Questo articolo illustra le differenze tra la versione 3 e la versione 4 del modello di programmazione Node.js e come aggiornare un'app v3 esistente. Se si vuole creare una nuova app v4 invece di aggiornare un'app v3 esistente, vedere l'esercitazione per Visual Studio Code (VS Code) o Funzioni di Azure Core Tools. Questo articolo usa gli avvisi "suggerimento" per evidenziare le azioni concrete più importanti da eseguire per aggiornare l'app.

La versione 4 è progettata per offrire agli sviluppatori Node.js i vantaggi seguenti:

Offrire un'esperienza familiare e intuitiva per Node.js sviluppatori.
Rendere flessibile la struttura di file con supporto per la personalizzazione completa.
Passare a un approccio incentrato sul codice per definire la configurazione delle funzioni.

Considerazioni

Il modello di programmazione Node.js non deve essere confuso con il runtime di Funzioni di Azure:
- Modello di programmazione: definisce come creare il codice ed è specifico per JavaScript e TypeScript.
- Runtime: definisce il comportamento sottostante di Funzioni di Azure e viene condiviso in tutti i linguaggi.
La versione del modello di programmazione è strettamente associata alla versione del pacchetto npm @azure/functions. Il controllo delle versioni viene eseguito indipendentemente dal runtime. Sia il runtime che il modello di programmazione usano il numero 4 come versione principale più recente, ma questa è una coincidenza.
Non è possibile combinare i modelli di programmazione v3 e v4 nella stessa app per le funzioni. Non appena si registra una funzione v4 nell'app, tutte le funzioni v3 registrate nei file function.json vengono ignorate.

Requisiti

La versione 4 del modello di programmazione Node.js richiede le versioni minime seguenti:

@azure/functions Pacchetto npm v4.0.0
Node.js v18+
Funzioni di Azure Runtime v4.25+
Funzioni di Azure Core Tools v4.0.5382+ (se in esecuzione in locale)

@azure/functions Pacchetto npm v4.0.0
Node.js v18+
TypeScript v4+
Funzioni di Azure Runtime v4.25+
Funzioni di Azure Core Tools v4.0.5382+ (se in esecuzione in locale)

Includere il pacchetto npm

Nella versione 4 il @azure/functions pacchetto npm contiene il codice sorgente primario che esegue il backup del modello di programmazione Node.js. Nelle versioni precedenti, il codice fornito direttamente in Azure e il pacchetto npm aveva solo i tipi TypeScript. È ora necessario includere questo pacchetto per le app TypeScript e JavaScript. È possibile includere il pacchetto per le app v3 esistenti, ma non è obbligatorio.

Suggerimento

Assicurarsi che il @azure/functions pacchetto sia elencato nella dependencies sezione (non devDependencies) del file package.json . È possibile installare v4 usando il comando seguente:

npm install @azure/functions

Impostare il punto di ingresso dell'app

Nella versione 4 del modello di programmazione è possibile strutturare il codice desiderato. Gli unici file necessari nella radice dell'app sono host.json e package.json.

In caso contrario, definire la struttura del file impostando il main campo nel file package.json . È possibile impostare il campo main su un singolo file o su più file usando un modello glob. La tabella seguente mostra i valori di esempio per il campo main:

Esempio	Descrizione
`src/index.js`	Registrare le funzioni da un singolo file radice.
*`src/functions/.js`**	Registrare ogni funzione dal proprio file.
*`src/{index.js,functions/.js}`**	Combinazione in cui si registra ogni funzione dal proprio file, ma è ancora disponibile un file radice per il codice generale a livello di app.

Esempio	Descrizione
`dist/src/index.js`	Registrare le funzioni da un singolo file radice.
*`dist/src/functions/.js`**	Registrare ogni funzione dal proprio file.
*`dist/src/{index.js,functions/.js}`**	Combinazione in cui si registra ogni funzione dal proprio file, ma è ancora disponibile un file radice per il codice generale a livello di app.

Suggerimento

Assicurarsi di definire un main campo nel file package.json .

Cambiare l'ordine degli argomenti

L'input del trigger, invece del contesto di chiamata, è ora il primo argomento del gestore di funzioni. Il contesto di chiamata, ora il secondo argomento, è semplificato nella versione 4 e non è necessario come input del trigger. È possibile lasciarlo disattivato se non lo si usa.

Suggerimento

Cambiare l'ordine degli argomenti. Ad esempio, se si usa un trigger HTTP, passare (context, request) a (request, context) o solo (request) se non si usa il contesto.

Definire la funzione nel codice

Non è più necessario creare e gestire i file di configurazione function.json separati. È ora possibile definire completamente le funzioni direttamente nei file TypeScript o JavaScript. Inoltre, molte proprietà ora hanno impostazioni predefinite in modo che non sia necessario specificarle ogni volta.

const { app } = require('@azure/functions');

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    handler: async (request, context) => {
        context.log(`Http function processed request for url "${request.url}"`);

        const name = request.query.get('name') || (await request.text()) || 'world';

        return { body: `Hello, ${name}!` };
    },
});

module.exports = async function (context, req) {
    context.log(`Http function processed request for url "${request.url}"`);

    const name = req.query.name || req.body || 'world';

    context.res = {
        body: `Hello, ${name}!`
    };
};

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    }
  ]
}

import { app, HttpRequest, HttpResponseInit, InvocationContext } from '@azure/functions';

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    context.log(`Http function processed request for url "${request.url}"`);

    const name = request.query.get('name') || (await request.text()) || 'world';

    return { body: `Hello, ${name}!` };
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    handler: httpTrigger1,
});

import { AzureFunction, Context, HttpRequest } from "@azure/functions"

const httpTrigger: AzureFunction = async function (context: Context, req: HttpRequest): Promise<void> {
    context.log(`Http function processed request for url "${request.url}"`);

    const name = req.query.name || req.body || 'world';

    context.res = {
        body: `Hello, ${name}!`
    };
};

export default httpTrigger;

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    }
  ],
  "scriptFile": "../dist/HttpTrigger1/index.js"
}

Suggerimento

Spostare la configurazione dal file function.json al codice. Il tipo del trigger corrisponde a un metodo sull'oggetto app nel nuovo modello. Ad esempio, se si usa un httpTrigger tipo in function.json, chiamare app.http() nel codice per registrare la funzione. Se si usa timerTrigger, chiamare app.timer().

Esaminare l'utilizzo del contesto

Nella versione 4 l'oggetto context è semplificato per ridurre la duplicazione e semplificare la scrittura di unit test. Ad esempio, è stato semplificato l'input e l'output primario in modo che siano accessibili solo come argomento e valore restituito del gestore di funzioni.

Non è più possibile accedere all'input e all'output primario sull'oggetto context , ma è comunque necessario accedere agli input e agli output secondari sull'oggetto context . Per altre informazioni sugli input e gli output secondari, vedere la guida per sviluppatori Node.js.

Ottenere l'input primario come argomento

L'input primario viene chiamato anche trigger ed è l'unico input o output richiesto. È necessario avere un solo trigger (e uno).

La versione 4 supporta solo un modo per ottenere l'input del trigger, come primo argomento:

async function httpTrigger1(request, context) {
  const onlyOption = request;

async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
  const onlyOption = request;

La versione 3 supporta diversi modi per ottenere l'input del trigger:

async function httpTrigger1(context, request) {
    const option1 = request;
    const option2 = context.req;
    const option3 = context.bindings.req;

async function httpTrigger1(context: Context, req: HttpRequest): Promise<void> {
    const option1 = request;
    const option2 = context.req;
    const option3 = context.bindings.req;

Suggerimento

Assicurarsi di non usare context.req o context.bindings di ottenere l'input.

Impostare l'output primario come valore restituito

La versione 4 supporta solo un modo per impostare l'output primario, tramite il valore restituito:

return { 
  body: `Hello, ${name}!` 
};

async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    // ...
    return { 
      body: `Hello, ${name}!` 
    };
}

La versione 3 supporta diversi modi per impostare l'output primario:

// Option 1
context.res = {
    body: `Hello, ${name}!`
};
// Option 2, but you can't use this option with any async code:
context.done(null, {
    body: `Hello, ${name}!`
});
// Option 3, but you can't use this option with any async code:
context.res.send(`Hello, ${name}!`);
// Option 4, if "name" in function.json is "res":
context.bindings.res = {
    body: `Hello, ${name}!`
}
// Option 5, if "name" in function.json is "$return":
return {
    body: `Hello, ${name}!`
};

Suggerimento

Assicurarsi di restituire sempre l'output nel gestore di funzioni, anziché impostarlo con l'oggetto context .

Registrazione del contesto

Nella versione 4 i metodi di registrazione sono stati spostati nell'oggetto radice context , come illustrato nell'esempio seguente. Per altre informazioni sulla registrazione, vedere la guida per sviluppatori Node.js.

context.log('This is an info log');
context.error('This is an error');
context.warn('This is an error');

context.log('This is an info log');
context.log.error('This is an error');
context.log.warn('This is an error');

Creare un contesto di test

La versione 3 non supporta la creazione di un contesto di chiamata all'esterno del runtime di Funzioni di Azure, quindi la creazione di unit test può essere difficile. La versione 4 consente di creare un'istanza del contesto di chiamata, anche se le informazioni durante i test non sono dettagliate a meno che non vengano aggiunte manualmente.

const testInvocationContext = new InvocationContext({
  functionName: 'testFunctionName',
  invocationId: 'testInvocationId'
});

Esaminare l'utilizzo dei tipi HTTP

I tipi di richiesta e risposta HTTP sono ora un subset dello standard di recupero. Non sono più unici per Funzioni di Azure.

I tipi usano il undici pacchetto in Node.js. Questo pacchetto segue lo standard di recupero ed è attualmente integrato in Node.js core.

HttpRequest

Testo. È possibile accedere al corpo usando un metodo specifico del tipo che si vuole ricevere:

const body = await request.text();
const body = await request.json();
const body = await request.formData();
const body = await request.arrayBuffer();
const body = await request.blob();

Intestazione:

const header = request.headers.get('content-type');

Parametro di query:

const name = request.query.get('name');

Testo. È possibile accedere al corpo in diversi modi, ma il tipo restituito non è sempre coerente:

// returns a string, object, or Buffer
const body = request.body;
// returns a string
const body = request.rawBody;
// returns a Buffer
const body = request.bufferBody;
// returns an object representing a form
const body = await request.parseFormBody();

Intestazione. È possibile recuperare un'intestazione in diversi modi:

const header = request.get('content-type');
const header = request.headers.get('content-type');
const header = context.bindingData.headers['content-type'];

Parametro di query:
```
const name = request.query.name;
```

HttpResponse

Stato:
```
return { status: 200 };
```
Corpo:

Usare la body proprietà per restituire la maggior parte dei tipi, ad esempio o string Buffer:
```
return { body: "Hello, world!" };
```
Usare la jsonBody proprietà per il modo più semplice per restituire una risposta JSON:
```
return { jsonBody: { hello: "world" } };
```

Intestazione. È possibile impostare l'intestazione in due modi, a seconda che si usi la HttpResponse classe o l'interfaccia HttpResponseInit :

const response = new HttpResponse();
response.headers.set('content-type', 'application/json');
return response;

return {
  headers: { 'content-type': 'application/json' }
};

Stato. È possibile impostare uno stato in diversi modi:

context.res.status(200);
context.res = { status: 200}
context.res = { statusCode: 200 };
return { status: 200};
return { statusCode: 200 };

Testo. È possibile impostare un corpo in diversi modi ed è lo stesso indipendentemente dal tipo di corpo (string, , Bufferoggetto JSON e così via):
```
context.res.send("Hello, world!");
context.res.end("Hello, world!");
context.res = { body: "Hello, world!" };
return { body: "Hello, world!" };
```

Intestazione. È possibile impostare un'intestazione in diversi modi:

response.set('content-type', 'application/json');
response.setHeader('content-type', 'application/json');
response.headers = { 'content-type': 'application/json' }
context.res = {
  headers: { 'content-type': 'application/json' }
};
return {
  headers: { 'content-type': 'application/json' }
};

Suggerimento

Aggiornare qualsiasi logica usando i tipi di richiesta o risposta HTTP in modo che corrispondano ai nuovi metodi.

Suggerimento

Aggiornare qualsiasi logica usando i tipi di richiesta o risposta HTTP in modo che corrispondano ai nuovi metodi. È consigliabile ottenere errori di compilazione TypeScript per identificare se si usano metodi precedenti.

Risoluzione dei problemi

Vedere la guida alla risoluzione dei problemi Node.js.

Condividi tramite

Eseguire la migrazione alla versione 4 del modello di programmazione Node.js per Funzioni di Azure

Considerazioni

Requisiti

Includere il pacchetto npm

Impostare il punto di ingresso dell'app

Cambiare l'ordine degli argomenti

Definire la funzione nel codice

Esaminare l'utilizzo del contesto

Ottenere l'input primario come argomento

Impostare l'output primario come valore restituito

Registrazione del contesto

Creare un contesto di test

Esaminare l'utilizzo dei tipi HTTP

HttpRequest

HttpResponse

Risoluzione dei problemi

Commenti e suggerimenti

Risorse aggiuntive