Migreren naar versie 4 van het Node.js-programmeermodel voor Azure Functions

In dit artikel worden de verschillen besproken tussen versie 3 en versie 4 van het Node.js-programmeermodel en het upgraden van een bestaande v3-app. Als u een nieuwe v4-app wilt maken in plaats van een bestaande v3-app te upgraden, raadpleegt u de zelfstudie voor Visual Studio Code (VS Code) of Azure Functions Core Tools. In dit artikel worden 'tip'-waarschuwingen gebruikt om de belangrijkste concrete acties te markeren die u moet ondernemen om uw app te upgraden.

Versie 4 is ontworpen om Node.js-ontwikkelaars de volgende voordelen te bieden:

• Bied een vertrouwde en intuïtieve ervaring voor Node.js-ontwikkelaars.
• Maak de bestandsstructuur flexibel met ondersteuning voor volledige aanpassing.
• Schakel over naar een codegerichte benadering voor het definiëren van functieconfiguratie.

Overwegingen

• Het Node.js-programmeermodel mag niet worden verward met de Azure Functions-runtime:
  • Programmeermodel: Definieert hoe u uw code ontwerpt en specifiek is voor JavaScript en TypeScript.
  • Runtime: Definieert het onderliggende gedrag van Azure Functions en wordt gedeeld in alle talen.
• De versie van het programmeermodel is strikt gekoppeld aan de versie van het @azure/functions npm-pakket. Deze versie wordt onafhankelijk van de runtime geversied. Zowel de runtime als het programmeermodel gebruiken het nummer 4 als de nieuwste primaire versie, maar dat is toeval.
• U kunt de v3- en v4-programmeermodellen niet combineren in dezelfde functie-app. Zodra u één v4-functie in uw app registreert, worden alle v3-functies die zijn geregistreerd in function.json-bestanden genegeerd.

Vereisten

Voor versie 4 van het node.js-programmeermodel zijn de volgende minimale versies vereist:

• @azure/functions npm-pakket v4.0.0
• Node.js v18+
• Azure Functions Runtime v4.25+
• Azure Functions Core Tools v4.0.5382+ (indien lokaal uitgevoerd)

• @azure/functions npm-pakket v4.0.0
• Node.js v18+
• TypeScript v4+
• Azure Functions Runtime v4.25+
• Azure Functions Core Tools v4.0.5382+ (indien lokaal uitgevoerd)

Het npm-pakket opnemen

In v4 bevat het @azure/functions npm-pakket de primaire broncode die het Node.js-programmeermodel back-ups maakt. In eerdere versies had die code rechtstreeks in Azure verzonden en het npm-pakket alleen de TypeScript-typen. U moet dit pakket nu opnemen voor zowel TypeScript- als JavaScript-apps. U kunt het pakket voor bestaande v3-apps opnemen, maar dit is niet vereist.

Tip

Zorg ervoor dat het @azure/functions pakket wordt vermeld in de dependencies sectie (niet devDependencies) van uw package.json-bestand . U kunt v4 installeren met behulp van de volgende opdracht:

npm install @azure/functions

Uw app-invoerpunt instellen

In v4 van het programmeermodel kunt u de code naar wens structuren. De enige bestanden die u nodig hebt in de hoofdmap van uw app zijn host.json en package.json.

Anders definieert u de bestandsstructuur door het main veld in uw package.json-bestand in te stellen. U kunt het main veld instellen op één bestand of meerdere bestanden met behulp van een glob-patroon. In de volgende tabel ziet u voorbeeldwaarden voor het main veld:

Opmerking	Beschrijving
src/index.js	Registreer functies uit één hoofdbestand.
src/functions/*.js	Registreer elke functie uit een eigen bestand.
src/{index.js,functions/*.js}	Een combinatie waarbij u elke functie registreert vanuit een eigen bestand, maar u hebt nog steeds een hoofdbestand voor algemene code op app-niveau.

Opmerking	Beschrijving
dist/src/index.js	Registreer functies uit één hoofdbestand.
dist/src/functions/*.js	Registreer elke functie uit een eigen bestand.
dist/src/{index.js,functions/*.js}	Een combinatie waarbij u elke functie registreert vanuit een eigen bestand, maar u hebt nog steeds een hoofdbestand voor algemene code op app-niveau.

Tip

Zorg ervoor dat u een main veld in uw package.json-bestand definieert.

De volgorde van argumenten wijzigen

De triggerinvoer is nu het eerste argument voor de functie-handler in plaats van de aanroepcontext. De aanroepcontext, nu het tweede argument, is vereenvoudigd in v4 en is niet zo vereist als de triggerinvoer. U kunt het uitschakelen als u deze niet gebruikt.

Tip

De volgorde van de argumenten wijzigen. Als u bijvoorbeeld een HTTP-trigger gebruikt, schakelt u over naar (context, request) of (request, context) alleen (request) als u de context niet gebruikt.

Uw functie definiëren in code

U hoeft deze afzonderlijke function.json-configuratiebestanden niet meer te maken en te onderhouden. U kunt nu uw functies rechtstreeks definiëren in uw TypeScript- of JavaScript-bestanden. Bovendien hebben veel eigenschappen nu standaardwaarden, zodat u ze niet elke keer hoeft op te geven.

v4

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}!` };
    },
});

v3

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

v4

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,
});

v3

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

Tip

Verplaats de configuratie van het bestand function.json naar uw code. Het type trigger komt overeen met een methode op het app object in het nieuwe model. Als u bijvoorbeeld een httpTrigger type in function.json gebruikt, roept app.http() u uw code aan om de functie te registreren. Als u gebruikt timerTrigger, belt u app.timer().

Uw gebruik van context controleren

In v4 is het context object vereenvoudigd om duplicatie te verminderen en schrijfeenheidtests eenvoudiger te maken. We hebben bijvoorbeeld de primaire invoer en uitvoer gestroomlijnd, zodat ze alleen worden geopend als het argument en de retourwaarde van uw functie-handler.

U hebt geen toegang meer tot de primaire invoer en uitvoer van het context object, maar u moet nog steeds toegang krijgen tot secundaire invoer en uitvoer op het context object. Zie de ontwikkelaarshandleiding voor Node.js voor meer informatie over secundaire invoer en uitvoer.

De primaire invoer als argument ophalen

De primaire invoer wordt ook wel de trigger genoemd en is de enige vereiste invoer of uitvoer. U moet één (en slechts één) trigger hebben.

v4

Versie 4 ondersteunt slechts één manier om de triggerinvoer op te halen, als eerste argument:

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

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

v3

Versie 3 ondersteunt verschillende manieren om de triggerinvoer op te halen:

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;

Tip

Zorg ervoor dat u de invoer niet gebruikt context.req of context.bindings wilt ophalen.

De primaire uitvoer instellen als uw retourwaarde

v4

Versie 4 ondersteunt slechts één manier om de primaire uitvoer in te stellen via de retourwaarde:

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

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

v3

Versie 3 ondersteunt verschillende manieren om de primaire uitvoer in te stellen:

// 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}!`
};

Tip

Zorg ervoor dat u altijd de uitvoer in de functie-handler retourneert in plaats van deze in te stellen met het context object.

Logboekregistratie van context

In v4 zijn logboekregistratiemethoden verplaatst naar het hoofdobject context , zoals wordt weergegeven in het volgende voorbeeld. Zie de ontwikkelaarshandleiding voor Node.js voor meer informatie over logboekregistratie.

v4

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

v3

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

Een testcontext maken

Versie 3 biedt geen ondersteuning voor het maken van een aanroepcontext buiten de Azure Functions-runtime, zodat het ontwerpen van eenheidstests lastig kan zijn. Met versie 4 kunt u een exemplaar van de aanroepcontext maken, hoewel de informatie tijdens tests niet gedetailleerd is, tenzij u deze zelf toevoegt.

v4

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

v3

Niet mogelijk.

Uw gebruik van HTTP-typen controleren

De HTTP-aanvraag- en antwoordtypen zijn nu een subset van de ophaalstandaard. Ze zijn niet meer uniek voor Azure Functions.

De typen gebruiken het undici pakket in Node.js. Dit pakket volgt de ophaalstandaard en wordt momenteel geïntegreerd in Node.js core.

HttpRequest

v4

• Hoofdtekst. U kunt de hoofdtekst openen met behulp van een methode die specifiek is voor het type dat u wilt ontvangen:

  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();
  

• Header:

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

• Queryparameter:

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

v3

• Hoofdtekst. U hebt op verschillende manieren toegang tot de hoofdtekst, maar het geretourneerde type is niet altijd consistent:

  // 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();
  

• Koptekst. U kunt een header op verschillende manieren ophalen:

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

• Queryparameter:

  const name = request.query.name;
  

HttpResponse

v4

• Status:

  return { status: 200 };
  

• Hoofdtekst:

  Gebruik de eigenschap om de body meeste typen te retourneren, zoals een string of Buffer:

  return { body: "Hello, world!" };
  

  Gebruik de jsonBody eigenschap voor de eenvoudigste manier om een JSON-antwoord te retourneren:

  return { jsonBody: { hello: "world" } };
  

• Koptekst. U kunt de header op twee manieren instellen, afhankelijk van of u de HttpResponse klasse of de HttpResponseInit interface gebruikt:

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

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

v3

• Status. U kunt een status op verschillende manieren instellen:

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

• Hoofdtekst. U kunt een hoofdtekst op verschillende manieren instellen en dit is hetzelfde, ongeacht het type hoofdtekst (string, BufferJSON-object, enzovoort):

  context.res.send("Hello, world!");
  context.res.end("Hello, world!");
  context.res = { body: "Hello, world!" };
  return { body: "Hello, world!" };
  

• Koptekst. U kunt een koptekst op verschillende manieren instellen:

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

Tip

Werk alle logica bij met behulp van de HTTP-aanvraag- of antwoordtypen zodat deze overeenkomen met de nieuwe methoden.

Tip

Werk alle logica bij met behulp van de HTTP-aanvraag- of antwoordtypen zodat deze overeenkomen met de nieuwe methoden. U krijgt typeScript-buildfouten om u te helpen identificeren of u oude methoden gebruikt.

Problemen oplossen

Raadpleeg de handleiding voor het oplossen van problemen met Node.js.